diff options
Diffstat (limited to 'doc')
374 files changed, 5085 insertions, 2854 deletions
diff --git a/doc/README.md b/doc/README.md index 8ce5d2e240a..9a0252cc334 100644 --- a/doc/README.md +++ b/doc/README.md @@ -358,7 +358,7 @@ The following documentation relates to the DevOps **Secure** stage: | [Dependency Scanning](user/application_security/dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | | [Dynamic Application Security Testing (DAST)](user/application_security/dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | | [Group Security Dashboard](user/application_security/security_dashboard/index.md) **(ULTIMATE)** | View vulnerabilities in all the projects in a group and its subgroups. | -| [License Management](user/application_security/license_management/index.md) **(ULTIMATE)** | Search your project's dependencies for their licenses. | +| [License Compliance](user/application_security/license_compliance/index.md) **(ULTIMATE)** | Search your project's dependencies for their licenses. | | [Project Security Dashboard](user/application_security/security_dashboard/index.md) **(ULTIMATE)** | View the latest security reports for your project. | | [Static Application Security Testing (SAST)](user/application_security/sast/index.md) **(ULTIMATE)** | Analyze source code for known vulnerabilities. | diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index 02de2caf558..8075a40cae7 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -75,6 +75,8 @@ From there, you can see the following actions: - User was removed from project - Project export was downloaded - Project repository was downloaded +- Project was archived +- Project was unarchived ### Instance events **(PREMIUM ONLY)** 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 86dd398343b..7c14d4004db 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 @@ -32,7 +32,7 @@ For example, [Active Directory](https://technet.microsoft.com/en-us/library/hh83 We won't cover the installation and configuration of Windows Server or Active Directory Domain Services in this tutorial. There are a number of resources online to guide you through this process: -- Install Windows Server 2012 - (_technet.microsoft.com_) - [Installing Windows Server 2012 ](https://technet.microsoft.com/en-us/library/jj134246(v=ws.11).aspx) +- Install Windows Server 2012 - (_technet.microsoft.com_) - [Installing Windows Server 2012](https://technet.microsoft.com/en-us/library/jj134246(v=ws.11).aspx) - Install Active Directory Domain Services (AD DS) (_technet.microsoft.com_)- [Install Active Directory Domain Services](https://technet.microsoft.com/windows-server-docs/identity/ad-ds/deploy/install-active-directory-domain-services--level-100-#BKMK_PS) @@ -249,7 +249,7 @@ After configuring LDAP, basic authentication will be available. Users can then l Users that are removed from the LDAP base group (e.g `OU=GitLab INT,DC=GitLab,DC=org`) will be **blocked** in GitLab. [More information](../ldap.md#security) on LDAP security. -If `allow_username_or_email_login` is enabled in the LDAP configuration, GitLab will ignore everything after the first '@' in the LDAP username used on login. Example: The username `` jon.doe@example.com `` is converted to `jon.doe` when authenticating with the LDAP server. Disable this setting if you use `userPrincipalName` as the `uid`. +If `allow_username_or_email_login` is enabled in the LDAP configuration, GitLab will ignore everything after the first '@' in the LDAP username used on login. Example: The username `jon.doe@example.com` is converted to `jon.doe` when authenticating with the LDAP server. Disable this setting if you use `userPrincipalName` as the `uid`. ## LDAP extended features on GitLab EE diff --git a/doc/administration/auth/okta.md b/doc/administration/auth/okta.md index 5524c3ba092..41745e8caae 100644 --- a/doc/administration/auth/okta.md +++ b/doc/administration/auth/okta.md @@ -98,20 +98,20 @@ Now that the Okta app is configured, it's time to enable it in GitLab. >**Notes:** > >- Change the value for `assertion_consumer_service_url` to match the HTTPS endpoint - of GitLab (append `users/auth/saml/callback` to the HTTPS URL of your GitLab - installation to generate the correct value). + > of GitLab (append `users/auth/saml/callback` to the HTTPS URL of your GitLab + > installation to generate the correct value). > >- To get the `idp_cert_fingerprint` fingerprint, first download the - certificate from the Okta app you registered and then run: - `openssl x509 -in okta.cert -noout -fingerprint`. Substitute `okta.cert` - with the location of your certificate. + > certificate from the Okta app you registered and then run: + > `openssl x509 -in okta.cert -noout -fingerprint`. Substitute `okta.cert` + > with the location of your certificate. > >- Change the value of `idp_sso_target_url`, with the value of the - **Identity Provider Single Sign-On URL** from the step when you - configured the Okta app. + > **Identity Provider Single Sign-On URL** from the step when you + > configured the Okta app. > >- Change the value of `issuer` to the value of the **Audience Restriction** from your Okta app configuration. This will identify GitLab - to the IdP. + > to the IdP. > >- Leave `name_identifier_format` as-is. diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md index d0adeb89543..f5d58db0133 100644 --- a/doc/administration/container_registry.md +++ b/doc/administration/container_registry.md @@ -137,6 +137,15 @@ otherwise you will run into conflicts. 1. Save the file and [reconfigure GitLab][] for the changes to take effect. +1. Validate using: + + ```sh + openssl s_client -showcerts -servername gitlab.example.com -connect gitlab.example.com:443 > cacert.pem + ``` + +NOTE: **Note:** +If your certificate provider provides the CA Bundle certificates, append them to the TLS certificate file. + **Installations from source** 1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and @@ -163,9 +172,13 @@ docker login gitlab.example.com:4567 If the Registry is configured to use its own domain, you will need a TLS certificate for that specific domain (e.g., `registry.example.com`) or maybe -a wildcard certificate if hosted under a subdomain of your existing GitLab +a wildcard certificate if hosted under a subdomain of your existing GitLab domain (e.g., `registry.gitlab.example.com`). +NOTE: **Note:** +As well as manually generated SSL certificates (explained here), certificates automatically +generated by Let's Encrypt are also [supported in Omnibus installs](https://docs.gitlab.com/omnibus/settings/ssl.html#host-services). + Let's assume that you want the container Registry to be accessible at `https://registry.gitlab.example.com`. @@ -458,7 +471,7 @@ You can use GitLab as an auth endpoint and use a non-bundled Container Registry. ``` 1. A certificate keypair is required for GitLab and the Container Registry to - communicate securely. By default omnibus-gitlab will generate one keypair, + communicate securely. By default Omnibus GitLab will generate one keypair, which is saved to `/var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key`. When using a non-bundled Container Registry, you will need to supply a custom certificate key. To do that, add the following to @@ -474,7 +487,7 @@ You can use GitLab as an auth endpoint and use a non-bundled Container Registry. **Note:** The file specified at `registry_key_path` gets populated with the content specified by `internal_key`, each time reconfigure is executed. If - no file is specified, omnibus-gitlab will default it to + no file is specified, Omnibus GitLab will default it to `/var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key` and will populate it. diff --git a/doc/administration/custom_hooks.md b/doc/administration/custom_hooks.md index 32462a95a1a..7238d08ab09 100644 --- a/doc/administration/custom_hooks.md +++ b/doc/administration/custom_hooks.md @@ -12,17 +12,17 @@ NOTE: **Note:** Custom Git hooks won't be replicated to secondary nodes if you use [GitLab Geo](geo/replication/index.md) Git natively supports hooks that are executed on different actions. -Examples of server-side git hooks include pre-receive, post-receive, and update. +Examples of server-side Git hooks include pre-receive, post-receive, and update. See [Git SCM Server-Side Hooks][hooks] for more information about each hook type. -As of gitlab-shell version 2.2.0 (which requires GitLab 7.5+), GitLab -administrators can add custom git hooks to any GitLab project. +As of GitLab Shell version 2.2.0 (which requires GitLab 7.5+), GitLab +administrators can add custom Git hooks to any GitLab project. ## Create a custom Git hook for a repository Server-side Git hooks are typically placed in the repository's `hooks` -subdirectory. In GitLab, hook directories are symlinked to the gitlab-shell -`hooks` directory for ease of maintenance between gitlab-shell upgrades. +subdirectory. In GitLab, hook directories are symlinked to the GitLab Shell +`hooks` directory for ease of maintenance between GitLab Shell upgrades. Custom hooks are implemented differently, but the behavior is exactly the same once the hook is created. Follow the steps below to set up a custom hook for a repository: @@ -36,7 +36,7 @@ repository: 1. Inside the new `custom_hooks` directory, create a file with a name matching the hook type. For a pre-receive hook the file name should be `pre-receive` with no extension. -1. Make the hook file executable and make sure it's owned by git. +1. Make the hook file executable and make sure it's owned by Git. 1. Write the code to make the Git hook function as expected. Hooks can be in any language. Ensure the 'shebang' at the top properly reflects the language type. For example, if the script is in Ruby the shebang will probably be @@ -49,17 +49,17 @@ as appropriate. To create a Git hook that applies to all of your repositories in your instance, set a global Git hook. Since all the repositories' `hooks` -directories are symlinked to gitlab-shell's `hooks` directory, adding any hook -to the gitlab-shell `hooks` directory will also apply it to all repositories. Follow +directories are symlinked to GitLab Shell's `hooks` directory, adding any hook +to the GitLab Shell `hooks` directory will also apply it to all repositories. Follow the steps below to properly set up a custom hook for all repositories: 1. On the GitLab server, navigate to the configured custom hook directory. The - default is in the gitlab-shell directory. The gitlab-shell `hook` directory + default is in the GitLab Shell directory. The GitLab Shell `hook` directory for an installation from source the path is usually `/home/git/gitlab-shell/hooks`. For Omnibus installs the path is usually `/opt/gitlab/embedded/service/gitlab-shell/hooks`. To look in a different directory for the global custom hooks, - set `custom_hooks_dir` in the gitlab-shell config. For + set `custom_hooks_dir` in the GitLab Shell config. For Omnibus installations, this can be set in `gitlab.rb`; and in source installations, this can be set in `gitlab-shell/config.yml`. 1. Create a new directory in this location. Depending on your hook, it will be diff --git a/doc/administration/database_load_balancing.md b/doc/administration/database_load_balancing.md index dc4cc401fca..64eca0b00f6 100644 --- a/doc/administration/database_load_balancing.md +++ b/doc/administration/database_load_balancing.md @@ -122,6 +122,7 @@ production: discover: nameserver: localhost record: secondary.postgresql.service.consul + record_type: A port: 8600 interval: 60 disconnect_timeout: 120 @@ -137,12 +138,16 @@ The following options can be set: | Option | Description | Default | |----------------------|---------------------------------------------------------------------------------------------------|-----------| | `nameserver` | The nameserver to use for looking up the DNS record. | localhost | -| `record` | The A record to look up. This option is required for service discovery to work. | | +| `record` | The record to look up. This option is required for service discovery to work. | | +| `record_type` | Optional record type to look up, this can be either A or SRV (since GitLab 12.3) | A | | `port` | The port of the nameserver. | 8600 | | `interval` | The minimum time in seconds between checking the DNS record. | 60 | | `disconnect_timeout` | The time in seconds after which an old connection is closed, after the list of hosts was updated. | 120 | | `use_tcp` | Lookup DNS resources using TCP instead of UDP | false | +If `record_type` is set to `SRV`, GitLab will continue to use a round-robin algorithm +and will ignore the `weight` and `priority` in the record. + The `interval` value specifies the _minimum_ time between checks. If the A record has a TTL greater than this value, then service discovery will honor said TTL. For example, if the TTL of the A record is 90 seconds, then service diff --git a/doc/administration/dependency_proxy.md b/doc/administration/dependency_proxy.md index d2c52b67e67..5153666705f 100644 --- a/doc/administration/dependency_proxy.md +++ b/doc/administration/dependency_proxy.md @@ -48,7 +48,7 @@ local location or even use object storage. The dependency proxy files for Omnibus GitLab installations are stored under `/var/opt/gitlab/gitlab-rails/shared/dependency_proxy/` and for source -installations under `shared/dependency_proxy/` (relative to the git home directory). +installations under `shared/dependency_proxy/` (relative to the Git home directory). To change the local storage path: **Omnibus GitLab installations** diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index d44e141b66b..407539885a6 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -1,4 +1,4 @@ -# Disaster Recovery **(PREMIUM ONLY)** +# Disaster Recovery (Geo) **(PREMIUM ONLY)** Geo replicates your database, your Git repositories, and few other assets. We will support and replicate more data in the future, that will enable you to @@ -297,7 +297,7 @@ for another **primary** node. All the old replication settings will be overwritt ## Troubleshooting -### I followed the disaster recovery instructions and now two-factor auth is broken! +### I followed the disaster recovery instructions and now two-factor auth is broken The setup instructions for Geo prior to 10.5 failed to replicate the `otp_key_base` secret, which is used to encrypt the two-factor authentication diff --git a/doc/administration/geo/replication/index.md b/doc/administration/geo/replication/index.md index 5aedb665935..dbd466b906d 100644 --- a/doc/administration/geo/replication/index.md +++ b/doc/administration/geo/replication/index.md @@ -1,4 +1,4 @@ -# Geo Replication **(PREMIUM ONLY)** +# Replication (Geo) **(PREMIUM ONLY)** > - Introduced in GitLab Enterprise Edition 8.9. > - Using Geo in combination with @@ -6,7 +6,7 @@ > is considered **Generally Available** (GA) in > [GitLab Premium](https://about.gitlab.com/pricing/) 10.4. -Geo is the solution for widely distributed development teams. +Replication with Geo is the solution for widely distributed development teams. ## Overview diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index fe1557fd8b5..3ae92b07736 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -538,7 +538,7 @@ can simply reset the existing tracking database with: sudo gitlab-rake geo:db:reset ``` -### Geo node has a database that is writable which is an indication it is not configured for replication with the primary node. +### Geo node has a database that is writable which is an indication it is not configured for replication with the primary node This error refers to a problem with the database replica on a **secondary** node, which Geo expects to have access to. It usually means, either: @@ -552,7 +552,7 @@ PostgreSQL instances: - A read-only replica of the **primary** node. - A regular, writable instance that holds replication metadata. That is, the Geo tracking database. -### Geo node does not appear to be replicating the database from the primary node. +### Geo node does not appear to be replicating the database from the primary node The most common problems that prevent the database from replicating correctly are: diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index 1780e1babe9..9d653d4e09e 100644 --- a/doc/administration/git_protocol.md +++ b/doc/administration/git_protocol.md @@ -53,7 +53,7 @@ sudo service ssh restart ## Instructions In order to use the new protocol, clients need to either pass the configuration -`-c protocol.version=2` to the git command, or set it globally: +`-c protocol.version=2` to the Git command, or set it globally: ```sh git config --global protocol.version 2 diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 150494c47e5..eab4b2c6eea 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -64,6 +64,7 @@ The following list depicts what the network architecture of Gitaly is: topology. - A `(Gitaly address, Gitaly token)` corresponds to a Gitaly server. - A Gitaly server hosts one or more storages. +- A GitLab server can use one or more Gitaly servers. - Gitaly addresses must be specified in such a way that they resolve correctly for ALL Gitaly clients. - Gitaly clients are: Unicorn, Sidekiq, gitlab-workhorse, @@ -77,14 +78,16 @@ The following list depicts what the network architecture of Gitaly is: - Authentication is done through a static token which is shared among the Gitaly and GitLab Rails nodes. -Below we describe how to configure a Gitaly server at address -`gitaly.internal:8075` with secret token `abc123secret`. We assume -your GitLab installation has two repository storages, `default` and -`storage1`. +Below we describe how to configure two Gitaly servers one at +`gitaly1.internal` and the other at `gitaly2.internal` +with secret token `abc123secret`. We assume +your GitLab installation has three repository storages: `default`, +`storage1` and `storage2`. ### 1. Installation -First install Gitaly using either Omnibus GitLab or install it from source: +First install Gitaly on each Gitaly server using either +Omnibus GitLab or install it from source: - For Omnibus GitLab: [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab package you want using **steps 1 and 2** from the GitLab downloads page but @@ -119,7 +122,7 @@ Configure a token on the instance that runs the GitLab Rails application. ### 3. Gitaly server configuration -Next, on the Gitaly server, you need to configure storage paths, enable +Next, on the Gitaly servers, you need to configure storage paths, enable the network listener and configure the token. NOTE: **Note:** if you want to reduce the risk of downtime when you enable @@ -136,7 +139,7 @@ Git operations in GitLab will result in an API error. NOTE: **Note:** In most or all cases, the storage paths below end in `/repositories` which is -not that case with `path` in `git_data_dirs` of Omnibus GitLab installations. +not the case with `path` in `git_data_dirs` of Omnibus GitLab installations. Check the directory layout on your Gitaly server to be sure. **For Omnibus GitLab** @@ -175,15 +178,29 @@ Check the directory layout on your Gitaly server to be sure. gitaly['listen_addr'] = "0.0.0.0:8075" gitaly['auth_token'] = 'abc123secret' + # To use TLS for Gitaly you need to add + gitaly['tls_listen_addr'] = "0.0.0.0:9999" + gitaly['certificate_path'] = "path/to/cert.pem" + gitaly['key_path'] = "path/to/key.pem" + ``` + +1. Append the following to `/etc/gitlab/gitlab.rb` for each respective server: + + For `gitaly1.internal`: + + ``` gitaly['storage'] = [ { 'name' => 'default' }, { 'name' => 'storage1' }, ] + ``` - # To use TLS for Gitaly you need to add - gitaly['tls_listen_addr'] = "0.0.0.0:9999" - gitaly['certificate_path'] = "path/to/cert.pem" - gitaly['key_path'] = "path/to/key.pem" + For `gitaly2.internal`: + + ``` + gitaly['storage'] = [ + { 'name' => 'storage2' }, + ] ``` NOTE: **Note:** @@ -206,7 +223,13 @@ Check the directory layout on your Gitaly server to be sure. [auth] token = 'abc123secret' + ``` + +1. Append the following to `/home/git/gitaly/config.toml` for each respective server: + + For `gitaly1.internal`: + ```toml [[storage]] name = 'default' @@ -214,6 +237,13 @@ Check the directory layout on your Gitaly server to be sure. name = 'storage1' ``` + For `gitaly2.internal`: + + ```toml + [[storage]] + name = 'storage2' + ``` + NOTE: **Note:** In some cases, you'll have to set `path` for each `[[storage]]` in the format `path = '/mnt/gitlab/<storage name>/repositories'`. @@ -231,9 +261,13 @@ then all Gitaly requests will fail. Additionally, you need to [disable Rugged if previously manually enabled](../high_availability/nfs.md#improving-nfs-performance-with-gitlab). -We assume that your Gitaly server can be reached at -`gitaly.internal:8075` from your GitLab server, and that Gitaly can read and -write to `/mnt/gitlab/default` and `/mnt/gitlab/storage1` respectively. +We assume that your `gitaly1.internal` Gitaly server can be reached at +`gitaly1.internal:8075` from your GitLab server, and that Gitaly server +can read and write to `/mnt/gitlab/default` and `/mnt/gitlab/storage1`. + +We assume also that your `gitaly2.internal` Gitaly server can be reached at +`gitaly2.internal:8075` from your GitLab server, and that Gitaly server +can read and write to `/mnt/gitlab/storage2`. **For Omnibus GitLab** @@ -241,17 +275,14 @@ write to `/mnt/gitlab/default` and `/mnt/gitlab/storage1` respectively. ```ruby git_data_dirs({ - 'default' => { 'gitaly_address' => 'tcp://gitaly.internal:8075' }, - 'storage1' => { 'gitaly_address' => 'tcp://gitaly.internal:8075' }, + 'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' }, + 'storage1' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' }, + 'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' }, }) gitlab_rails['gitaly_token'] = 'abc123secret' ``` - NOTE: **Note:** - In some cases, you'll have to set `path` for each `git_data_dirs` in the - format `'path' => '/mnt/gitlab/<storage name>'`. - 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Tail the logs to see the requests: @@ -268,17 +299,23 @@ write to `/mnt/gitlab/default` and `/mnt/gitlab/storage1` respectively. repositories: storages: default: - gitaly_address: tcp://gitaly.internal:8075 + gitaly_address: tcp://gitaly1.internal:8075 + path: /some/dummy/path storage1: - gitaly_address: tcp://gitaly.internal:8075 + gitaly_address: tcp://gitaly1.internal:8075 + path: /some/dummy/path + storage2: + gitaly_address: tcp://gitaly2.internal:8075 + path: /some/dummy/path gitaly: token: 'abc123secret' ``` NOTE: **Note:** - In some cases, you'll have to set `path` for each of the `storages` in the - format `path: /mnt/gitlab/<storage name>/repositories`. + `/some/dummy/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 + [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. Tail the logs to see the requests: @@ -350,8 +387,9 @@ To configure Gitaly with TLS: ```ruby git_data_dirs({ - 'default' => { 'gitaly_address' => 'tls://gitaly.internal:9999' }, - 'storage1' => { 'gitaly_address' => 'tls://gitaly.internal:9999' }, + 'default' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' }, + 'storage1' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' }, + 'storage2' => { 'gitaly_address' => 'tls://gitaly2.internal:9999' }, }) gitlab_rails['gitaly_token'] = 'abc123secret' @@ -377,17 +415,23 @@ To configure Gitaly with TLS: repositories: storages: default: - gitaly_address: tls://gitaly.internal:9999 + gitaly_address: tls://gitaly1.internal:9999 + path: /some/dummy/path storage1: - gitaly_address: tls://gitaly.internal:9999 + gitaly_address: tls://gitaly1.internal:9999 + path: /some/dummy/path + storage2: + gitaly_address: tls://gitaly2.internal:9999 + path: /some/dummy/path gitaly: token: 'abc123secret' ``` NOTE: **Note:** - In some cases, you'll have to set `path` for each of the `storages` in the - format `path: /mnt/gitlab/<storage name>/repositories`. + `/some/dummy/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 + [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. On the Gitaly server nodes, edit `/home/git/gitaly/config.toml`: @@ -474,6 +518,48 @@ One current feature of GitLab that still requires a shared directory (NFS) is There is [work in progress](https://gitlab.com/gitlab-org/gitlab-pages/issues/196) to eliminate the need for NFS to support GitLab Pages. +## Limiting RPC concurrency + +It can happen that CI clone traffic puts a large strain on your Gitaly +service. The bulk of the work gets done in the SSHUploadPack (for Git +SSH) and PostUploadPack (for Git HTTP) RPC's. To prevent such workloads +from overcrowding your Gitaly server you can set concurrency limits in +Gitaly's configuration file. + +```ruby +# in /etc/gitlab/gitlab.rb + +gitaly['concurrency'] = [ + { + 'rpc' => "/gitaly.SmartHTTPService/PostUploadPack", + 'max_per_repo' => 20 + }, + { + 'rpc' => "/gitaly.SSHService/SSHUploadPack", + 'max_per_repo' => 20 + } +] +``` + +This will limit the number of in-flight RPC calls for the given RPC's. +The limit is applied per repository. In the example above, each on the +Gitaly server can have at most 20 simultaneous PostUploadPack calls in +flight, and the same for SSHUploadPack. If another request comes in for +a repository that hase used up its 20 slots, that request will get +queued. + +You can observe the behavior of this queue via the Gitaly logs and via +Prometheus. In the Gitaly logs, you can look for the string (or +structured log field) `acquire_ms`. Messages that have this field are +reporting about the concurrency limiter. In Prometheus, look for the +`gitaly_rate_limiting_in_progress`, `gitaly_rate_limiting_queued` and +`gitaly_rate_limiting_seconds` metrics. + +The name of the Prometheus metric is not quite right because this is a +concurrency limiter, not a rate limiter. If a client makes 1000 requests +in a row in a very short timespan, the concurrency will not exceed 1, +and this mechanism (the concurrency limiter) will do nothing. + ## Troubleshooting Gitaly ### Commits, pushes, and clones return a 401 @@ -615,3 +701,33 @@ To fix this problem, confirm that your [`gitlab-secrets.json` file](#3-gitaly-se on the Gitaly node matches the one on all other nodes. If it doesn't match, update the secrets file on the Gitaly node to match the others, then [reconfigure the node](../restart_gitlab.md#omnibus-gitlab-reconfigure). + +### Command line tools cannot connect to Gitaly + +If you are having trouble connecting to a Gitaly node with command line (CLI) tools, and certain actions result in a `14: Connect Failed` error message, it means that gRPC cannot reach your Gitaly node. + +Verify that you can reach Gitaly via TCP: + +```bash +sudo gitlab-rake gitlab:tcp_check[GITALY_SERVER_IP,GITALY_LISTEN_PORT] +``` + +If the TCP connection fails, check your network settings and your firewall rules. If the TCP connection succeeds, your networking and firewall rules are correct. + +If you use proxy servers in your command line environment, such as Bash, these can interfere with your gRPC traffic. + +If you use Bash or a compatible command line environment, run the following commands to determine whether you have proxy servers configured: + +```bash +echo $http_proxy +echo $https_proxy +``` + +If either of these variables have a value, your Gitaly CLI connections may be getting routed through a proxy which cannot connect to Gitaly. + +To remove the proxy setting, run the following commands (depending on which variables had values): + +```bash +unset http_proxy +unset https_proxy +``` diff --git a/doc/administration/high_availability/gitlab.md b/doc/administration/high_availability/gitlab.md index 8818a9606de..0d1dd06871a 100644 --- a/doc/administration/high_availability/gitlab.md +++ b/doc/administration/high_availability/gitlab.md @@ -4,9 +4,9 @@ type: reference # Configuring GitLab for Scaling and High Availability -> **Note:** There is some additional configuration near the bottom for - additional GitLab application servers. It's important to read and understand - these additional steps before proceeding with GitLab installation. +NOTE: **Note:** There is some additional configuration near the bottom for +additional GitLab application servers. It's important to read and understand +these additional steps before proceeding with GitLab installation. 1. If necessary, install the NFS client utility packages using the following commands: @@ -82,19 +82,19 @@ type: reference 1. [Enable monitoring](#enable-monitoring) - > **Note:** To maintain uniformity of links across HA clusters, the `external_url` + NOTE: **Note:** To maintain uniformity of links across HA clusters, the `external_url` on the first application server as well as the additional application servers should point to the external url that users will use to access GitLab. In a typical HA setup, this will be the url of the load balancer which will route traffic to all GitLab application servers in the HA cluster. - > - > **Note:** When you specify `https` in the `external_url`, as in the example + + NOTE: **Note:** When you specify `https` in the `external_url`, as in the example above, GitLab assumes you have SSL certificates in `/etc/gitlab/ssl/`. If certificates are not present, Nginx will fail to start. See [Nginx documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) for more information. - > - > **Note:** It is best to set the `uid` and `gid`s prior to the initial reconfigure + + NOTE: **Note:** It is best to set the `uid` and `gid`s prior to the initial reconfigure of GitLab. Omnibus will not recursively `chown` directories if set after the initial reconfigure. ## First GitLab application server @@ -105,8 +105,8 @@ Do not run this on additional application servers. 1. Initialize the database by running `sudo gitlab-rake gitlab:setup`. 1. Run `sudo gitlab-ctl reconfigure` to compile the configuration. -> **WARNING:** Only run this setup task on **NEW** GitLab instances because it - will wipe any existing data. + CAUTION: **WARNING:** Only run this setup task on **NEW** GitLab instances because it + will wipe any existing data. ## Extra configuration for additional GitLab application servers @@ -173,9 +173,10 @@ If you enable Monitoring, it must be enabled on **all** GitLab servers. 1. Run `sudo gitlab-ctl reconfigure` to compile the configuration. -> **Warning:** After changing `unicorn['listen']` in `gitlab.rb`, and running `sudo gitlab-ctl reconfigure`, - it can take an extended period of time for unicorn to complete reloading after receiving a `HUP`. - For more information, see the [issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/4401). + CAUTION: **Warning:** + After changing `unicorn['listen']` in `gitlab.rb`, and running `sudo gitlab-ctl reconfigure`, + it can take an extended period of time for unicorn to complete reloading after receiving a `HUP`. + For more information, see the [issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/4401). ## Troubleshooting diff --git a/doc/administration/high_availability/load_balancer.md b/doc/administration/high_availability/load_balancer.md index 9e9f604317a..f11d27487d1 100644 --- a/doc/administration/high_availability/load_balancer.md +++ b/doc/administration/high_availability/load_balancer.md @@ -60,11 +60,21 @@ for details on managing SSL certificates and configuring Nginx. ### Basic ports -| LB Port | Backend Port | Protocol | -| ------- | ------------ | --------------- | -| 80 | 80 | HTTP [^1] | -| 443 | 443 | TCP or HTTPS [^1] [^2] | -| 22 | 22 | TCP | +| LB Port | Backend Port | Protocol | +| ------- | ------------ | ------------------------ | +| 80 | 80 | HTTP (*1*) | +| 443 | 443 | TCP or HTTPS (*1*) (*2*) | +| 22 | 22 | TCP | + +- (*1*): [Web terminal](../../ci/environments.md#web-terminals) support requires + your load balancer to correctly handle WebSocket connections. When using + HTTP or HTTPS proxying, this means your load balancer must be configured + 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 + certificate to the load balancers. If you wish to terminate SSL at the + GitLab application server instead, use TCP protocol. ### GitLab Pages Ports @@ -72,12 +82,19 @@ If you're using GitLab Pages with custom domain support you will 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 -[GitLab Pages documentation][gitlab-pages] for more information. +[GitLab Pages documentation](../pages/index.md) for more information. -| LB Port | Backend Port | Protocol | -| ------- | ------------ | -------- | -| 80 | Varies [^3] | HTTP | -| 443 | Varies [^3] | TCP [^4] | +| LB Port | Backend Port | Protocol | +| ------- | ------------- | --------- | +| 80 | Varies (*1*) | HTTP | +| 443 | Varies (*1*) | TCP (*2*) | + +- (*1*): The backend port for GitLab Pages depends on the + `gitlab_pages['external_http']` and `gitlab_pages['external_https']` + setting. See [GitLab Pages documentation](../pages/index.md) for more details. +- (*2*): Port 443 for GitLab Pages should always use the TCP protocol. Users can + configure custom domains with custom SSL, which would not be possible + if SSL was terminated at the load balancer. ### Alternate SSH Port @@ -86,7 +103,7 @@ 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 compared to the other GitLab HTTP configuration above. -Configure DNS for an alternate SSH hostname such as altssh.gitlab.example.com. +Configure DNS for an alternate SSH hostname such as `altssh.gitlab.example.com`. | LB Port | Backend Port | Protocol | | ------- | ------------ | -------- | @@ -101,24 +118,6 @@ Read more on high-availability configuration: 1. [Configure NFS](nfs.md) 1. [Configure the GitLab application servers](gitlab.md) -[^1]: [Web terminal](../../ci/environments.md#web-terminals) support requires - your load balancer to correctly handle WebSocket connections. When using - HTTP or HTTPS proxying, this means your load balancer must be configured - 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 - certificate to the load balancers. If you wish to terminate SSL at the - GitLab application server instead, use TCP protocol. -[^3]: The backend port for GitLab Pages depends on the - `gitlab_pages['external_http']` and `gitlab_pages['external_https']` - setting. See [GitLab Pages documentation][gitlab-pages] for more details. -[^4]: Port 443 for GitLab Pages should always use the TCP protocol. Users can - configure custom domains with custom SSL, which would not be possible - if SSL was terminated at the load balancer. - -[gitlab-pages]: ../pages/index.md - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 73a39a6dd35..29915cb3a99 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -151,7 +151,7 @@ Reply by email should now be working. #### Postfix -Example configuration for Postfix mail server. Assumes mailbox incoming@gitlab.example.com. +Example configuration for Postfix mail server. Assumes mailbox `incoming@gitlab.example.com`. Example for Omnibus installs: @@ -218,7 +218,7 @@ incoming_email: #### Gmail -Example configuration for Gmail/G Suite. Assumes mailbox gitlab-incoming@gmail.com. +Example configuration for Gmail/G Suite. Assumes mailbox `gitlab-incoming@gmail.com`. Example for Omnibus installs: diff --git a/doc/administration/index.md b/doc/administration/index.md index 2b25e8efd23..650cb10a64a 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -64,6 +64,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [External Classification Policy Authorization](../user/admin_area/settings/external_authorization.md) **(PREMIUM ONLY)** - [Upload a license](../user/admin_area/license.md): Upload a license to unlock features that are in paid tiers of GitLab. **(STARTER ONLY)** - [Admin Area](../user/admin_area/index.md): for self-managed instance-wide configuration and maintenance. +- [S/MIME Signing](smime_signing_email.md): how to sign all outgoing notification emails with S/MIME #### Customizing GitLab's appearance @@ -192,6 +193,6 @@ Learn how to install, configure, update, and maintain your GitLab instance. for troubleshooting Kubernetes-related issues. - Useful links from the Support Team: - [GitLab Developer Docs](https://docs.gitlab.com/ee/development/README.html). - - [Repairing and recovering broken git repositories](https://git.seveas.net/repairing-and-recovering-broken-git-repositories.html). + - [Repairing and recovering broken Git repositories](https://git.seveas.net/repairing-and-recovering-broken-git-repositories.html). - [Testing with OpenSSL](https://www.feistyduck.com/library/openssl-cookbook/online/ch-testing-with-openssl.html). - [Strace zine](https://wizardzines.com/zines/strace/). diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md index ab6a4646a71..825435deff9 100644 --- a/doc/administration/instance_review.md +++ b/doc/administration/instance_review.md @@ -14,4 +14,3 @@ Additionally you will be contacted by our team for further review which should h [6995]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6995 [ee]: https://about.gitlab.com/pricing/ - diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index 16a193550a1..df6c554decb 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -1,7 +1,6 @@ # PlantUML & GitLab -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8537) in -> GitLab 8.16. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8537) in GitLab 8.16. When [PlantUML](http://plantuml.com) integration is enabled and configured in GitLab we are able to create simple diagrams in AsciiDoc and Markdown documents diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md index e1bbabb2878..f9be06c6daf 100644 --- a/doc/administration/issue_closing_pattern.md +++ b/doc/administration/issue_closing_pattern.md @@ -1,8 +1,8 @@ # Issue closing pattern **(CORE ONLY)** >**Note:** -This is the administration documentation. -There is a separate [user documentation] on issue closing pattern. +This is the administration documentation. There is a separate [user documentation](../user/project/issues/managing_issues.md#closing-issues-automatically) +on issue closing pattern. When a commit or merge request resolves one or more issues, it is possible to automatically have these issues closed when the commit or merge request lands @@ -13,8 +13,8 @@ in the project's default branch. In order to change the pattern you need to have access to the server that GitLab is installed on. -The default pattern can be located in [gitlab.yml.example] under the -"Automatic issue closing" section. +The default pattern can be located in [`gitlab.yml.example`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example) +under the "Automatic issue closing" section. > **Tip:** You are advised to use <http://rubular.com> to test the issue closing pattern. @@ -31,7 +31,7 @@ Because Rubular doesn't understand `%{issue_ref}`, you can replace this by gitlab_rails['gitlab_issue_closing_pattern'] = "\b((?:[Cc]los(?:e[sd]|ing)|\b[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)" ``` -1. [Reconfigure] GitLab for the changes to take effect. +1. [Reconfigure](restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect. **For installations from source** @@ -42,9 +42,4 @@ Because Rubular doesn't understand `%{issue_ref}`, you can replace this by issue_closing_pattern: "\b((?:[Cc]los(?:e[sd]|ing)|\b[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)" ``` -1. [Restart] GitLab for the changes to take effect. - -[gitlab.yml.example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example -[reconfigure]: restart_gitlab.md#omnibus-gitlab-reconfigure -[restart]: restart_gitlab.md#installations-from-source -[user documentation]: ../user/project/issues/managing_issues.md#closing-issues-automatically +1. [Restart](restart_gitlab.md#installations-from-source) GitLab for the changes to take effect. diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 2b624f8de77..350cd5b7992 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -94,7 +94,7 @@ If you're enabling S3 in [GitLab HA](high_availability/README.md), you will need ### Object Storage Settings -For source installations the following settings are nested under `artifacts:` and then `object_store:`. On omnibus installs they are prefixed by `artifacts_object_store_`. +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 | |---------|-------------|---------| @@ -115,7 +115,7 @@ The connection settings match those provided by [Fog](https://github.com/fog), a | `aws_access_key_id` | AWS credentials, or compatible | | | `aws_secret_access_key` | AWS credentials, or compatible | | | `aws_signature_version` | AWS signature version to use. 2 or 4 are valid options. Digital Ocean Spaces and other providers may need 2. | 4 | -| `enable_signature_v4_streaming` | Set to true to enable HTTP chunked transfers with AWS v4 signatures (https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html). Oracle Cloud S3 needs this to be false | true +| `enable_signature_v4_streaming` | Set to true to enable HTTP chunked transfers with [AWS v4 signatures](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html). Oracle Cloud S3 needs this to be false | true | | `region` | AWS region | us-east-1 | | `host` | S3 compatible host for when not using AWS, e.g. `localhost` or `storage.example.com` | s3.amazonaws.com | | `endpoint` | Can be used when configuring an S3 compatible service such as [Minio](https://www.minio.io), by entering a URL such as `http://127.0.0.1:9000` | (optional) | diff --git a/doc/administration/logs.md b/doc/administration/logs.md index 306d611f6bf..9b1efb610f8 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -88,7 +88,7 @@ Introduced in GitLab 10.0, this file lives in It helps you see requests made directly to the API. For example: ```json -{"time":"2018-10-29T12:49:42.123Z","severity":"INFO","duration":709.08,"db":14.59,"view":694.49,"status":200,"method":"GET","path":"/api/v4/projects","params":[{"key":"action","value":"git-upload-pack"},{"key":"changes","value":"_any"},{"key":"key_id","value":"secret"},{"key":"secret_token","value":"[FILTERED]"}],"host":"localhost","ip":"::1","ua":"Ruby","route":"/api/:version/projects","user_id":1,"username":"root","queue_duration":100.31,"gitaly_calls":30,"gitaly_duration":5.36} +{"time":"2018-10-29T12:49:42.123Z","severity":"INFO","duration":709.08,"db":14.59,"view":694.49,"status":200,"method":"GET","path":"/api/v4/projects","params":[{"key":"action","value":"git-upload-pack"},{"key":"changes","value":"_any"},{"key":"key_id","value":"secret"},{"key":"secret_token","value":"[FILTERED]"}],"host":"localhost","remote_ip":"::1","ua":"Ruby","route":"/api/:version/projects","user_id":1,"username":"root","queue_duration":100.31,"gitaly_calls":30,"gitaly_duration":5.36} ``` This entry above shows an access to an internal endpoint to check whether an @@ -284,13 +284,16 @@ Introduced in GitLab 11.3. This file lives in `/var/log/gitlab/gitlab-rails/impo Omnibus GitLab packages or in `/home/git/gitlab/log/importer.log` for installations from source. -## `auth.log` +## `auth.log` Introduced in GitLab 12.0. This file lives in `/var/log/gitlab/gitlab-rails/auth.log` for Omnibus GitLab packages or in `/home/git/gitlab/log/auth.log` for installations from source. -It logs information whenever [Rack Attack] registers an abusive request. +This log records: + +- Information whenever [Rack Attack] registers an abusive request. +- Requests over the [Rate Limit] on raw endpoints. NOTE: **Note:** From [%12.1](https://gitlab.com/gitlab-org/gitlab-ce/issues/62756), user id and username are available on this log. @@ -334,3 +337,13 @@ installations from source. [repocheck]: repository_checks.md [Rack Attack]: ../security/rack_attack.md +[Rate Limit]: ../user/admin_area/settings/rate_limits_on_raw_endpoints.md + +## `database_load_balancing.log` + +Introduced in GitLab 12.3 for observability of [Database Load +Balancing](https://docs.gitlab.com/ee/administration/database_load_balancing.html) +when enabled. This file lives in +`/var/log/gitlab/gitlab-rails/database_load_balancing.log` for Omnibus GitLab +packages or in `/home/git/gitlab/log/database_load_balancing.log` for +installations from source. diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md index 0b065082ded..d52d865cec5 100644 --- a/doc/administration/merge_request_diffs.md +++ b/doc/administration/merge_request_diffs.md @@ -90,7 +90,7 @@ The connection settings match those provided by [Fog](https://github.com/fog), a | `aws_access_key_id` | AWS credentials, or compatible | | | `aws_secret_access_key` | AWS credentials, or compatible | | | `aws_signature_version` | AWS signature version to use. 2 or 4 are valid options. Digital Ocean Spaces and other providers may need 2. | 4 | -| `enable_signature_v4_streaming` | Set to true to enable HTTP chunked transfers with AWS v4 signatures (https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html). Oracle Cloud S3 needs this to be false | true +| `enable_signature_v4_streaming` | Set to true to enable HTTP chunked transfers with [AWS v4 signatures](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html). Oracle Cloud S3 needs this to be false | true | | `region` | AWS region | us-east-1 | | `host` | S3 compatible host for when not using AWS, e.g. `localhost` or `storage.example.com` | s3.amazonaws.com | | `endpoint` | Can be used when configuring an S3 compatible service such as [Minio](https://www.minio.io), by entering a URL such as `http://127.0.0.1:9000` | (optional) | diff --git a/doc/administration/monitoring/gitlab_instance_administration_project/index.md b/doc/administration/monitoring/gitlab_instance_administration_project/index.md index 8e33cea6217..d445b68721d 100644 --- a/doc/administration/monitoring/gitlab_instance_administration_project/index.md +++ b/doc/administration/monitoring/gitlab_instance_administration_project/index.md @@ -27,7 +27,7 @@ If that's not the case or if you have an external Prometheus instance or an HA s you should [configure it manually](../../../user/project/integrations/prometheus.md#manual-configuration-of-prometheus). -## Taking action on Prometheus alerts **[ULTIMATE]** +## Taking action on Prometheus alerts **(ULTIMATE)** You can [add a webhook](../../../user/project/integrations/prometheus.md#external-prometheus-instances) to the Prometheus config in order for GitLab to receive notifications of any alerts. diff --git a/doc/administration/monitoring/performance/request_profiling.md b/doc/administration/monitoring/performance/request_profiling.md index 9f671e0db11..c32edb60f9d 100644 --- a/doc/administration/monitoring/performance/request_profiling.md +++ b/doc/administration/monitoring/performance/request_profiling.md @@ -5,7 +5,7 @@ 1. Grab the profiling token from **Monitoring > Requests Profiles** admin page (highlighted in a blue in the image below).  -1. Pass the header `X-Profile-Token: <token>` and `X-Profile-Mode: <mode>`(where <mode> can be `execution` or `memory`) to the request you want to profile. You can use: +1. Pass the header `X-Profile-Token: <token>` and `X-Profile-Mode: <mode>`(where `<mode>` can be `execution` or `memory`) to the request you want to profile. You can use: - Browser extensions. For example, [ModHeader](https://chrome.google.com/webstore/detail/modheader/idgpnmonknjnojddfkpgkljpfnnfcklj) Chrome extension. - `curl`. For example, `curl --header 'X-Profile-Token: <token>' --header 'X-Profile-Mode: <mode>' https://gitlab.example.com/group/project`. 1. Once request is finished (which will take a little longer than usual), you can diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index ec26c0b2e7e..ca48326c6d0 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -1,7 +1,7 @@ # GitLab Prometheus metrics >**Note:** -Available since [Omnibus GitLab 9.3][29118]. For +Available since [Omnibus GitLab 9.3](https://gitlab.com/gitlab-org/gitlab-ce/issues/29118). For installations from source you'll have to configure it yourself. To enable the GitLab Prometheus metrics: @@ -9,125 +9,211 @@ To enable the GitLab Prometheus metrics: 1. Log into GitLab as an administrator, and go to the Admin area. 1. Click on the gear, then click on Settings. 1. Find the `Metrics - Prometheus` section, and click `Enable Prometheus Metrics` -1. [Restart GitLab][restart] for the changes to take effect +1. [Restart GitLab](../../restart_gitlab.md#omnibus-gitlab-restart) for the changes to take effect ## Collecting the metrics GitLab monitors its own internal service metrics, and makes them available at the -`/-/metrics` endpoint. Unlike other [Prometheus] exporters, in order to access -it, the client IP needs to be [included in a whitelist][whitelist]. +`/-/metrics` endpoint. Unlike other [Prometheus](https://prometheus.io) exporters, in order to access +it, the client IP needs to be [included in a whitelist](../ip_whitelist.md). For Omnibus and Chart installations, these metrics are automatically enabled and collected as of [GitLab 9.4](https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/1702). For source installations or earlier versions, these metrics will need to be enabled manually and collected by a Prometheus server. -## Unicorn Metrics available +## Metrics available The following metrics are available: -| Metric | Type | Since | Description | -|:--------------------------------- |:--------- |:----- |:----------- | -| db_ping_timeout | Gauge | 9.4 | Whether or not the last database ping timed out | -| db_ping_success | Gauge | 9.4 | Whether or not the last database ping succeeded | -| db_ping_latency_seconds | Gauge | 9.4 | Round trip time of the database ping | -| filesystem_access_latency_seconds | Gauge | 9.4 | Latency in accessing a specific filesystem | -| filesystem_accessible | Gauge | 9.4 | Whether or not a specific filesystem is accessible | -| filesystem_write_latency_seconds | Gauge | 9.4 | Write latency of a specific filesystem | -| filesystem_writable | Gauge | 9.4 | Whether or not the filesystem is writable | -| filesystem_read_latency_seconds | Gauge | 9.4 | Read latency of a specific filesystem | -| filesystem_readable | Gauge | 9.4 | Whether or not the filesystem is readable | -| gitlab_cache_misses_total | Counter | 10.2 | Cache read miss | -| gitlab_cache_operation_duration_seconds | Histogram | 10.2 | Cache access time | -| gitlab_cache_operations_total | Counter | 12.2 | Cache operations by controller/action | -| http_requests_total | Counter | 9.4 | Rack request count | -| http_request_duration_seconds | Histogram | 9.4 | HTTP response time from rack middleware | -| pipelines_created_total | Counter | 9.4 | Counter of pipelines created | -| rack_uncaught_errors_total | Counter | 9.4 | Rack connections handling uncaught errors count | -| redis_ping_timeout | Gauge | 9.4 | Whether or not the last redis ping timed out | -| redis_ping_success | Gauge | 9.4 | Whether or not the last redis ping succeeded | -| redis_ping_latency_seconds | Gauge | 9.4 | Round trip time of the redis ping | -| user_session_logins_total | Counter | 9.4 | Counter of how many users have logged in | -| upload_file_does_not_exist | Counter | 10.7 in EE, 11.5 in CE | Number of times an upload record could not find its file | -| failed_login_captcha_total | Gauge | 11.0 | Counter of failed CAPTCHA attempts during login | -| successful_login_captcha_total | Gauge | 11.0 | Counter of successful CAPTCHA attempts during login | -| unicorn_active_connections | Gauge | 11.0 | The number of active Unicorn connections (workers) | -| unicorn_queued_connections | Gauge | 11.0 | The number of queued Unicorn connections | -| unicorn_workers | Gauge | 12.0 | The number of Unicorn workers | +| Metric | Type | Since | Description | Labels | +|:---------------------------------------------------------------|:----------|-----------------------:|:----------------------------------------------------------------------------------------------------|:----------------------------------------------------| +| `gitlab_banzai_cached_render_real_duration_seconds` | Histogram | 9.4 | Duration of rendering markdown into HTML when cached output exists | controller, action | +| `gitlab_banzai_cacheless_render_real_duration_seconds` | Histogram | 9.4 | Duration of rendering markdown into HTML when cached outupt does not exist | controller, action | +| `gitlab_cache_misses_total` | Counter | 10.2 | Cache read miss | controller, action | +| `gitlab_cache_operation_duration_seconds` | Histogram | 10.2 | Cache access time | | +| `gitlab_cache_operations_total` | Counter | 12.2 | Cache operations by controller/action | controller, action, operation | +| `gitlab_database_transaction_seconds` | Histogram | 12.1 | Time spent in database transactions, in seconds | | +| `gitlab_method_call_duration_seconds` | Histogram | 10.2 | Method calls real duration | controller, action, module, method | +| `gitlab_rails_queue_duration_seconds` | Histogram | 9.4 | Measures latency between GitLab Workhorse forwarding a request to Rails | | +| `gitlab_sql_duration_seconds` | Histogram | 10.2 | SQL execution time, excluding SCHEMA operations and BEGIN / COMMIT | | +| `gitlab_transaction_allocated_memory_bytes` | Histogram | 10.2 | Allocated memory for all transactions (gitlab_transaction_* metrics) | | +| `gitlab_transaction_cache_<key>_count_total` | Counter | 10.2 | Counter for total Rails cache calls (per key) | | +| `gitlab_transaction_cache_<key>_duration_total` | Counter | 10.2 | Counter for total time (seconds) spent in Rails cache calls (per key) | | +| `gitlab_transaction_cache_count_total` | Counter | 10.2 | Counter for total Rails cache calls (aggregate) | | +| `gitlab_transaction_cache_duration_total` | Counter | 10.2 | Counter for total time (seconds) spent in Rails cache calls (aggregate) | | +| `gitlab_transaction_cache_read_hit_count_total` | Counter | 10.2 | Counter for cache hits for Rails cache calls | controller, action | +| `gitlab_transaction_cache_read_miss_count_total` | Counter | 10.2 | Counter for cache misses for Rails cache calls | controller, action | +| `gitlab_transaction_duration_seconds` | Histogram | 10.2 | Duration for all transactions (gitlab_transaction_* metrics) | controller, action | +| `gitlab_transaction_event_build_found_total` | Counter | 9.4 | Counter for build found for api /jobs/request | | +| `gitlab_transaction_event_build_invalid_total` | Counter | 9.4 | Counter for build invalid due to concurrency conflict for api /jobs/request | | +| `gitlab_transaction_event_build_not_found_cached_total` | Counter | 9.4 | Counter for cached response of build not found for api /jobs/request | | +| `gitlab_transaction_event_build_not_found_total` | Counter | 9.4 | Counter for build not found for api /jobs/request | | +| `gitlab_transaction_event_change_default_branch_total` | Counter | 9.4 | Counter when default branch is changed for any repository | | +| `gitlab_transaction_event_create_repository_total` | Counter | 9.4 | Counter when any repository is created | | +| `gitlab_transaction_event_etag_caching_cache_hit_total` | Counter | 9.4 | Counter for etag cache hit. | endpoint | +| `gitlab_transaction_event_etag_caching_header_missing_total` | Counter | 9.4 | Counter for etag cache miss - header missing | endpoint | +| `gitlab_transaction_event_etag_caching_key_not_found_total` | Counter | 9.4 | Counter for etag cache miss - key not found | endpoint | +| `gitlab_transaction_event_etag_caching_middleware_used_total` | Counter | 9.4 | Counter for etag middleware accessed | endpoint | +| `gitlab_transaction_event_etag_caching_resource_changed_total` | Counter | 9.4 | Counter for etag cache miss - resource changed | endpoint | +| `gitlab_transaction_event_fork_repository_total` | Counter | 9.4 | Counter for repository forks (RepositoryForkWorker). Only incremented when source repository exists | | +| `gitlab_transaction_event_import_repository_total` | Counter | 9.4 | Counter for repository imports (RepositoryImportWorker) | | +| `gitlab_transaction_event_push_branch_total` | Counter | 9.4 | Counter for all branch pushes | | +| `gitlab_transaction_event_push_commit_total` | Counter | 9.4 | Counter for commits | branch | +| `gitlab_transaction_event_push_tag_total` | Counter | 9.4 | Counter for tag pushes | | +| `gitlab_transaction_event_rails_exception_total` | Counter | 9.4 | Counter for number of rails exceptions | | +| `gitlab_transaction_event_receive_email_total` | Counter | 9.4 | Counter for recieved emails | handler | +| `gitlab_transaction_event_remote_mirrors_failed_total` | Counter | 10.8 | Counter for failed remote mirrors | | +| `gitlab_transaction_event_remote_mirrors_finished_total` | Counter | 10.8 | Counter for finished remote mirrors | | +| `gitlab_transaction_event_remote_mirrors_running_total` | Counter | 10.8 | Counter for running remote mirrors | | +| `gitlab_transaction_event_remove_branch_total` | Counter | 9.4 | Counter when a branch is removed for any repository | | +| `gitlab_transaction_event_remove_repository_total` | Counter | 9.4 | Counter when a repository is removed | | +| `gitlab_transaction_event_remove_tag_total` | Counter | 9.4 | Counter when a tag is remove for any repository | | +| `gitlab_transaction_event_sidekiq_exception_total` | Counter | 9.4 | Counter of sidekiq exceptions | | +| `gitlab_transaction_event_stuck_import_jobs_total` | Counter | 9.4 | Count of stuck import jobs | projects_without_jid_count, projects_with_jid_count | +| `gitlab_transaction_event_update_build_total` | Counter | 9.4 | Counter for update build for api /jobs/request/:id | | +| `gitlab_transaction_new_redis_connections_total` | Counter | 9.4 | Counter for new redis connections | | +| `gitlab_transaction_queue_duration_total` | Counter | 9.4 | Duration jobs were enqueued before processing | | +| `gitlab_transaction_rails_queue_duration_total` | Counter | 9.4 | Measures latency between GitLab Workhorse forwarding a request to Rails | controller, action | +| `gitlab_transaction_view_duration_total` | Counter | 9.4 | Duration for views | controller, action, view | +| `gitlab_view_rendering_duration_seconds` | Histogram | 10.2 | Duration for views (histogram) | controller, action, view | +| `http_requests_total` | Counter | 9.4 | Rack request count | method | +| `http_request_duration_seconds` | Histogram | 9.4 | HTTP response time from rack middleware | method, status | +| `pipelines_created_total` | Counter | 9.4 | Counter of pipelines created | | +| `rack_uncaught_errors_total` | Counter | 9.4 | Rack connections handling uncaught errors count | | +| `user_session_logins_total` | Counter | 9.4 | Counter of how many users have logged in | | +| `upload_file_does_not_exist` | Counter | 10.7 in EE, 11.5 in CE | Number of times an upload record could not find its file | | +| `failed_login_captcha_total` | Gauge | 11.0 | Counter of failed CAPTCHA attempts during login | | +| `successful_login_captcha_total` | Gauge | 11.0 | Counter of successful CAPTCHA attempts during login | | + +## Metrics controlled by a feature flag + +The following metrics can be controlled by feature flags: + +| Metric | Feature Flag | +|:---------------------------------------------------------------|:-------------------------------------------------------------------| +| `gitlab_method_call_duration_seconds` | `prometheus_metrics_method_instrumentation` | +| `gitlab_transaction_allocated_memory_bytes` | `prometheus_metrics_transaction_allocated_memory` | +| `gitlab_transaction_event_build_found_total` | `prometheus_transaction_event_build_found_total` | +| `gitlab_transaction_event_build_invalid_total` | `prometheus_transaction_event_build_invalid_total` | +| `gitlab_transaction_event_build_not_found_cached_total` | `prometheus_transaction_event_build_not_found_cached_total` | +| `gitlab_transaction_event_build_not_found_total` | `prometheus_transaction_event_build_not_found_total` | +| `gitlab_transaction_event_change_default_branch_total` | `prometheus_transaction_event_change_default_branch_total` | +| `gitlab_transaction_event_create_repository_total` | `prometheus_transaction_event_create_repository_total` | +| `gitlab_transaction_event_etag_caching_cache_hit_total` | `prometheus_transaction_event_etag_caching_cache_hit_total` | +| `gitlab_transaction_event_etag_caching_header_missing_total` | `prometheus_transaction_event_etag_caching_header_missing_total` | +| `gitlab_transaction_event_etag_caching_key_not_found_total` | `prometheus_transaction_event_etag_caching_key_not_found_total` | +| `gitlab_transaction_event_etag_caching_middleware_used_total` | `prometheus_transaction_event_etag_caching_middleware_used_total` | +| `gitlab_transaction_event_etag_caching_resource_changed_total` | `prometheus_transaction_event_etag_caching_resource_changed_total` | +| `gitlab_transaction_event_fork_repository_total` | `prometheus_transaction_event_fork_repository_total` | +| `gitlab_transaction_event_import_repository_total` | `prometheus_transaction_event_import_repository_total` | +| `gitlab_transaction_event_push_branch_total` | `prometheus_transaction_event_push_branch_total` | +| `gitlab_transaction_event_push_commit_total` | `prometheus_transaction_event_push_commit_total` | +| `gitlab_transaction_event_push_tag_total` | `prometheus_transaction_event_push_tag_total` | +| `gitlab_transaction_event_rails_exception_total` | `prometheus_transaction_event_rails_exception_total` | +| `gitlab_transaction_event_receive_email_total` | `prometheus_transaction_event_receive_email_total` | +| `gitlab_transaction_event_remote_mirrors_failed_total` | `prometheus_transaction_event_remote_mirrors_failed_total` | +| `gitlab_transaction_event_remote_mirrors_finished_total` | `prometheus_transaction_event_remote_mirrors_finished_total` | +| `gitlab_transaction_event_remote_mirrors_running_total` | `prometheus_transaction_event_remote_mirrors_running_total` | +| `gitlab_transaction_event_remove_branch_total` | `prometheus_transaction_event_remove_branch_total` | +| `gitlab_transaction_event_remove_repository_total` | `prometheus_transaction_event_remove_repository_total` | +| `gitlab_transaction_event_remove_tag_total` | `prometheus_transaction_event_remove_tag_total` | +| `gitlab_transaction_event_sidekiq_exception_total` | `prometheus_transaction_event_sidekiq_exception_total` | +| `gitlab_transaction_event_stuck_import_jobs_total` | `prometheus_transaction_event_stuck_import_jobs_total` | +| `gitlab_transaction_event_update_build_total` | `prometheus_transaction_event_update_build_total` | +| `gitlab_view_rendering_duration_seconds` | `prometheus_metrics_view_instrumentation` | ## Sidekiq Metrics available for Geo **(PREMIUM)** Sidekiq jobs may also gather metrics, and these metrics can be accessed if the Sidekiq exporter is enabled (e.g. via the `monitoring.sidekiq_exporter` configuration option in `gitlab.yml`. -| Metric | Type | Since | Description | Labels | -|:-------------------------------------------- |:------- |:----- |:----------- |:------ | -| geo_db_replication_lag_seconds | Gauge | 10.2 | Database replication lag (seconds) | url -| geo_repositories | Gauge | 10.2 | Total number of repositories available on primary | url -| geo_repositories_synced | Gauge | 10.2 | Number of repositories synced on secondary | url -| geo_repositories_failed | Gauge | 10.2 | Number of repositories failed to sync on secondary | url -| geo_lfs_objects | Gauge | 10.2 | Total number of LFS objects available on primary | url -| geo_lfs_objects_synced | Gauge | 10.2 | Number of LFS objects synced on secondary | url -| geo_lfs_objects_failed | Gauge | 10.2 | Number of LFS objects failed to sync on secondary | url -| geo_attachments | Gauge | 10.2 | Total number of file attachments available on primary | url -| geo_attachments_synced | Gauge | 10.2 | Number of attachments synced on secondary | url -| geo_attachments_failed | Gauge | 10.2 | Number of attachments failed to sync on secondary | url -| geo_last_event_id | Gauge | 10.2 | Database ID of the latest event log entry on the primary | url -| geo_last_event_timestamp | Gauge | 10.2 | UNIX timestamp of the latest event log entry on the primary | url -| geo_cursor_last_event_id | Gauge | 10.2 | Last database ID of the event log processed by the secondary | url -| geo_cursor_last_event_timestamp | Gauge | 10.2 | Last UNIX timestamp of the event log processed by the secondary | url -| geo_status_failed_total | Counter | 10.2 | Number of times retrieving the status from the Geo Node failed | url -| geo_last_successful_status_check_timestamp | Gauge | 10.2 | Last timestamp when the status was successfully updated | url -| geo_lfs_objects_synced_missing_on_primary | Gauge | 10.7 | Number of LFS objects marked as synced due to the file missing on the primary | url -| geo_job_artifacts_synced_missing_on_primary | Gauge | 10.7 | Number of job artifacts marked as synced due to the file missing on the primary | url -| geo_attachments_synced_missing_on_primary | Gauge | 10.7 | Number of attachments marked as synced due to the file missing on the primary | url -| geo_repositories_checksummed_count | Gauge | 10.7 | Number of repositories checksummed on primary | url -| geo_repositories_checksum_failed_count | Gauge | 10.7 | Number of repositories failed to calculate the checksum on primary | url -| geo_wikis_checksummed_count | Gauge | 10.7 | Number of wikis checksummed on primary | url -| geo_wikis_checksum_failed_count | Gauge | 10.7 | Number of wikis failed to calculate the checksum on primary | url -| geo_repositories_verified_count | Gauge | 10.7 | Number of repositories verified on secondary | url -| geo_repositories_verification_failed_count | Gauge | 10.7 | Number of repositories failed to verify on secondary | url -| geo_repositories_checksum_mismatch_count | Gauge | 10.7 | Number of repositories that checksum mismatch on secondary | url -| geo_wikis_verified_count | Gauge | 10.7 | Number of wikis verified on secondary | url -| geo_wikis_verification_failed_count | Gauge | 10.7 | Number of wikis failed to verify on secondary | url -| geo_wikis_checksum_mismatch_count | Gauge | 10.7 | Number of wikis that checksum mismatch on secondary | url -| geo_repositories_checked_count | Gauge | 11.1 | Number of repositories that have been checked via `git fsck` | url -| geo_repositories_checked_failed_count | Gauge | 11.1 | Number of repositories that have a failure from `git fsck` | url -| geo_repositories_retrying_verification_count | Gauge | 11.2 | Number of repositories verification failures that Geo is actively trying to correct on secondary | url -| geo_wikis_retrying_verification_count | Gauge | 11.2 | Number of wikis verification failures that Geo is actively trying to correct on secondary | url - -### Ruby metrics +| Metric | Type | Since | Description | Labels | +|:---------------------------------------------- |:------- |:----- |:----------- |:------ | +| `geo_db_replication_lag_seconds` | Gauge | 10.2 | Database replication lag (seconds) | url | +| `geo_repositories` | Gauge | 10.2 | Total number of repositories available on primary | url | +| `geo_repositories_synced` | Gauge | 10.2 | Number of repositories synced on secondary | url | +| `geo_repositories_failed` | Gauge | 10.2 | Number of repositories failed to sync on secondary | url | +| `geo_lfs_objects` | Gauge | 10.2 | Total number of LFS objects available on primary | url | +| `geo_lfs_objects_synced` | Gauge | 10.2 | Number of LFS objects synced on secondary | url | +| `geo_lfs_objects_failed` | Gauge | 10.2 | Number of LFS objects failed to sync on secondary | url | +| `geo_attachments` | Gauge | 10.2 | Total number of file attachments available on primary | url | +| `geo_attachments_synced` | Gauge | 10.2 | Number of attachments synced on secondary | url | +| `geo_attachments_failed` | Gauge | 10.2 | Number of attachments failed to sync on secondary | url | +| `geo_last_event_id` | Gauge | 10.2 | Database ID of the latest event log entry on the primary | url | +| `geo_last_event_timestamp` | Gauge | 10.2 | UNIX timestamp of the latest event log entry on the primary | url | +| `geo_cursor_last_event_id` | Gauge | 10.2 | Last database ID of the event log processed by the secondary | url | +| `geo_cursor_last_event_timestamp` | Gauge | 10.2 | Last UNIX timestamp of the event log processed by the secondary | url | +| `geo_status_failed_total` | Counter | 10.2 | Number of times retrieving the status from the Geo Node failed | url | +| `geo_last_successful_status_check_timestamp` | Gauge | 10.2 | Last timestamp when the status was successfully updated | url | +| `geo_lfs_objects_synced_missing_on_primary` | Gauge | 10.7 | Number of LFS objects marked as synced due to the file missing on the primary | url | +| `geo_job_artifacts_synced_missing_on_primary` | Gauge | 10.7 | Number of job artifacts marked as synced due to the file missing on the primary | url | +| `geo_attachments_synced_missing_on_primary` | Gauge | 10.7 | Number of attachments marked as synced due to the file missing on the primary | url | +| `geo_repositories_checksummed_count` | Gauge | 10.7 | Number of repositories checksummed on primary | url | +| `geo_repositories_checksum_failed_count` | Gauge | 10.7 | Number of repositories failed to calculate the checksum on primary | url | +| `geo_wikis_checksummed_count` | Gauge | 10.7 | Number of wikis checksummed on primary | url | +| `geo_wikis_checksum_failed_count` | Gauge | 10.7 | Number of wikis failed to calculate the checksum on primary | url | +| `geo_repositories_verified_count` | Gauge | 10.7 | Number of repositories verified on secondary | url | +| `geo_repositories_verification_failed_count` | Gauge | 10.7 | Number of repositories failed to verify on secondary | url | +| `geo_repositories_checksum_mismatch_count` | Gauge | 10.7 | Number of repositories that checksum mismatch on secondary | url | +| `geo_wikis_verified_count` | Gauge | 10.7 | Number of wikis verified on secondary | url | +| `geo_wikis_verification_failed_count` | Gauge | 10.7 | Number of wikis failed to verify on secondary | url | +| `geo_wikis_checksum_mismatch_count` | Gauge | 10.7 | Number of wikis that checksum mismatch on secondary | url | +| `geo_repositories_checked_count` | Gauge | 11.1 | Number of repositories that have been checked via `git fsck` | url | +| `geo_repositories_checked_failed_count` | Gauge | 11.1 | Number of repositories that have a failure from `git fsck` | url | +| `geo_repositories_retrying_verification_count` | Gauge | 11.2 | Number of repositories verification failures that Geo is actively trying to correct on secondary | url | +| `geo_wikis_retrying_verification_count` | Gauge | 11.2 | Number of wikis verification failures that Geo is actively trying to correct on secondary | url | + +## Database load balancing metrics **(PREMIUM ONLY)** + +The following metrics are available: + +| Metric | Type | Since | Description | +|:--------------------------------- |:--------- |:------------------------------------------------------------- |:-------------------------------------- | +| `db_load_balancing_hosts` | Gauge | [12.3](https://gitlab.com/gitlab-org/gitlab-ee/issues/13630) | Current number of load balancing hosts | +| `db_load_balancing_index` | Gauge | [12.3](https://gitlab.com/gitlab-org/gitlab-ee/issues/13630) | Current load balancing host index | + +## Ruby metrics Some basic Ruby runtime metrics are available: -| Metric | Type | Since | Description | -|:-------------------------------------- |:--------- |:----- |:----------- | -| ruby_gc_duration_seconds_total | Counter | 11.1 | Time spent by Ruby in GC | -| ruby_gc_stat_... | Gauge | 11.1 | Various metrics from [GC.stat] | -| ruby_file_descriptors | Gauge | 11.1 | File descriptors per process | -| ruby_memory_bytes | Gauge | 11.1 | Memory usage by process | -| ruby_sampler_duration_seconds_total | Counter | 11.1 | Time spent collecting stats | -| ruby_process_cpu_seconds_total | Gauge | 12.0 | Total amount of CPU time per process | -| ruby_process_max_fds | Gauge | 12.0 | Maximum number of open file descriptors per process | -| ruby_process_resident_memory_bytes | Gauge | 12.0 | Memory usage by process, measured in bytes | -| ruby_process_start_time_seconds | Gauge | 12.0 | UNIX timestamp of process start time | +| Metric | Type | Since | Description | +|:------------------------------------ |:--------- |:----- |:----------- | +| `ruby_gc_duration_seconds` | Counter | 11.1 | Time spent by Ruby in GC | +| `ruby_gc_stat_...` | Gauge | 11.1 | Various metrics from [GC.stat] | +| `ruby_file_descriptors` | Gauge | 11.1 | File descriptors per process | +| `ruby_memory_bytes` | Gauge | 11.1 | Memory usage by process | +| `ruby_sampler_duration_seconds` | Counter | 11.1 | Time spent collecting stats | +| `ruby_process_cpu_seconds_total` | Gauge | 12.0 | Total amount of CPU time per process | +| `ruby_process_max_fds` | Gauge | 12.0 | Maximum number of open file descriptors per process | +| `ruby_process_resident_memory_bytes` | Gauge | 12.0 | Memory usage by process, measured in bytes | +| `ruby_process_start_time_seconds` | Gauge | 12.0 | UNIX timestamp of process start time | -[GC.stat]: https://ruby-doc.org/core-2.3.0/GC.html#method-c-stat +[GC.stat]: https://ruby-doc.org/core-2.6.3/GC.html#method-c-stat + +## Unicorn Metrics + +Unicorn specific metrics, when Unicorn is used. + +| Metric | Type | Since | Description | +|:-----------------------------|:------|:------|:---------------------------------------------------| +| `unicorn_active_connections` | Gauge | 11.0 | The number of active Unicorn connections (workers) | +| `unicorn_queued_connections` | Gauge | 11.0 | The number of queued Unicorn connections | +| `unicorn_workers` | Gauge | 12.0 | The number of Unicorn workers | ## Puma Metrics **(EXPERIMENTAL)** -When Puma is used instead of Unicorn, following metrics are available: - -| Metric | Type | Since | Description | -|:-------------------------------------------- |:------- |:----- |:----------- | -| puma_workers | Gauge | 12.0 | Total number of workers | -| puma_running_workers | Gauge | 12.0 | Number of booted workers | -| puma_stale_workers | Gauge | 12.0 | Number of old workers | -| puma_running | Gauge | 12.0 | Number of running threads | -| puma_queued_connections | Gauge | 12.0 | Number of connections in that worker's "todo" set waiting for a worker thread | -| puma_active_connections | Gauge | 12.0 | Number of threads processing a request | -| puma_pool_capacity | Gauge | 12.0 | Number of requests the worker is capable of taking right now | -| puma_max_threads | Gauge | 12.0 | Maximum number of worker threads | -| puma_idle_threads | Gauge | 12.0 | Number of spawned threads which are not processing a request | -| rack_state_total | Gauge | 12.0 | Number of requests in a given rack state | -| puma_killer_terminations_total | Gauge | 12.0 | Number of workers terminated by PumaWorkerKiller | +When Puma is used instead of Unicorn, the following metrics are available: + +| Metric | Type | Since | Description | +|:---------------------------------------------- |:------- |:----- |:----------- | +| `puma_workers` | Gauge | 12.0 | Total number of workers | +| `puma_running_workers` | Gauge | 12.0 | Number of booted workers | +| `puma_stale_workers` | Gauge | 12.0 | Number of old workers | +| `puma_running` | Gauge | 12.0 | Number of running threads | +| `puma_queued_connections` | Gauge | 12.0 | Number of connections in that worker's "todo" set waiting for a worker thread | +| `puma_active_connections` | Gauge | 12.0 | Number of threads processing a request | +| `puma_pool_capacity` | Gauge | 12.0 | Number of requests the worker is capable of taking right now | +| `puma_max_threads` | Gauge | 12.0 | Maximum number of worker threads | +| `puma_idle_threads` | Gauge | 12.0 | Number of spawned threads which are not processing a request | +| `puma_killer_terminations_total` | Gauge | 12.0 | Number of workers terminated by PumaWorkerKiller | ## Metrics shared directory @@ -144,9 +230,3 @@ If GitLab is installed using Omnibus and `tmpfs` is available then metrics directory will be automatically configured. [← Back to the main Prometheus page](index.md) - -[29118]: https://gitlab.com/gitlab-org/gitlab-ce/issues/29118 -[Prometheus]: https://prometheus.io -[restart]: ../../restart_gitlab.md#omnibus-gitlab-restart -[whitelist]: ../ip_whitelist.md -[reconfigure]: ../../restart_gitlab.md#omnibus-gitlab-reconfigure diff --git a/doc/administration/packages.md b/doc/administration/packages.md index c0f8777a8c0..1628b6d6f91 100644 --- a/doc/administration/packages.md +++ b/doc/administration/packages.md @@ -55,7 +55,7 @@ local location or even use object storage. The packages for Omnibus GitLab installations are stored under `/var/opt/gitlab/gitlab-rails/shared/packages/` and for source -installations under `shared/packages/` (relative to the git homedir). +installations under `shared/packages/` (relative to the Git homedir). To change the local storage path: **Omnibus GitLab installations** diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index c77a1a9638f..fdfde22647d 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -343,21 +343,6 @@ world. Custom domains and TLS are supported. 1. Restart NGINX 1. [Restart GitLab][restart] -## Change storage path - -Follow the steps below to change the default path where GitLab Pages' contents -are stored. - -1. Pages are stored by default in `/var/opt/gitlab/gitlab-rails/shared/pages`. - If you wish to store them in another location you must set it up in - `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_rails['pages_path'] = "/mnt/storage/pages" - ``` - -1. [Reconfigure GitLab][reconfigure] - ## NGINX caveats >**Note:** @@ -468,7 +453,6 @@ than GitLab to prevent XSS attacks. [NGINX configs]: https://gitlab.com/gitlab-org/gitlab-ee/tree/8-5-stable-ee/lib/support/nginx [pages-readme]: https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md [pages-userguide]: ../../user/project/pages/index.md -[reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure [restart]: ../restart_gitlab.md#installations-from-source [gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.4.0 [gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/init.d/gitlab.default.example diff --git a/doc/administration/plugins.md b/doc/administration/plugins.md index 4cf3c607dae..92a4d56ca63 100644 --- a/doc/administration/plugins.md +++ b/doc/administration/plugins.md @@ -39,7 +39,7 @@ Follow the steps below to set up a custom hook: 1. Inside the `plugins` directory, create a file with a name of your choice, without spaces or special characters. -1. Make the hook file executable and make sure it's owned by the git user. +1. Make the hook file executable and make sure it's owned by the Git user. 1. Write the code to make the plugin function as expected. That can be in any language, and ensure the 'shebang' at the top properly reflects the language type. For example, if the script is in Ruby the shebang will @@ -112,4 +112,4 @@ Validating plugins from /plugins directory [system hooks]: ../system_hooks/system_hooks.md [webhooks]: ../user/project/integrations/webhooks.md -[highly available]: ./high_availability/README.md
\ No newline at end of file +[highly available]: ./high_availability/README.md diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index ccd9c0afb1d..f8eecc97c33 100644 --- a/doc/administration/raketasks/github_import.md +++ b/doc/administration/raketasks/github_import.md @@ -1,6 +1,6 @@ # GitHub import -> [Introduced]( https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10308) in GitLab 9.1. +> [Introduced]( https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10308) in GitLab 9.1. In order to retrieve and import GitHub repositories, you will need a [GitHub personal access token](https://github.com/settings/tokens). diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md index e880d76e756..d0ebe272b6d 100644 --- a/doc/administration/raketasks/ldap.md +++ b/doc/administration/raketasks/ldap.md @@ -19,8 +19,6 @@ sudo gitlab-rake gitlab:ldap:check sudo -u git -H bundle exec rake gitlab:ldap:check RAILS_ENV=production ``` ------- - By default, the task will return a sample of 100 LDAP users. Change this limit by passing a number to the check task: @@ -135,8 +133,6 @@ What is the old provider? Ex. 'ldapmain': ldapmain What is the new provider? Ex. 'ldapcustom': ldapmycompany ``` ------- - This tasks also accepts the `force` environment variable which will skip the confirmation dialog: diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index 8d0b5b42515..89335fcd2a8 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.md @@ -260,7 +260,7 @@ To check the status of 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 will output a table with a `Status` of `up` or `down` for each Migration ID. ```bash @@ -269,4 +269,4 @@ database: gitlabhq_production Status Migration ID Migration Name -------------------------------------------------- up migration_id migration_name -```
\ No newline at end of file +``` diff --git a/doc/administration/raketasks/uploads/migrate.md b/doc/administration/raketasks/uploads/migrate.md index 86e8b763f51..d9b4c9b3369 100644 --- a/doc/administration/raketasks/uploads/migrate.md +++ b/doc/administration/raketasks/uploads/migrate.md @@ -108,7 +108,7 @@ sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, MergeReque > Introduced in GitLab 12.3. -To migrate all uploads created by legacy uploaders, run: +To migrate all uploads created by legacy uploaders, run: ```shell bundle exec rake gitlab:uploads:legacy:migrate diff --git a/doc/administration/raketasks/uploads/sanitize.md b/doc/administration/raketasks/uploads/sanitize.md index ae5ccfb9e37..7574660d848 100644 --- a/doc/administration/raketasks/uploads/sanitize.md +++ b/doc/administration/raketasks/uploads/sanitize.md @@ -37,6 +37,8 @@ Parameter | Type | Description `stop_id` | integer | Only uploads with equal or smaller ID will be processed `dry_run` | boolean | Do not remove EXIF data, only check if EXIF data are present or not, default: true `sleep_time` | float | Pause for number of seconds after processing each image, default: 0.3 seconds +`uploader` | string | Run sanitization only for uploads of the given uploader (`FileUploader`, `PersonalFileUploader`, `NamespaceFileUploader`) +`since` | date | Run sanitization only for uploads newer than given date (e.g. `2019-05-01`) If you have too many uploads, you can speed up sanitization by setting `sleep_time` to a lower value or by running multiple rake tasks in parallel, diff --git a/doc/administration/reply_by_email_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md index 406f7e8a034..56cd23b2eb8 100644 --- a/doc/administration/reply_by_email_postfix_setup.md +++ b/doc/administration/reply_by_email_postfix_setup.md @@ -18,7 +18,7 @@ The instructions make the assumption that you will be using the email address `i sudo apt-get install postfix ``` - When asked about the environment, select 'Internet Site'. When asked to confirm the hostname, make sure it matches gitlab.example.com`. + When asked about the environment, select 'Internet Site'. When asked to confirm the hostname, make sure it matches `gitlab.example.com`. 1. Install the `mailutils` package. @@ -331,7 +331,7 @@ Courier, which we will install later to add IMAP authentication, requires mailbo a logout ``` -## Done! +## Done If all the tests were successful, Postfix is all set up and ready to receive email! Continue with the [incoming email] guide to configure GitLab. diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index 05a7cb006a3..ab911c1cf0e 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -3,7 +3,7 @@ > [Introduced][ce-3232] in GitLab 8.7. It is OFF by default because it still causes too many false alarms. -Git has a built-in mechanism, [git fsck][git-fsck], to verify the +Git has a built-in mechanism, [`git fsck`][git-fsck], to verify the integrity of all data committed to a repository. GitLab administrators can trigger such a check for a project via the project page under the admin panel. The checks run asynchronously so it may take a few minutes diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index 1669f8b128c..3ee8673b297 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -82,19 +82,17 @@ by another folder with the next 2 characters. They are both stored in a special > [Introduced](https://gitlab.com/gitlab-org/gitaly/issues/1606) in GitLab 12.1. -Forks of public projects are deduplicated by creating a third repository, the object pool, containing the objects from the source project. Using `objects/info/alternates`, the source project and forks use the object pool for shared objects. Objects are moved from the source project to the object pool when housekeeping is run on the source project. +Forks of public projects are deduplicated by creating a third repository, the +object pool, containing the objects from the source project. Using +`objects/info/alternates`, the source project and forks use the object pool for +shared objects. Objects are moved from the source project to the object pool +when housekeeping is run on the source project. ```ruby # object pool paths "@pools/#{hash[0..1]}/#{hash[2..3]}/#{hash}.git" ``` -Object pools can be disabled using the `object_pools` feature flag, and can be -disabled for individual projects by executing -`Feature.disable(:object_pools, Project.find(<id>))`. Disabling object pools -will not change existing deduplicated forks, but will prevent new forks from -being deduplicated. - DANGER: **Danger:** Do not run `git prune` or `git gc` in pool repositories! This can cause data loss in "real" repositories that depend on the pool in @@ -118,7 +116,7 @@ If you do have any existing integration, you may want to do a small rollout firs to validate. You can do so by specifying a range with the operation. This is an example of how to limit the rollout to Project IDs 50 to 100, running in -an Omnibus Gitlab installation: +an Omnibus GitLab installation: ```bash sudo gitlab-rake gitlab:storage:migrate_to_hashed ID_FROM=50 ID_TO=100 @@ -139,7 +137,7 @@ To schedule a complete rollback, see the [rake task documentation for storage rollback](raketasks/storage.md#rollback-from-hashed-storage-to-legacy-storage) for instructions. The rollback task also supports specifying a range of Project IDs. Here is an example -of limiting the rollout to Project IDs 50 to 100, in an Omnibus Gitlab installation: +of limiting the rollout to Project IDs 50 to 100, in an Omnibus GitLab installation: ```bash sudo gitlab-rake gitlab:storage:rollback_to_legacy ID_FROM=50 ID_TO=100 @@ -185,7 +183,7 @@ CI Artifacts are S3 compatible since **9.4** (GitLab Premium), and available in ##### LFS Objects -LFS Objects implements a similar storage pattern using 2 chars, 2 level folders, following git own implementation: +LFS Objects implements a similar storage pattern using 2 chars, 2 level folders, following Git own implementation: ```ruby "shared/lfs-objects/#{oid[0..1}/#{oid[2..3]}/#{oid[4..-1]}" diff --git a/doc/administration/smime_signing_email.md b/doc/administration/smime_signing_email.md new file mode 100644 index 00000000000..b2e3bf8487b --- /dev/null +++ b/doc/administration/smime_signing_email.md @@ -0,0 +1,49 @@ +# Signing outgoing email with S/MIME + +Notification emails sent by Gitlab can be signed with S/MIME for improved +security. + +> **Note:** +Please be aware that S/MIME certificates and TLS/SSL certificates are not the +same and are used for different purposes: TLS creates a secure channel, whereas +S/MIME signs and/or encrypts the message itself + +## Enable S/MIME signing + +This setting must be explicitly enabled and a single pair of key and certificate +files must be provided in `gitlab.rb` or `gitlab.yml` if you are using Omnibus +GitLab or installed GitLab from source respectively: + +```yaml +email_smime: + enabled: true + key_file: /etc/pki/smime/private/gitlab.key + cert_file: /etc/pki/smime/certs/gitlab.crt +``` + +- Both files must be provided PEM-encoded. +- The key file must be unencrypted so that Gitlab can read it without user + intervention. + +NOTE: **Note:** Be mindful of the access levels for your private keys and visibility to +third parties. + +### How to convert S/MIME PKCS#12 / PFX format to PEM encoding + +Typically S/MIME certificates are handled in binary PKCS#12 format (`.pfx` or `.p12` +extensions), which contain the following in a single encrypted file: + +- Server certificate +- Intermediate certificates (if any) +- Private key + +In order to export the required files in PEM encoding from the PKCS#12 file, +the `openssl` command can be used: + +```bash +#-- Extract private key in PEM encoding (no password, unencrypted) +$ openssl pkcs12 -in gitlab.p12 -nocerts -nodes -out gitlab.key + +#-- Extract certificates in PEM encoding (full certs chain including CA) +$ openssl pkcs12 -in gitlab.p12 -nokeys -out gitlab.crt +``` diff --git a/doc/administration/troubleshooting/elasticsearch.md b/doc/administration/troubleshooting/elasticsearch.md index c4a7ba01fae..13b9c30b29d 100644 --- a/doc/administration/troubleshooting/elasticsearch.md +++ b/doc/administration/troubleshooting/elasticsearch.md @@ -266,9 +266,9 @@ ElasticSearch administrator. Generally speaking, ensure: -* The ElasticSearch server **is not** running on the same node as GitLab. -* The ElasticSearch server have enough RAM and CPU cores. -* That sharding **is** being used. +- The ElasticSearch server **is not** running on the same node as GitLab. +- The ElasticSearch server have enough RAM and CPU cores. +- That sharding **is** being used. Going into some more detail here, if ElasticSearch is running on the same server as GitLab, resource contention is **very** likely to occur. Ideally, ElasticSearch, which requires ample resources, should be running on its own server (maybe coupled with logstash and kibana). diff --git a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md index 95cdb1508fa..260af333e8e 100644 --- a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md +++ b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md @@ -29,7 +29,7 @@ and they will assist you with any issues you are having. ```bash # for minikube: minikube dashboard —url - # for non-local installations if access via kubectl is configured: + # for non-local installations if access via Kubectl is configured: kubectl proxy ``` @@ -49,7 +49,7 @@ and they will assist you with any issues you are having. - What to do with pods in `CrashLoopBackoff` status: - Check logs via Kubernetes dashboard. - - Check logs via `kubectl`: + - Check logs via Kubectl: ```bash kubectl logs <unicorn pod> -c dependencies @@ -72,7 +72,7 @@ and they will assist you with any issues you are having. This is the principle of Kubernetes, read [Twelve-factor app](https://12factor.net/) for details. -## Gitlab-specific kubernetes information +## GitLab-specific kubernetes information - Minimal config that can be used to test a Kubernetes helm chart can be found [here](https://gitlab.com/charts/gitlab/issues/620). @@ -83,12 +83,22 @@ and they will assist you with any issues you are having. kubectl logs gitlab-unicorn-7656fdd6bf-jqzfs -c unicorn ``` -- It is not possible to get all the logs via `kubectl` at once, like with `gitlab-ctl tail`, - but a number of third-party tools can be used to do it: +- Tail and follow all pods that share a label (in this case, `unicorn`): - - [Kubetail](https://github.com/johanhaleby/kubetail) - - [kail: kubernetes tail](https://github.com/boz/kail) - - [stern](https://github.com/wercker/stern) + ```bash + # all containers in the unicorn pods + kubectl logs -f -l app=unicorn --all-containers=true --max-log-requests=50 + + # only the unicorn containers in all unicorn pods + kubectl logs -f -l app=unicorn -c unicorn --max-log-requests=50 + ``` + +- One can stream logs from all containers at once, similar to the Omnibus + command `gitlab-ctl tail`: + + ```bash + kubectl logs -f -l release=gitlab --all-containers=true --max-log-requests=100 + ``` - Check all events in the `gitlab` namespace (the namespace name can be different if you specified a different one when deploying the helm chart): @@ -131,7 +141,7 @@ and they will assist you with any issues you are having. - Check the output of `kubectl get events -w --all-namespaces`. - Check the logs of pods within `gitlab-managed-apps` namespace. - On the side of GitLab check sidekiq log and kubernetes log. When GitLab is installed - via helm chart, kubernetes.log can be found inside the sidekiq pod. + via Helm Chart, `kubernetes.log` can be found inside the sidekiq pod. - How to get your initial admin password <https://docs.gitlab.com/charts/installation/deployment.html#initial-login>: @@ -142,19 +152,19 @@ and they will assist you with any issues you are having. kubectl get secret <secret-name> -ojsonpath={.data.password} | base64 --decode ; echo ``` -- How to connect to a GitLab postgres database: +- How to connect to a GitLab Postgres database: ```bash kubectl exec -it <task-runner-pod-name> -- /srv/gitlab/bin/rails dbconsole -p ``` -- How to get info about helm installation status: +- How to get info about Helm installation status: ```bash helm status name-of-installation ``` -- How to update GitLab installed using helm chart: +- How to update GitLab installed using Helm Chart: ```bash helm repo upgrade @@ -179,25 +189,25 @@ and they will assist you with any issues you are having. helm upgrade <release name> <chart path> -f gitlab.yaml ``` -## Installation of minimal GitLab config via minukube on macOS +## Installation of minimal GitLab config via Minukube on macOS This section is based on [Developing for Kubernetes with Minikube](https://gitlab.com/charts/gitlab/blob/master/doc/minikube/index.md) and [Helm](https://gitlab.com/charts/gitlab/blob/master/doc/helm/index.md). Refer to those documents for details. -- Install kubectl via Homebrew: +- Install Kubectl via Homebrew: ```bash brew install kubernetes-cli ``` -- Install minikube via Homebrew: +- Install Minikube via Homebrew: ```bash brew cask install minikube ``` -- Start minikube and configure it. If minikube cannot start, try running `minikube delete && minikube start` +- Start Minikube and configure it. If Minikube cannot start, try running `minikube delete && minikube start` and repeat the steps: ```bash @@ -206,7 +216,7 @@ to those documents for details. minikube addons enable kube-dns ``` -- Install helm via Homebrew and initialize it: +- Install Helm via Homebrew and initialize it: ```bash brew install kubernetes-helm @@ -219,7 +229,7 @@ to those documents for details. - Find the IP address in the output of `minikube ip` and update the yaml file with this IP address. -- Install the GitLab helm chart: +- Install the GitLab Helm Chart: ```bash helm repo add gitlab https://charts.gitlab.io diff --git a/doc/administration/troubleshooting/sidekiq.md b/doc/administration/troubleshooting/sidekiq.md index 7067958ecb4..c41edb5dbfc 100644 --- a/doc/administration/troubleshooting/sidekiq.md +++ b/doc/administration/troubleshooting/sidekiq.md @@ -96,8 +96,9 @@ corresponding Ruby code where this is happening. `gdb` can be another effective tool for debugging Sidekiq. It gives you a little more interactive way to look at each thread and see what's causing problems. -> **Note:** Attaching to a process with `gdb` will suspends the normal operation - of the process (Sidekiq will not process jobs while `gdb` is attached). +NOTE: **Note:** +Attaching to a process with `gdb` will suspends the normal operation +of the process (Sidekiq will not process jobs while `gdb` is attached). Start by attaching to the Sidekiq PID: @@ -169,3 +170,121 @@ The PostgreSQL wiki has details on the query you can run to see blocking queries. The query is different based on PostgreSQL version. See [Lock Monitoring](https://wiki.postgresql.org/wiki/Lock_Monitoring) for the query details. + +## Managing Sidekiq queues + +It is possible to use [Sidekiq API](https://github.com/mperham/sidekiq/wiki/API) +to perform a number of troubleshoting on Sidekiq. + +These are the administrative commands and it should only be used if currently +admin interface is not suitable due to scale of installation. + +All this commands should be run using `gitlab-rails console`. + +### View the queue size + +```ruby +Sidekiq::Queue.new("pipeline_processing:build_queue").size +``` + +### Enumerate all enqueued jobs + +```ruby +queue = Sidekiq::Queue.new("chaos:chaos_sleep") +queue.each do |job| + # job.klass # => 'MyWorker' + # job.args # => [1, 2, 3] + # job.jid # => jid + # job.queue # => chaos:chaos_sleep + # job["retry"] # => 3 + # job.item # => { + # "class"=>"Chaos::SleepWorker", + # "args"=>[1000], + # "retry"=>3, + # "queue"=>"chaos:chaos_sleep", + # "backtrace"=>true, + # "queue_namespace"=>"chaos", + # "jid"=>"39bc482b823cceaf07213523", + # "created_at"=>1566317076.266069, + # "correlation_id"=>"c323b832-a857-4858-b695-672de6f0e1af", + # "enqueued_at"=>1566317076.26761}, + # } + + # job.delete if job.jid == 'abcdef1234567890' +end +``` + +### Enumerate currently running jobs + +```ruby +workers = Sidekiq::Workers.new +workers.each do |process_id, thread_id, work| + # process_id is a unique identifier per Sidekiq process + # thread_id is a unique identifier per thread + # work is a Hash which looks like: + # {"queue"=>"chaos:chaos_sleep", + # "payload"=> + # { "class"=>"Chaos::SleepWorker", + # "args"=>[1000], + # "retry"=>3, + # "queue"=>"chaos:chaos_sleep", + # "backtrace"=>true, + # "queue_namespace"=>"chaos", + # "jid"=>"b2a31e3eac7b1a99ff235869", + # "created_at"=>1566316974.9215662, + # "correlation_id"=>"e484fb26-7576-45f9-bf21-b99389e1c53c", + # "enqueued_at"=>1566316974.9229589}, + # "run_at"=>1566316974}], +end +``` + +### Remove sidekiq jobs for given parameters (destructive) + +```ruby +# for jobs like this: +# RepositoryImportWorker.new.perform_async(100) +id_list = [100] + +queue = Sidekiq::Queue.new('repository_import') +queue.each do |job| + job.delete if id_list.include?(job.args[0]) +end +``` + +### Remove specific job ID (destructive) + +```ruby +queue = Sidekiq::Queue.new('repository_import') +queue.each do |job| + job.delete if job.jid == 'my-job-id' +end +``` + +## Canceling running jobs (destructive) + +> Introduced in GitLab 12.3. + +This is highly risky operation and use it as last resort. +Doing that might result in data corruption, as the job +is interrupted mid-execution and it is not guaranteed +that proper rollback of transactions is implemented. + +```ruby +Gitlab::SidekiqMonitor.cancel_job('job-id') +``` + +> This requires the Sidekiq to be run with `SIDEKIQ_MONITOR_WORKER=1` +> environment variable. + +To perform of the interrupt we use `Thread.raise` which +has number of drawbacks, as mentioned in [Why Ruby’s Timeout is dangerous (and Thread.raise is terrifying)](https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/): + +> This is where the implications get interesting, and terrifying. This means that an exception can get raised: +> +> - during a network request (ok, as long as the surrounding code is prepared to catch Timeout::Error) +> - during the cleanup for the network request +> - during a rescue block +> - while creating an object to save to the database afterwards +> - in any of your code, regardless of whether it could have possibly raised an exception before +> +> Nobody writes code to defend against an exception being raised on literally any line. That’s not even possible. So Thread.raise is basically like a sneak attack on your code that could result in almost anything. It would probably be okay if it were pure-functional code that did not modify any state. But this is Ruby, so that’s unlikely :) diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index 99f1c386183..a4bed72b965 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -57,7 +57,7 @@ This configuration relies on valid AWS credentials to be configured already. ## Object Storage Settings -For source installations the following settings are nested under `uploads:` and then `object_store:`. On omnibus installs they are prefixed by `uploads_object_store_`. +For source installations the following settings are nested under `uploads:` and then `object_store:`. On Omnibus GitLab installs they are prefixed by `uploads_object_store_`. | Setting | Description | Default | |---------|-------------|---------| @@ -78,7 +78,7 @@ The connection settings match those provided by [Fog](https://github.com/fog), a | `aws_access_key_id` | AWS credentials, or compatible | | | `aws_secret_access_key` | AWS credentials, or compatible | | | `aws_signature_version` | AWS signature version to use. 2 or 4 are valid options. Digital Ocean Spaces and other providers may need 2. | 4 | -| `enable_signature_v4_streaming` | Set to true to enable HTTP chunked transfers with AWS v4 signatures (https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html). Oracle Cloud S3 needs this to be false | true +| `enable_signature_v4_streaming` | Set to true to enable HTTP chunked transfers with [AWS v4 signatures](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html). Oracle Cloud S3 needs this to be false | true | | `region` | AWS region | us-east-1 | | `host` | S3 compatible host for when not using AWS, e.g. `localhost` or `storage.example.com` | s3.amazonaws.com | | `endpoint` | Can be used when configuring an S3 compatible service such as [Minio](https://www.minio.io), by entering a URL such as `http://127.0.0.1:9000` | (optional) | @@ -220,7 +220,7 @@ _The uploads are stored by default in openstack_temp_url_key: OPENSTACK_TEMP_URL_KEY openstack_auth_url: 'https://auth.cloud.ovh.net/v2.0/' openstack_region: DE1 - openstack_tenant: 'TENANT_ID' + openstack_tenant: 'TENANT_ID' ``` 1. Save the file and [reconfigure GitLab][] for the changes to take effect. diff --git a/doc/api/README.md b/doc/api/README.md index b7ee710b87a..036b46da6e5 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -77,11 +77,12 @@ authentication is not provided. For those cases where it is not required, this will be mentioned in the documentation for each individual endpoint. For example, the [`/projects/:id` endpoint](projects.md). -There are three ways to authenticate with the GitLab API: +There are four ways to authenticate with the GitLab API: 1. [OAuth2 tokens](#oauth2-tokens) 1. [Personal access tokens](#personal-access-tokens) 1. [Session cookie](#session-cookie) +1. [GitLab CI job token](#gitlab-ci-job-token-premium) **(PREMIUM)** For admins who want to authenticate with the API as a specific user, or who want to build applications or scripts that do so, two options are available: @@ -151,6 +152,14 @@ The primary user of this authentication method is the web frontend of GitLab its which can use the API as the authenticated user to get a list of their projects, for example, without needing to explicitly pass an access token. +### GitLab CI job token **(PREMIUM)** + +With a few API endpoints you can use a [GitLab CI job token](../user/project/new_ci_build_permissions_model.md#job-token) +to authenticate with the API: + +- [Get job artifacts](jobs.md#get-job-artifacts) +- [Pipeline triggers](pipeline_triggers.md) + ### Impersonation tokens > [Introduced][ce-9099] in GitLab 9.0. Needs admin permissions. @@ -387,7 +396,7 @@ GET /api/v4/projects/diaspora%2Fdiaspora NOTE: **Note:** A project's **path** is not necessarily the same as its **name**. A -project's path can found in the project's URL or in the project's settings +project's path can be found in the project's URL or in the project's settings under **General > Advanced > Change path**. ## Branches and tags name encoding @@ -413,7 +422,7 @@ We can call the API with `array` and `hash` types parameters as shown below: curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ -d "import_sources[]=github" \ -d "import_sources[]=bitbucket" \ -"https://gitlab.example.com/api/v4/some_endpoint +https://gitlab.example.com/api/v4/some_endpoint ``` ### `hash` diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index b32f11464ef..9af5430f1c8 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -67,7 +67,7 @@ The following API resources are available in the project context: | [Search](search.md) | `/projects/:id/search` (also available for groups and standalone) | | [Services](services.md) | `/projects/:id/services` | | [Tags](tags.md) | `/projects/:id/repository/tags` | -| [Vulnerabilities](vulnerabilities.md) **(ULTIMATE)** | `/projects/:id/vulnerabilities` (also available for groups) | +| [Vulnerabilities](vulnerabilities.md) **(ULTIMATE)** | `/projects/:id/vulnerabilities` | [Wikis](wikis.md) | `/projects/:id/wikis` | ## Group resources diff --git a/doc/api/boards.md b/doc/api/boards.md index 08ec1d832df..b848d7788cd 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -466,7 +466,7 @@ Example response: ## Delete a board list -Only for admins and project owners. Soft deletes the board list in question. +Only for admins and project owners. Deletes the board list in question. ``` DELETE /projects/:id/boards/:board_id/lists/:list_id diff --git a/doc/api/dependencies.md b/doc/api/dependencies.md index 015ffbe60f6..5296d4e316f 100644 --- a/doc/api/dependencies.md +++ b/doc/api/dependencies.md @@ -5,20 +5,21 @@ This API is in an alpha stage and considered unstable. The response payload may be subject to change or breakage across GitLab releases. -Every call to this endpoint requires authentication. To perform this call, user should be authorized to read -[Project Security Dashboard](../user/application_security/security_dashboard/index.md#project-security-dashboard). +Every call to this endpoint requires authentication. To perform this call, user should be authorized to read repository. +To see vulnerabilities in response, user should be authorized to read +[Project Security Dashboard](../user/application_security/security_dashboard/index.md#project-security-dashboard). ## List project dependencies -Get a list of project dependencies. This API partially mirroring +Get a list of project dependencies. This API partially mirroring [Dependency List](../user/application_security/dependency_list/index.md) feature. This list can be generated only for [languages and package managers](../user/application_security/dependency_scanning/index.md#supported-languages-and-package-managers) -supported by Gemnasium. +supported by Gemnasium. ``` GET /projects/:id/dependencies -GET /projects/:id/vulnerabilities?package_manager=maven -GET /projects/:id/vulnerabilities?package_manager=yarn,bundler +GET /projects/:id/dependencies?package_manager=maven +GET /projects/:id/dependencies?package_manager=yarn,bundler ``` | Attribute | Type | Required | Description | @@ -38,13 +39,18 @@ Example response: "name": "rails", "version": "5.0.1", "package_manager": "bundler", - "dependency_file_path": "Gemfile.lock" + "dependency_file_path": "Gemfile.lock", + "vulnerabilities": [{ + "name": "DDoS", + "severity": "unknown" + }] }, { "name": "hanami", "version": "1.3.1", "package_manager": "bundler", - "dependency_file_path": "Gemfile.lock" + "dependency_file_path": "Gemfile.lock", + "vulnerabilities": [] } ] ``` diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index 94351e1a300..2e2e1bb5e1e 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -203,6 +203,7 @@ Example response: "created_at" : "2015-08-29T12:44:31.550Z" } ``` + ## Adding deploy keys to multiple projects If you want to easily add the same deploy key to multiple projects in the same @@ -211,22 +212,25 @@ group, this can be achieved quite easily with the API. First, find the ID of the projects you're interested in, by either listing all projects: -``` +```bash curl --header 'PRIVATE-TOKEN: <your_access_token>' https://gitlab.example.com/api/v4/projects ``` -Or finding the ID of a group and then listing all projects in that group: +Or finding the ID of a group: -``` +```bash curl --header 'PRIVATE-TOKEN: <your_access_token>' https://gitlab.example.com/api/v4/groups +``` + +Then listing all projects in that group (for example, group 1234): -# For group 1234: +```bash curl --header 'PRIVATE-TOKEN: <your_access_token>' https://gitlab.example.com/api/v4/groups/1234 ``` With those IDs, add the same deploy key to all: -``` +```bash for project_id in 321 456 987; do curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ --data '{"title": "my key", "key": "ssh-rsa AAAA..."}' https://gitlab.example.com/api/v4/projects/${project_id}/deploy_keys diff --git a/doc/api/discussions.md b/doc/api/discussions.md index b4a2d0b15f6..12dbba78291 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -160,7 +160,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Adds a new note to the thread. This can also [create a thread from a single comment](../user/discussions/#start-a-thread-by-replying-to-a-standard-comment). **WARNING** -Notes can be added to other items than comments (system notes, etc.) making them threads. +Notes can be added to other items than comments (system notes, etc.) making them threads. ``` POST /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes diff --git a/doc/api/epics.md b/doc/api/epics.md index 3036b3c2364..08eb84bfb63 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -65,6 +65,8 @@ Example response: "title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.", "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.", "state": "opened", + "web_edit_url": "http://localhost:3001/groups/test/-/epics/4", + "reference": "&4", "author": { "id": 10, "name": "Lu Mayer", @@ -118,6 +120,8 @@ Example response: "title": "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.", "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.", "state": "opened", + "web_edit_url": "http://localhost:3001/groups/test/-/epics/5", + "reference": "&5", "author":{ "id": 7, "name": "Pamella Huel", @@ -161,7 +165,7 @@ POST /groups/:id/epics | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | The title of the epic | | `labels` | string | no | The comma separated list of labels | -| `description` | string | no | The description of the epic | +| `description` | string | no | The description of the epic. Limited to 1 000 000 characters. | | `start_date_is_fixed` | boolean | no | Whether start date should be sourced from `start_date_fixed` or from milestones (since 11.3) | | `start_date_fixed` | string | no | The fixed start date of an epic (since 11.3) | | `due_date_is_fixed` | boolean | no | Whether due date should be sourced from `due_date_fixed` or from milestones (since 11.3) | @@ -182,6 +186,8 @@ Example response: "title": "Epic", "description": "Epic description", "state": "opened", + "web_edit_url": "http://localhost:3001/groups/test/-/epics/6", + "reference": "&6", "author": { "name" : "Alexandra Bashirian", "avatar_url" : null, @@ -225,7 +231,7 @@ PUT /groups/:id/epics/:epic_iid | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic | | `title` | string | no | The title of an epic | -| `description` | string | no | The description of an epic | +| `description` | string | no | The description of an epic. Limited to 1 000 000 characters. | | `labels` | string | no | The comma separated list of labels | | `start_date_is_fixed` | boolean | no | Whether start date should be sourced from `start_date_fixed` or from milestones (since 11.3) | | `start_date_fixed` | string | no | The fixed start date of an epic (since 11.3) | @@ -247,6 +253,8 @@ Example response: "title": "New Title", "description": "Epic description", "state": "opened", + "web_edit_url": "http://localhost:3001/groups/test/-/epics/6", + "reference": "&6", "author": { "name" : "Alexandra Bashirian", "avatar_url" : null, diff --git a/doc/api/events.md b/doc/api/events.md index 6dca8e52f69..1cd7047b867 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -70,7 +70,7 @@ Parameters: Example request: -``` +```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/events?target_type=issue&action=created&after=2017-01-31&before=2017-03-01 ``` @@ -275,7 +275,7 @@ Parameters: Example request: -``` +```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:project_id/events?target_type=issue&action=created&after=2017-01-31&before=2017-03-01 ``` @@ -343,8 +343,8 @@ Example response: "username": "root", "id": 1, "state": "active", - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", - "web_url": "http://localhost:3000/root" + "avatar_url": "https://gitlab.example.com/uploads/user/avatar/1/fox_avatar.png", + "web_url": "https://gitlab.example.com/root" }, "created_at": "2015-12-04T10:33:56.698Z", "system": false, @@ -357,8 +357,8 @@ Example response: "username": "root", "id": 1, "state": "active", - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png", - "web_url": "http://localhost:3000/root" + "avatar_url": "https://gitlab.example.com/uploads/user/avatar/1/fox_avatar.png", + "web_url": "https://gitlab.example.com/root" }, "author_username": "root" } diff --git a/doc/api/features.md b/doc/api/features.md index 6ecd4ec14b9..e8d0c7c942b 100644 --- a/doc/api/features.md +++ b/doc/api/features.md @@ -60,8 +60,8 @@ POST /features/:name | `value` | integer/string | yes | `true` or `false` to enable/disable, or an integer for percentage of time | | `feature_group` | string | no | A Feature group 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-ce' | +| `group` | string | no | A GitLab group's path, for example `gitlab-org` | +| `project` | string | no | A projects path, for example `gitlab-org/gitlab-ce` | 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. diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index d0b33ab467f..5eba7f038ed 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -111,7 +111,7 @@ PUT /geo_nodes/:id |-----------------------------|---------|-----------|---------------------------------------------------------------------------| | `id` | integer | yes | The ID of the Geo node. | | `enabled` | boolean | no | Flag indicating if the Geo node is enabled. | -| `name` | string | yes | The unique identifier for the Geo node. Must match `geo_node_name` if it is set in gitlab.rb, otherwise it must match `external_url`. | +| `name` | string | yes | The unique identifier for the Geo node. Must match `geo_node_name` if it is set in `gitlab.rb`, otherwise it must match `external_url`. | | `url` | string | yes | The user-facing URL of the Geo node. | | `internal_url` | string | no | The URL defined on the primary node that secondary nodes should use to contact it. Returns `url` if not set.| | `files_max_capacity` | integer | no | Control the maximum concurrency of LFS/attachment backfill for this secondary node. | diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 2d3bec4ff67..e87270f884a 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -109,6 +109,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `visibility` | String | | | `lfsEnabled` | Boolean | | | `requestAccessEnabled` | Boolean | | +| `rootStorageStatistics` | RootStorageStatistics | The aggregated storage statistics. Only available if the namespace has no parent | | `userPermissions` | GroupPermissions! | Permissions for the current user on the resource | | `webUrl` | String! | | | `avatarUrl` | String | | @@ -453,6 +454,17 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `exists` | Boolean! | | | `tree` | Tree | | +### RootStorageStatistics + +| Name | Type | Description | +| --- | ---- | ---------- | +| `storageSize` | Int! | The total storage in Bytes | +| `repositorySize` | Int! | The git repository size in Bytes | +| `lfsObjectsSize` | Int! | The LFS objects size in Bytes | +| `buildArtifactsSize` | Int! | The CI artifacts size in Bytes | +| `packagesSize` | Int! | The packages size in Bytes | +| `wikiSize` | Int! | The wiki size in Bytes | + ### Submodule | Name | Type | Description | @@ -504,4 +516,3 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `username` | String! | | | `avatarUrl` | String! | | | `webUrl` | String! | | - diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index 4d10f83720b..99b522a7ae9 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -536,7 +536,7 @@ Example response: ## Delete a group issue board list -Only for admins and group owners. Soft deletes the board list in question. +Only for admins and group owners. Deletes the board list in question. ``` DELETE /groups/:id/boards/:board_id/lists/:list_id diff --git a/doc/api/groups.md b/doc/api/groups.md index 0d500f783aa..d7f5b1b463b 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -158,6 +158,7 @@ Parameters: | `with_shared` | boolean | no | Include projects shared to this group. Default is `true` | | `include_subgroups` | boolean | no | Include projects in subgroups of this group. Default is `false` | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | +| `with_security_reports` | boolean | no | **(ULTIMATE)** Return only projects that have security reports artifacts present in any of their builds. This means "projects with security reports enabled". Default is `false` | Example response: diff --git a/doc/api/issues.md b/doc/api/issues.md index 96a547551f1..7498d2d840b 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -49,7 +49,7 @@ GET /issues?confidential=true | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | | `iids[]` | integer array | no | Return only the issues having the given `iid` | -| `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search issues against their `title` and `description` | | `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | @@ -136,7 +136,6 @@ Example response: "award_emoji":"http://example.com/api/v4/projects/1/issues/76/award_emoji", "project":"http://example.com/api/v4/projects/1" }, - "subscribed": false, "task_completion_status":{ "count":0, "completed_count":0 @@ -199,7 +198,7 @@ GET /groups/:id/issues?confidential=true | `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be 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. _([Introduced][ce-14016] in GitLab 10.0)_ | | `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | -| `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search group issues against their `title` and `description` | | `created_after` | datetime | no | Return issues created on or after the given time | @@ -285,7 +284,6 @@ Example response: "award_emoji":"http://example.com/api/v4/projects/4/issues/41/award_emoji", "project":"http://example.com/api/v4/projects/4" }, - "subscribed": false, "task_completion_status":{ "count":0, "completed_count":0 @@ -348,7 +346,7 @@ GET /projects/:id/issues?confidential=true | `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be 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. _([Introduced][ce-14016] in GitLab 10.0)_ | | `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | -| `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search project issues against their `title` and `description` | | `created_after` | datetime | no | Return issues created on or after the given time | @@ -441,7 +439,6 @@ Example response: "award_emoji":"http://example.com/api/v4/projects/4/issues/41/award_emoji", "project":"http://example.com/api/v4/projects/4" }, - "subscribed": false, "task_completion_status":{ "count":0, "completed_count":0 @@ -593,7 +590,7 @@ POST /projects/:id/issues | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `iid` | integer/string | no | The internal ID of the project's issue (requires admin or project owner rights) | | `title` | string | yes | The title of an issue | -| `description` | string | no | The description of an issue | +| `description` | string | no | The description of an issue. Limited to 1 000 000 characters. | | `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | | `assignee_ids` | integer array | no | The ID of a user to assign issue | | `milestone_id` | integer | no | The global ID of a milestone to assign issue | @@ -694,7 +691,7 @@ PUT /projects/:id/issues/:issue_iid | `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 | | `title` | string | no | The title of an issue | -| `description` | string | no | The description of an issue | +| `description` | string | no | The description of an issue. Limited to 1 000 000 characters. | | `confidential` | boolean | no | Updates an issue to be confidential | | `assignee_ids` | integer array | no | The ID of the user(s) to assign the issue to. Set to `0` or provide an empty value to unassign all assignees. | | `milestone_id` | integer | no | The global ID of a milestone to assign the issue to. Set to `0` or provide an empty value to unassign a milestone.| @@ -790,7 +787,7 @@ the `weight` parameter: ## Delete an issue -Only for admins and project owners. Soft deletes the issue in question. +Only for admins and project owners. Deletes the issue in question. ``` DELETE /projects/:id/issues/:issue_iid diff --git a/doc/api/labels.md b/doc/api/labels.md index 5db0edcf14d..9692cc8b710 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -137,8 +137,9 @@ DELETE /projects/:id/labels | 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 | -| `name` | string | yes | The name of the label | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `label_id` | integer | yes (or `name`) | The id of the existing label | +| `name` | string | yes (or `label_id`) | The name of the existing label | ```bash curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels?name=bug" @@ -156,7 +157,8 @@ PUT /projects/:id/labels | 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 | -| `name` | string | yes | The name of the existing label | +| `label_id` | integer | yes (or `name`) | The id of the existing label | +| `name` | string | yes (or `label_id`) | The name of the existing label | | `new_name` | string | yes if `color` is not provided | The new name of the label | | `color` | string | yes if `new_name` is not provided | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | | `description` | string | no | The new description of the label | @@ -184,6 +186,40 @@ Example response: } ``` +## Promote a project label to a group label + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/25218) in GitLab 12.3. + +Promotes a project label to a group label. + +``` +PUT /projects/:id/labels/promote +``` + +| 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 | +| `name` | string | yes | The name of the existing label | + +```bash +curl --request PUT --data "name=documentation" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/promote" +``` + +Example response: + +```json +{ + "id" : 8, + "name" : "documentation", + "color" : "#8E44AD", + "description": "Documentation", + "open_issues_count": 1, + "closed_issues_count": 0, + "open_merge_requests_count": 2, + "subscribed": false +} +``` + ## Subscribe to a label Subscribes the authenticated user to a label to receive notifications. diff --git a/doc/api/lint.md b/doc/api/lint.md index 79f5e629c7f..dacd3f4c493 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -1,4 +1,4 @@ -# Validate the .gitlab-ci.yml (API) +# Validate the `.gitlab-ci.yml` (API) > [Introduced][ce-5953] in GitLab 8.12. @@ -10,7 +10,7 @@ POST /ci/lint | Attribute | Type | Required | Description | | ---------- | ------- | -------- | -------- | -| `content` | string | yes | the .gitlab-ci.yaml content| +| `content` | string | yes | the `.gitlab-ci.yaml` content| ```bash curl --header "Content-Type: application/json" https://gitlab.example.com/api/v4/ci/lint --data '{"content": "{ \"image\": \"ruby:2.6\", \"services\": [\"postgres\"], \"before_script\": [\"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}' diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index cc95689a65f..b73fe38f53e 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -23,36 +23,6 @@ GET /projects/:id/approvals ```json { - "approvers": [ - { - "user": { - "id": 5, - "name": "John Doe6", - "username": "user5", - "state":"active","avatar_url":"https://www.gravatar.com/avatar/4aea8cf834ed91844a2da4ff7ae6b491?s=80\u0026d=identicon","web_url":"http://localhost/user5" - } - } - ], - "approver_groups": [ - { - "group": { - "id": 1, - "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 - } - } - ], "approvals_before_merge": 2, "reset_approvals_on_push": true, "disable_overriding_approvers_per_merge_request": false @@ -75,7 +45,7 @@ POST /projects/:id/approvals | Attribute | Type | Required | Description | | ------------------------------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------- | | `id` | integer | yes | The ID of a project | -| `approvals_before_merge` | integer | no | How many approvals are required before an MR can be merged | +| `approvals_before_merge` | integer | no | How many approvals are required before an MR can be merged. Deprecated in 12.0 in favor of Approval Rules API. | | `reset_approvals_on_push` | boolean | no | Reset approvals on a new push | | `disable_overriding_approvers_per_merge_request` | boolean | no | Allow/Disallow overriding approvers per MR | | `merge_requests_author_approval` | boolean | no | Allow/Disallow authors from self approving merge requests; `true` means authors cannot self approve | @@ -83,20 +53,68 @@ POST /projects/:id/approvals ```json { - "approvers": [ - { - "user": { + "approvals_before_merge": 2, + "reset_approvals_on_push": true, + "disable_overriding_approvers_per_merge_request": false, + "merge_requests_author_approval": false, + "merge_requests_disable_committers_approval": false +} +``` + +### Get project-level rules + +>**Note:** This API endpoint is only available on 12.3 Starter and above. + +You can request information about a project's approval rules using the following endpoint: + +``` +GET /projects/:id/approval_rules +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|----------------------|---------|----------|-----------------------------------------------------------| +| `id` | integer | yes | The ID of a project | + +```json +[ + { + "id": 1, + "name": "security", + "rule_type": "regular", + "eligible_approvers": [ + { "id": 5, - "name": "John Doe6", - "username": "user5", - "state":"active","avatar_url":"https://www.gravatar.com/avatar/4aea8cf834ed91844a2da4ff7ae6b491?s=80\u0026d=identicon","web_url":"http://localhost/user5" + "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" } - } - ], - "approver_groups": [ - { - "group": { - "id": 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": "", @@ -111,18 +129,187 @@ POST /projects/:id/approvals "ldap_cn": null, "ldap_access": null } + ], + "contains_hidden_groups": false + } +] +``` + +### Create project-level rule + +>**Note:** This API endpoint is only available on 12.3 Starter and above. + +You can create project approval rules using the following endpoint: + +``` +POST /projects/:id/approval_rules +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|----------------------|---------|----------|-----------------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `name` | string | yes | The name of the approval rule | +| `approvals_required` | integer | yes | The number of required approvals for this rule | +| `user_ids` | Array | no | The ids of users as approvers | +| `group_ids` | Array | no | The ids of groups as approvers | + +```json +{ + "id": 1, + "name": "security", + "rule_type": "regular", + "eligible_approvers": [ + { + "id": 2, + "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_before_merge": 2, - "reset_approvals_on_push": true, - "disable_overriding_approvers_per_merge_request": false, - "merge_requests_author_approval": false, - "merge_requests_disable_committers_approval": false + "approvals_required": 1, + "users": [ + { + "id": 2, + "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 + } + ], + "contains_hidden_groups": false +} +``` + +### Update project-level rule + +>**Note:** This API endpoint is only available on 12.3 Starter and above. + +You can update project approval rules using the following endpoint: + +``` +PUT /projects/:id/approval_rules/:approval_rule_id +``` + +**Important:** Approvers and groups not in the `users`/`groups` param will be **removed** + +**Parameters:** + +| Attribute | Type | Required | Description | +|----------------------|---------|----------|-----------------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `approval_rule_id` | integer | yes | The ID of a approval rule | +| `name` | string | yes | The name of the approval rule | +| `approvals_required` | integer | yes | The number of required approvals for this rule | +| `user_ids` | Array | no | The ids of users as approvers | +| `group_ids` | Array | no | The ids of groups as approvers | + +```json +{ + "id": 1, + "name": "security", + "rule_type": "regular", + "eligible_approvers": [ + { + "id": 2, + "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": 1, + "users": [ + { + "id": 2, + "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 + } + ], + "contains_hidden_groups": false } ``` +### Delete project-level rule + +>**Note:** This API endpoint is only available on 12.3 Starter and above. + +You can delete project approval rules using the following endpoint: + +``` +DELETE /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 + ### Change allowed approvers +>**Note:** This API endpoint has been deprecated. Please use Approval Rule API instead. >**Note:** This API endpoint is only available on 10.6 Starter and above. If you are allowed to, you can change approvers and approver groups using @@ -227,8 +414,6 @@ GET /projects/:id/merge_requests/:merge_request_iid/approvals } } ], - "approvers": [], - "approver_groups": [] } ``` @@ -249,7 +434,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals |----------------------|---------|----------|--------------------------------------------| | `id` | integer | yes | The ID of a project | | `merge_request_iid` | integer | yes | The IID of MR | -| `approvals_required` | integer | yes | Approvals required before MR can be merged | +| `approvals_required` | integer | yes | Approvals required before MR can be merged. Deprecated in 12.0 in favor of Approval Rules API. | ```json { @@ -264,14 +449,13 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals "merge_status": "cannot_be_merged", "approvals_required": 2, "approvals_left": 2, - "approved_by": [], - "approvers": [], - "approver_groups": [] + "approved_by": [] } ``` ### Change allowed approvers for Merge Request +>**Note:** This API endpoint has been deprecated. Please use Approval Rule API instead. >**Note:** This API endpoint is only available on 10.6 Starter and above. If you are allowed to, you can change approvers and approver groups using @@ -341,6 +525,270 @@ PUT /projects/:id/merge_requests/:merge_request_iid/approvers } ``` +### Get merge request level rules + +>**Note:** This API endpoint is only available on 12.3 Starter and above. + +You can request information about a merge request's approval rules using the following endpoint: + +``` +GET /projects/:id/merge_requests/:merge_request_iid/approval_rules +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|---------------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `merge_request_iid` | integer | yes | The IID of MR | + +```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, + "source_rule": null, + "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 + } + ], + "contains_hidden_groups": false + } +] +``` + +### Create merge request level rule + +>**Note:** This API endpoint is only available on 12.3 Starter and above. + +You can create merge request approval rules using the following endpoint: + +``` +POST /projects/:id/merge_requests/:merge_request_iid/approval_rules +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|----------------------------|---------|----------|------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `merge_request_iid` | integer | yes | The IID of MR | +| `name` | string | yes | The name of the approval rule | +| `approvals_required` | integer | yes | The number of required approvals for this rule | +| `approval_project_rule_id` | integer | no | The ID of a project-level approval rule | +| `user_ids` | Array | no | The ids of users as approvers | +| `group_ids` | Array | no | The ids of groups as approvers | + +**Important:** When `approval_project_rule_id` is set, the `name`, `users` and +`groups` of project-level rule will be copied. The `approvals_required` specified +will be used. + +```json +{ + "id": 1, + "name": "security", + "rule_type": "regular", + "eligible_approvers": [ + { + "id": 2, + "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": 1, + "source_rule": null, + "users": [ + { + "id": 2, + "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 + } + ], + "contains_hidden_groups": false +} +``` + +### Update merge request level rule + +>**Note:** This API endpoint is only available on 12.3 Starter and above. + +You can update merge request approval rules using the following endpoint: + +``` +PUT /projects/:id/merge_request/:merge_request_iid/approval_rules/:approval_rule_id +``` + +**Important:** Approvers and groups not in the `users`/`groups` param will be **removed** + +**Important:** Updating a `report_approver` or `code_owner` rule is not allowed. +These are system generated rules. + +**Parameters:** + +| Attribute | Type | Required | Description | +|----------------------|---------|----------|------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `merge_request_iid` | integer | yes | The ID of MR | +| `approval_rule_id` | integer | yes | The ID of a approval rule | +| `name` | string | yes | The name of the approval rule | +| `approvals_required` | integer | yes | The number of required approvals for this rule | +| `user_ids` | Array | no | The ids of users as approvers | +| `group_ids` | Array | no | The ids of groups as approvers | + +```json +{ + "id": 1, + "name": "security", + "rule_type": "regular", + "eligible_approvers": [ + { + "id": 2, + "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": 1, + "source_rule": null, + "users": [ + { + "id": 2, + "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 + } + ], + "contains_hidden_groups": false +} +``` + +### Delete merge request level rule + +>**Note:** This API endpoint is only available on 12.3 Starter and above. + +You can delete merge request approval rules using the following endpoint: + +``` +DELETE /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id +``` + +**Important:** Deleting a `report_approver` or `code_owner` rule is not allowed. +These are system generated rules. + +**Parameters:** + +| Attribute | Type | Required | Description | +|---------------------|---------|----------|---------------------------| +| `id` | integer | yes | The ID of a project | +| `merge_request_iid` | integer | yes | The ID of MR | +| `approval_rule_id` | integer | yes | The ID of a approval rule | + ## Approve Merge Request >**Note:** This API endpoint is only available on 8.9 Starter and above. @@ -401,8 +849,6 @@ does not match, the response code will be `409`. } } ], - "approvers": [], - "approver_groups": [] } ``` diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 1ade46efb1c..0d030ef30c8 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -837,7 +837,7 @@ POST /projects/:id/merge_requests | `title` | string | yes | Title of MR | | `assignee_id` | integer | no | Assignee user ID | | `assignee_ids` | integer array | no | The ID of the user(s) to assign the MR to. Set to `0` or provide an empty value to unassign all assignees. | -| `description` | string | no | Description of MR | +| `description` | string | no | Description of MR. Limited to 1 000 000 characters. | | `target_project_id` | integer | no | The target project (numeric id) | | `labels` | string | no | Labels for MR as a comma-separated list | | `milestone_id` | integer | no | The global ID of a milestone | @@ -990,7 +990,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid | `assignee_ids` | integer array | no | The ID of the user(s) to assign the MR to. Set to `0` or provide an empty value to unassign all assignees. | | `milestone_id` | integer | no | The global ID of a milestone to assign the merge request to. Set to `0` or provide an empty value to unassign a milestone.| | `labels` | string | no | Comma-separated label names for a merge request. Set to an empty string to unassign all labels. | -| `description` | string | no | Description of MR | +| `description` | string | no | Description of MR. Limited to 1 000 000 characters. | | `state_event` | string | no | New state (close/reopen) | | `remove_source_branch` | boolean | no | Flag indicating if a merge request should remove the source branch when merging | | `squash` | boolean | no | Squash commits into a single commit when merging | @@ -1127,7 +1127,7 @@ the `approvals_before_merge` parameter: ## Delete a merge request -Only for admins and project owners. Soft deletes the merge request in question. +Only for admins and project owners. Deletes the merge request in question. ``` DELETE /projects/:id/merge_requests/:merge_request_iid diff --git a/doc/api/notes.md b/doc/api/notes.md index acbf0334563..1f5baf7d0e1 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -113,7 +113,7 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) - `issue_iid` (required) - The IID of an issue -- `body` (required) - The content of a note +- `body` (required) - The content of a note. Limited to 1 000 000 characters. - `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) ```bash @@ -133,7 +133,7 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) - `issue_iid` (required) - The IID of an issue - `note_id` (required) - The ID of a note -- `body` (required) - The content of a note +- `body` (required) - The content of a note. Limited to 1 000 000 characters. ```bash curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note @@ -231,7 +231,7 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) - `snippet_id` (required) - The ID of a snippet -- `body` (required) - The content of a note +- `body` (required) - The content of a note. Limited to 1 000 000 characters. - `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z ```bash @@ -251,7 +251,7 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) - `snippet_id` (required) - The ID of a snippet - `note_id` (required) - The ID of a note -- `body` (required) - The content of a note +- `body` (required) - The content of a note. Limited to 1 000 000 characters. ```bash curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/notes?body=note @@ -354,7 +354,7 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) - `merge_request_iid` (required) - The IID of a merge request -- `body` (required) - The content of a note +- `body` (required) - The content of a note. Limited to 1 000 000 characters. - `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z ### Modify existing merge request note @@ -370,7 +370,7 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) - `merge_request_iid` (required) - The IID of a merge request - `note_id` (required) - The ID of a note -- `body` (required) - The content of a note +- `body` (required) - The content of a note. Limited to 1 000 000 characters. ```bash curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note @@ -472,7 +472,7 @@ Parameters: | --------- | -------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | -| `body` | string | yes | The content of a note | +| `body` | string | yes | The content of a note. Limited to 1 000 000 characters. | ```bash curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note @@ -493,7 +493,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `note_id` | integer | yes | The ID of a note | -| `body` | string | yes | The content of a note | +| `body` | string | yes | The content of a note. Limited to 1 000 000 characters. | ```bash curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index c1588f2292a..58d9d1cd4d8 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -81,6 +81,27 @@ Parameters: - `code` (required) - The content of a snippet - `visibility` (required) - The snippet's visibility +Example request: + +```bash +curl --request POST https://gitlab.com/api/v4/projects/:id/snippets \ + --header "PRIVATE-TOKEN: <your access token>" \ + --header "Content-Type: application/json" \ + -d @snippet.json +``` + +`snippet.json` used in the above example request: + +```json +{ + "title" : "Example Snippet Title", + "description" : "More verbose snippet description", + "file_name" : "example.txt", + "code" : "source code \n with multiple lines\n", + "visibility" : "private" +} +``` + ## Update snippet Updates an existing project snippet. The user must have permission to change an existing snippet. @@ -99,6 +120,27 @@ Parameters: - `code` (optional) - The content of a snippet - `visibility` (optional) - The snippet's visibility +Example request: + +```bash +curl --request PUT https://gitlab.com/api/v4/projects/:id/snippets \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --header "Content-Type: application/json" \ + -d @snippet.json +``` + +`snippet.json` used in the above example request: + +```json +{ + "title" : "Updated Snippet Title", + "description" : "More verbose snippet description", + "file_name" : "new_filename.txt", + "code" : "updated source code \n with multiple lines\n", + "visibility" : "private" +} +``` + ## Delete snippet Deletes an existing project snippet. This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found. @@ -112,6 +154,13 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project's snippet +Example request: + +```bash +curl --request DELETE https://gitlab.com/api/v4/projects/:id/snippets \ + --header "PRIVATE-TOKEN: <your_access_token>" +``` + ## Snippet content Returns the raw project snippet as plain text. @@ -125,6 +174,13 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project's snippet +Example request: + +```bash +curl --request GET https://gitlab.com/api/v4/projects/:id/snippets/:snippet_id/raw \ + --header "PRIVATE-TOKEN: <your_access_token>" +``` + ## Get user agent details > [Introduced][ce-29508] in GitLab 9.4. @@ -140,6 +196,8 @@ GET /projects/:id/snippets/:snippet_id/user_agent_detail | `id` | Integer | yes | The ID of a project | | `snippet_id` | Integer | yes | The ID of a snippet | +Example request: + ```bash curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/snippets/2/user_agent_detail ``` diff --git a/doc/api/projects.md b/doc/api/projects.md index 70df44ec0fd..cf28ea84704 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -852,9 +852,10 @@ Get the users list of a project. GET /projects/:id/users ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `search` | string | no | Search for specific users | +| Attribute | Type | Required | Description | +| ------------ | ------------- | -------- | ----------- | +| `search` | string | no | Search for specific users | +| `skip_users` | integer array | no | Filter out users with the specified IDs | ```json [ @@ -2036,13 +2037,13 @@ Read more in the [Project Badges](project_badges.md) documentation. The non-default [issue and merge request description templates](../user/project/description_templates.md) are managed inside the project's repository. So you can manage them via the API through the [Repositories API](repositories.md) and the [Repository Files API](repository_files.md). -## Download snapshot of a git repository +## Download snapshot of a Git repository > Introduced in GitLab 10.7 This endpoint may only be accessed by an administrative user. -Download a snapshot of the project (or wiki, if requested) git repository. This +Download a snapshot of the project (or wiki, if requested) Git repository. This snapshot is always in uncompressed [tar](https://en.wikipedia.org/wiki/Tar_(computing)) format. diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 9309306ba05..ffb4a70168b 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -185,6 +185,7 @@ Example response: { "access_level": 30, "access_level_description": "Developers + Maintainers" + } ], "unprotect_access_levels": [ { @@ -217,6 +218,7 @@ Example response: "user_id": null, "group_id": null, "access_level_description": "Developers + Maintainers" + } ], "unprotect_access_levels": [ { @@ -232,7 +234,7 @@ Example response: ### Example with user / group level access **(STARTER)** Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect` array should take the -form `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md#restricting-push-and-merge-access-to-certain-users-starter) and were [added to the API in ][ee-3516] in GitLab 10.3 EE. +form `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md#restricting-push-and-merge-access-to-certain-users-starter) and were [added to the API in](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3516) in GitLab 10.3 EE. ```bash curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&allowed_to_push%5B%5D%5Buser_id%5D=1' @@ -242,29 +244,29 @@ Example response: ```json { - "name":"*-stable", + "name": "*-stable", "push_access_levels": [ { - "access_level":null, - "user_id":1, - "group_id":null, - "access_level_description":"Administrator" + "access_level": null, + "user_id": 1, + "group_id": null, + "access_level_description": "Administrator" } ], "merge_access_levels": [ { - "access_level":40, - "user_id":null, - "group_id":null, - "access_level_description":"Maintainers" + "access_level": 40, + "user_id": null, + "group_id": null, + "access_level_description": "Maintainers" } ], "unprotect_access_levels": [ { - "access_level":40, - "user_id":null, - "group_id":null, - "access_level_description":"Maintainers" + "access_level": 40, + "user_id": null, + "group_id": null, + "access_level_description": "Maintainers" } ] } @@ -286,5 +288,3 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" 'https://git | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch | - -[ee-3516]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3516 "ProtectedBranches API handles per user/group granularity" diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index b292c9dd7de..513dc996c91 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -246,7 +246,7 @@ error message. Possible causes for a failed commit include: user tried to make an empty commit; - the branch was updated by a Git push while the file edit was in progress. -Currently gitlab-shell has a boolean return code, preventing GitLab from specifying the error. +Currently GitLab Shell has a boolean return code, preventing GitLab from specifying the error. ## Delete existing file in repository diff --git a/doc/api/settings.md b/doc/api/settings.md index 248d19461f6..6cf06bde575 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -68,6 +68,9 @@ Example response: "allow_local_requests_from_hooks_and_services": true, "allow_local_requests_from_web_hooks_and_services": true, "allow_local_requests_from_system_hooks": false + "asset_proxy_enabled": true, + "asset_proxy_url": "https://assets.example.com", + "asset_proxy_whitelist": ["example.com", "*.example.com", "your-instance.com"] } ``` @@ -121,6 +124,10 @@ Example response: "domain_whitelist": [], "domain_blacklist_enabled" : false, "domain_blacklist" : [], + "external_authorization_service_enabled": true, + "external_authorization_service_url": "https://authorize.me", + "external_authorization_service_default_label": "default", + "external_authorization_service_timeout": 0.5, "user_oauth_applications": true, "after_sign_out_path": "", "container_registry_token_expire_delay": 5, @@ -141,6 +148,9 @@ Example response: "user_show_add_ssh_key_message": true, "file_template_project_id": 1, "local_markdown_version": 0, + "asset_proxy_enabled": true, + "asset_proxy_url": "https://assets.example.com", + "asset_proxy_whitelist": ["example.com", "*.example.com", "your-instance.com"], "geo_node_allowed_ips": "0.0.0.0/0, ::/0", "allow_local_requests_from_hooks_and_services": true, "allow_local_requests_from_web_hooks_and_services": true, @@ -151,20 +161,13 @@ Example response: Users on GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/) may also see these parameters: -- `external_authorization_service_enabled` -- `external_authorization_service_url` -- `external_authorization_service_default_label` -- `external_authorization_service_timeout` - `file_template_project_id` - `geo_node_allowed_ips` +- `geo_status_timeout` Example responses: **(PREMIUM ONLY)** ```json - "external_authorization_service_enabled": true, - "external_authorization_service_url": "https://authorize.me", - "external_authorization_service_default_label": "default", - "external_authorization_service_timeout": 0.5, "file_template_project_id": 1, "geo_node_allowed_ips": "0.0.0.0/0, ::/0" ``` @@ -184,57 +187,66 @@ are listed in the descriptions of the relevant settings. | `akismet_enabled` | boolean | no | (**If enabled, requires:** `akismet_api_key`) Enable or disable akismet spam protection. | | `allow_group_owners_to_manage_ldap` | boolean | no | **(PREMIUM)** Set to `true` to allow group owners to manage LDAP | | `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_web_hooks_and_services` | boolean | no | Allow requests to the local network from web 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>. | +| `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. | | `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. | | `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. | -| `clientside_sentry_dsn` | string | required by: `clientside_sentry_enabled` | Clientside Sentry Data Source Name. | -| `clientside_sentry_enabled` | boolean | no | (**If enabled, requires:** `clientside_sentry_dsn`) Enable Sentry error reporting for the client side. | +| `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. | | `default_branch_protection` | integer | no | Determine if developers can push to master. Can take: `0` _(not protected, both developers and maintainers can push new commits, force push, or delete the branch)_, `1` _(partially protected, developers and maintainers can push new commits, but cannot force push or delete the branch)_ or `2` _(fully protected, developers cannot push new commits, but maintainers can; no-one can force push or delete the branch)_ as a parameter. Default is `2`. | | `default_group_visibility` | string | no | What visibility level new groups receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | -| `default_project_visibility` | string | no | What visibility level new projects receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | +| `default_project_creation` | integer | no | Default project creation protection. Can take: `0` _(No one)_, `1` _(Maintainers)_ or `2` _(Developers + Maintainers)_| | `default_projects_limit` | integer | no | Project limit per user. Default is `100000`. | +| `default_project_visibility` | string | no | What visibility level new projects receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `default_snippet_visibility` | string | no | What visibility level new snippets receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | +| `diff_max_patch_bytes` | integer | no | Maximum diff patch size (Bytes). | | `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_blacklist` | array of strings | required by: `domain_blacklist_enabled` | 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_blacklist_enabled` | boolean | no | (**If enabled, requires:** `domain_blacklist`) Allows blocking sign-ups from emails from specific domains. | | `domain_whitelist` | array of strings | no | Force people to use only corporate emails for sign-up. Default is `null`, meaning there is no restriction. | -| `outbound_local_requests_whitelist` | array of strings | no | Define a list of trusted domains or ip addresses to which local requests are allowed when local requests for hooks and services are disabled. | `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. | | `ed25519_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ED25519 key. Default is `0` (no restriction). `-1` disables ED25519 keys. | -| `elasticsearch_aws` | boolean | no | **(PREMIUM)** Enable the use of AWS hosted Elasticsearch | | `elasticsearch_aws_access_key` | string | no | **(PREMIUM)** AWS IAM access key | +| `elasticsearch_aws` | boolean | no | **(PREMIUM)** Enable the use of AWS hosted Elasticsearch | | `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_experimental_indexer` | boolean | no | **(PREMIUM)** Use the experimental elasticsearch indexer. More info: <https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer> | | `elasticsearch_indexing` | boolean | no | **(PREMIUM)** Enable Elasticsearch indexing | -| `elasticsearch_search` | boolean | no | **(PREMIUM)** Enable Elasticsearch search | -| `elasticsearch_url` | string | no | **(PREMIUM)** The url to use for connecting to Elasticsearch. Use a comma-separated list to support cluster (e.g., `http://localhost:9200, http://localhost:9201"`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). | | `elasticsearch_limit_indexing` | boolean | no | **(PREMIUM)** Limit Elasticsearch to index certain namespaces and projects | -| `elasticsearch_project_ids` | array of integers | no | **(PREMIUM)** The projects to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | | `elasticsearch_namespace_ids` | array of integers | no | **(PREMIUM)** The namespaces to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | +| `elasticsearch_project_ids` | array of integers | no | **(PREMIUM)** The projects to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | +| `elasticsearch_search` | boolean | no | **(PREMIUM)** Enable Elasticsearch search | +| `elasticsearch_url` | string | no | **(PREMIUM)** The url to use for connecting to Elasticsearch. Use a comma-separated list to support cluster (e.g., `http://localhost:9200, http://localhost:9201"`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). | | `email_additional_text` | string | no | **(PREMIUM)** Additional text added to the bottom of every email for legal/auditing/compliance reasons | | `email_author_in_body` | boolean | no | Some email servers do not support overriding the email sender name. Enable this option to include the name of the author of the issue, merge request or comment in the email body instead. | | `enabled_git_access_protocol` | string | no | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `nil` to allow both protocols. | | `enforce_terms` | boolean | no | (**If enabled, requires:** `terms`) Enforce application ToS to all users. | -| `external_auth_client_cert` | string | no | **(PREMIUM)** (**If enabled, requires:** `external_auth_client_key`) The certificate to use to authenticate with the external authorization service | -| `external_auth_client_key` | string | required by: `external_auth_client_cert` | **(PREMIUM)** Private key for the certificate when authentication is required for the external authorization service, this is encrypted when stored | -| `external_auth_client_key_pass` | string | no | **(PREMIUM)** Passphrase to use for the private key when authenticating with the external service this is encrypted when stored | -| `external_authorization_service_enabled` | boolean | no | **(PREMIUM)** (**If enabled, requires:** `external_authorization_service_default_label`, `external_authorization_service_timeout` and `external_authorization_service_url` ) Enable using an external authorization service for accessing projects | -| `external_authorization_service_default_label` | string | required by: `external_authorization_service_enabled` | **(PREMIUM)** The default classification label to use when requesting authorization and no classification label has been specified on the project | -| `external_authorization_service_timeout` | float | required by: `external_authorization_service_enabled` | **(PREMIUM)** The timeout after which an authorization request is aborted, in seconds. When a request times out, access is denied to the user. (min: 0.001, max: 10, step: 0.001) | -| `external_authorization_service_url` | string | required by: `external_authorization_service_enabled` | **(PREMIUM)** URL to which authorization requests will be directed | +| `external_auth_client_cert` | string | no | (**If enabled, requires:** `external_auth_client_key`) The certificate to use to authenticate with the external authorization service | +| `external_auth_client_key_pass` | string | no | Passphrase to use for the private key when authenticating with the external service this is encrypted when stored | +| `external_auth_client_key` | string | required by: `external_auth_client_cert` | Private key for the certificate when authentication is required for the external authorization service, this is encrypted when stored | +| `external_authorization_service_default_label` | string | required by: `external_authorization_service_enabled` | The default classification label to use when requesting authorization and no classification label has been specified on the project | +| `external_authorization_service_enabled` | boolean | no | (**If enabled, requires:** `external_authorization_service_default_label`, `external_authorization_service_timeout` and `external_authorization_service_url` ) Enable using an external authorization service for accessing projects | +| `external_authorization_service_timeout` | float | required by: `external_authorization_service_enabled` | The timeout after which an authorization request is aborted, in seconds. When a request times out, access is denied to the user. (min: 0.001, max: 10, step: 0.001) | +| `external_authorization_service_url` | string | required by: `external_authorization_service_enabled` | URL to which authorization requests will be directed | | `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. | -| `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_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. (EXPERIMENTAL) | | `help_page_hide_commercial_content` | boolean | no | Hide marketing-related entries from help. | @@ -244,13 +256,15 @@ are listed in the descriptions of the relevant settings. | `hide_third_party_offers` | boolean | no | Do not display offers from third parties within GitLab. | | `home_page_url` | string | no | Redirect to this URL when not logged in. | | `housekeeping_bitmaps_enabled` | boolean | required by: `housekeeping_enabled` | Enable Git pack file bitmap creation. | -| `housekeeping_enabled` | boolean | no | (**If enabled, requires:** `housekeeping_bitmaps_enabled`, `housekeeping_full_repack_period`, `housekeeping_gc_period`, and `housekeeping_incremental_repack_period`) Enable or disable git housekeeping. | +| `housekeeping_enabled` | boolean | no | (**If enabled, requires:** `housekeeping_bitmaps_enabled`, `housekeeping_full_repack_period`, `housekeeping_gc_period`, and `housekeeping_incremental_repack_period`) Enable or disable Git housekeeping. | | `housekeeping_full_repack_period` | integer | required by: `housekeeping_enabled` | Number of Git pushes after which an incremental `git repack` is run. | | `housekeeping_gc_period` | integer | required by: `housekeeping_enabled` | Number of Git pushes after which `git gc` is run. | | `housekeeping_incremental_repack_period` | integer | required by: `housekeeping_enabled` | Number of Git pushes after which an incremental `git repack` is run. | | `html_emails_enabled` | boolean | no | Enable HTML emails. | +| `import_sources` | array of strings | no | Sources to allow project import from, possible values: `github`, `bitbucket`, `bitbucket_server`, `gitlab`, `google_code`, `fogbugz`, `git`, `gitlab_project`, `gitea`, `manifest`, and `phabricator`. | + | `instance_statistics_visibility_private` | boolean | no | When set to `true` Instance statistics will only be available to admins. | -| `import_sources` | array of strings | no | Sources to allow project import from, possible values: `github`, `bitbucket`, `gitlab`, `google_code`, `fogbugz`, `git`, and `gitlab_project`. | +| `local_markdown_version` | integer | no | Increase this value when any cached markdown should be invalidated. | | `max_artifacts_size` | integer | no | Maximum artifacts size in MB | | `max_attachment_size` | integer | no | Limit attachment size in MB | | `max_pages_size` | integer | no | Maximum size of pages repositories in MB | @@ -266,6 +280,7 @@ are listed in the descriptions of the relevant settings. | `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. | +| `outbound_local_requests_whitelist` | array of strings | no | Define a list of trusted domains or ip addresses to which local requests are allowed when local requests for hooks and services are disabled. | `pages_domain_verification_enabled` | boolean | no | Require users to prove ownership of custom domains. Domain verification is an essential security measure for public GitLab sites. Users are required to demonstrate they control a domain before it is enabled. | | `password_authentication_enabled_for_git` | boolean | no | Enable authentication for Git over HTTP(S) via a GitLab account password. Default is `true`. | | `password_authentication_enabled_for_web` | boolean | no | Enable authentication for the web interface via a GitLab account password. Default is `true`. | @@ -277,10 +292,12 @@ are listed in the descriptions of the relevant settings. | `polling_interval_multiplier` | decimal | no | Interval multiplier used by endpoints that perform polling. Set to `0` to disable polling. | | `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. | `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_size_limit` | integer | no | **(PREMIUM)** Size limit per repository (MB) | | `repository_storages` | array of strings | no | A list of names of enabled storage paths, taken from `gitlab.yml`. New projects will be created in one of these stores, chosen at random. | @@ -292,13 +309,17 @@ are listed in the descriptions of the relevant settings. | `shared_runners_enabled` | boolean | no | (**If enabled, requires:** `shared_runners_text` and `shared_runners_minutes`) Enable shared runners for new projects. | | `shared_runners_minutes` | integer | required by: `shared_runners_enabled` | **(PREMIUM)** Set the maximum number of pipeline minutes that a group can use on shared Runners per month. | | `shared_runners_text` | string | required by: `shared_runners_enabled` | Shared runners text. | -| `sign_in_text` | string | no | Text on the login page. | | `signin_enabled` | string | no | (Deprecated: Use `password_authentication_enabled_for_web` instead) Flag indicating if password authentication is enabled for the web interface. | +| `sign_in_text` | string | no | Text on the login page. | | `signup_enabled` | boolean | no | Enable registration. Default is `true`. | | `slack_app_enabled` | boolean | no | **(PREMIUM)** (**If enabled, requires:** `slack_app_id`, `slack_app_secret` and `slack_app_secret`) Enable Slack app. | | `slack_app_id` | string | required by: `slack_app_enabled` | **(PREMIUM)** The app id of the Slack-app. | | `slack_app_secret` | string | required by: `slack_app_enabled` | **(PREMIUM)** The app secret of the Slack-app. | | `slack_app_verification_token` | string | required by: `slack_app_enabled` | **(PREMIUM)** The verification token of the Slack-app. | +| `snowplow_collector_hostname` | string | required by: `snowplow_enabled` | The Snowplow collector hostname. (e.g. `snowplow.trx.gitlab.net`) | +| `snowplow_cookie_domain` | string | no | The Snowplow cookie domain. (e.g. `.gitlab.com`) | +| `snowplow_enabled` | boolean | no | Enable snowplow tracking. | +| `snowplow_site_id` | string | no | The Snowplow site name / application id. (e.g. `gitlab`) | | `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to `0` for unlimited time. | | `terms` | text | required by: `enforce_terms` | (**Required by:** `enforce_terms`) Markdown content for the ToS. | | `throttle_authenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_api_period_in_seconds` and `throttle_authenticated_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (e.g. from crawlers or abusive bots). | @@ -317,12 +338,8 @@ are listed in the descriptions of the relevant settings. | `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. | +| `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. | | `version_check_enabled` | boolean | no | Let GitLab inform you when an update is available. | -| `local_markdown_version` | integer | no | Increase this value when any cached markdown should be invalidated. | -| `snowplow_enabled` | boolean | no | Enable snowplow tracking. | -| `snowplow_collector_hostname` | string | required by: `snowplow_enabled` | The Snowplow collector hostname. (e.g. `snowplow.trx.gitlab.net`) | -| `snowplow_site_id` | string | no | The Snowplow site name / application id. (e.g. `gitlab`) | -| `snowplow_cookie_domain` | string | no | The Snowplow cookie domain. (e.g. `.gitlab.com`) | -| `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`. | +| `web_ide_clientside_preview_enabled` | boolean | no | Client side evaluation (allow live previews of JavaScript projects in the Web IDE using CodeSandbox client side evaluation). | diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 1ce0b1e7a62..f90447e124e 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -165,15 +165,15 @@ Parameters: |:--------------|:-------|:---------|:---------------------------------------------------| | `title` | string | yes | Title of a snippet. | | `file_name` | string | yes | Name of a snippet file. | -| `code` | string | yes | Content of a snippet. | +| `content` | string | yes | Content of a snippet. | | `description` | string | no | Description of a snippet. | -| `visibility` | string | yes | Snippet's [visibility](#snippet-visibility-level). | +| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level). | Example request: ```sh curl --request POST \ - --data '{"title": "This is a snippet", "code": "Hello world", "description": "Hello World snippet", "file_name": "test.txt", "visibility": "internal" }' \ + --data '{"title": "This is a snippet", "content": "Hello world", "description": "Hello World snippet", "file_name": "test.txt", "visibility": "internal" }' \ --header 'Content-Type: application/json' \ --header "PRIVATE-TOKEN: valid_api_token" \ https://gitlab.example.com/api/v4/snippets @@ -222,14 +222,14 @@ Parameters: | `title` | string | no | Title of a snippet. | | `file_name` | string | no | Name of a snippet file. | | `description` | string | no | Description of a snippet. | -| `code` | string | no | Content of a snippet. | +| `content` | string | no | Content of a snippet. | | `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level). | Example request: ```sh curl --request PUT \ - --data '{"title": "foo", "code": "bar"}' \ + --data '{"title": "foo", "content": "bar"}' \ --header 'Content-Type: application/json' \ --header "PRIVATE-TOKEN: valid_api_token" \ https://gitlab.example.com/api/v4/snippets/1 diff --git a/doc/api/tags.md b/doc/api/tags.md index af86ba961f4..1d874fea1f8 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -112,7 +112,7 @@ Parameters: - `tag_name` (required) - The name of a tag - `ref` (required) - Create tag using commit SHA, another tag name, or branch name. - `message` (optional) - Creates annotated tag. -- `release_description` (optional) - Add release notes to the git tag and store it in the GitLab database. +- `release_description` (optional) - Add release notes to the Git tag and store it in the GitLab database. ```json { @@ -166,7 +166,7 @@ Parameters: ## Create a new release -Add release notes to the existing git tag. If there +Add release notes to the existing Git tag. If there already exists a release for the given tag, status code `409` is returned. ``` diff --git a/doc/ci/README.md b/doc/ci/README.md index ca9d0aa61bd..90d0e6a7dc6 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -131,7 +131,7 @@ Its feature set is listed on the table below according to DevOps stages. | **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 Management](../user/application_security/license_management/index.md) **(ULTIMATE)** | Search your project dependencies for their licenses. | +| [License Compliance](../user/application_security/license_compliance/index.md) **(ULTIMATE)** | Search your project dependencies for their licenses. | | [Security Test reports](../user/project/merge_requests/index.md#security-reports-ultimate) **(ULTIMATE)** | Check for app vulnerabilities. | ## Examples @@ -174,7 +174,7 @@ been necessary. These are: #### 12.0 -- [Use refspec to clone/fetch git +- [Use refspec to clone/fetch Git repository](https://gitlab.com/gitlab-org/gitlab-runner/issues/4069). - [Old cache configuration](https://gitlab.com/gitlab-org/gitlab-runner/issues/4070). diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index f8151e3e18c..ab9fa517e23 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -172,6 +172,29 @@ job: cache: {} ``` +### Inherit global config, but override specific settings per job + +You can override cache settings without overwriting the global cache by using +[anchors](../yaml/README.md#anchors). For example, if you want to override the +`policy` for one job: + +```yaml +cache: &global_cache + key: ${CI_COMMIT_REF_SLUG} + paths: + - node_modules/ + - public/ + - vendor/ + policy: pull-push + +job: + cache: + # inherit all global cache settings + <<: *global_cache + # override the policy + policy: pull +``` + For more fine tuning, read also about the [`cache: policy`](../yaml/README.md#cachepolicy). 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 f639e3dadee..fa56503072d 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -11,35 +11,10 @@ GitLab. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a video on [Using GitLab CI/CD pipelines with GitHub repositories](https://www.youtube.com/watch?v=qgl3F2j-1cI). -## Connect with GitHub integration - -If the [GitHub integration](../../integration/github.md) has been enabled by your GitLab -administrator: - -1. In GitLab create a **CI/CD for external repo** project and select - **GitHub**. - -  - -1. Once authenticated, you will be redirected to a list of your repositories to - connect. Click **Connect** to select the repository. - -  - -1. In GitHub, add a `.gitlab-ci.yml` to [configure GitLab CI/CD](../quick_start/README.md). - -GitLab will: - -1. Import the project. -1. Enable [Pull Mirroring](../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter). -1. Enable [GitHub project integration](../../user/project/integrations/github.md). -1. Create a web hook on GitHub to notify GitLab of new commits. - -CAUTION: **Caution:** -Due to a 10-token limitation on the [GitHub OAuth Implementation](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#creating-multiple-tokens-for-oauth-apps), -if you import more than 10 times, your oldest imported project's token will be -revoked. See issue [#9147](https://gitlab.com/gitlab-org/gitlab-ee/issues/9147) -for more information. +NOTE: **Note:** +Because of [GitHub limitations](https://gitlab.com/gitlab-org/gitlab-ee/issues/9147), +[GitHub OAuth](../../integration/github.html#enabling-github-oauth) +cannot be used to authenticate with GitHub as an external CI/CD repository. ## Connect with Personal Access Token @@ -47,8 +22,7 @@ NOTE: **Note:** Personal access tokens can only be used to connect GitHub.com repositories to GitLab. -If you are not using the [GitHub integration](../../integration/github.md), you can -still perform a one-off authorization with GitHub to grant GitLab access your +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 @@ -69,18 +43,19 @@ repositories: 1. In GitHub, add a `.gitlab-ci.yml` to [configure GitLab CI/CD](../quick_start/README.md). -GitLab will import the project, enable [Pull Mirroring](../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter), enable -[GitHub project integration](../../user/project/integrations/github.md), and create a web hook -on GitHub to notify GitLab of new commits. +GitLab will: + +1. Import the project. +1. Enable [Pull Mirroring](../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter) +1. Enable [GitHub project integration](../../user/project/integrations/github.md) +1. Create a web hook on GitHub to notify GitLab of new commits. ## Connect manually NOTE: **Note:** -To use **GitHub Enterprise** with **GitLab.com** use this method. +To use **GitHub Enterprise** with **GitLab.com**, use this method. -If the [GitHub integration](../../integration/github.md) is not enabled, or is enabled -for a different GitHub instance, you GitLab CI/CD can be manually enabled for -your repository: +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 diff --git a/doc/ci/ci_cd_for_external_repos/img/github_repo_list.png b/doc/ci/ci_cd_for_external_repos/img/github_repo_list.png Binary files differdeleted file mode 100644 index 73579dd3cf1..00000000000 --- a/doc/ci/ci_cd_for_external_repos/img/github_repo_list.png +++ /dev/null diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index e54be9f3bd9..60e3120ba33 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -36,7 +36,7 @@ It has a pipeline that looks like the following: | ----- | ---- | ------ | | build_a | test_a | deploy_a | | build_b | test_b | deploy_b | -| build_c | test_c | deploy_c | +| build_c | test_c | deploy_c | | build_d | test_d | deploy_d | Using a DAG, you can relate the `_a` jobs to each other separately from the `_b` jobs, @@ -65,7 +65,7 @@ as quickly as possible. Relationships are defined between jobs using the [`needs:` keyword](../yaml/README.md#needs). Note that `needs:` also works with the [parallel](../yaml/README.md#parallel) keyword, -giving your powerful options for parallelization within your pipeline. +giving you powerful options for parallelization within your pipeline. ## Limitations diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 2cbad5f101c..7c173970324 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -575,6 +575,42 @@ For private and internal projects: docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY ``` +### Using docker-in-docker image from Container Registry + +If you want to use your own Docker images for docker-in-docker there are a few things you need to do in addition to the steps in the [docker-in-docker](#use-docker-in-docker-workflow-with-docker-executor) section: + +1. Update the `image` and `service` to point to your registry. +1. Add a service [alias](https://docs.gitlab.com/ee/ci/yaml/#servicesalias) + +Below is an example of how your `.gitlab-ci.yml` should look like, assuming you have it configured with [TLS enabled](#tls-enabled): + +```yaml + build: + image: $CI_REGISTRY/group/project/docker:19.03.1 + services: + - name: $CI_REGISTRY/group/project/docker:19.03.1-dind + alias: docker + variables: + # 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 + # build container. + DOCKER_TLS_CERTDIR: "/certs" + DOCKER_DRIVER: overlay2 + stage: build + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests +``` + +If you forget to set the service alias the `docker:19.03.1` image won't find the +`dind` service, and an error like the following is thrown: + +```sh +$ docker info +error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host +``` + ### Container Registry examples If you're using docker-in-docker on your Runners, this is how your `.gitlab-ci.yml` diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index d5056568dff..489791141ed 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -495,14 +495,6 @@ that runner. ## Define an image from a private Container Registry -> **Notes:** -> -> - This feature requires GitLab Runner **1.8** or higher -> - For GitLab Runner versions **>= 0.6, <1.8** there was a partial -> support for using private registries, which required manual configuration -> of credentials on runner's host. We recommend to upgrade your Runner to -> at least version **1.8** if you want to use private registries. - To access private container registries, the GitLab Runner process can use: - [Statically defined credentials](#using-statically-defined-credentials). That is, a username and password for a specific registry. @@ -525,6 +517,17 @@ it's provided as an environment variable. This is because GitLab Runnner uses ** `config.toml` configuration and doesn't interpolate **ANY** environment variables at runtime. +### Requirements and limitations + +- This feature requires GitLab Runner **1.8** or higher. +- For GitLab Runner versions **>= 0.6, <1.8** there was a partial + support for using private registries, which required manual configuration + of credentials on runner's host. We recommend to upgrade your Runner to + at least version **1.8** if you want to use private registries. +- Not available for [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html), + follow <https://gitlab.com/gitlab-org/gitlab-runner/issues/2673> for + details. + ### Using statically-defined credentials There are two approaches that you can take in order to access a diff --git a/doc/ci/examples/license_management.md b/doc/ci/examples/license_management.md index 53e38111bf3..0d12c9a20f2 100644 --- a/doc/ci/examples/license_management.md +++ b/doc/ci/examples/license_management.md @@ -1,5 +1,5 @@ --- -redirect_to: '../../user/application_security/license_management/index.md' +redirect_to: '../../user/application_security/license_compliance/index.md' --- -This document was moved to [another location](../../user/application_security/license_management/index.md). +This document was moved to [another location](../../user/application_security/license_compliance/index.md). diff --git a/doc/ci/jenkins/index.md b/doc/ci/jenkins/index.md index f8a3fab88e3..ace1204511e 100644 --- a/doc/ci/jenkins/index.md +++ b/doc/ci/jenkins/index.md @@ -32,7 +32,7 @@ There are some high level differences between the products worth mentioning: ## Groovy vs. YAML -Jenkins Pipelines are based on [Groovy](https://groovy-lang.org/), so the pipeline specification is written as code. +Jenkins Pipelines are based on [Groovy](https://groovy-lang.org/), so the pipeline specification is written as code. GitLab works a bit differently, we use the more highly structured [YAML](https://yaml.org/) format, which places scripting elements inside of `script:` blocks separate from the pipeline specification itself. @@ -56,7 +56,7 @@ rspec: - .in-docker script: - rake rspec -``` +``` ## Artifact publishing @@ -143,7 +143,7 @@ default: GitLab CI also lets you define stages, but is a little bit more free-form to configure. The GitLab [`stages` keyword](../yaml/README.md#stages) is a top level setting that enumerates the list of stages, but you are not required to nest individual jobs underneath -the `stages` section. Any job defined in the `.gitlab-ci.yml` can be made a part of any stage through use of the +the `stages` section. Any job defined in the `.gitlab-ci.yml` can be made a part of any stage through use of the [`stage:` keyword](../yaml/README.md#stage). Note that, unless otherwise specified, every pipeline is instantiated with a `build`, `test`, and `deploy` stage @@ -229,4 +229,4 @@ our very powerful [`only/except` rules system](../yaml/README.md#onlyexcept-basi ```yaml my_job: only: branches -```
\ No newline at end of file +``` 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 ad07c662965..126e12e460f 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 @@ -35,10 +35,9 @@ get out of WIP status or resolve merge conflicts as soon as possible. ## Requirements and limitations -Pipelines for merged results require: +Pipelines for merged results require a [GitLab Runner][runner] 11.9 or newer. -- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer. -- [Gitaly](https://gitlab.com/gitlab-org/gitaly) 1.21.0 or newer. +[runner]: https://gitlab.com/gitlab-org/gitlab-runner In addition, pipelines for merged results have the following limitations: 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 80a1c264bc4..7998b0452be 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 @@ -141,4 +141,4 @@ please ask administrator to execute the following commands: > sudo gitlab-rails console # Login to Rails console of GitLab instance. > Feature.enabled?(:merge_trains_enabled) # Check if it's enabled or not. > Feature.disable(:merge_trains_enabled) # Disable the feature flag. -```
\ No newline at end of file +``` diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index cb8d383f7d9..61f260cb70d 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -205,5 +205,5 @@ Some features are not implemented yet. For example, support for environments. - `stage` - `allow_failure` - `only` and `except` -- `when` +- `when` (only with `on_success`, `on_failure`, and `always` values) - `extends` diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index ed8d0e3bc35..eaa6efc526d 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -377,6 +377,10 @@ This functionality is only available: - For users with at least Developer access. - If the the stage contains [manual actions](#manual-actions-from-pipeline-graphs). +## Most Recent Pipeline + +There's a link to the latest pipeline for the last commit of a given branch at `/project/pipelines/[branch]/latest`. Also, `/project/pipelines/latest` will redirect you to the latest pipeline for the last commit on the project's default branch. + ## Security on protected branches A strict security model is enforced when pipelines are executed on diff --git a/doc/ci/quick_start/img/build_log.png b/doc/ci/quick_start/img/build_log.png Binary files differindex 2bf0992c50e..16698629edc 100644 --- a/doc/ci/quick_start/img/build_log.png +++ b/doc/ci/quick_start/img/build_log.png diff --git a/doc/ci/quick_start/img/builds_status.png b/doc/ci/quick_start/img/builds_status.png Binary files differindex 58978e23978..b4aeeb988d2 100644 --- a/doc/ci/quick_start/img/builds_status.png +++ b/doc/ci/quick_start/img/builds_status.png diff --git a/doc/ci/quick_start/img/pipelines_status.png b/doc/ci/quick_start/img/pipelines_status.png Binary files differindex 06d1559f5d2..39a77a26b25 100644 --- a/doc/ci/quick_start/img/pipelines_status.png +++ b/doc/ci/quick_start/img/pipelines_status.png diff --git a/doc/ci/quick_start/img/runners_activated.png b/doc/ci/quick_start/img/runners_activated.png Binary files differindex cd83c1a7e4c..ac09e1d0137 100644 --- a/doc/ci/quick_start/img/runners_activated.png +++ b/doc/ci/quick_start/img/runners_activated.png diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 8474d4ef66e..abb503c6516 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -88,7 +88,7 @@ visit the project you want to make the Runner work for in GitLab: ## Registering a group Runner -Creating a group Runner requires Maintainer permissions for the group. To create a +Creating a group Runner requires Owner permissions for the group. To create a group Runner visit the group you want to make the Runner work for in GitLab: 1. Go to **Settings > CI/CD** to obtain the token @@ -124,9 +124,9 @@ To lock/unlock a Runner: ## Assigning a Runner to another project -If you are Maintainer on a project where a specific Runner is assigned to, and the +If you are an Owner on a project where a specific Runner is assigned to, and the Runner is not [locked only to that project](#locking-a-specific-runner-from-being-enabled-for-other-projects), -you can enable the Runner also on any other project where you have Maintainer permissions. +you can enable the Runner also on any other project where you have Owner permissions. To enable/disable a Runner in your project: @@ -156,8 +156,7 @@ An admin can enable/disable a specific Runner for projects: ## Protected Runners -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13194) -> in GitLab 10.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13194) in GitLab 10.0. You can protect Runners from revealing sensitive information. Whenever a Runner is protected, the Runner picks only jobs created on @@ -250,7 +249,7 @@ When you [register a Runner][register], its default behavior is to **only pick** [tagged jobs](../yaml/README.md#tags). NOTE: **Note:** -Maintainer [permissions](../../user/permissions.md) are required to change the +Owner [permissions](../../user/permissions.md) are required to change the Runner settings. To make a Runner pick untagged jobs: diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index 9ea113969c8..ce69a7df885 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -27,8 +27,8 @@ variables: NOTE: **Note:** The `MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` variables can't be set in the GitLab UI. -To set them, assign them to a variable [in the UI](../variables/README.md#via-the-ui), -and then assign that variable to the +To set them, assign them to a variable [in the UI](../variables/README.md#via-the-ui), +and then assign that variable to the `MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` variables in your `.gitlab-ci.yml`. And then configure your application to use the database, for example: diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index d9f022a7125..b6aebd3bd78 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -76,7 +76,7 @@ to access it. This is where an SSH key pair comes in handy. ## without extra base64 encoding. ## https://gitlab.com/gitlab-examples/ssh-private-key/issues/1#note_48526556 ## - - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - > /dev/null + - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - ## ## Create the SSH directory and give it the right permissions diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index 2a382f18038..f62a4660713 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -58,8 +58,7 @@ Read more about the [pipelines trigger API][trigapi]. #### When a pipeline depends on the artifacts of another pipeline **(PREMIUM)** -> The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346] - in [GitLab Premium][ee] 9.5. +> The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346] in [GitLab Premium][ee] 9.5. With the introduction of dependencies between different projects, one of them may need to access artifacts created by a previous one. This process @@ -271,7 +270,7 @@ Old triggers, created before GitLab 9.0 will be 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 -removed with one of the future versions of GitLab. +removed with one of the future versions of GitLab. [ee-2017]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2017 [ee-2346]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2346 diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index d741482b662..5a15b907da0 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -94,7 +94,10 @@ This means that the value of the variable will be hidden in job logs, though it must match certain requirements to do so: - The value must be in a single line. -- The value must only consist of characters from the Base64 alphabet ([RFC4648](https://tools.ietf.org/html/rfc4648)) with the addition of `@` and `:`. +- The value must only consist of characters from the Base64 alphabet (RFC4648). + + [In GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-ce/issues/63043) + and newer, `@` and `:` are also valid values. - The value must be at least 8 characters long. - The value must not use variables. @@ -509,7 +512,7 @@ Below you can find supported syntax reference: 1. Checking for an empty variable Examples: - + - `$VARIABLE == ""` - `$VARIABLE != ""` (introduced in GitLab 11.11) diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 2be93433b36..38276de6791 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -100,6 +100,7 @@ The following table lists available parameters for jobs: | [`stage`](#stage) | Defines a job stage (default: `test`). | | [`only`](#onlyexcept-basic) | Limit when jobs are created. Also available: [`only:refs`, `only:kubernetes`, `only:variables`, and `only:changes`](#onlyexcept-advanced). | | [`except`](#onlyexcept-basic) | Limit when jobs are not created. Also available: [`except:refs`, `except:kubernetes`, `except:variables`, and `except:changes`](#onlyexcept-advanced). | +| [`rules`](#rules) | List of coniditions to evaluate and determine selected attributes of a build and whether or not it is created. May not be used alongside `only`/`except`. | [`tags`](#tags) | List of tags which are used to select Runner. | | [`allow_failure`](#allow_failure) | Allow job to fail. Failed job doesn't contribute to commit status. | | [`when`](#when) | When to run job. Also available: `when:manual` and `when:delayed`. | @@ -386,7 +387,7 @@ In addition, `only` and `except` allow the use of special keywords: | `triggers` | For pipelines created using a trigger token. | | `web` | For pipelines created using **Run pipeline** button in GitLab UI (under your project's **Pipelines**). | | `merge_requests` | When a merge request is created or updated (See [pipelines for merge requests](../merge_request_pipelines/index.md)). | -| `chats` | For jobs created using a [GitLab ChatOps](../chatops/README.md) command. | +| `chat` | For jobs created using a [GitLab ChatOps](../chatops/README.md) command. | In the example below, `job` will run only for refs that start with `issue-`, whereas all branches will be skipped: @@ -518,10 +519,24 @@ Four keys are available: - `changes` - `kubernetes` -If you use multiple keys under `only` or `except`, they act as an AND. The logic is: +If you use multiple keys under `only` or `except`, the keys will be evaluated as a +single conjoined expression. That is: + +- `only:` means "include this job if all of the conditions match". +- `except:` means "exclude this job if any of the conditions match". + +With `only`, individual keys are logically joined by an AND: > (any of refs) AND (any of variables) AND (any of changes) AND (if kubernetes is active) +`except` is implemented as a negation of this complete expression: + +> NOT((any of refs) AND (any of variables) AND (any of changes) AND (if kubernetes is active)) + +This, more intuitively, means the keys join by an OR. A functionally equivalent expression: + +> (any of refs) OR (any of variables) OR (any of changes) OR (if kubernetes is active) + #### `only:refs`/`except:refs` > `refs` policy introduced in GitLab 10.0. @@ -676,6 +691,125 @@ In the scenario above, if a merge request is created or updated that changes either files in `service-one` directory or the `Dockerfile`, GitLab creates and triggers the `docker build service one` job. +### `rules` + +Using `rules` allows for a list of individual rule objects to be evaluated +*in order*, until one matches and dynamically provides attributes to the job. + +Available rule clauses include: + +- `if` (similar to [`only:variables`](#onlyvariablesexceptvariables)). +- `changes` (same as [`only:changes`](#onlychangesexceptchanges)). + +For example, using `if`: + +```yaml +job: + script: "echo Hello, Rules!" + rules: + - if: '$CI_MERGE_REQUEST_TARGET_BRANCH == "master"' # This rule will be evaluated + when: always + - if: '$VAR =~ /pattern/' # This rule will only be evaluated if the first does not match + when: manual + - when: on_success # A Rule entry with no conditional clauses evaluates to true. If neither of the first two Rules match, this one will and set job:when to "on_success" +``` + +If the first rule does not match, further rules will be evaluated sequentially +until a match is found. The above configuration will specify that `job` should +be built and run for every pipeline on merge requests targeting `master`, +regardless of the status of other builds. + +#### `rules:if` + +`rules:if` differs slightly from `only:variables` by accepting only a single +expression string, rather than an array of them. Any set of expressions to be +evaluated should be conjoined into a single expression using `&&` or `||`. For example: + +```yaml +job: + script: "echo Hello, Rules!" + rules: + - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH == "master"' # This rule will be evaluated + when: always + - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH =~ /^feature/' # This rule will only be evaluated if the target branch is not "master" + when: manual + - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH' # If neither of the first two match but the simple presence does, we set to "on_success" by default +``` + +If none of the provided rules match, the job will be set to `when:never`, and +not included in the pipeline. If `rules:when` is not included in the configuration +at all, the behavior defaults to `job:when`, which continues to default to +`on_success`. + +#### `rules:changes` + +`changes` works exactly the same way as [`only`/`except`](#onlychangesexceptchanges), +accepting an array of paths. The following configuration configures a job to be +run manually if `Dockerfile` has changed OR `$VAR == "string value"`. Otherwise +it is set to `when:on_success` by the last rule, where 0 clauses evaluate as +vacuously true. + +```yaml +docker build: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + rules: + - changes: # Will include the job and set to when:manual if any of the follow paths match a modified file. + - Dockerfile + when: manual + - if: '$VAR == "string value"' + when: manual # Will include the job and set to when:manual if the expression evaluates to true, after the `changes:` rule fails to match. + - when: on_success # If neither of the first rules match, set to on_success + +``` + +#### Complex Rule Clauses + +To conjoin `if` and `changes` clauses with an AND, use them in the same rule. +Here we run the job manually if `Dockerfile` or any file in `docker/scripts/` +has changed AND `$VAR == "string value"`. Otherwise, the job will not be +included in the pipeline. + +```yaml +docker build: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + rules: + - if: '$VAR == "string value"' + changes: # Will include the job and set to when:manual if any of the follow paths match a modified file. + - Dockerfile + - docker/scripts/* + when: manual + # - when: never would be redundant here, this is implied any time rules are listed. +``` + +The only clauses currently available are `if` and `changes`. Keywords such as +`branches` or `refs` that are currently available for `only`/`except` are not +yet available in `rules` as they are being individually considered for their +usage and behavior in the newer context. + +#### Permitted attributes + +The only job attributes currently set by `rules` are `when` and `start_in`, if +`when` is set to `delayed`. A job will be included in a pipeline if `when` is +evaluated to any value except `never`. + +Delayed jobs require a `start_in` value, so rule objects do as well. For example: + +```yaml +docker build: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + rules: + - changes: # Will include the job and delay 3 hours when the Dockerfile has changed + - Dockerfile + when: delayed + start_in: '3 hours' + - when: on_success # Otherwise include the job and set to run normally + +``` + +Additional Job configuration may be added to rules in the future, if something +useful isn't available, please open an issue on +[Gitlab CE](https://www.gitlab.com/gitlab-org/gitlab-ce/issues). + ### `tags` `tags` is used to select specific Runners from the list of all Runners that are @@ -1565,10 +1699,10 @@ dashboards. > Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above. -The `license_management` report collects [Licenses](../../user/project/merge_requests/license_management.md) +The `license_management` report collects [Licenses](../../user/application_security/license_compliance/index.md) as artifacts. -The collected License Management report will be uploaded to GitLab as an artifact and will +The collected License Compliance report will be uploaded to GitLab as an artifact and will be automatically shown in merge requests, pipeline view and provide data for security dashboards. @@ -1686,19 +1820,19 @@ mac:build: linux:rspec: stage: test - needs: [linux:build] + needs: ["linux:build"] linux:rubocop: stage: test - needs: [linux:build] + needs: ["linux:build"] mac:rspec: stage: test - needs: [mac:build] + needs: ["mac:build"] mac:rubocop: stage: test - needs: [mac:build] + needs: ["mac:build"] production: stage: deploy @@ -1721,7 +1855,7 @@ This example creates three paths of execution: 1. If `needs:` is set to point to a job that is not instantiated because of `only/except` rules or otherwise does not exist, the job will fail. -1. Note that one day one of the launch, we are temporarily limiting the +1. Note that on day one of the launch, we are temporarily limiting the maximum number of jobs that a single job can need in the `needs:` array. Track our [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/7541) for details on the current limit. @@ -1734,8 +1868,8 @@ This example creates three paths of execution: in the first stage (see [gitlab-ce#65504](https://gitlab.com/gitlab-org/gitlab-ce/issues/65504)). 1. If `needs:` refers to a job that is marked as `parallel:`. the current job will depend on all parallel jobs created. -1. `needs:` is similar to `dependencies:` in that needs to use jobs from - prior stages, this means that it is impossible to create circular +1. `needs:` is similar to `dependencies:` in that it needs to use jobs from + prior stages, meaning it is impossible to create circular dependencies or depend on jobs in the current stage (see [gitlab-ce#65505](https://gitlab.com/gitlab-org/gitlab-ce/issues/65505)). 1. Related to the above, stages must be explicitly defined for all jobs that have the keyword `needs:` or are referred to by one. @@ -1765,9 +1899,8 @@ job1: ### `retry` -> [Introduced][ce-12909] in GitLab 9.5. -> [Behaviour expanded](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21758) -> in GitLab 11.5 to control on which failures to retry. +> - [Introduced][ce-12909] in GitLab 9.5. +> - [Behaviour expanded](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21758) in GitLab 11.5 to control on which failures to retry. `retry` allows you to configure how many times a job is going to be retried in case of a failure. @@ -1856,6 +1989,7 @@ Marking a job to be run in parallel requires only a simple addition to your conf script: rspec + parallel: 5 ``` + TIP: **Tip:** Parallelize tests suites across parallel jobs. Different languages have different tools to facilitate this. diff --git a/doc/customization/libravatar.md b/doc/customization/libravatar.md index 1c3bf877fa1..6d96528f760 100644 --- a/doc/customization/libravatar.md +++ b/doc/customization/libravatar.md @@ -14,7 +14,7 @@ server. ## Configuration -In the [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122), set +In the [`gitlab.yml` gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122), set the configuration options as follows: ### For HTTP @@ -46,7 +46,7 @@ For example, you host a service on `http://libravatar.example.com` and the `http://libravatar.example.com/avatar/%{hash}?s=%{size}&d=identicon` -### Omnibus-gitlab example +### Omnibus GitLab example In `/etc/gitlab/gitlab.rb`: diff --git a/doc/customization/system_header_and_footer_messages.md b/doc/customization/system_header_and_footer_messages.md index 15830be4e8a..bd2de3e201c 100644 --- a/doc/customization/system_header_and_footer_messages.md +++ b/doc/customization/system_header_and_footer_messages.md @@ -8,7 +8,7 @@ Navigate to the **Admin** area and go to the **Appearance** page. Under **System header and footer** insert your header message and/or footer message. Both background and font color of the header and footer are customizable. -You can also apply the header and footer messages to gitlab emails, +You can also apply the header and footer messages to GitLab emails, by checking the **Enable header and footer in emails** checkbox. Note that color settings will only be applied within the app interface and not to emails diff --git a/doc/development/README.md b/doc/development/README.md index 6281bb809ff..3912a828dec 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -5,7 +5,7 @@ description: 'Learn how to contribute to GitLab.' # Contributor and Development Docs -## Get started! +## Get started - Set up GitLab's development environment with [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/README.md) - [GitLab contributing guide](contributing/index.md) @@ -65,6 +65,7 @@ description: 'Learn how to contribute to GitLab.' - [Repository mirroring](repository_mirroring.md) - [Git LFS](lfs.md) - [Developing against interacting components or features](interacting_components.md) +- [File uploads](uploads.md) ## Performance guides @@ -116,6 +117,7 @@ description: 'Learn how to contribute to GitLab.' ## Case studies - [Database case study: Filtering by label](filtering_by_label.md) +- [Database case study: Namespaces storage statistics](namespaces_storage_statistics.md) ## Integration guides diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index 0866d3baeeb..61576236c96 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -51,7 +51,7 @@ allowed. – <https://github.com/ruby-grape/grape#declared> -### Exclude params from parent namespaces! +### Exclude params from parent namespaces > By default `declared(params)`includes parameters that were defined in all parent namespaces. @@ -64,7 +64,7 @@ In most cases you will want to exclude params from the parent namespaces: declared(params, include_parent_namespaces: false) ``` -### When to use `declared(params)`? +### When to use `declared(params)` You should always use `declared(params)` when you pass the params hash as arguments to a method call. diff --git a/doc/development/architecture.md b/doc/development/architecture.md index 87405bc2fec..2adca2dae28 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -12,21 +12,21 @@ New versions of GitLab are released in stable branches and the master branch is For information, see the [GitLab Release Process](https://gitlab.com/gitlab-org/release/docs/tree/master#gitlab-release-process). -Both EE and CE require some add-on components called gitlab-shell and Gitaly. These components are available from the [gitlab-shell](https://gitlab.com/gitlab-org/gitlab-shell/tree/master) and [gitaly](https://gitlab.com/gitlab-org/gitaly/tree/master) repositories respectively. New versions are usually tags but staying on the master branch will give you the latest stable version. New releases are generally around the same time as GitLab CE releases with exception for informal security updates deemed critical. +Both EE and CE require some add-on components called GitLab Shell and Gitaly. These components are available from the [GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell/tree/master) and [Gitaly](https://gitlab.com/gitlab-org/gitaly/tree/master) repositories respectively. New versions are usually tags but staying on the master branch will give you the latest stable version. New releases are generally around the same time as GitLab CE releases with exception for informal security updates deemed critical. ## Components A typical install of GitLab will be on GNU/Linux. It uses Nginx or Apache as a web front end to proxypass the Unicorn web server. By default, communication between Unicorn and the front end is via a Unix domain socket but forwarding requests via TCP is also supported. The web front end accesses `/home/git/gitlab/public` bypassing the Unicorn server to serve static pages, uploads (e.g. avatar images or attachments), and precompiled assets. GitLab serves web pages and a [GitLab API](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/api) using the Unicorn web server. It uses Sidekiq as a job queue which, in turn, uses redis as a non-persistent database backend for job information, meta data, and incoming jobs. -We also support deploying GitLab on Kubernetes using our [gitlab Helm chart](https://docs.gitlab.com/charts/). +We also support deploying GitLab on Kubernetes using our [GitLab Helm chart](https://docs.gitlab.com/charts/). -The GitLab web app uses MySQL or PostgreSQL for persistent database information (e.g. users, permissions, issues, other meta data). GitLab stores the bare git repositories it serves in `/home/git/repositories` by default. It also keeps default branch and hook information with the bare repository. +The GitLab web app uses PostgreSQL for persistent database information (e.g. users, permissions, issues, other meta data). GitLab stores the bare Git repositories it serves in `/home/git/repositories` by default. It also keeps default branch and hook information with the bare repository. -When serving repositories over HTTP/HTTPS GitLab utilizes the GitLab API to resolve authorization and access as well as serving git objects. +When serving repositories over HTTP/HTTPS GitLab utilizes the GitLab API to resolve authorization and access as well as serving Git objects. -The add-on component gitlab-shell serves repositories over SSH. It manages the SSH keys within `/home/git/.ssh/authorized_keys` which should not be manually edited. gitlab-shell accesses the bare repositories through Gitaly to serve git objects and communicates with redis to submit jobs to Sidekiq for GitLab to process. gitlab-shell queries the GitLab API to determine authorization and access. +The add-on component GitLab Shell serves repositories over SSH. It manages the SSH keys within `/home/git/.ssh/authorized_keys` which should not be manually edited. GitLab Shell accesses the bare repositories through Gitaly to serve Git objects and communicates with redis to submit jobs to Sidekiq for GitLab to process. GitLab Shell queries the GitLab API to determine authorization and access. -Gitaly executes git operations from gitlab-shell and the GitLab web app, and provides an API to the GitLab web app to get attributes from git (e.g. title, branches, tags, other meta data), and to get blobs (e.g. diffs, commits, files). +Gitaly executes Git operations from GitLab Shell and the GitLab web app, and provides an API to the GitLab web app to get attributes from Git (e.g. title, branches, tags, other meta data), and to get blobs (e.g. diffs, commits, files). You may also be interested in the [production architecture of GitLab.com](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/). @@ -130,7 +130,7 @@ Component statuses are linked to configuration documentation for each component. | [NGINX](#nginx) | Routes requests to appropriate components, terminates SSL | [✅][nginx-omnibus] | [✅][nginx-charts] | [⚙][nginx-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#service-architecture) | [⤓][nginx-source] | ❌ | CE & EE | | [Unicorn (GitLab Rails)](#unicorn) | Handles requests for the web interface and API | [✅][unicorn-omnibus] | [✅][unicorn-charts] | [✅][unicorn-charts] | [✅](../user/gitlab_com/index.md#unicorn) | [⚙][unicorn-source] | [✅][gitlab-yml] | CE & EE | | [Sidekiq](#sidekiq) | Background jobs processor | [✅][sidekiq-omnibus] | [✅][sidekiq-charts] | [✅](https://docs.gitlab.com/charts/charts/gitlab/sidekiq/index.html) | [✅](../user/gitlab_com/index.md#sidekiq) | [✅][gitlab-yml] | [✅][gitlab-yml] | CE & EE | -| [Gitaly](#gitaly) | Git RPC service for handling all git calls made by GitLab | [✅][gitaly-omnibus] | [✅][gitaly-charts] | [✅][gitaly-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#service-architecture) | [⚙][gitaly-source] | ✅ | CE & EE | +| [Gitaly](#gitaly) | Git RPC service for handling all Git calls made by GitLab | [✅][gitaly-omnibus] | [✅][gitaly-charts] | [✅][gitaly-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#service-architecture) | [⚙][gitaly-source] | ✅ | CE & EE | | [GitLab Workhorse](#gitlab-workhorse) | Smart reverse proxy, handles large HTTP requests | [✅][workhorse-omnibus] | [✅][workhorse-charts] | [✅][workhorse-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#service-architecture) | [⚙][workhorse-source] | ✅ | CE & EE | | [GitLab Shell](#gitlab-shell) | Handles `git` over SSH sessions | [✅][shell-omnibus] | [✅][shell-charts] | [✅][shell-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#service-architecture) | [⚙][shell-source] | [✅][gitlab-yml] | CE & EE | | [GitLab Pages](#gitlab-pages) | Hosts static websites | [⚙][pages-omnibus] | [❌][pages-charts] | [❌][pages-charts] | [✅](../user/gitlab_com/index.md#gitlab-pages) | [⚙][pages-source] | [⚙][pages-gdk] | CE & EE | @@ -185,7 +185,7 @@ GitLab can be considered to have two layers from a process perspective: - Layer: Monitoring - Process: `alertmanager` -[Alert manager](https://prometheus.io/docs/alerting/alertmanager/) is a tool provided by Prometheus that _"handles alerts sent by client applications such as the Prometheus server. It takes care of deduplicating, grouping, and routing them to the correct receiver integration such as email, PagerDuty, or OpsGenie. It also takes care of silencing and inhibition of alerts."_ You can read more in [issue gitlab-ce#45740](https://gitlab.com/gitlab-org/gitlab-ce/issues/45740) about what we will be alerting on. +[Alert manager](https://prometheus.io/docs/alerting/alertmanager/) is a tool provided by Prometheus that _"handles alerts sent by client applications such as the Prometheus server. It takes care of deduplicating, grouping, and routing them to the correct receiver integration such as email, PagerDuty, or OpsGenie. It also takes care of silencing and inhibition of alerts."_ You can read more in [issue #45740](https://gitlab.com/gitlab-org/gitlab-ce/issues/45740) about what we will be alerting on. #### Certificate management @@ -223,12 +223,12 @@ Elasticsearch is a distributed RESTful search engine built for the cloud. Gitaly is a service designed by GitLab to remove our need for NFS for Git storage in distributed deployments of GitLab (think GitLab.com or High Availability Deployments). As of 11.3.0, this service handles all Git level access in GitLab. You can read more about the project [in the project's readme](https://gitlab.com/gitlab-org/gitaly). -#### Gitlab Geo +#### GitLab Geo - Configuration: [Omnibus][geo-omnibus], [Charts][geo-charts], [GDK][geo-gdk] - Layer: Core Service (Processor) -#### Gitlab Monitor +#### GitLab Monitor - [Project page](https://gitlab.com/gitlab-org/gitlab-monitor) - Configuration: [Omnibus][gitlab-monitor-omnibus], [Charts][gitlab-monitor-charts] @@ -237,7 +237,7 @@ Gitaly is a service designed by GitLab to remove our need for NFS for Git storag GitLab Monitor is a process designed in house that allows us to export metrics about GitLab application internals to Prometheus. You can read more [in the project's readme](https://gitlab.com/gitlab-org/gitlab-monitor). -#### Gitlab Pages +#### GitLab Pages - Configuration: [Omnibus][pages-omnibus], [Charts][pages-charts], [Source][pages-source], [GDK][pages-gdk] - Layer: Core Service (Processor) @@ -246,7 +246,7 @@ GitLab Pages is a feature that allows you to publish static websites directly fr You can use it either for personal or business websites, such as portfolios, documentation, manifestos, and business presentations. You can also attribute any license to your content. -#### Gitlab Runner +#### GitLab Runner - [Project page](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/README.md) - Configuration: [Omnibus][runner-omnibus], [Charts][runner-charts], [Source][runner-source], [GDK][runner-gdk] @@ -256,7 +256,7 @@ GitLab Runner runs tests and sends the results to GitLab. GitLab CI is the open-source continuous integration service included with GitLab that coordinates the testing. The old name of this project was GitLab CI Multi Runner but please use "GitLab Runner" (without CI) from now on. -#### Gitlab Shell +#### GitLab Shell - [Project page](https://gitlab.com/gitlab-org/gitlab-shell/blob/master/README.md) - Configuration: [Omnibus][shell-omnibus], [Charts][shell-charts], [Source][shell-source], [GDK][gitlab-yml] @@ -264,7 +264,7 @@ GitLab CI is the open-source continuous integration service included with GitLab [GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell) is a program designed at GitLab to handle ssh-based `git` sessions, and modifies the list of authorized keys. GitLab Shell is not a Unix shell nor a replacement for Bash or Zsh. -#### Gitlab Workhorse +#### GitLab Workhorse - [Project page](https://gitlab.com/gitlab-org/gitlab-workhorse/blob/master/README.md) - Configuration: [Omnibus][workhorse-omnibus], [Charts][workhorse-charts], [Source][workhorse-source] @@ -475,7 +475,7 @@ It's important to understand the distinction as some processes are used in both When making a request to an HTTP Endpoint (think `/users/sign_in`) the request will take the following path through the GitLab Service: - nginx - Acts as our first line reverse proxy. -- gitlab-workhorse - This determines if it needs to go to the Rails application or somewhere else to reduce load on Unicorn. +- GitLab Workhorse - This determines if it needs to go to the Rails application or somewhere else to reduce load on Unicorn. - unicorn - Since this is a web request, and it needs to access the application it will go to Unicorn. - Postgres/Gitaly/Redis - Depending on the type of request, it may hit these services to store or retrieve data. @@ -493,13 +493,13 @@ TODO ## System Layout -When referring to `~git` in the pictures it means the home directory of the git user which is typically `/home/git`. +When referring to `~git` in the pictures it means the home directory of the Git user which is typically `/home/git`. GitLab is primarily installed within the `/home/git` user home directory as `git` user. Within the home directory is where the gitlabhq server software resides as well as the repositories (though the repository location is configurable). The bare repositories are located in `/home/git/repositories`. GitLab is a ruby on rails application so the particulars of the inner workings can be learned by studying how a ruby on rails application works. -To serve repositories over SSH there's an add-on application called gitlab-shell which is installed in `/home/git/gitlab-shell`. +To serve repositories over SSH there's an add-on application called GitLab Shell which is installed in `/home/git/gitlab-shell`. ### Installation Folder Summary @@ -511,11 +511,19 @@ To summarize here's the [directory structure of the `git` user home directory](. ps aux | grep '^git' ``` -GitLab has several components to operate. As a system user (i.e. any user that is not the `git` user) it requires a persistent database (MySQL/PostreSQL) and redis database. It also uses Apache httpd or Nginx to proxypass Unicorn. As the `git` user it starts Sidekiq and Unicorn (a simple ruby HTTP server running on port `8080` by default). Under the GitLab user there are normally 4 processes: `unicorn_rails master` (1 process), `unicorn_rails worker` (2 processes), `sidekiq` (1 process). +GitLab has several components to operate. It requires a persistent database +(PostgreSQL) and redis database, and uses Apache httpd or Nginx to proxypass +Unicorn. All these components should run as different system users to GitLab +(e.g., `postgres`, `redis` and `www-data`, instead of `git`). + +As the `git` user it starts Sidekiq and Unicorn (a simple ruby HTTP server +running on port `8080` by default). Under the GitLab user there are normally 4 +processes: `unicorn_rails master` (1 process), `unicorn_rails worker` +(2 processes), `sidekiq` (1 process). ### Repository access -Repositories get accessed via HTTP or SSH. HTTP cloning/push/pull utilizes the GitLab API and SSH cloning is handled by gitlab-shell (previously explained). +Repositories get accessed via HTTP or SSH. HTTP cloning/push/pull utilizes the GitLab API and SSH cloning is handled by GitLab Shell (previously explained). ## Troubleshooting @@ -523,28 +531,28 @@ See the README for more information. ### Init scripts of the services -The GitLab init script starts and stops Unicorn and Sidekiq. +The GitLab init script starts and stops Unicorn and Sidekiq: ``` /etc/init.d/gitlab Usage: service gitlab {start|stop|restart|reload|status} ``` -Redis (key-value store/non-persistent database) +Redis (key-value store/non-persistent database): ``` /etc/init.d/redis Usage: /etc/init.d/redis {start|stop|status|restart|condrestart|try-restart} ``` -SSH daemon +SSH daemon: ``` /etc/init.d/sshd Usage: /etc/init.d/sshd {start|stop|restart|reload|force-reload|condrestart|try-restart|status} ``` -Web server (one of the following) +Web server (one of the following): ``` /etc/init.d/httpd @@ -554,54 +562,46 @@ $ /etc/init.d/nginx Usage: nginx {start|stop|restart|reload|force-reload|status|configtest} ``` -Persistent database (one of the following) +Persistent database: ``` -/etc/init.d/mysqld -Usage: /etc/init.d/mysqld {start|stop|status|restart|condrestart|try-restart|reload|force-reload} - $ /etc/init.d/postgresql Usage: /etc/init.d/postgresql {start|stop|restart|reload|force-reload|status} [version ..] ``` ### Log locations of the services -gitlabhq (includes Unicorn and Sidekiq logs) +gitlabhq (includes Unicorn and Sidekiq logs): - `/home/git/gitlab/log/` contains `application.log`, `production.log`, `sidekiq.log`, `unicorn.stdout.log`, `git_json.log` and `unicorn.stderr.log` normally. -gitlab-shell +GitLab Shell: - `/home/git/gitlab-shell/gitlab-shell.log` -ssh +SSH: - `/var/log/auth.log` auth log (on Ubuntu). - `/var/log/secure` auth log (on RHEL). -nginx +nginx: - `/var/log/nginx/` contains error and access logs. -Apache httpd +Apache httpd: - [Explanation of Apache logs](https://httpd.apache.org/docs/2.2/logs.html). - `/var/log/apache2/` contains error and output logs (on Ubuntu). - `/var/log/httpd/` contains error and output logs (on RHEL). -redis +Redis: - `/var/log/redis/redis.log` there are also log-rotated logs there. -PostgreSQL +PostgreSQL: - `/var/log/postgresql/*` -MySQL - -- `/var/log/mysql/*` -- `/var/log/mysql.*` - ### GitLab specific config files GitLab has configuration files located in `/home/git/gitlab/config/*`. Commonly referenced config files include: @@ -610,7 +610,7 @@ GitLab has configuration files located in `/home/git/gitlab/config/*`. Commonly - `unicorn.rb` - Unicorn web server settings. - `database.yml` - Database connection settings. -gitlab-shell has a configuration file at `/home/git/gitlab-shell/config.yml`. +GitLab Shell has a configuration file at `/home/git/gitlab-shell/config.yml`. ### Maintenance Tasks diff --git a/doc/development/automatic_ce_ee_merge.md b/doc/development/automatic_ce_ee_merge.md index 98b8a48abf4..c2700461467 100644 --- a/doc/development/automatic_ce_ee_merge.md +++ b/doc/development/automatic_ce_ee_merge.md @@ -173,13 +173,13 @@ Now, every time you create an MR for CE and EE: ## How we run the Automatic CE->EE merge at GitLab -At GitLab, we use the [Merge Train](https://gitlab.com/gitlab-org/merge-train) -project to keep our [gitlab-ee](https://gitlab.com/gitlab-org/gitlab-ee) -repository updated with commits from -[gitlab-ce](https://gitlab.com/gitlab-org/gitlab-ce). +At GitLab, we use the [Merge Train](https://gitlab.com/gitlab-org/merge-train) +project to keep our [GitLab EE](https://gitlab.com/gitlab-org/gitlab-ee) +repository updated with commits from +[GitLab CE](https://gitlab.com/gitlab-org/gitlab-ce). We have a mirror of the [Merge Train](https://gitlab.com/gitlab-org/merge-train) -project [configured](https://ops.gitlab.net/gitlab-org/merge-train) to run an +project [configured](https://ops.gitlab.net/gitlab-org/merge-train) to run an automatic CE->EE merge job every twenty minutes as a scheduled CI job. The [configured](https://ops.gitlab.net/gitlab-org/merge-train) Merge Train project is only accessible to authorized GitLab staff. @@ -200,7 +200,7 @@ code. ### Why merge automatically? As we work towards continuous deployments and a single repository for both CE -and EE, we need to first make sure that all CE changes make their way into CE as +and EE, we need to first make sure that all CE changes make their way into EE as fast as possible. Past experiences and data have shown that periodic CE to EE merge requests do not scale, and often take a very long time to complete. For example, [in this diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index 642dac614c7..3fd95537eaa 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -294,7 +294,7 @@ to migrate you database down and up, which can result in other background migrations being called. That means that using `spy` test doubles with `have_received` is encouraged, instead of using regular test doubles, because your expectations defined in a `it` block can conflict with what is being -called in RSpec hooks. See [gitlab-org/gitlab-ce#35351][issue-rspec-hooks] +called in RSpec hooks. See [issue #35351][issue-rspec-hooks] for more details. ## Best practices diff --git a/doc/development/build_test_package.md b/doc/development/build_test_package.md index c5f6adfeaeb..21891f70d73 100644 --- a/doc/development/build_test_package.md +++ b/doc/development/build_test_package.md @@ -3,7 +3,7 @@ While developing a new feature or modifying an existing one, it is helpful if an installable package (or a docker image) containing those changes is available for testing. For this very purpose, a manual job is provided in the GitLab CI/CD -pipeline that can be used to trigger a pipeline in the omnibus-gitlab repository +pipeline that can be used to trigger a pipeline in the Omnibus GitLab repository that will create: - A deb package for Ubuntu 16.04, available as a build artifact, and @@ -12,7 +12,7 @@ that will create: (images titled `gitlab-ce` and `gitlab-ee` respectively and image tag is the commit which triggered the pipeline). -When you push a commit to either the gitlab-ce or gitlab-ee project, the +When you push a commit to either the GitLab CE or GitLab EE project, the pipeline for that commit will have a `build-package` manual action you can trigger. @@ -30,9 +30,9 @@ branch `0-1-stable`, modify the content of `GITALY_SERVER_VERSION` to `0-1-stable` and push the commit. This will create a manual job that can be used to trigger the build. -## Specifying the branch in omnibus-gitlab repository +## Specifying the branch in Omnibus GitLab repository -In scenarios where a configuration change is to be introduced and omnibus-gitlab +In scenarios where a configuration change is to be introduced and Omnibus GitLab repository already has the necessary changes in a specific branch, you can build a package against that branch through an environment variable named `OMNIBUS_BRANCH`. To do this, specify that environment variable with the name of diff --git a/doc/development/changelog.md b/doc/development/changelog.md index bd07a01e782..814624c7586 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -35,6 +35,7 @@ the `author` field. GitLab team members **should not**. - Any user-facing change **should** have a changelog entry. Example: "GitLab now uses system fonts for all text." +- Any docs-only changes **should not** have a changelog entry. - Any change behind a feature flag **should not** have a changelog entry. The entry should be added [in the merge request removing the feature flags](feature_flags/development.md). - A fix for a regression introduced and then fixed in the same release (i.e., fixing a bug introduced during a monthly release candidate) **should not** diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 853882e8642..887f17b05b8 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -65,7 +65,7 @@ Sign up for the mailing list, answer GitLab questions on StackOverflow or respond in the IRC channel. You can also sign up on [CodeTriage][codetriage] to help with the remaining issues on the GitHub issue tracker. -## I want to contribute! +## I want to contribute If you want to contribute to GitLab, [issues with the `Accepting merge requests` label](issue_workflow.md#label-for-community-contributors) @@ -93,26 +93,20 @@ When submitting code to GitLab, you may feel that your contribution requires the When your code contains more than 500 changes, any major breaking changes, or an external library, `@mention` a maintainer in the merge request. If you are not sure who to mention, the reviewer will add one early in the merge request process. -## Issues +## Issues workflow -This [documentation](issue_workflow.md) outlines the current issue process. +This [documentation](issue_workflow.md) outlines the current issue workflow: -- [Type labels](issue_workflow.md#type-labels) -- [Subject labels](issue_workflow.md#subject-labels) -- [Team labels](issue_workflow.md#team-labels) -- [Release Scoping labels](issue_workflow.md#release-scoping-labels) -- [Priority labels](issue_workflow.md#priority-labels) -- [Severity labels](issue_workflow.md#severity-labels) -- [Label for community contributors](issue_workflow.md#label-for-community-contributors) +- [Issue tracker guidelines](issue_workflow.md#issue-tracker-guidelines) - [Issue triaging](issue_workflow.md#issue-triaging) +- [Labels](issue_workflow.md#labels) - [Feature proposals](issue_workflow.md#feature-proposals) -- [Issue tracker guidelines](issue_workflow.md#issue-tracker-guidelines) - [Issue weight](issue_workflow.md#issue-weight) - [Regression issues](issue_workflow.md#regression-issues) - [Technical and UX debt](issue_workflow.md#technical-and-ux-debt) -- [Stewardship](issue_workflow.md#stewardship) +- [Technical debt in follow-up issues](issue_workflow.md#technical-debt-in-follow-up-issues) -## Merge requests +## Merge requests workflow This [documentation](merge_request_workflow.md) outlines the current merge request process. diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index a38794c49af..8b5d380ad9e 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -1,17 +1,51 @@ -# Workflow labels +# Issues workflow -To allow for asynchronous issue handling, we use [milestones][milestones-page] +## Issue tracker guidelines + +**[Search the issue tracker](https://gitlab.com/gitlab-org/gitlab-ce/issues)** for similar entries before +submitting your own, there's a good chance somebody else had the same issue or +feature proposal. Show your support with an award emoji and/or join the +discussion. + +Please submit bugs using the ['Bug' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/Bug.md) provided on the issue tracker. +The text in the parenthesis is there to help you with what to include. Omit it +when submitting the actual issue. You can copy-paste it and then edit as you +see fit. + +## Issue triaging + +Our issue triage policies are [described in our handbook](https://about.gitlab.com/handbook/engineering/issue-triage/). +You are very welcome to help the GitLab team triage issues. +We also organize [issue bash events](https://gitlab.com/gitlab-org/gitlab-ce/issues/17815) +once every quarter. + +The most important thing is making sure valid issues receive feedback from the +development team. Therefore the priority is mentioning developers that can help +on those issues. Please select someone with relevant experience from the +[GitLab team](https://about.gitlab.com/team/). +If there is nobody mentioned with that expertise look in the commit history for +the affected files to find someone. + +We also use [GitLab Triage](https://gitlab.com/gitlab-org/gitlab-triage) to +automate some triaging policies. This is currently set up as a +[scheduled pipeline](https://gitlab.com/gitlab-org/quality/triage-ops/pipeline_schedules/10512/edit) +running on [quality/triage-ops](https://gitlab.com/gitlab-org/quality/triage-ops) project. + +## Labels + +To allow for asynchronous issue handling, we use [milestones](https://gitlab.com/groups/gitlab-org/-/milestones) and [labels](https://gitlab.com/gitlab-org/gitlab-ce/-/labels). Leads and product managers handle most of the scheduling into milestones. Labelling is a task for everyone. Most issues will have labels for at least one of the following: - Type: ~feature, ~bug, ~backstage, etc. -- Subject: ~wiki, ~"Container Registry", ~ldap, ~api, etc. -- Team: ~Documentation, ~Delivery, etc. - Stage: ~"devops::plan", ~"devops::create", etc. -- Group: ~"group::source code" ~"group::knowledge" ~"group::editor", etc. +- Group: ~"group::source code", ~"group::knowledge", ~"group::editor", etc. +- Category: ~"Category:Code Analytics", ~"Category:DevOps Score", ~"Category:Templates", etc. +- Feature: ~wiki, ~ldap, ~api, ~issues, ~"merge requests", etc. - Department: ~UX, ~Quality +- Team: ~Documentation, ~Delivery - Specialization: ~frontend, ~backend - Release Scoping: ~Deliverable, ~Stretch, ~"Next Patch Release" - Priority: ~P1, ~P2, ~P3, ~P4 @@ -23,14 +57,18 @@ All labels, their meaning and priority are defined on the If you come across an issue that has none of these, and you're allowed to set labels, you can _always_ add the team and type, and often also the subject. -[milestones-page]: https://gitlab.com/groups/gitlab-org/-/milestones - -## Type labels +### Type labels Type labels are very important. They define what kind of issue this is. Every -issue should have one or more. +issue should have one and only one. -Examples of type labels are ~feature, ~bug, ~backstage and ~security +The current type labels are: + +- ~feature +- ~bug +- ~backstage +- ~"support request" +- ~meta A number of type labels have a priority assigned to them, which automatically makes them float to the top, depending on their importance. @@ -38,115 +76,173 @@ makes them float to the top, depending on their importance. Type labels are always lowercase, and can have any color, besides blue (which is already reserved for subject labels). -The descriptions on the [labels page](https://gitlab.com/gitlab-org/gitlab-ce/-/labels) explain what falls under each type label. +The descriptions on the [labels page](https://gitlab.com/groups/gitlab-org/-/labels) +explain what falls under each type label. -## Subject labels +### Facet labels -Subject labels are labels that define what area or feature of GitLab this issue -hits. They are not always necessary, but very convenient. +Sometimes it's useful to refine the type of an issue. In those cases, you can +add facet labels. -Subject labels are now used to infer and apply relevant group and devops stage -labels. Please apply them whenever possible to facilitate accurate matching. -Please refer to [this merge request][inferred-labels] for more information. +Following is a non-exhaustive list of facet labels: -Examples of subject labels are ~wiki, ~ldap, ~api, -~issues, ~"merge requests", ~labels, and ~"Container Registry". +- ~enhancement: This label can refine an issue that has the ~feature label. +- ~"master:broken": This label can refine an issue that has the ~bug label. +- ~"master:flaky": This label can refine an issue that has the ~bug label. +- ~"technical debt": This label can refine an issue that has the ~backstage label. +- ~"static analysis": This label can refine an issue that has the ~backstage label. +- ~"ci-build": This label can refine an issue that has the ~backstage label. +- ~performance: A performance issue could describe a ~bug or a ~feature. +- ~security: A security issue could describe a ~bug or a ~feature. +- ~database: A database issue could describe a ~bug or a ~feature. +- ~customer: This relates to an issue that was created by a customer, or that is of interest for a customer. -If you are an expert in a particular area, it makes it easier to find issues to -work on. You can also subscribe to those labels to receive an email each time an -issue is labeled with a subject label corresponding to your expertise. +### Stage labels -Subject labels are always all-lowercase. +Stage labels specify which [stage](https://about.gitlab.com/handbook/product/categories/#hierarchy) the issue belongs to. -## Team labels +#### Naming and color convention -**Important**: Most of the team labels will be soon deprecated in favor of [Group labels](#group-labels). +Stage labels respects the `devops::<stage_key>` naming convention. +`<stage_key>` is the stage key as it is in the single source of truth for stages at +<https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml> +with `_` replaced with a space. -Team labels specify what team is responsible for this issue. -Assigning a team label makes sure issues get the attention of the appropriate -people. +For instance, the "Manage" stage is represented by the ~"devops::manage" label in +the `gitlab-org` group since its key under `stages` is `manage`. -The team labels planned for deprecation are: - -- ~Configure -- ~Create -- ~Defend -- ~Distribution -- ~Ecosystem -- ~Geo -- ~Gitaly -- ~Growth -- ~Manage -- ~Memory -- ~Monitor -- ~Plan -- ~Release -- ~Secure -- ~Verify - -The following team labels are **true** teams per our [organization structure](https://about.gitlab.com/company/team/structure/#organizational-structure) which will remain post deprecation. +The current stage labels can be found by [searching the labels list for `devops::`](https://gitlab.com/groups/gitlab-org/-/labels?search=devops::). -- ~Delivery -- ~Documentation - -The descriptions on the [labels page](https://gitlab.com/gitlab-org/gitlab-ce/-/labels) explain what falls under the -responsibility of each team. - -Team labels are always capitalized so that they show up as the first label for -any issue. - -## Stage labels +These labels are [scoped labels](../../user/project/labels.md#scoped-labels-premium) +and thus are mutually exclusive. -Stage labels specify which [DevOps stage][devops-stages] the issue belongs to. +The Stage labels are used to generate the [direction pages](https://about.gitlab.com/direction/) automatically. -The current stage labels can be found by [searching the labels list for `devops::`](https://gitlab.com/groups/gitlab-org/-/labels?search=devops%3A%3A). +### Group labels -These labels are [scoped labels](../../user/project/labels.md#scoped-labels-premium) -and thus are mutually exclusive. +Group labels specify which [groups](https://about.gitlab.com/company/team/structure/#product-groups) the issue belongs to. -The Stage labels are used to generate the [direction pages][direction-pages] automatically. +It's highly recommended to add a group label, as it's used by our triage +automation to +[infer the correct stage label](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#auto-labelling-of-issues). -[devops-stages]: https://about.gitlab.com/direction/#devops-stages -[direction-pages]: https://about.gitlab.com/direction/ +#### Naming and color convention -## Group labels +Group labels respects the `group::<group_key>` naming convention and +their color is `#A8D695`. +`<group_key>` is the group key as it is in the single source of truth for groups at +<https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml>, +with `_` replaced with a space. -Group labels specify which [groups][structure-groups] the issue belongs to. +For instance, the "Continuous Integration" group is represented by the +~"group::continuous integration" label in the `gitlab-org` group since its key +under `stages.manage.groups` is `continuous_integration`. -The current group labels can be found by [searching the labels list for `group::`](https://gitlab.com/groups/gitlab-org/-/labels?search=group%3A%3A). +The current group labels can be found by [searching the labels list for `group::`](https://gitlab.com/groups/gitlab-org/-/labels?search=group::). These labels are [scoped labels](../../user/project/labels.md#scoped-labels-premium) and thus are mutually exclusive. -You can find the groups listed in the [Product Stages, Groups, and Categories][product-categories] page. +You can find the groups listed in the [Product Stages, Groups, and Categories](https://about.gitlab.com/handbook/product/categories/) page. -We use the term group to map down product requirements from our product stages. +We use the term group to map down product requirements from our product stages. As a team needs some way to collect the work their members are planning to be assigned to, we use the `~group::` labels to do so. Normally there is a 1:1 relationship between Stage labels and Group labels. In the spirit of "Everyone can contribute", any issue can be picked up by any group, depending on current priorities. For example, an issue labeled ~"devops::create" may be picked up by the ~"group::access" group. -We also use stage and group labels to help quantify our [throughput](https://about.gitlab.com/handbook/engineering/management/throughput). +We also use stage and group labels to help quantify our [throughput](https://about.gitlab.com/handbook/engineering/management/throughput). Please read [Stage and Group labels in Throughtput](https://about.gitlab.com/handbook/engineering/management/throughput/#stage-and-group-labels-in-throughput) for more information on how the labels are used in this context. -[structure-groups]: https://about.gitlab.com/company/team/structure/#groups -[product-categories]: https://about.gitlab.com/handbook/product/categories/ +### Category labels + +From the handbook's +[Product stages, groups, and categories](https://about.gitlab.com/handbook/product/categories/#hierarchy) +page: + +> Categories are high-level capabilities that may be a standalone product at +another company. e.g. Portfolio Management. + +It's highly recommended to add a category label, as it's used by our triage +automation to +[infer the correct group and stage labels](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#auto-labelling-of-issues). + +If you are an expert in a particular area, it makes it easier to find issues to +work on. You can also subscribe to those labels to receive an email each time an +issue is labeled with a category label corresponding to your expertise. + +#### Naming and color convention + +Category labels respects the `Category:<Category Name>` naming convention and +their color is `#428BCA`. +`<Category Name>` is the category name as it is in the single source of truth for categories at +<https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml>. + +For instance, the "Code Analytics" category is represented by the +~"Category:Code Analytics" label in the `gitlab-org` group since its +`code_analytics.name` value is "Code Analytics". + +If a category's label doesn't respect this naming convention, it should be specified +with [the `label` attribute](https://about.gitlab.com/handbook/marketing/website/#category-attributes) +in <https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml>. + +### Feature labels + +From the handbook's +[Product stages, groups, and categories](https://about.gitlab.com/handbook/product/categories/#hierarchy) +page: + +> Features: Small, discrete functionalities. e.g. Issue weights. Some common +features are listed within parentheses to facilitate finding responsible PMs by keyword. + +It's highly recommended to add a feature label if no category label applies, as +it's used by our triage automation to +[infer the correct group and stage labels](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#auto-labelling-of-issues). + +If you are an expert in a particular area, it makes it easier to find issues to +work on. You can also subscribe to those labels to receive an email each time an +issue is labeled with a feature label corresponding to your expertise. + +Examples of feature labels are ~wiki, ~ldap, ~api, ~issues, ~"merge requests" etc. + +#### Naming and color convention -## Department labels +Feature labels are all-lowercase. + +### Department labels The current department labels are: - ~UX - ~Quality -## Specialization labels +### Team labels + +**Important**: Most of the historical team labels (e.g. Manage, Plan etc.) are +now deprecated in favor of [Group labels](#group-labels) and [Stage labels](#stage-labels). + +Team labels specify what team is responsible for this issue. +Assigning a team label makes sure issues get the attention of the appropriate +people. + +The current team labels are: + +- ~Delivery +- ~Documentation + +#### Naming and color convention + +Team labels are always capitalized so that they show up as the first label for +any issue. + +### Specialization labels These labels narrow the [specialization](https://about.gitlab.com/company/team/structure/#specialist) on a unit of work. - ~frontend - ~backend -## Release Scoping labels +### Release scoping labels Release Scoping labels help us clearly communicate expectations of the work for the release. There are three levels of Release Scoping labels: @@ -164,7 +260,7 @@ Each issue scheduled for the current milestone should be labeled ~Deliverable or ~"Stretch". Any open issue for a previous milestone should be labeled ~"Next Patch Release", or otherwise rescheduled to a different milestone. -### Priority labels +#### Priority labels Priority labels help us define the time a ~bug fix should be completed. Priority determines how quickly the defect turnaround time must be. If there are multiple defects, the priority decides which defect has to be fixed immediately versus later. @@ -177,7 +273,7 @@ This label documents the planned timeline & urgency which is used to measure aga | ~P3 | Medium Priority | Within the next 3 releases (approx one quarter or 90 days) | | ~P4 | Low Priority | Anything outside the next 3 releases (more than one quarter or 120 days) | -## Severity labels +### Severity labels Severity labels help us clearly communicate the impact of a ~bug on users. There can be multiple facets of the impact. The below is a guideline. @@ -206,7 +302,7 @@ If a bug seems to fall between two severity labels, assign it to the higher-seve - Label colors are incorrect. - UI elements are not fully aligned. -## Label for community contributors +### Label for community contributors Issues that are beneficial to our users, 'nice to haves', that we currently do not have the capacity for or want to give the priority to, are labeled as @@ -236,11 +332,11 @@ After adding the ~"Accepting merge requests" label, we try to estimate the [weight](#issue-weight) of the issue. We use issue weight to let contributors know how difficult the issue is. Additionally: -- We advertise [`Accepting merge requests` issues with weight < 5][up-for-grabs] +- We advertise [`Accepting merge requests` issues with weight < 5](https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight) as suitable for people that have never contributed to GitLab before on the [Up For Grabs campaign](http://up-for-grabs.net) - We encourage people that have never contributed to any open source project to - look for [`Accepting merge requests` issues with a weight of 1][first-timers] + look for [`Accepting merge requests` issues with a weight of 1](https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight&weight=1) If you've decided that you would like to work on an issue, please @-mention the [appropriate product manager](https://about.gitlab.com/handbook/product/#who-to-talk-to-for-what) @@ -253,42 +349,29 @@ GitLab team members who apply the ~"Accepting merge requests" label to an issue should update the issue description with a responsible product manager, inviting any potential community contributor to @-mention per above. -[up-for-grabs]: https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight -[first-timers]: https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight&weight=1 +### Stewardship label -## Issue triaging - -Our issue triage policies are [described in our handbook]. You are very welcome -to help the GitLab team triage issues. We also organize [issue bash events] once -every quarter. - -The most important thing is making sure valid issues receive feedback from the -development team. Therefore the priority is mentioning developers that can help -on those issues. Please select someone with relevant experience from the -[GitLab team][team]. If there is nobody mentioned with that expertise look in -the commit history for the affected files to find someone. +For issues related to the open source stewardship of GitLab, +there is the ~"stewardship" label. -We also use [GitLab Triage] to automate some triaging policies. This is -currently set up as a [scheduled pipeline] running on [quality/triage-ops] -project. +This label is to be used for issues in which the stewardship of GitLab +is a topic of discussion. For instance if GitLab Inc. is planning to add +features from GitLab EE to GitLab CE, related issues would be labelled with +~"stewardship". -[described in our handbook]: https://about.gitlab.com/handbook/engineering/issue-triage/ -[issue bash events]: https://gitlab.com/gitlab-org/gitlab-ce/issues/17815 -[GitLab Triage]: https://gitlab.com/gitlab-org/gitlab-triage -[scheduled pipeline]: https://gitlab.com/gitlab-org/quality/triage-ops/pipeline_schedules/10512/edit -[quality/triage-ops]: https://gitlab.com/gitlab-org/quality/triage-ops -[team]: https://about.gitlab.com/team/ +A recent example of this was the issue for +[bringing the time tracking API to GitLab CE](https://gitlab.com/gitlab-org/gitlab-ce/issues/25517#note_20019084). ## Feature proposals To create a feature proposal for CE, open an issue on the -[issue tracker of CE][ce-tracker]. +[issue tracker of CE](https://gitlab.com/gitlab-org/gitlab-ce/issues). For feature proposals for EE, open an issue on the -[issue tracker of EE][ee-tracker]. +[issue tracker of EE](https://gitlab.com/gitlab-org/gitlab-ee/issues). In order to help track the feature proposals, we have created a -[`feature`][fl] label. For the time being, users that are not members +[`feature`](https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=feature) label. For the time being, users that are not members of the project cannot add labels. You can instead ask one of the [core team](https://about.gitlab.com/community/core-team/) members to add the label ~feature to the issue or add the following code snippet right after your description in a new line: `~feature`. @@ -305,20 +388,6 @@ need to ask one of the [core team](https://about.gitlab.com/community/core-team/ If you want to create something yourself, consider opening an issue first to discuss whether it is interesting to include this in GitLab. -[fl]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=feature - -## Issue tracker guidelines - -**[Search the issue tracker][ce-tracker]** for similar entries before -submitting your own, there's a good chance somebody else had the same issue or -feature proposal. Show your support with an award emoji and/or join the -discussion. - -Please submit bugs using the ['Bug' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/Bug.md) provided on the issue tracker. -The text in the parenthesis is there to help you with what to include. Omit it -when submitting the actual issue. You can copy-paste it and then edit as you -see fit. - ## Issue weight Issue weight allows us to get an idea of the amount of work required to solve @@ -364,7 +433,7 @@ addressed. ## Technical and UX debt In order to track things that can be improved in GitLab's codebase, -we use the ~"technical debt" label in [GitLab's issue tracker][ce-tracker]. +we use the ~"technical debt" label in [GitLab's issue tracker](https://gitlab.com/gitlab-org/gitlab-ce/issues). For missed user experience requirements, we use the ~"UX debt" label. These labels should be added to issues that describe things that can be improved, @@ -425,25 +494,6 @@ should be of the same quality as those created **must not** begin with `Follow-up`! The creating maintainer should also expect to be involved in some capacity when work begins on the follow-up issue. -## Stewardship - -For issues related to the open source stewardship of GitLab, -there is the ~"stewardship" label. - -This label is to be used for issues in which the stewardship of GitLab -is a topic of discussion. For instance if GitLab Inc. is planning to add -features from GitLab EE to GitLab CE, related issues would be labelled with -~"stewardship". - -A recent example of this was the issue for -[bringing the time tracking API to GitLab CE][time-tracking-issue]. - -[time-tracking-issue]: https://gitlab.com/gitlab-org/gitlab-ce/issues/25517#note_20019084 - --- [Return to Contributing documentation](index.md) - -[ce-tracker]: https://gitlab.com/gitlab-org/gitlab-ce/issues -[ee-tracker]: https://gitlab.com/gitlab-org/gitlab-ee/issues -[inferred-labels]: https://gitlab.com/gitlab-org/quality/triage-ops/merge_requests/155 diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 4e9c5c81379..bdb026d498d 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -1,4 +1,4 @@ -# Merge requests +# Merge requests workflow We welcome merge requests from everyone, with fixes and improvements to GitLab code, tests, and documentation. The issues that are specifically suitable diff --git a/doc/development/database_debugging.md b/doc/development/database_debugging.md index eb3b227473b..6c9fa983c96 100644 --- a/doc/development/database_debugging.md +++ b/doc/development/database_debugging.md @@ -9,7 +9,7 @@ An easy first step is to search for your error in Slack or google "GitLab (my er Available `RAILS_ENV` -- `production` (generally not for your main GDK db, but you may need this for e.g. omnibus) +- `production` (generally not for your main GDK db, but you may need this for e.g. Omnibus) - `development` (this is your main GDK db) - `test` (used for tests like rspec) diff --git a/doc/development/database_review.md b/doc/development/database_review.md index 3f1b359cb0b..367a481ee11 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -91,7 +91,7 @@ and details for a database reviewer: concurrent index/foreign key helpers (with transactions disabled) - Check consistency with `db/schema.rb` and that migrations are [reversible](migration_style_guide.md#reversibility) - Check queries timing (If any): Queries executed in a migration - need to fit comfortable within `15s` - preferably much less than that - on GitLab.com. + need to fit comfortably within `15s` - preferably much less than that - on GitLab.com. - Check [background migrations](background_migrations.md): - For data migrations, establish a time estimate for execution - They should only be used when migrating data in larger tables. diff --git a/doc/development/distributed_tracing.md b/doc/development/distributed_tracing.md index bfce7488a8d..4776c8348d4 100644 --- a/doc/development/distributed_tracing.md +++ b/doc/development/distributed_tracing.md @@ -179,4 +179,3 @@ 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 they appear in the Jaeger UI. - diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index ac93ada5a4b..00c76fe0f1b 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -69,7 +69,7 @@ To follow a consistent workflow every month, documentation changes involve the Product Managers, the developer who shipped the feature, and the technical writer for the DevOps stage. Each role is described below. -The Documentation items in the GitLab CE/EE [Feature Proposal issue template](https://gitlab.com/gitlab-org/gitlab-ce/raw/template-improvements-for-documentation/.gitlab/issue_templates/Feature%20proposal.md) +The Documentation items in the GitLab CE/EE [Feature Proposal issue template](https://gitlab.com/gitlab-org/gitlab-ce/raw/master/.gitlab/issue_templates/Feature%20proposal.md) and default merge request template will assist you with following this process. ### Product Manager role diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index c9ae00d148a..edd83f67d3b 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -88,7 +88,7 @@ in an EE MR. To pass the test, simply remove the docs changes from the EE MR, an ## Changing document location Changing a document's location requires specific steps to be followed to ensure that -users can seamlessly access the new doc page, whether they are accesing content +users can seamlessly access the new doc page, whether they are accessing content on a GitLab instance domain at `/help` or at docs.gitlab.com. Be sure to ping a GitLab technical writer if you have any questions during the process (such as whether the move is necessary), and ensure that a technical writer reviews this diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index 025a946da0e..158e69df2a6 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -13,7 +13,7 @@ and the section on Content in the [Style Guide](styleguide.md). ## Components of a documentation page -Most pages will be dedicated to a specifig GitLab feature or to a use case that involves +Most pages will be dedicated to a specific GitLab feature or to a use case that involves one or more features, potentially in conjunction with third-party tools. Every feature or use case document should include the following content in the following sequence, diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index c1e3eb9680b..283e8bea8d5 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -506,15 +506,6 @@ Example: For more information, see the [confidential issue](../../user/project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab-ce/issues/<issue_number>`. ``` -### Unlinking emails - -By default, all email addresses will render in an email tag on docs.gitlab.com. -To escape the code block and unlink email addresses, use two backticks: - -```md -`` example@email.com `` -``` - ## Navigation To indicate the steps of navigation through the UI: @@ -783,8 +774,6 @@ For multiple paragraphs, use the symbol `>` before every line: > > - This is a list item > - Second item in the list -> -> ### This is an `h3` ``` Which renders to: @@ -795,9 +784,6 @@ Which renders to: > > - This is a list item > - Second item in the list -> -> ### This is an `h3` ->{:.no_toc} ## Terms diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 2217dedccd3..391361a4b8f 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -910,7 +910,7 @@ import bundle from 'ee_else_ce/protected_branches/protected_branches_bundle.js'; ``` See the frontend guide [performance section](fe_guide/performance.md) for -information on managing page-specific javascript within EE. +information on managing page-specific JavaScript within EE. ## Vue code in `assets/javascript` @@ -945,7 +945,7 @@ export default { - Since we [can't async load a mixin](https://github.com/vuejs/vue-loader/issues/418#issuecomment-254032223) we will use the [`ee_else_ce`](../development/ee_features.md#javascript-code-in-assetsjavascripts) alias we already have for webpack. - This means all the EE specific props, computed properties, methods, etc that are EE only should be in a mixin in the `ee/` folder and we need to create a CE counterpart of the mixin -##### Example: +##### Example ```javascript import mixin from 'ee_else_ce/path/mixin'; @@ -976,7 +976,7 @@ For regular JS files, the approach is similar. 1. An EE file should be created with the EE only code, and it should extend the CE counterpart. 1. For code inside functions that can't be extended, the code should be moved into a new file and we should use `ee_else_ce` helper: -#### Example: +#### Example ```javascript import eeCode from 'ee_else_ce/ee_code'; @@ -1047,8 +1047,6 @@ code base. Examples of backports include the following: Here is a workflow to make sure those changes end up backported safely into CE too. -(This approach does not refer to changes introduced via [csslab](https://gitlab.com/gitlab-org/csslab/).) - 1. **Make your changes in the EE branch.** If possible, keep a separated commit (to be squashed) to help backporting and review. 1. **Open merge request to EE project.** 1. **Apply the changes you made to CE files in a branch of the CE project.** (Tip: Use `patch` with the diff from your commit in EE branch) @@ -1057,7 +1055,7 @@ Here is a workflow to make sure those changes end up backported safely into CE t **Note:** regarding SCSS, make sure the files living outside `/ee/` don't diverge between CE and EE projects. -## gitlab-svgs +## GitLab-svgs Conflicts in `app/assets/images/icons.json` or `app/assets/images/icons.svg` can be resolved simply by regenerating those assets with diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index 635895051bc..f2412c249c1 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.md @@ -40,9 +40,11 @@ There is no need to install any plugins If you're interested on working with the new beta repo indexer, all you need to do is: -- git clone git@gitlab.com:gitlab-org/gitlab-elasticsearch-indexer.git -- make -- make install +```sh +git clone git@gitlab.com:gitlab-org/gitlab-elasticsearch-indexer.git +make +make install +``` this adds `gitlab-elasticsearch-indexer` to `$GOPATH/bin`, please make sure that is in your `$PATH`. After that GitLab will find it and you'll be able to enable it in the admin settings area. @@ -148,26 +150,49 @@ Uses an [Edge NGram token filter](https://www.elastic.co/guide/en/elasticsearch/ - Searches can have their own analyzers. Remember to check when editing analyzers - `Character` filters (as opposed to token filters) always replace the original character, so they're not a good choice as they can hinder exact searches -## Architecture +## Zero downtime reindexing with multiple indices + +Currently GitLab can only handle a single version of setting. Any setting/schema changes would require reindexing everything from scratch. Since reindexing can take a long time, this can cause search functionality downtime. + +To avoid downtime, GitLab is working to support multiple indices that +can function at the same time. Whenever the schema changes, the admin +will be able to create a new index and reindex to it, while searches +continue to go to the older, stable index. Any data updates will be +forwarded to both indices. Once the new index is ready, an admin can +mark it active, which will direct all searches to it, and remove the old +index. + +This is also helpful for migrating to new servers, e.g. moving to/from AWS. + +Currently we are on the process of migrating to this new design. Everything is hardwired to work with one single version for now. -GitLab uses `elasticsearch-rails` for handling communication with Elasticsearch server. However, in order to achieve zero-downtime deployment during schema changes, an extra abstraction layer is built to allow: +### Architecture -* Indexing (writes) to multiple indexes, with different mappings -* Switching to different index for searches (reads) on the fly +The traditional setup, provided by `elasticsearch-rails`, is to communicate through its internal proxy classes. Developers would write model-specific logic in a module for the model to include in (e.g. `SnippetsSearch`). The `__elasticsearch__` methods would return a proxy object, e.g.: -Currently we are on the process of migrating models to this new design (e.g. `Snippet`), and it is hardwired to work with a single version for now. +- `Issue.__elasticsearch__` returns an instance of `Elasticsearch::Model::Proxy::ClassMethodsProxy` +- `Issue.first.__elasticsearch__` returns an instance of `Elasticsearch::Model::Proxy::InstanceMethodsProxy`. -Traditionally, `elasticsearch-rails` provides class and instance level `__elasticsearch__` proxy methods. If you call `Issue.__elasticsearch__`, you will get an instance of `Elasticsearch::Model::Proxy::ClassMethodsProxy`, and if you call `Issue.first.__elasticsearch__`, you will get an instance of `Elasticsearch::Model::Proxy::InstanceMethodsProxy`. These proxy objects would talk to Elasticsearch server directly. +These proxy objects would talk to Elasticsearch server directly (see top half of the diagram). -In the new design, `__elasticsearch__` instead represents one extra layer of proxy. It would keep multiple versions of the actual proxy objects, and it would forward read and write calls to the proxy of the intended version. + -The `elasticsearch-rails`'s way of specifying each model's mappings and other settings is to create a module for the model to include. However in the new design, each model would have its own corresponding subclassed proxy object, where the settings reside in. For example, snippet related setting in the past reside in `SnippetsSearch` module, but in the new design would reside in `SnippetClassProxy` (which is a subclass of `Elasticsearch::Model::Proxy::ClassMethodsProxy`). This reduces namespace pollution in model classes. +In the planned new design, each model would have a pair of corresponding subclassed proxy objects, in which model-specific logic is located. For example, `Snippet` would have `SnippetClassProxy` and `SnippetInstanceProxy` (being subclass of `Elasticsearch::Model::Proxy::ClassMethodsProxy` and `Elasticsearch::Model::Proxy::InstanceMethodsProxy`, respectively). + +`__elasticsearch__` would represent another layer of proxy object, keeping track of multiple actual proxy objects. It would forward method calls to the appropriate index. For example: + +- `model.__elasticsearch__.search` would be forwarded to the one stable index, since it is a read operation. +- `model.__elasticsearch__.update_document` would be forwarded to all indices, to keep all indices up-to-date. The global configurations per version are now in the `Elastic::(Version)::Config` class. You can change mappings there. ### Creating new version of schema -Currently GitLab would still work with a single version of setting. Once it is implemented, multiple versions of setting can exists in different folders (e.g. `ee/lib/elastic/v12p1` and `ee/lib/elastic/v12p3`). To keep a continuous git history, the latest version lives under the `/latest` folder, but is aliased as the latest version. +NOTE: **Note:** this is not applicable yet as multiple indices functionality is not fully implemented. + +Folders like `ee/lib/elastic/v12p1` contain snapshots of search logic from different versions. To keep a continuous Git history, the latest version lives under `ee/lib/elastic/latest`, but its classes are aliased under an actual version (e.g. `ee/lib/elastic/v12p3`). When referencing these classes, never use the `Latest` namespace directly, but use the actual version (e.g. `V12p3`). + +The version name basically follows GitLab's release version. If setting is changed in 12.3, we will create a new namespace called `V12p3` (p stands for "point"). Raise an issue if there is a need to name a version differently. If the current version is `v12p1`, and we need to create a new version for `v12p3`, the steps are as follows: @@ -176,7 +201,7 @@ If the current version is `v12p1`, and we need to create a new version for `v12p 1. Delete `v12p1` folder 1. Copy the entire folder of `latest` as `v12p1` 1. Change the namespace for files under `v12p1` folder from `Latest` to `V12p1` -1. Make changes to `Latest` as needed +1. Make changes to files under the `latest` folder as needed ## Troubleshooting diff --git a/doc/development/emails.md b/doc/development/emails.md index e6af075a282..5676c3b32f4 100644 --- a/doc/development/emails.md +++ b/doc/development/emails.md @@ -5,6 +5,10 @@ To view rendered emails "sent" in your development instance, visit [`/rails/letter_opener`](http://localhost:3000/rails/letter_opener). +Please note that [S/MIME signed](../administration/smime_signing_email.md) emails +[cannot be currently previewed](https://github.com/fgrehm/letter_opener_web/issues/96) with +`letter_opener`. + ## Mailer previews Rails provides a way to preview our mailer templates in HTML and plaintext using diff --git a/doc/development/fe_guide/axios.md b/doc/development/fe_guide/axios.md index 09b4a3c3d96..6e7cf523f36 100644 --- a/doc/development/fe_guide/axios.md +++ b/doc/development/fe_guide/axios.md @@ -38,7 +38,7 @@ Advantages over [`spyOn()`]: - no need to create response objects - does not allow call through (which we want to avoid) -- simple API to test error cases +- simple API to test error cases - provides `replyOnce()` to allow for different responses We have also decided against using [axios interceptors] because they are not suitable for mocking. diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index 676bce32998..3a8ea04407f 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -81,7 +81,7 @@ bundle and included on the page. > can find this out by inspecting `document.body.dataset.page` within your > browser's developer console while on any page within gitlab. -#### Important Considerations: +#### Important Considerations - **Keep Entry Points Lite:** Page-specific javascript entry points should be as lite as possible. These diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index d3fa350b847..125b11afcd0 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -21,31 +21,31 @@ See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/ 1. **Never Ever EVER** disable eslint globally for a file ```javascript - // bad - /* eslint-disable */ + // bad + /* eslint-disable */ - // better - /* eslint-disable some-rule, some-other-rule */ + // better + /* eslint-disable some-rule, some-other-rule */ - // best - // nothing :) + // best + // nothing :) ``` 1. If you do need to disable a rule for a single violation, try to do it as locally as possible ```javascript - // bad - /* eslint-disable no-new */ + // bad + /* eslint-disable no-new */ - import Foo from 'foo'; + import Foo from 'foo'; - new Foo(); + new Foo(); - // better - import Foo from 'foo'; + // better + import Foo from 'foo'; - // eslint-disable-next-line no-new - new Foo(); + // eslint-disable-next-line no-new + new Foo(); ``` 1. There are few rules that we need to disable due to technical debt. Which are: @@ -56,16 +56,16 @@ See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/ followed by any global declarations, then a blank newline prior to any imports or code. ```javascript - // bad - /* global Foo */ - /* eslint-disable no-new */ - import Bar from './bar'; + // bad + /* global Foo */ + /* eslint-disable no-new */ + import Bar from './bar'; - // good - /* eslint-disable no-new */ - /* global Foo */ + // good + /* eslint-disable no-new */ + /* global Foo */ - import Bar from './bar'; + import Bar from './bar'; ``` 1. **Never** disable the `no-undef` rule. Declare globals with `/* global Foo */` instead. @@ -73,23 +73,23 @@ See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/ 1. When declaring multiple globals, always use one `/* global [name] */` line per variable. ```javascript - // bad - /* globals Flash, Cookies, jQuery */ + // bad + /* globals Flash, Cookies, jQuery */ - // good - /* global Flash */ - /* global Cookies */ - /* global jQuery */ + // good + /* global Flash */ + /* global Cookies */ + /* global jQuery */ ``` 1. Use up to 3 parameters for a function or class. If you need more accept an Object instead. ```javascript - // bad - fn(p1, p2, p3, p4) {} + // bad + fn(p1, p2, p3, p4) {} - // good - fn(options) {} + // good + fn(options) {} ``` #### Modules, Imports, and Exports @@ -97,32 +97,32 @@ See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/ 1. Use ES module syntax to import modules ```javascript - // bad - const SomeClass = require('some_class'); + // bad + const SomeClass = require('some_class'); - // good - import SomeClass from 'some_class'; + // good + import SomeClass from 'some_class'; - // bad - module.exports = SomeClass; + // bad + module.exports = SomeClass; - // good - export default SomeClass; + // good + export default SomeClass; ``` Import statements are following usual naming guidelines, for example object literals use camel case: ```javascript - // some_object file - export default { - key: 'value', - }; + // some_object file + export default { + key: 'value', + }; - // bad - import ObjectLiteral from 'some_object'; + // bad + import ObjectLiteral from 'some_object'; - // good - import objectLiteral from 'some_object'; + // good + import objectLiteral from 'some_object'; ``` 1. Relative paths: when importing a module in the same directory, a child @@ -171,22 +171,22 @@ See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/ 1. Avoid adding to the global namespace. ```javascript - // bad - window.MyClass = class { /* ... */ }; + // bad + window.MyClass = class { /* ... */ }; - // good - export default class MyClass { /* ... */ } + // good + export default class MyClass { /* ... */ } ``` 1. Side effects are forbidden in any script which contains export ```javascript - // bad - export default class MyClass { /* ... */ } + // bad + export default class MyClass { /* ... */ } - document.addEventListener("DOMContentLoaded", function(event) { - new MyClass(); - } + document.addEventListener("DOMContentLoaded", function(event) { + new MyClass(); + } ``` #### Data Mutation and Pure functions @@ -257,17 +257,17 @@ See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/ `.reduce` or `.filter` ```javascript - const users = [ { name: 'Foo' }, { name: 'Bar' } ]; + const users = [ { name: 'Foo' }, { name: 'Bar' } ]; - // bad - users.forEach((user, index) => { - user.id = index; - }); + // bad + users.forEach((user, index) => { + user.id = index; + }); - // good - const usersWithId = users.map((user, index) => { - return Object.assign({}, user, { id: index }); - }); + // good + const usersWithId = users.map((user, index) => { + return Object.assign({}, user, { id: index }); + }); ``` #### Parse Strings into Numbers @@ -275,14 +275,14 @@ See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/ 1. `parseInt()` is preferable over `Number()` or `+` ```javascript - // bad - +'10' // 10 + // bad + +'10' // 10 - // good - Number('10') // 10 + // good + Number('10') // 10 - // better - parseInt('10', 10); + // better + parseInt('10', 10); ``` #### CSS classes used for JavaScript @@ -290,15 +290,15 @@ See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/ 1. If the class is being used in Javascript it needs to be prepend with `js-` ```html - // bad - <button class="add-user"> - Add User - </button> + // bad + <button class="add-user"> + Add User + </button> - // good - <button class="js-add-user"> - Add User - </button> + // good + <button class="js-add-user"> + Add User + </button> ``` ### Vue.js @@ -315,41 +315,41 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. 1. Use a function in the bundle file to instantiate the Vue component: ```javascript - // bad - class { - init() { - new Component({}) - } + // bad + class { + init() { + new Component({}) } + } - // good - document.addEventListener('DOMContentLoaded', () => new Vue({ - el: '#element', - components: { - componentName - }, - render: createElement => createElement('component-name'), - })); + // good + document.addEventListener('DOMContentLoaded', () => new Vue({ + el: '#element', + components: { + componentName + }, + render: createElement => createElement('component-name'), + })); ``` 1. Do not use a singleton for the service or the store ```javascript - // bad - class Store { - constructor() { - if (!this.prototype.singleton) { - // do something - } + // bad + class Store { + constructor() { + if (!this.prototype.singleton) { + // do something } } + } - // good - class Store { - constructor() { - // do something - } + // good + class Store { + constructor() { + // do something } + } ``` 1. Use `.vue` for Vue templates. Do not use `%template` in HAML. @@ -360,36 +360,36 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. 1. **Reference Naming**: Use PascalCase for their instances: ```javascript - // bad - import cardBoard from 'cardBoard.vue' + // bad + import cardBoard from 'cardBoard.vue' - components: { - cardBoard, - }; + components: { + cardBoard, + }; - // good - import CardBoard from 'cardBoard.vue' + // good + import CardBoard from 'cardBoard.vue' - components: { - CardBoard, - }; + components: { + CardBoard, + }; ``` 1. **Props Naming:** Avoid using DOM component prop names. 1. **Props Naming:** Use kebab-case instead of camelCase to provide props in templates. ```javascript - // bad - <component class="btn"> + // bad + <component class="btn"> - // good - <component css-class="btn"> + // good + <component css-class="btn"> - // bad - <component myProp="prop" /> + // bad + <component myProp="prop" /> - // good - <component my-prop="prop" /> + // good + <component my-prop="prop" /> ``` [#34371]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34371 @@ -401,37 +401,37 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. 1. With more than one attribute, all attributes should be on a new line: ```javascript - // bad - <component v-if="bar" - param="baz" /> + // bad + <component v-if="bar" + param="baz" /> - <button class="btn">Click me</button> + <button class="btn">Click me</button> - // good - <component - v-if="bar" - param="baz" - /> + // good + <component + v-if="bar" + param="baz" + /> - <button class="btn"> - Click me - </button> + <button class="btn"> + Click me + </button> ``` 1. The tag can be inline if there is only one attribute: ```javascript - // good - <component bar="bar" /> + // good + <component bar="bar" /> - // good - <component - bar="bar" - /> + // good + <component + bar="bar" + /> - // bad - <component - bar="bar" /> + // bad + <component + bar="bar" /> ``` #### Quotes @@ -439,15 +439,15 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. 1. Always use double quotes `"` inside templates and single quotes `'` for all other JS. ```javascript - // bad - template: ` - <button :class='style'>Button</button> - ` + // bad + template: ` + <button :class='style'>Button</button> + ` - // good - template: ` - <button :class="style">Button</button> - ` + // good + template: ` + <button :class="style">Button</button> + ` ``` #### Props @@ -455,37 +455,37 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. 1. Props should be declared as an object ```javascript - // bad - props: ['foo'] - - // good - props: { - foo: { - type: String, - required: false, - default: 'bar' - } + // bad + props: ['foo'] + + // good + props: { + foo: { + type: String, + required: false, + default: 'bar' } + } ``` 1. Required key should always be provided when declaring a prop ```javascript - // bad - props: { - foo: { - type: String, - } + // bad + props: { + foo: { + type: String, } + } - // good - props: { - foo: { - type: String, - required: false, - default: 'bar' - } + // good + props: { + foo: { + type: String, + required: false, + default: 'bar' } + } ``` 1. Default key should be provided if the prop is not required. @@ -493,30 +493,30 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. On those a default key should not be provided. ```javascript - // good - props: { - foo: { - type: String, - required: false, - } + // good + props: { + foo: { + type: String, + required: false, } + } - // good - props: { - foo: { - type: String, - required: false, - default: 'bar' - } + // good + props: { + foo: { + type: String, + required: false, + default: 'bar' } + } - // good - props: { - foo: { - type: String, - required: true - } + // good + props: { + foo: { + type: String, + required: true } + } ``` #### Data @@ -524,17 +524,17 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. 1. `data` method should always be a function ```javascript - // bad - data: { - foo: 'foo' - } + // bad + data: { + foo: 'foo' + } - // good - data() { - return { - foo: 'foo' - }; - } + // good + data() { + return { + foo: 'foo' + }; + } ``` #### Directives @@ -542,31 +542,31 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. 1. Shorthand `@` is preferable over `v-on` ```javascript - // bad - <component v-on:click="eventHandler"/> + // bad + <component v-on:click="eventHandler"/> - // good - <component @click="eventHandler"/> + // good + <component @click="eventHandler"/> ``` 1. Shorthand `:` is preferable over `v-bind` ```javascript - // bad - <component v-bind:class="btn"/> + // bad + <component v-bind:class="btn"/> - // good - <component :class="btn"/> + // good + <component :class="btn"/> ``` 1. Shorthand `#` is preferable over `v-slot` ```javascript - // bad - <template v-slot:header></template> + // bad + <template v-slot:header></template> - // good - <template #header></template> + // good + <template #header></template> ``` #### Closing tags @@ -574,11 +574,11 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. 1. Prefer self closing component tags ```javascript - // bad - <component></component> + // bad + <component></component> - // good - <component /> + // good + <component /> ``` #### Ordering @@ -610,48 +610,48 @@ When using `v-for` you need to provide a *unique* `:key` attribute for each item 1. If the elements of the array being iterated have an unique `id` it is advised to use it: ```html - <div - v-for="item in items" - :key="item.id" - > - <!-- content --> - </div> + <div + v-for="item in items" + :key="item.id" + > + <!-- content --> + </div> ``` 1. When the elements being iterated don't have a unique id, you can use the array index as the `:key` attribute ```html - <div - v-for="(item, index) in items" - :key="index" - > - <!-- content --> - </div> + <div + v-for="(item, index) in items" + :key="index" + > + <!-- content --> + </div> ``` 1. When using `v-for` with `template` and there is more than one child element, the `:key` values must be unique. It's advised to use `kebab-case` namespaces. ```html - <template v-for="(item, index) in items"> - <span :key="`span-${index}`"></span> - <button :key="`button-${index}`"></button> - </template> + <template v-for="(item, index) in items"> + <span :key="`span-${index}`"></span> + <button :key="`button-${index}`"></button> + </template> ``` 1. When dealing with nested `v-for` use the same guidelines as above. ```html - <div - v-for="item in items" - :key="item.id" + <div + v-for="item in items" + :key="item.id" + > + <span + v-for="element in array" + :key="element.id" > - <span - v-for="element in array" - :key="element.id" - > - <!-- content --> - </span> - </div> + <!-- content --> + </span> + </div> ``` Useful links: @@ -664,19 +664,19 @@ Useful links: 1. Tooltips: Do not rely on `has-tooltip` class name for Vue components ```javascript - // bad - <span - class="has-tooltip" - title="Some tooltip text"> - Text - </span> + // bad + <span + class="has-tooltip" + title="Some tooltip text"> + Text + </span> - // good - <span - v-tooltip - title="Some tooltip text"> - Text - </span> + // good + <span + v-tooltip + title="Some tooltip text"> + Text + </span> ``` 1. Tooltips: When using a tooltip, include the tooltip directive, `./app/assets/javascripts/vue_shared/directives/tooltip.js` @@ -684,13 +684,13 @@ Useful links: 1. Don't change `data-original-title`. ```javascript - // bad - <span data-original-title="tooltip text">Foo</span> + // bad + <span data-original-title="tooltip text">Foo</span> - // good - <span title="tooltip text">Foo</span> + // good + <span title="tooltip text">Foo</span> - $('span').tooltip('_fixTitle'); + $('span').tooltip('_fixTitle'); ``` ### The Javascript/Vue Accord diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 9eeaee4482f..557d3132d71 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -313,7 +313,7 @@ export default { 1. Do not call a mutation directly. Always use an action to commit a mutation. Doing so will keep consistency throughout the application. From Vuex docs: - > why don't we just call store.commit('action') directly? Well, remember that mutations must be synchronous? Actions aren't. We can perform asynchronous operations inside an action. + > Why don't we just call store.commit('action') directly? Well, remember that mutations must be synchronous? Actions aren't. We can perform asynchronous operations inside an action. ```javascript // component.vue diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index 56872f8c075..f1374b9e280 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -8,5 +8,5 @@ disable those changes, without having to revert an entire release. Before using feature flags for GitLab's development, read through the following: - [Process for using features flags](process.md). -- [Developing with feature flags documentation](development.md). -- [Controlling feature flags documentation](controls.md). +- [Developing with feature flags](development.md). +- [Controlling feature flags](controls.md). diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md index 475d1c1611e..44af2b020a4 100644 --- a/doc/development/file_storage.md +++ b/doc/development/file_storage.md @@ -2,6 +2,8 @@ We use the [CarrierWave] gem to handle file upload, store and retrieval. +File uploads should be accelerated by workhorse, for details please refer to [uploads development documentation](uploads.md). + There are many places where file uploading is used, according to contexts: - System diff --git a/doc/development/filtering_by_label.md b/doc/development/filtering_by_label.md index 5e7376db725..dd8944ff1c8 100644 --- a/doc/development/filtering_by_label.md +++ b/doc/development/filtering_by_label.md @@ -40,16 +40,14 @@ In particular, note that: This is more complicated than is ideal. It makes the query construction more prone to errors (such as -[gitlab-org/gitlab-ce#15557](https://gitlab.com/gitlab-org/gitlab-ce/issues/15557)). +[issue #15557](https://gitlab.com/gitlab-org/gitlab-ce/issues/15557)). ## Attempt A: WHERE EXISTS ### Attempt A1: use multiple subqueries with WHERE EXISTS -In -[gitlab-org/gitlab-ce#37137](https://gitlab.com/gitlab-org/gitlab-ce/issues/37137) -and its associated merge request -[gitlab-org/gitlab-ce!14022](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14022), +In [issue #37137](https://gitlab.com/gitlab-org/gitlab-ce/issues/37137) +and its associated [merge request](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14022), we tried to replace the `GROUP BY` with multiple uses of `WHERE EXISTS`. For the example above, this would give: @@ -81,12 +79,11 @@ it did not improve query performance. ## Attempt B: Denormalize using an array column -Having [removed MySQL support in GitLab -12.1](https://about.gitlab.com/2019/06/27/removing-mysql-support/), using -[Postgres's arrays](https://www.postgresql.org/docs/9.6/arrays.html) became more +Having [removed MySQL support in GitLab 12.1](https://about.gitlab.com/2019/06/27/removing-mysql-support/), +using [Postgres's arrays](https://www.postgresql.org/docs/9.6/arrays.html) became more tractable as we didn't have to support two databases. We discussed denormalizing the `label_links` table for querying in -[gitlab-org/gitlab-ce#49651](https://gitlab.com/gitlab-org/gitlab-ce/issues/49651), +[issue #49651](https://gitlab.com/gitlab-org/gitlab-ce/issues/49651), with two options: label IDs and titles. We can think of both of those as array columns on `issues`, `merge_requests`, @@ -150,8 +147,7 @@ WHERE label_titles @> ARRAY['Plan', 'backend'] ``` -And our [tests in -gitlab-org/gitlab-ce#49651](https://gitlab.com/gitlab-org/gitlab-ce/issues/49651#note_188777346) +And our [tests in issue #49651](https://gitlab.com/gitlab-org/gitlab-ce/issues/49651#note_188777346) showed that this could be fast. However, at present, the disadvantages outweigh the advantages. diff --git a/doc/development/gemfile.md b/doc/development/gemfile.md index ec9718cea71..8d93c52e7bc 100644 --- a/doc/development/gemfile.md +++ b/doc/development/gemfile.md @@ -3,9 +3,9 @@ When adding a new entry to `Gemfile` or upgrading an existing dependency pay attention to the following rules. -## No gems fetched from git repositories +## No gems fetched from Git repositories -We do not allow gems that are fetched from git repositories. All gems have +We do not allow gems that are fetched from Git repositories. All gems have to be available in the RubyGems index. We want to minimize external build dependencies and build times. diff --git a/doc/development/geo.md b/doc/development/geo.md index 24f16eae9fa..cc3e2d1ccc5 100644 --- a/doc/development/geo.md +++ b/doc/development/geo.md @@ -170,7 +170,7 @@ while `pull` requests will continue to be served by the **secondary** node for m HTTPS and SSH requests are handled differently: - With HTTPS, we will give the user a `HTTP 302 Redirect` pointing to the project on the **primary** node. - The git client is wise enough to understand that status code and process the redirection. + The Git client is wise enough to understand that status code and process the redirection. - With SSH, because there is no equivalent way to perform a redirect, we have to proxy the request. This is done inside [`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell), by first translating the request to the HTTP protocol, and then proxying it to the **primary** node. diff --git a/doc/development/git_object_deduplication.md b/doc/development/git_object_deduplication.md index 5ce59891afa..e8af6346524 100644 --- a/doc/development/git_object_deduplication.md +++ b/doc/development/git_object_deduplication.md @@ -8,30 +8,6 @@ storage disk use. To counteract this problem, we are adding Git object deduplication for forks to GitLab. In this document, we will describe how GitLab implements Git object deduplication. -## Enabling Git object deduplication via feature flags - -As of GitLab 12.0, Git object deduplication in GitLab is still behind a -feature flag. In this document, you can read about the effects of -enabling the feature. Also, note that Git object deduplication is -limited to forks of public projects on hashed repository storage. - -You can enable deduplication globally by setting the `object_pools` -feature flag to `true`: - -``` {.ruby} -Feature.enable(:object_pools) -``` - -Or just for forks of a specific project: - -``` {.ruby} -fork_parent = Project.find(MY_PROJECT_ID) -Feature.enable(:object_pools, fork_parent) -``` - -To check if a project uses Git object deduplication, look in a Rails -console if `project.pool_repository` is present. - ## Pool repositories ### Understanding Git alternates @@ -193,7 +169,7 @@ There are three different things that can go wrong here. In this case, we miss out on disk space savings but all RPC's on A itself will function fine. The next time garbage collection runs on A, the alternates connection gets established in Gitaly. This is done by -`Projects::GitDeduplicationService` in gitlab-rails. +`Projects::GitDeduplicationService` in GitLab Rails. #### 2. SQL says repo A belongs to pool P1 but Gitaly says A has alternate objects in pool P2 @@ -210,7 +186,7 @@ When a pool repository record is created in SQL on a Geo primary, this will eventually trigger an event on the Geo secondary. The Geo secondary will then create the pool repository in Gitaly. This leads to an "eventually consistent" situation because as each pool participant gets -synchronized, Geo will eventuall trigger garbage collection in Gitaly on +synchronized, Geo will eventually trigger garbage collection in Gitaly on the secondary, at which stage Git objects will get deduplicated. > TODO How do we handle the edge case where at the time the Geo diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 2ade59b76ed..592fc13873b 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -45,13 +45,13 @@ The process for adding new Gitaly features is: - release a new version of gitaly-proto - write implementation and tests for the RPC [in Gitaly](https://gitlab.com/gitlab-org/gitaly), in Go or Ruby - release a new version of Gitaly -- write client code in gitlab-ce/ee, gitlab-workhorse or gitlab-shell that calls the new Gitaly RPC +- write client code in GitLab CE/EE, GitLab Workhorse or GitLab Shell that calls the new Gitaly RPC These steps often overlap. It is possible to use an unreleased version of Gitaly and gitaly-proto during testing and development. - See the [Gitaly repo](https://gitlab.com/gitlab-org/gitaly/blob/master/CONTRIBUTING.md#development-and-testing-with-a-custom-gitaly-proto) for instructions on writing server side code with an unreleased protocol. -- See [below](#running-tests-with-a-locally-modified-version-of-gitaly) for instructions on running gitlab-ce tests with a modified version of Gitaly. +- See [below](#running-tests-with-a-locally-modified-version-of-gitaly) for instructions on running GitLab CE tests with a modified version of Gitaly. - In GDK run `gdk install` and restart `gdk run` (or `gdk run app`) to use a locally modified Gitaly version for development ### Gitaly-ruby @@ -146,7 +146,7 @@ Once the code is wrapped in this block, this code-path will be excluded from n+1 ## Request counts -Commits and other git data, is now fetched through Gitaly. These fetches can, +Commits and other Git data, is now fetched through Gitaly. These fetches can, much like with a database, be batched. This improves performance for the client and for Gitaly itself and therefore for the users too. To keep performance stable and guard performance regressions, Gitaly calls can be counted and the call count @@ -164,10 +164,10 @@ end ## Running tests with a locally modified version of Gitaly -Normally, gitlab-ce/ee tests use a local clone of Gitaly in +Normally, GitLab CE/EE tests use a local clone of Gitaly in `tmp/tests/gitaly` pinned at the version specified in `GITALY_SERVER_VERSION`. The `GITALY_SERVER_VERSION` file supports -`=my-branch` syntax to use a custom branch in gitlab-org/gitaly. If +`=my-branch` syntax to use a custom branch in <https://gitlab.com/gitlab-org/gitaly>. 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 the `=my-branch` syntax forces a Gitaly re-install each time @@ -276,9 +276,9 @@ Here are the steps to gate a new feature in Gitaly behind a feature flag. require.NoError(t, err) ``` -### Gitlab-Rails +### GitLab Rails -1. Add feature flag to `lib/gitlab/gitaly_client.rb` (in gitlab-rails): +1. Add feature flag to `lib/gitlab/gitaly_client.rb` (in GitLab Rails): ```ruby SERVER_FEATURE_FLAGS = %w[go-find-all-tags].freeze diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index 83444093f9c..2df0e846671 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -94,7 +94,7 @@ become available, you will be able to share job templates like this Dependencies should be kept to the minimum. The introduction of a new dependency should be argued in the merge request, as per our [Approval Guidelines](../code_review.md#approval-guidelines). Both [License -Management](../../user/project/merge_requests/license_management.md) +Management](../../user/application_security/license_compliance/index.md) **(ULTIMATE)** and [Dependency Scanning](../../user/application_security/dependency_scanning/index.md) **(ULTIMATE)** should be activated on all projects to ensure new dependencies diff --git a/doc/development/hash_indexes.md b/doc/development/hash_indexes.md index e6c1b3590b1..417ea18e22f 100644 --- a/doc/development/hash_indexes.md +++ b/doc/development/hash_indexes.md @@ -1,6 +1,6 @@ # Hash Indexes -Both PostgreSQL and MySQL support hash indexes besides the regular btree +PostgreSQL supports hash indexes besides the regular btree indexes. Hash indexes however are to be avoided at all costs. While they may _sometimes_ provide better performance the cost of rehashing can be very high. More importantly: at least until PostgreSQL 10.0 hash indexes are not diff --git a/doc/development/i18n/translation.md b/doc/development/i18n/translation.md index 62be3786549..15b1af1aa8f 100644 --- a/doc/development/i18n/translation.md +++ b/doc/development/i18n/translation.md @@ -92,4 +92,3 @@ To propose additions to the glossary please In French, the "écriture inclusive" is now over (see on [Legifrance](https://www.legifrance.gouv.fr/affichTexte.do?cidTexte=JORFTEXT000036068906&categorieLien=id)). So, to include both genders, write “Utilisateurs et utilisatrices” instead of “Utilisateur·rice·s”. When space is missing, the male gender should be used alone. - diff --git a/doc/development/img/elasticsearch_architecture.svg b/doc/development/img/elasticsearch_architecture.svg new file mode 100644 index 00000000000..2f38f9b04ee --- /dev/null +++ b/doc/development/img/elasticsearch_architecture.svg @@ -0,0 +1 @@ +<svg version="1.2" width="210mm" height="297mm" viewBox="0 0 21000 29700" preserveAspectRatio="xMidYMid" fill-rule="evenodd" stroke-width="28.222" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg"><defs class="ClipPathGroup"><clipPath id="a" clipPathUnits="userSpaceOnUse"><path d="M0 0h21000v29700H0z"/></clipPath></defs><g class="SlideGroup"><g class="Slide" clip-path="url(#a)"><g class="Page"><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1975 5575h3051v1651H1975z"/><path fill="#FFF" d="M3500 7200H2000V5600h3000v1600H3500z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3500 7200H2000V5600h3000v1600H3500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="2778" y="6311"><tspan>Snippet</tspan></tspan><tspan class="TextPosition" x="2099" y="6785"><tspan>(ActiveRecord)</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1475 3975h4051v3551H1475z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3500 7500H1500V4000h4000v3500H3500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="1788" y="5048"><tspan>ApplicationSearch</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M5975 4675h8051v701H5975z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M6000 5350h4000v-650h4000"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M5975 5325h8051v1101H5975z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M6000 5350h4000v1050h4000"/></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1075 2875h4951v4951H1075z"/><path fill="none" stroke="#F33" stroke-width="50" d="M3550 7800H1100V2900h4900v4900H3550z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="1946" y="3514"><tspan fill="#C9211E">SnippetsSearch</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1975 12175h3051v1651H1975z"/><path fill="#FFF" d="M3500 13800H2000v-1600h3000v1600H3500z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3500 13800H2000v-1600h3000v1600H3500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="2778" y="12911"><tspan>Snippet</tspan></tspan><tspan class="TextPosition" x="2099" y="13385"><tspan>(ActiveRecord)</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1075 10775h4951v3251H1075z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3550 14000H1100v-3200h4900v3200H3550z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="2511" y="11461"><tspan>Application</tspan></tspan><tspan class="TextPosition" x="1933" y="11935"><tspan>VersionedSearch</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M3525 13975h4501v7451H3525z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3550 14000v7400h4450"/></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M14008 14075h4985v851h-4985z"/><path fill="none" stroke="#999" stroke-width="50" d="M16500 14900h-2467v-800h4934v800h-2467z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14720" y="14648"><tspan fill="gray">ClassMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13375 13075h6251v2151h-6251z"/><path fill="none" stroke="#F33" stroke-width="50" d="M16500 15200h-3100v-2100h6200v2100h-3100z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="13799" y="13731"><tspan fill="#C9211E">V12p1::SnippetClassProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M7975 14575h3051v1851H7975z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M9500 16400H8000v-1800h3000v1800H9500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="8277" y="15411"><tspan>MultiVersion-</tspan></tspan><tspan class="TextPosition" x="8429" y="15885"><tspan>ClassProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M14008 16875h4985v851h-4985z"/><path fill="none" stroke="#999" stroke-width="50" d="M16500 17700h-2467v-800h4934v800h-2467z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14720" y="17448"><tspan fill="gray">ClassMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13375 15875h6251v2151h-6251z"/><path fill="none" stroke="#F33" stroke-width="50" d="M16500 18000h-3100v-2100h6200v2100h-3100z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="13799" y="16531"><tspan fill="#C9211E">V12p2::SnippetClassProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10975 14125h2451v1401h-2451z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M11000 15500h1463v-1350h937"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10975 15475h2451v1501h-2451z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M11000 15500h1463v1450h937"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M3525 13975h4501v1551H3525z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M3550 14000v1500h4450"/></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M14008 19975h4985v851h-4985z"/><path fill="none" stroke="#999" stroke-width="50" d="M16500 20800h-2467v-800h4934v800h-2467z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14445" y="20548"><tspan fill="gray">InstanceMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13375 18975h6251v2151h-6251z"/><path fill="none" stroke="#F33" stroke-width="50" d="M16500 21100h-3100v-2100h6200v2100h-3100z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="13505" y="19631"><tspan fill="#C9211E">V12p1::SnippetInstanceProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M7975 20275h3051v2251H7975z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M9500 22500H8000v-2200h3000v2200H9500z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="8277" y="21311"><tspan>MultiVersion-</tspan></tspan><tspan class="TextPosition" x="8154" y="21785"><tspan>InstanceProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M14008 22775h4985v851h-4985z"/><path fill="none" stroke="#999" stroke-width="50" d="M16500 23600h-2467v-800h4934v800h-2467z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14445" y="23348"><tspan fill="gray">InstanceMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13375 21775h6251v2151h-6251z"/><path fill="none" stroke="#F33" stroke-width="50" d="M16500 23900h-3100v-2100h6200v2100h-3100z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="13505" y="22431"><tspan fill="#C9211E">V12p2::SnippetInstanceProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10975 20025h2451v1401h-2451z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M11000 21400h1463v-1350h937"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10975 21375h2451v1501h-2451z"/><path fill="none" stroke="#3465A4" stroke-width="50" d="M11000 21400h1463v1450h937"/></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M900 1600h10697v879H900z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="564" font-weight="400"><tspan class="TextPosition" x="1150" y="2233"><tspan>Standard elasticsearch-rails setup</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M900 9300h7683v879H900z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="564" font-weight="400"><tspan class="TextPosition" x="1150" y="9933"><tspan>GitLab multi-indices setup</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M3400 21300h4821v1197H3400z"/><text class="TextShape"><tspan class="TextParagraph" font-size="388" font-weight="400"><tspan class="TextPosition" x="4250" y="21840"><tspan fill="gray">(instance method)</tspan></tspan><tspan class="TextPosition" x="3651" y="22264"><tspan font-family="Courier" font-size="423">__elasticsearch__</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M3380 15400h4821v1197H3380z"/><text class="TextShape"><tspan class="TextParagraph" font-size="388" font-weight="400"><tspan class="TextPosition" x="4512" y="15940"><tspan fill="gray">(class method)</tspan></tspan><tspan class="TextPosition" x="3631" y="16364"><tspan font-family="Courier" font-size="423">__elasticsearch__</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M9000 3500h4821v1197H9000z"/><text class="TextShape"><tspan class="TextParagraph" font-size="388" font-weight="400"><tspan class="TextPosition" x="10132" y="4040"><tspan fill="gray">(class method)</tspan></tspan><tspan class="TextPosition" x="9251" y="4464"><tspan font-family="Courier" font-size="423">__elasticsearch__</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M9000 6400h4821v1197H9000z"/><text class="TextShape"><tspan class="TextParagraph" font-size="388" font-weight="400"><tspan class="TextPosition" x="9850" y="6940"><tspan fill="gray">(instance method)</tspan></tspan><tspan class="TextPosition" x="9251" y="7364"><tspan font-family="Courier" font-size="423">__elasticsearch__</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1975 25175h2051v851H1975z"/><path fill="none" stroke="#999" stroke-width="50" d="M3000 26000H2000v-800h2000v800H3000z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="2634" y="25748"><tspan fill="gray">Foo</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M4400 25200h7101v726H4400z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="4650" y="25710"><tspan>elasticsearch-rails’ internal class</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M4400 26400h8601v1200H4400z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="4650" y="26910"><tspan>where model-specific logic is</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M1975 26275h2051v851H1975z"/><path fill="none" stroke="#F33" stroke-width="50" d="M3000 27100H2000v-800h2000v800H3000z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="700"><tspan class="TextPosition" x="2613" y="26848"><tspan fill="#C9211E">Foo</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M4900 17289h5901v2312H4900z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="370" font-weight="400"><tspan class="TextPosition" x="7236" y="17748"><tspan fill="gray">Write operations like </tspan></tspan><tspan class="TextPosition" x="5323" y="18159"><tspan fill="gray">indexing/updating are forwarded </tspan></tspan><tspan class="TextPosition" x="8024" y="18570"><tspan fill="gray">to all instances.</tspan></tspan></tspan><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="370" font-weight="400"><tspan class="TextPosition" x="5501" y="18981"><tspan fill="gray">Read operations are forwarded </tspan></tspan><tspan class="TextPosition" x="7126" y="19392"><tspan fill="gray">to specified instance.</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10785 15769h1422v2691h-1422z"/><path fill="none" stroke="#999" stroke-width="30" d="M10800 18444c1429 0 934-1618 1119-2337"/><path fill="#999" d="M12206 15769l-460 293 267 217 193-510z"/></g><g class="com.sun.star.drawing.ConnectorShape"><path class="BoundingBox" fill="none" d="M10785 18429h1528v2862h-1528z"/><path fill="none" stroke="#999" stroke-width="30" d="M10800 18444c1509 0 970 1782 1200 2526"/><path fill="#999" d="M12312 21290l-227-496-252 235 479 261z"/></g><g class="com.sun.star.drawing.TextShape"><path class="BoundingBox" fill="none" d="M1800 24000h7101v807H1800z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="494" font-weight="700"><tspan class="TextPosition" x="2050" y="24574"><tspan>Legend</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13975 4275h5085v851h-5085z"/><path fill="none" stroke="#999" stroke-width="50" d="M16517 5100h-2517v-800h5034v800h-2517z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14737" y="4848"><tspan fill="gray">ClassMethodProxy</tspan></tspan></tspan></text></g><g class="com.sun.star.drawing.CustomShape"><path class="BoundingBox" fill="none" d="M13975 5975h5085v851h-5085z"/><path fill="none" stroke="#999" stroke-width="50" d="M16517 6800h-2517v-800h5034v800h-2517z"/><text class="TextShape"><tspan class="TextParagraph" font-family="Arial, sans-serif" font-size="423" font-weight="400"><tspan class="TextPosition" x="14462" y="6548"><tspan fill="gray">InstanceMethodProxy</tspan></tspan></tspan></text></g></g></g></g></svg>
\ No newline at end of file diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md index 5f95cf3707c..777d372ec60 100644 --- a/doc/development/instrumentation.md +++ b/doc/development/instrumentation.md @@ -1,6 +1,6 @@ # Instrumenting Ruby Code -GitLab Performance Monitoring allows instrumenting of both methods and custom +[GitLab Performance Monitoring](../administration/monitoring/performance/index.md) allows instrumenting of both methods and custom blocks of Ruby code. Method instrumentation is the primary form of instrumentation with block-based instrumentation only being used when we want to drill down to specific regions of code within a method. diff --git a/doc/development/interacting_components.md b/doc/development/interacting_components.md index 74d52d808e2..5e6dc8d460a 100644 --- a/doc/development/interacting_components.md +++ b/doc/development/interacting_components.md @@ -9,8 +9,8 @@ when making _backend_ changes that might involve multiple features or [component ## Uploads -GitLab supports uploads to [object storage]. That means every feature and -change that affects uploads should also be tested against [object storage], +GitLab supports uploads to [object storage]. That means every feature and +change that affects uploads should also be tested against [object storage], which is _not_ enabled by default in [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit). When working on a related feature, make sure to enable and test it diff --git a/doc/development/kubernetes.md b/doc/development/kubernetes.md index 4b2d48903ac..f4528667814 100644 --- a/doc/development/kubernetes.md +++ b/doc/development/kubernetes.md @@ -107,7 +107,7 @@ Mitigation strategies include: ## Debugging Logs related to the Kubernetes integration can be found in -[kubernetes.log](../administration/logs.md#kuberneteslog). On a local +[`kubernetes.log`](../administration/logs.md#kuberneteslog). On a local GDK install, this will be present in `log/kubernetes.log`. Some services such as diff --git a/doc/development/lfs.md b/doc/development/lfs.md index 8c3408eb6e2..cb4c2d8967b 100644 --- a/doc/development/lfs.md +++ b/doc/development/lfs.md @@ -8,4 +8,4 @@ In April 2019, Francisco Javier López hosted a [Deep Dive] on GitLab's [Git LFS [Git LFS]: ../workflow/lfs/manage_large_binaries_with_git_lfs.html [recording on YouTube]: https://www.youtube.com/watch?v=Yyxwcksr0Qc [Google Slides]: https://docs.google.com/presentation/d/1E-aw6-z0rYd0346YhIWE7E9A65zISL9iIMAOq2zaw9E/edit -[PDF]: https://gitlab.com/gitlab-org/create-stage/uploads/07a89257a140db067bdfb484aecd35e1/Git_LFS_Deep_Dive__Create_.pdf
\ No newline at end of file +[PDF]: https://gitlab.com/gitlab-org/create-stage/uploads/07a89257a140db067bdfb484aecd35e1/Git_LFS_Deep_Dive__Create_.pdf diff --git a/doc/development/logging.md b/doc/development/logging.md index 4f63c84fc0e..b43f1029cc6 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -133,7 +133,7 @@ importer progresses. Here's what to do: 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 - for most users, but you may need to tweak them in [omnibus-gitlab](https://gitlab.com/gitlab-org/omnibus-gitlab). + for most users, but you may need to tweak them in [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab). 1. If you add a new file, submit an issue to the [production tracker](https://gitlab.com/gitlab-com/gl-infra/production/issues) or diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 3181b3a88cc..4740cf4de7b 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -1,12 +1,12 @@ # Migration Style Guide When writing migrations for GitLab, you have to take into account that -these will be ran by hundreds of thousands of organizations of all sizes, some with +these will be run by hundreds of thousands of organizations of all sizes, some with many years of data in their database. In addition, having to take a server offline for an upgrade small or big is a -big burden for most organizations. For this reason it is important that your -migrations are written carefully, can be applied online and adhere to the style +big burden for most organizations. For this reason, it is important that your +migrations are written carefully, can be applied online, and adhere to the style guide below. Migrations are **not** allowed to require GitLab installations to be taken @@ -85,7 +85,38 @@ be possible to downgrade in case of a vulnerability or bugs. In your migration, add a comment describing how the reversibility of the migration was tested. -## Multi Threading +## Atomicity + +By default, migrations are single transaction. That is, a transaction is opened +at the beginning of the migration, and committed after all steps are processed. + +Running migrations in a single transaction makes sure that if one of the steps fails, +none of the steps will be executed, leaving the database in valid state. +Therefore, either: + +- Put all migrations in one single-transaction migration. +- If necessary, put most actions in one migration and create a separate migration + for the steps that cannot be done in a single transaction. + +For example, if you create an empty table and need to build an index for it, +it is recommended to use a regular single-transaction migration and the default +rails schema statement: [`add_index`](https://api.rubyonrails.org/v5.2/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_index). +This is a blocking operation, but it won't cause problems because the table is not yet used, +and therefore it does not have any records yet. + +## Heavy operations in a single transaction + +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. + +In case you need to insert, update, or delete a significant amount of data, you: + +- Must disable the single transaction with `disable_ddl_transaction!`. +- Should consider doing it in a [Background Migration](background_migrations.md). + +## Multi-Threading Sometimes a migration might need to use multiple Ruby threads to speed up a migration. For this to work your migration needs to include the module @@ -122,16 +153,16 @@ pool. This ensures each thread has its own connection object, and won't time out when trying to obtain one. **NOTE:** PostgreSQL has a maximum amount of connections that it allows. This -limit can vary from installation to installation. As a result it's recommended -you do not use more than 32 threads in a single migration. Usually 4-8 threads +limit can vary from installation to installation. As a result, it's recommended +you do not use more than 32 threads in a single migration. Usually, 4-8 threads should be more than enough. ## Removing indexes -When removing an index make sure to use the method `remove_concurrent_index` instead -of the regular `remove_index` method. The `remove_concurrent_index` method -automatically drops concurrent indexes when using PostgreSQL, removing the -need for downtime. To use this method you must disable single-transaction mode +If the table is not empty when removing an index, make sure to use the method +`remove_concurrent_index` instead of the regular `remove_index` method. +The `remove_concurrent_index` method drops indexes concurrently, so no locking is required, +and there is no need for downtime. To use this method, you must disable single-transaction mode by calling the method `disable_ddl_transaction!` in the body of your migration class like so: @@ -149,19 +180,25 @@ end Note that it is not necessary to check if the index exists prior to removing it. +For a small table (such as an empty one or one with less than `1,000` records), +it is recommended to use `remove_index` in a single-transaction migration, +combining it with other operations that don't require `disable_ddl_transaction!`. + ## Adding indexes -If you need to add a unique index please keep in mind there is the possibility +If you need to add a unique index, please keep in mind there is the possibility of existing duplicates being present in the database. This means that should always _first_ add a migration that removes any duplicates, before adding the unique index. -When adding an index make sure to use the method `add_concurrent_index` instead -of the regular `add_index` method. The `add_concurrent_index` method -automatically creates concurrent indexes when using PostgreSQL, removing the -need for downtime. To use this method you must disable transactions by calling -the method `disable_ddl_transaction!` in the body of your migration class like -so: +When adding an index to a non-empty table make sure to use the method +`add_concurrent_index` instead of the regular `add_index` method. +The `add_concurrent_index` method automatically creates concurrent indexes +when using PostgreSQL, removing the need for downtime. + +To use this method, you must disable single-transactions mode +by calling the method `disable_ddl_transaction!` in the body of your migration +class like so: ```ruby class MyMigration < ActiveRecord::Migration[4.2] @@ -179,16 +216,20 @@ class MyMigration < ActiveRecord::Migration[4.2] end ``` +For a small table (such as an empty one or one with less than `1,000` records), +it is recommended to use `add_index` in a single-transaction migration, combining it with other +operations that don't require `disable_ddl_transaction!`. + ## Adding foreign-key constraints -When adding a foreign-key constraint to either an existing or new -column remember to also add a index on the column. +When adding a foreign-key constraint to either an existing or a new column also +remember to add an index on the column. This is **required** for all foreign-keys, e.g., to support efficient cascading deleting: when a lot of rows in a table get deleted, the referenced records need to be deleted too. The database has to look for corresponding records in the referenced table. Without an index, this will result in a sequential scan on the -table which can take a long time. +table, which can take a long time. Here's an example where we add a new column with a foreign key constraint. Note it includes `index: true` to create an index for it. @@ -202,13 +243,17 @@ class Migration < ActiveRecord::Migration[4.2] end ``` -When adding a foreign-key constraint to an existing column, we -have to employ `add_concurrent_foreign_key` and `add_concurrent_index` +When adding a foreign-key constraint to an existing column in a non-empty table, +we have to employ `add_concurrent_foreign_key` and `add_concurrent_index` instead of `add_reference`. +For an empty table (such as a fresh one), it is recommended to use +`add_reference` in a single-transaction migration, combining it with other +operations that don't require `disable_ddl_transaction!`. + ## Adding Columns With Default Values -When adding columns with default values you must use the method +When adding columns with default values to non-empty tables, you must use `add_column_with_default`. This method ensures the table is updated without requiring downtime. This method is not reversible so you must manually define the `up` and `down` methods in your migration class. @@ -232,10 +277,14 @@ end ``` Keep in mind that this operation can easily take 10-15 minutes to complete on -larger installations (e.g. GitLab.com). As a result you should only add default -values if absolutely necessary. There is a RuboCop cop that will fail if this -method is used on some tables that are very large on GitLab.com, which would -cause other issues. +larger installations (e.g. GitLab.com). As a result, you should only add +default values if absolutely necessary. There is a RuboCop cop that will fail if +this method is used on some tables that are very large on GitLab.com, which +would cause other issues. + +For a small table (such as an empty one or one with less than `1,000` records), +use `add_column` and `change_column_default` in a single-transaction migration, +combining it with other operations that don't require `disable_ddl_transaction!`. ## Updating an existing column @@ -253,8 +302,10 @@ update_column_in_batches(:projects, :foo, 10) do |table, query| end ``` -To perform a computed update, the value can be wrapped in `Arel.sql`, so Arel -treats it as an SQL literal. The below example is the same as the one above, but +If a computed update is needed, the value can be wrapped in `Arel.sql`, so Arel +treats it as an SQL literal. It's also a required deprecation for [Rails 6](https://gitlab.com/gitlab-org/gitlab-ce/issues/61451). + +The below example is the same as the one above, but the value is set to the product of the `bar` and `baz` columns: ```ruby @@ -275,12 +326,12 @@ staging environment - or asking someone else to do so for you - beforehand. By default, an integer column can hold up to a 4-byte (32-bit) number. That is a max value of 2,147,483,647. Be aware of this when creating a column that will -hold file sizes in byte units. If you are tracking file size in bytes this +hold file sizes in byte units. If you are tracking file size in bytes, this restricts the maximum file size to just over 2GB. To allow an integer column to hold up to an 8-byte (64-bit) number, explicitly set the limit to 8-bytes. This will allow the column to hold a value up to -9,223,372,036,854,775,807. +`9,223,372,036,854,775,807`. Rails migration example: @@ -294,9 +345,11 @@ add_column(:projects, :foo, :integer, default: 10, limit: 8) ## Timestamp column type -By default, Rails uses the `timestamp` data type that stores timestamp data without timezone information. -The `timestamp` data type is used by calling either the `add_timestamps` or the `timestamps` method. -Also Rails converts the `:datetime` data type to the `timestamp` one. +By default, Rails uses the `timestamp` data type that stores timestamp data +without timezone information. The `timestamp` data type is used by calling +either the `add_timestamps` or the `timestamps` method. + +Also, Rails converts the `:datetime` data type to the `timestamp` one. Example: @@ -317,14 +370,16 @@ def up end ``` -Instead of using these methods one should use the following methods to store timestamps with timezones: +Instead of using these methods, one should use the following methods to store +timestamps with timezones: - `add_timestamps_with_timezone` - `timestamps_with_timezone` -This ensures all timestamps have a time zone specified. This in turn means existing timestamps won't -suddenly use a different timezone when the system's timezone changes. It also makes it very clear which -timezone was used in the first place. +This ensures all timestamps have a time zone specified. This, in turn, means +existing timestamps won't suddenly use a different timezone when the system's +timezone changes. It also makes it very clear which timezone was used in the +first place. ## Storing JSON in database @@ -359,7 +414,7 @@ Make sure your migration can be reversed. ## Data migration Please prefer Arel and plain SQL over usual ActiveRecord syntax. In case of -using plain SQL you need to quote all input manually with `quote_string` helper. +using plain SQL, you need to quote all input manually with `quote_string` helper. Example with Arel: @@ -384,7 +439,7 @@ select_all("SELECT name, COUNT(id) as cnt FROM tags GROUP BY name HAVING COUNT(i end ``` -If you need more complex logic you can define and use models local to a +If you need more complex logic, you can define and use models local to a migration. For example: ```ruby @@ -395,13 +450,13 @@ class MyMigration < ActiveRecord::Migration[4.2] end ``` -When doing so be sure to explicitly set the model's table name so it's not +When doing so be sure to explicitly set the model's table name, so it's not derived from the class name or namespace. ### Renaming reserved paths -When a new route for projects is introduced that could conflict with any -existing records. The path for this records should be renamed, and the +When a new route for projects is introduced, it could conflict with any +existing records. The path for these records should be renamed, and the related data should be moved on disk. Since we had to do this a few times already, there are now some helpers to help diff --git a/doc/development/namespaces_storage_statistics.md b/doc/development/namespaces_storage_statistics.md new file mode 100644 index 00000000000..2c7e5935435 --- /dev/null +++ b/doc/development/namespaces_storage_statistics.md @@ -0,0 +1,178 @@ +# Database case study: Namespaces storage statistics + +## Introduction + +On [Storage and limits management for groups](https://gitlab.com/groups/gitlab-org/-/epics/886), +we want to facilitate a method for easily viewing the amount of +storage consumed by a group, and allow easy management. + +## Proposal + +1. Create a new ActiveRecord model to hold the namespaces' statistics in an aggregated form (only for root namespaces). +1. Refresh the statistics in this model every time a project belonging to this namespace is changed. + +## Problem + +In GitLab, we update the project storage statistics through a +[callback](https://gitlab.com/gitlab-org/gitlab-ce/blob/v12.2.0.pre/app/models/project.rb#L90) +every time the project is saved. + +The summary of those statistics per namespace is then retrieved +by [`Namespaces#with_statistics`](https://gitlab.com/gitlab-org/gitlab-ce/blob/v12.2.0.pre/app/models/namespace.rb#L70) scope. Analyzing this query we noticed that: + +- It takes up to `1.2` seconds for namespaces with over `15k` projects. +- It can't be analyzed with [ChatOps](chatops_on_gitlabcom.md), as it times out. + +Additionally, the pattern that is currently used to update the project statistics +(the callback) doesn't scale adequately. It is currently one of the largest +[database queries transactions on production](https://gitlab.com/gitlab-org/gitlab-ce/issues/62488) +that takes the most time overall. We can't add one more query to it as +it will increase the transaction's length. + +Because of all of the above, we can't apply the same pattern to store +and update the namespaces statistics, as the `namespaces` table is one +of the largest tables on GitLab.com. Therefore we needed to find a performant and +alternative method. + +## Attempts + +### Attempt A: PostgreSQL materialized view + +Model can be updated through a refresh strategy based on a project routes SQL and a [materialized view](https://www.postgresql.org/docs/9.6/rules-materializedviews.html): + +```sql +SELECT split_part("rs".path, '/', 1) as root_path, + COALESCE(SUM(ps.storage_size), 0) AS storage_size, + COALESCE(SUM(ps.repository_size), 0) AS repository_size, + COALESCE(SUM(ps.wiki_size), 0) AS wiki_size, + COALESCE(SUM(ps.lfs_objects_size), 0) AS lfs_objects_size, + COALESCE(SUM(ps.build_artifacts_size), 0) AS build_artifacts_size, + COALESCE(SUM(ps.packages_size), 0) AS packages_size +FROM "projects" + INNER JOIN routes rs ON rs.source_id = projects.id AND rs.source_type = 'Project' + INNER JOIN project_statistics ps ON ps.project_id = projects.id +GROUP BY root_path +``` + +We could then execute the query with: + +```sql +REFRESH MATERIALIZED VIEW root_namespace_storage_statistics; +``` + +While this implied a single query update (and probably a fast one), it has some downsides: + +- Materialized views syntax varies from PostgreSQL and MySQL. While this feature was worked on, MySQL was still supported by GitLab. +- Rails does not have native support for materialized views. We'd need to use a specialized gem to take care of the management of the database views, which implies additional work. + +### Attempt B: An update through a CTE + +Similar to Attempt A: Model update done through a refresh strategy with a [Common Table Expression](https://www.postgresql.org/docs/9.1/queries-with.html) + +```sql +WITH refresh AS ( + SELECT split_part("rs".path, '/', 1) as root_path, + COALESCE(SUM(ps.storage_size), 0) AS storage_size, + COALESCE(SUM(ps.repository_size), 0) AS repository_size, + COALESCE(SUM(ps.wiki_size), 0) AS wiki_size, + COALESCE(SUM(ps.lfs_objects_size), 0) AS lfs_objects_size, + COALESCE(SUM(ps.build_artifacts_size), 0) AS build_artifacts_size, + COALESCE(SUM(ps.packages_size), 0) AS packages_size + FROM "projects" + INNER JOIN routes rs ON rs.source_id = projects.id AND rs.source_type = 'Project' + INNER JOIN project_statistics ps ON ps.project_id = projects.id + GROUP BY root_path) +UPDATE namespace_storage_statistics +SET storage_size = refresh.storage_size, + repository_size = refresh.repository_size, + wiki_size = refresh.wiki_size, + lfs_objects_size = refresh.lfs_objects_size, + build_artifacts_size = refresh.build_artifacts_size, + packages_size = refresh.packages_size +FROM refresh + INNER JOIN routes rs ON rs.path = refresh.root_path AND rs.source_type = 'Namespace' +WHERE namespace_storage_statistics.namespace_id = rs.source_id +``` + +Same benefits and downsides as attempt A. + +### Attempt C: Get rid of the model and store the statistics on Redis + +We could get rid of the model that stores the statistics in aggregated form and instead use a Redis Set. +This would be the [boring solution](https://about.gitlab.com/handbook/values/#boring-solutions) and the fastest one +to implement, as GitLab already includes Redis as part of its [Architecture](architecture.md#redis). + +The downside of this approach is that Redis does not provide the same persistence/consistency guarantees as PostgreSQL, +and this is information we can't afford to lose in a Redis failure. + +### Attempt D: Tag the root namespace and its child namespaces + +Directly relate the root namespace to its child namespaces, so +whenever a namespace is created without a parent, this one is tagged +with the root namespace ID: + +| id | root_id | parent_id +|:---|:--------|:---------- +| 1 | 1 | NULL +| 2 | 1 | 1 +| 3 | 1 | 2 + +To aggregate the statistics inside a namespace we'd execute something like: + +```sql +SELECT COUNT(...) +FROM projects +WHERE namespace_id IN ( + SELECT id + FROM namespaces + WHERE root_id = X +) +``` + +Even though this approach would make aggregating much easier, it has some major downsides: + +- We'd have to migrate **all namespaces** by adding and filling a new column. Because of the size of the table, dealing with time/cost will not be great. The background migration will take approximately `153h`, see <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29772>. +- Background migration has to be shipped one release before, delaying the functionality by another milestone. + +### Attempt E (final): Update the namespace storage statistics in async way + +This approach consists of keep using the incremental statistics updates we currently already have, +but we refresh them through Sidekiq jobs and in different transactions: + +1. Create a second table (`namespace_aggregation_schedules`) with two columns `id` and `namespace_id`. +1. Whenever the statistics of a project changes, insert a row into `namespace_aggregation_schedules` + - We don't insert a new row if there's already one related to the root namespace. + - Keeping in mind the length of the transaction that involves updating `project_statistics`(<https://gitlab.com/gitlab-org/gitlab-ce/issues/62488>), the insertion should be done in a different transaction and through a Sidekiq Job. +1. After inserting the row, we schedule another worker to be executed async at two different moments: + - One enqueued for immediate execution and another one scheduled in `1.5h` hours. + - We only schedule the jobs, if we can obtain a `1.5h` lease on Redis on a key based on the root namespace ID. + - If we can't obtain the lease, it indicates there's another aggregation already in progress, or scheduled in no more than `1.5h`. +1. This worker will: + - Update the root namespace storage statistics by querying all the namespaces through a service. + - Delete the related `namespace_aggregation_schedules` after the update. +1. Another Sidekiq job is also included to traverse any remaining rows on the `namespace_aggregation_schedules` table and schedule jobs for every pending row. + - This job is scheduled with cron to run every night (UTC). + +This implementation has the following benefits: + +- All the updates are done async, so we're not increasing the length of the transactions for `project_statistics`. +- We're doing the update in a single SQL query. +- It is compatible with PostgreSQL and MySQL. +- No background migration required. + +The only downside of this approach is that namespaces' statistics are updated up to `1.5` hours after the change is done, +which means there's a time window in which the statistics are inaccurate. Because we're still not +[enforcing storage limits](https://gitlab.com/gitlab-org/gitlab-ce/issues/30421), this is not a major problem. + +## Conclusion + +Updating the storage statistics asynchronously, was the less problematic and +performant approach of aggregating the root namespaces. + +All the details regarding this use case can be found on: + +- <https://gitlab.com/gitlab-org/gitlab-ce/issues/62214> +- Merge Request with the implementation: <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/28996> + +Performance of the namespace storage statistics were measured in staging and production (GitLab.com). All results were posted +on <https://gitlab.com/gitlab-org/gitlab-ce/issues/64092>: No problem has been reported so far. diff --git a/doc/development/new_fe_guide/dependencies.md b/doc/development/new_fe_guide/dependencies.md index 8a6930acd37..161ffb1fb57 100644 --- a/doc/development/new_fe_guide/dependencies.md +++ b/doc/development/new_fe_guide/dependencies.md @@ -1,6 +1,6 @@ # Dependencies -## Adding Dependencies. +## Adding Dependencies GitLab uses `yarn` to manage dependencies. These dependencies are defined in two groups within `package.json`, `dependencies` and `devDependencies`. For diff --git a/doc/development/new_fe_guide/development/testing.md b/doc/development/new_fe_guide/development/testing.md index f7ea496d935..b990425ca3c 100644 --- a/doc/development/new_fe_guide/development/testing.md +++ b/doc/development/new_fe_guide/development/testing.md @@ -1,361 +1,5 @@ -# Overview of Frontend Testing +--- +redirect_to: '../../testing_guide/frontend_testing.md' +--- -Tests relevant for frontend development can be found at the following places: - -- `spec/javascripts/` which are run by Karma (command: `yarn karma`) and contain - - [frontend unit tests](#frontend-unit-tests) - - [frontend component tests](#frontend-component-tests) - - [frontend integration tests](#frontend-integration-tests) -- `spec/frontend/` which are run by Jest (command: `yarn jest`) and contain - - [frontend unit tests](#frontend-unit-tests) - - [frontend component tests](#frontend-component-tests) - - [frontend integration tests](#frontend-integration-tests) -- `spec/features/` which are run by RSpec and contain - - [feature tests](#feature-tests) - -All tests in `spec/javascripts/` will eventually be migrated to `spec/frontend/` (see also [#52483](https://gitlab.com/gitlab-org/gitlab-ce/issues/52483)). - -In addition there were feature tests in `features/` run by Spinach in the past. -These have been removed from our codebase in May 2018 ([#23036](https://gitlab.com/gitlab-org/gitlab-ce/issues/23036)). - -See also: - -- [Old testing guide](../../testing_guide/frontend_testing.html). -- [Notes on testing Vue components](../../fe_guide/vue.html#testing-vue-components). - -## Frontend unit tests - -Unit tests are on the lowest abstraction level and typically test functionality that is not directly perceivable by a user. - -### When to use unit tests - -<details> - <summary>exported functions and classes</summary> - Anything that is exported can be reused at various places in a way you have no control over. - Therefore it is necessary to document the expected behavior of the public interface with tests. -</details> - -<details> - <summary>Vuex actions</summary> - Any Vuex action needs to work in a consistent way independent of the component it is triggered from. -</details> - -<details> - <summary>Vuex mutations</summary> - For complex Vuex mutations it helps to identify the source of a problem by separating the tests from other parts of the Vuex store. -</details> - -### When *not* to use unit tests - -<details> - <summary>non-exported functions or classes</summary> - Anything that is not exported from a module can be considered private or an implementation detail and doesn't need to be tested. -</details> - -<details> - <summary>constants</summary> - Testing the value of a constant would mean to copy it. - This results in extra effort without additional confidence that the value is correct. -</details> - -<details> - <summary>Vue components</summary> - Computed properties, methods, and lifecycle hooks can be considered an implementation detail of components and don't need to be tested. - They are implicitly covered by component tests. - The <a href="https://vue-test-utils.vuejs.org/guides/#getting-started">official Vue guidelines</a> suggest the same. -</details> - -### What to mock in unit tests - -<details> - <summary>state of the class under test</summary> - Modifying the state of the class under test directly rather than using methods of the class avoids side-effects in test setup. -</details> - -<details> - <summary>other exported classes</summary> - Every class needs to be tested in isolation to prevent test scenarios from growing exponentially. -</details> - -<details> - <summary>single DOM elements if passed as parameters</summary> - For tests that only operate on single DOM elements rather than a whole page, creating these elements is cheaper than loading a whole HTML fixture. -</details> - -<details> - <summary>all server requests</summary> - When running frontend unit tests, the backend may not be reachable. - Therefore all outgoing requests need to be mocked. -</details> - -<details> - <summary>asynchronous background operations</summary> - Background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects. -</details> - -### What *not* to mock in unit tests - -<details> - <summary>non-exported functions or classes</summary> - Everything that is not exported can be considered private to the module and will be implicitly tested via the exported classes / functions. -</details> - -<details> - <summary>methods of the class under test</summary> - By mocking methods of the class under test, the mocks will be tested and not the real methods. -</details> - -<details> - <summary>utility functions (pure functions, or those that only modify parameters)</summary> - If a function has no side effects because it has no state, it is safe to not mock it in tests. -</details> - -<details> - <summary>full HTML pages</summary> - Loading the HTML of a full page slows down tests, so it should be avoided in unit tests. -</details> - -## Frontend component tests - -Component tests cover the state of a single component that is perceivable by a user depending on external signals such as user input, events fired from other components, or application state. - -### When to use component tests - -- Vue components - -### When *not* to use component tests - -<details> - <summary>Vue applications</summary> - Vue applications may contain many components. - Testing them on a component level requires too much effort. - Therefore they are tested on frontend integration level. -</details> - -<details> - <summary>HAML templates</summary> - HAML templates contain only Markup and no frontend-side logic. - Therefore they are not complete components. -</details> - -### What to mock in component tests - -<details> - <summary>DOM</summary> - Operating on the real DOM is significantly slower than on the virtual DOM. -</details> - -<details> - <summary>properties and state of the component under test</summary> - Similarly to testing classes, modifying the properties directly (rather than relying on methods of the component) avoids side-effects. -</details> - -<details> - <summary>Vuex store</summary> - To avoid side effects and keep component tests simple, Vuex stores are replaced with mocks. -</details> - -<details> - <summary>all server requests</summary> - Similar to unit tests, when running component tests, the backend may not be reachable. - Therefore all outgoing requests need to be mocked. -</details> - -<details> - <summary>asynchronous background operations</summary> - Similar to unit tests, background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects. -</details> - -<details> - <summary>child components</summary> - Every component is tested individually, so child components are mocked. - See also <a href="https://vue-test-utils.vuejs.org/api/#shallowmount">shallowMount()</a> -</details> - -### What *not* to mock in component tests - -<details> - <summary>methods or computed properties of the component under test</summary> - By mocking part of the component under test, the mocks will be tested and not the real component. -</details> - -<details> - <summary>functions and classes independent from Vue</summary> - All plain JavaScript code is already covered by unit tests and needs not to be mocked in component tests. -</details> - -## Frontend integration tests - -Integration tests cover the interaction between all components on a single page. -Their abstraction level is comparable to how a user would interact with the UI. - -### When to use integration tests - -<details> - <summary>page bundles (<code>index.js</code> files in <code>app/assets/javascripts/pages/</code>)</summary> - Testing the page bundles ensures the corresponding frontend components integrate well. -</details> - -<details> - <summary>Vue applications outside of page bundles</summary> - Testing Vue applications as a whole ensures the corresponding frontend components integrate well. -</details> - -### What to mock in integration tests - -<details> - <summary>HAML views (use fixtures instead)</summary> - Rendering HAML views requires a Rails environment including a running database which we cannot rely on in frontend tests. -</details> - -<details> - <summary>all server requests</summary> - Similar to unit and component tests, when running component tests, the backend may not be reachable. - Therefore all outgoing requests need to be mocked. -</details> - -<details> - <summary>asynchronous background operations that are not perceivable on the page</summary> - Background operations that affect the page need to be tested on this level. - All other background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects. -</details> - -### What *not* to mock in integration tests - -<details> - <summary>DOM</summary> - Testing on the real DOM ensures our components work in the environment they are meant for. - Part of this will be delegated to <a href="https://gitlab.com/gitlab-org/quality/team-tasks/issues/45">cross-browser testing</a>. -</details> - -<details> - <summary>properties or state of components</summary> - On this level, all tests can only perform actions a user would do. - For example to change the state of a component, a click event would be fired. -</details> - -<details> - <summary>Vuex stores</summary> - When testing the frontend code of a page as a whole, the interaction between Vue components and Vuex stores is covered as well. -</details> - -## Feature tests - -In contrast to [frontend integration tests](#frontend-integration-tests), feature tests make requests against the real backend instead of using fixtures. -This also implies that database queries are executed which makes this category significantly slower. - -See also the [RSpec testing guidelines](../../testing_guide/best_practices.md#rspec). - -### When to use feature tests - -- use cases that require a backend and cannot be tested using fixtures -- behavior that is not part of a page bundle but defined globally - -### Relevant notes - -A `:js` flag is added to the test to make sure the full environment is loaded. - -``` -scenario 'successfully', :js do - sign_in(create(:admin)) -end -``` - -The steps of each test are written using capybara methods ([documentation](https://www.rubydoc.info/gems/capybara)). - -Bear in mind <abbr title="XMLHttpRequest">XHR</abbr> calls might require you to use `wait_for_requests` in between steps, like so: - -```rspec -find('.form-control').native.send_keys(:enter) - -wait_for_requests - -expect(page).not_to have_selector('.card') -``` - -## Test helpers - -### Vuex Helper: `testAction` - -We have a helper available to make testing actions easier, as per [official documentation](https://vuex.vuejs.org/guide/testing.html): - -``` -testAction( - actions.actionName, // action - { }, // params to be passed to action - state, // state - [ - { type: types.MUTATION}, - { type: types.MUTATION_1, payload: {}}, - ], // mutations committed - [ - { type: 'actionName', payload: {}}, - { type: 'actionName1', payload: {}}, - ] // actions dispatched - done, -); -``` - -Check an example in [spec/javascripts/ide/stores/actions_spec.jsspec/javascripts/ide/stores/actions_spec.js](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/javascripts/ide/stores/actions_spec.js). - -### Vue Helper: `mountComponent` - -To make mounting a Vue component easier and more readable, we have a few helpers available in `spec/helpers/vue_mount_component_helper`. - -- `createComponentWithStore` -- `mountComponentWithStore` - -Examples of usage: - -``` -beforeEach(() => { - vm = createComponentWithStore(Component, store); - - vm.$store.state.currentBranchId = 'master'; - - vm.$mount(); -}, -``` - -``` -beforeEach(() => { - vm = mountComponentWithStore(Component, { - el: '#dummy-element', - store, - props: { badge }, - }); -}, -``` - -Don't forget to clean up: - -``` -afterEach(() => { - vm.$destroy(); -}); -``` - -## Testing with older browsers - -Some regressions only affect a specific browser version. We can install and test in particular browsers with either Firefox or Browserstack using the following steps: - -### Browserstack - -[Browserstack](https://www.browserstack.com/) allows you to test more than 1200 mobile devices and browsers. -You can use it directly through the [live app](https://www.browserstack.com/live) or you can install the [chrome extension](https://chrome.google.com/webstore/detail/browserstack/nkihdmlheodkdfojglpcjjmioefjahjb) for easy access. -You can find the credentials on 1Password, under `frontendteam@gitlab.com`. - -### Firefox - -#### macOS - -You can download any older version of Firefox from the releases FTP server, <https://ftp.mozilla.org/pub/firefox/releases/> - -1. From the website, select a version, in this case `50.0.1`. -1. Go to the mac folder. -1. Select your preferred language, you will find the dmg package inside, download it. -1. Drag and drop the application to any other folder but the `Applications` folder. -1. Rename the application to something like `Firefox_Old`. -1. Move the application to the `Applications` folder. -1. Open up a terminal and run `/Applications/Firefox_Old.app/Contents/MacOS/firefox-bin -profilemanager` to create a new profile specific to that Firefox version. -1. Once the profile has been created, quit the app, and run it again like normal. You now have a working older Firefox version. +This document was moved to [another location](../../testing_guide/frontend_testing.md). diff --git a/doc/development/new_fe_guide/modules/dirty_submit.md b/doc/development/new_fe_guide/modules/dirty_submit.md index 6c03958b463..217743ea395 100644 --- a/doc/development/new_fe_guide/modules/dirty_submit.md +++ b/doc/development/new_fe_guide/modules/dirty_submit.md @@ -1,7 +1,6 @@ # Dirty Submit -> [Introduced][ce-21115] in GitLab 11.3. -> [dirty_submit][dirty-submit] +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21115) in GitLab 11.3. ## Summary @@ -9,6 +8,9 @@ Prevent submitting forms with no changes. Currently handles `input`, `textarea` and `select` elements. +Also, see [the code](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/dirty_submit/) +within the GitLab project. + ## Usage ```js @@ -18,6 +20,3 @@ new DirtySubmitForm(document.querySelector('form')); // or new DirtySubmitForm(document.querySelectorAll('form')); ``` - -[ce-21115]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21115 -[dirty-submit]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/dirty_submit/
\ No newline at end of file diff --git a/doc/development/new_fe_guide/style/javascript.md b/doc/development/new_fe_guide/style/javascript.md index 802ebd12d92..b742d567f41 100644 --- a/doc/development/new_fe_guide/style/javascript.md +++ b/doc/development/new_fe_guide/style/javascript.md @@ -192,4 +192,4 @@ rules only if you are invoking/instantiating existing code modules. - [class-method-use-this](http://eslint.org/docs/rules/class-methods-use-this) > Note: Disable these rules on a per line basis. This makes it easier to refactor - in the future. E.g. use `eslint-disable-next-line` or `eslint-disable-line`. +> in the future. E.g. use `eslint-disable-next-line` or `eslint-disable-line`. diff --git a/doc/development/omnibus.md b/doc/development/omnibus.md index 0ba354d28a2..ea5c18f1a8c 100644 --- a/doc/development/omnibus.md +++ b/doc/development/omnibus.md @@ -1,32 +1,32 @@ -# What you should know about omnibus packages +# What you should know about Omnibus packages -Most users install GitLab using our omnibus packages. As a developer it can be -good to know how the omnibus packages differ from what you have on your laptop +Most users install GitLab using our Omnibus packages. As a developer it can be +good to know how the Omnibus packages differ from what you have on your laptop when you are coding. ## Files are owned by root by default -All the files in the Rails tree (`app/`, `config/` etc.) are owned by 'root' in -omnibus installations. This makes the installation simpler and it provides -extra security. The omnibus reconfigure script contains commands that give -write access to the 'git' user only where needed. +All the files in the Rails tree (`app/`, `config/` etc.) are owned by `root` in +Omnibus installations. This makes the installation simpler and it provides +extra security. The Omnibus reconfigure script contains commands that give +write access to the `git` user only where needed. -For example, the 'git' user is allowed to write in the `log/` directory, in +For example, the `git` user is allowed to write in the `log/` directory, in `public/uploads`, and they are allowed to rewrite the `db/schema.rb` file. In other cases, the reconfigure script tricks GitLab into not trying to write a file. For instance, GitLab will generate a `.secret` file if it cannot find one -and write it to the Rails root. In the omnibus packages, reconfigure writes the +and write it to the Rails root. In the Omnibus packages, reconfigure writes the `.secret` file first, so that GitLab never tries to write it. ## Code, data and logs are in separate directories -The omnibus design separates code (read-only, under `/opt/gitlab`) from data +The Omnibus design separates code (read-only, under `/opt/gitlab`) from data (read/write, under `/var/opt/gitlab`) and logs (read/write, under `/var/log/gitlab`). To make this happen the reconfigure script sets custom paths where it can in GitLab config files, and where there are no path settings, it uses symlinks. For example, `config/gitlab.yml` is treated as data so that file is a symlink. -The same goes for `public/uploads`. The `log/` directory is replaced by omnibus +The same goes for `public/uploads`. The `log/` directory is replaced by Omnibus with a symlink to `/var/log/gitlab/gitlab-rails`. diff --git a/doc/development/python_guide/index.md b/doc/development/python_guide/index.md index a80bee27d4a..47d9d96766c 100644 --- a/doc/development/python_guide/index.md +++ b/doc/development/python_guide/index.md @@ -7,9 +7,9 @@ As of GitLab 11.10, we require Python 3. ## Installation -There are several ways of installing python on your system. To be able to use the same version we use in production, -we suggest you use [pyenv](https://github.com/pyenv/pyenv). It works and behave similar to its counterpart in the -ruby world: [rbenv](https://github.com/rbenv/rbenv). +There are several ways of installing Python on your system. To be able to use the same version we use in production, +we suggest you use [pyenv](https://github.com/pyenv/pyenv). It works and behaves similarly to its counterpart in the +Ruby world: [rbenv](https://github.com/rbenv/rbenv). ### macOS @@ -67,7 +67,7 @@ Running this command will install both the required Python version as well as re ## Use instructions -To run any python code under the Pipenv environment, you need to first start a `virtualenv` based on the dependencies +To run any Python code under the Pipenv environment, you need to first start a `virtualenv` based on the dependencies of the application. With Pipenv, this is a simple as running: ```bash diff --git a/doc/development/query_recorder.md b/doc/development/query_recorder.md index a6b60149ea4..3787e2ef187 100644 --- a/doc/development/query_recorder.md +++ b/doc/development/query_recorder.md @@ -36,6 +36,13 @@ it "avoids N+1 database queries" do end ``` +## Use request specs instead of controller specs + +Use a [request spec](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/spec/requests) when writing a N+1 test on the controller level. + +Controller specs should not be used to write N+1 tests as the controller is only initialized once per example. +This could lead to false successes where subsequent "requests" could have queries reduced (e.g. because of memoization). + ## Finding the source of the query It may be useful to identify the source of the queries by looking at the call backtrace. diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index 67f36eb1ab4..e9d6cfe00b2 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -9,7 +9,7 @@ bundle exec rake setup ``` The `setup` task is an alias for `gitlab:setup`. -This tasks calls `db:reset` to create the database, calls `add_limits_mysql` that adds limits to the database schema in case of a MySQL database and finally it calls `db:seed_fu` to seed the database. +This tasks calls `db:reset` to create the database, and calls `db:seed_fu` to seed the database. Note: `db:setup` calls `db:seed` but this does nothing. ### Seeding issues for all or a given project @@ -216,4 +216,3 @@ bundle exec rake routes Since these take some time to create, it's often helpful to save the output to a file for quick reference. - diff --git a/doc/development/repository_mirroring.md b/doc/development/repository_mirroring.md index f8c33ff2b85..dc51bf80e92 100644 --- a/doc/development/repository_mirroring.md +++ b/doc/development/repository_mirroring.md @@ -8,4 +8,4 @@ In December 2018, Tiago Botelho hosted a [Deep Dive] on GitLab's [Pull Repositor [Pull Repository Mirroring functionality]: ../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter [recording on YouTube]: https://www.youtube.com/watch?v=sSZq0fpdY-Y [Google Slides]: https://docs.google.com/presentation/d/17BTT6M6RyNRckV4wTt-dr07nIfBvD325_xVBoLtSoPM/edit?usp=sharing -[PDF]: https://gitlab.com/gitlab-org/create-stage/uploads/8693404888a941fd851f8a8ecdec9675/Gitlab_Create_-_Pull_Mirroring_Deep_Dive.pdf
\ No newline at end of file +[PDF]: https://gitlab.com/gitlab-org/create-stage/uploads/8693404888a941fd851f8a8ecdec9675/Gitlab_Create_-_Pull_Mirroring_Deep_Dive.pdf diff --git a/doc/development/session.md b/doc/development/session.md index 9edce3dbda0..971795d8816 100644 --- a/doc/development/session.md +++ b/doc/development/session.md @@ -17,7 +17,7 @@ When storing values in a session it is best to: - Use simple primitives and avoid storing objects to avoid marshaling complications. - Clean up after unneeded variables to keep memory usage in Redis down. -## Gitlab::Session +## GitLab::Session Sometimes you might want to persist data in the session instead of another store like the database. `Gitlab::Session` lets you access this without passing the session around extensively. For example, you could access it from within a policy without having to pass the session through to each place permissions are checked from. diff --git a/doc/development/sha1_as_binary.md b/doc/development/sha1_as_binary.md index 3151cc29bbc..6c4252ec634 100644 --- a/doc/development/sha1_as_binary.md +++ b/doc/development/sha1_as_binary.md @@ -2,7 +2,7 @@ Storing SHA1 hashes as strings is not very space efficient. A SHA1 as a string requires at least 40 bytes, an additional byte to store the encoding, and -perhaps more space depending on the internals of PostgreSQL and MySQL. +perhaps more space depending on the internals of PostgreSQL. On the other hand, if one were to store a SHA1 as binary one would only need 20 bytes for the actual SHA1, and 1 or 4 bytes of additional space (again depending diff --git a/doc/development/shell_commands.md b/doc/development/shell_commands.md index 7bdf676be58..1300c99622e 100644 --- a/doc/development/shell_commands.md +++ b/doc/development/shell_commands.md @@ -35,7 +35,7 @@ Gitlab::Popen.popen(%W(find /some/path -not -path /some/path -mmin +120 -delete) This coding style could have prevented CVE-2013-4490. -## Always use the configurable git binary path for git commands +## Always use the configurable Git binary path for Git commands ```ruby # Wrong @@ -114,7 +114,7 @@ user = `whoami` user, exit_status = Gitlab::Popen.popen(%W(whoami)) ``` -In other repositories, such as gitlab-shell you can also use `IO.popen`. +In other repositories, such as GitLab Shell you can also use `IO.popen`. ```ruby # Safe IO.popen example diff --git a/doc/development/shell_scripting_guide/index.md b/doc/development/shell_scripting_guide/index.md index ae7f2154682..0809f8b1a0a 100644 --- a/doc/development/shell_scripting_guide/index.md +++ b/doc/development/shell_scripting_guide/index.md @@ -24,7 +24,8 @@ Having said all of the above, we recommend staying away from shell scripts as much as possible. A language like Ruby or Python (if required for consistency with codebases that we leverage) is almost always a better choice. The high-level interpreted languages have more readable syntax, offer much more -mature capabilities for unit-testing, linting, and error reporting. +mature capabilities for unit-testing, linting, and error reporting. + Use shell scripts only if there's a strong restriction on project's dependencies size or any other requirements that are more important in a particular case. @@ -48,12 +49,12 @@ that is: This section describes the tools that should be made a mandatory part of a project's CI pipeline if it contains shell scripts. These tools -automate shell code formatting, checking for errors or vulnerabilities, etc. +automate shell code formatting, checking for errors or vulnerabilities, etc. ### Linting We're using the [ShellCheck](https://www.shellcheck.net/) utility in its default configuration to lint our -shell scripts. +shell scripts. All projects with shell scripts should use this GitLab CI/CD job: @@ -98,7 +99,7 @@ NOTE: **Note:** This is a work in progress. It is an [ongoing effort](https://gitlab.com/gitlab-org/gitlab-ce/issues/64016) to evaluate different tools for the -automated testing of shell scripts (like [BATS](https://github.com/sstephenson/bats)). +automated testing of shell scripts (like [BATS](https://github.com/sstephenson/bats)). ## Code Review diff --git a/doc/development/sql.md b/doc/development/sql.md index a256fd46c09..2584dcfb4ca 100644 --- a/doc/development/sql.md +++ b/doc/development/sql.md @@ -15,14 +15,11 @@ FROM issues WHERE title LIKE 'WIP:%'; ``` -On PostgreSQL the `LIKE` statement is case-sensitive. On MySQL this depends on -the case-sensitivity of the collation, which is usually case-insensitive. To -perform a case-insensitive `LIKE` on PostgreSQL you have to use `ILIKE` instead. -This statement in turn isn't supported on MySQL. +On PostgreSQL the `LIKE` statement is case-sensitive. To perform a case-insensitive +`LIKE` you have to use `ILIKE` instead. -To work around this problem you should write `LIKE` queries using Arel instead -of raw SQL fragments as Arel automatically uses `ILIKE` on PostgreSQL and `LIKE` -on MySQL. This means that instead of this: +To handle this automatically you should use `LIKE` queries using Arel instead +of raw SQL fragments, as Arel automatically uses `ILIKE` on PostgreSQL. ```ruby Issue.where('title LIKE ?', 'WIP:%') @@ -45,7 +42,7 @@ table = Issue.arel_table Issue.where(table[:title].matches('WIP:%').or(table[:foo].matches('WIP:%'))) ``` -For PostgreSQL this produces: +On PostgreSQL, this produces: ```sql SELECT * @@ -53,18 +50,10 @@ FROM issues WHERE (title ILIKE 'WIP:%' OR foo ILIKE 'WIP:%') ``` -In turn for MySQL this produces: - -```sql -SELECT * -FROM issues -WHERE (title LIKE 'WIP:%' OR foo LIKE 'WIP:%') -``` - ## LIKE & Indexes -Neither PostgreSQL nor MySQL use any indexes when using `LIKE` / `ILIKE` with a -wildcard at the start. For example, this will not use any indexes: +PostgreSQL won't use any indexes when using `LIKE` / `ILIKE` with a wildcard at +the start. For example, this will not use any indexes: ```sql SELECT * @@ -75,9 +64,8 @@ WHERE title ILIKE '%WIP:%'; Because the value for `ILIKE` starts with a wildcard the database is not able to use an index as it doesn't know where to start scanning the indexes. -MySQL provides no known solution to this problem. Luckily PostgreSQL _does_ -provide a solution: trigram GIN indexes. These indexes can be created as -follows: +Luckily, PostgreSQL _does_ provide a solution: trigram GIN indexes. These +indexes can be created as follows: ```sql CREATE INDEX [CONCURRENTLY] index_name_here diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index 9d6792e9139..0f982c3a48b 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -13,17 +13,7 @@ a level that is difficult to manage. Test heuristics can help solve this problem. They concisely address many of the common ways bugs manifest themselves within our code. When designing our tests, take time to review known test heuristics to inform our test design. We can find some helpful heuristics documented in the Handbook in the -[Test Design](https://about.gitlab.com/handbook/engineering/quality/guidelines/test-engineering/test-design/) section. - -## Run tests against MySQL - -By default, tests are only run against PostgreSQL, but you can run them on -demand against MySQL by following one of the following conventions: - -| Convention | Valid example | -|:----------------------|:-----------------------------| -| Include `mysql` in your branch name | `enhance-mysql-support` | -| Include `[run mysql]` in your commit message | `Fix MySQL support<br><br>[run mysql]` | +[Test Engineering](https://about.gitlab.com/handbook/engineering/quality/test-engineering/#test-heuristics) section. ## Test speed @@ -455,6 +445,19 @@ complexity of RSpec expectations.They should be placed under a certain type of specs only (e.g. features, requests etc.) but shouldn't be if they apply to multiple type of specs. +#### `be_like_time` + +Time returned from a database can differ in precision from time objects +in Ruby, so we need flexible tolerances when comparing in specs. We can +use `be_like_time` to compare that times are within one second of each +other. + +Example: + +```ruby +expect(metrics.merged_at).to be_like_time(time) +``` + #### `have_gitlab_http_status` Prefer `have_gitlab_http_status` over `have_http_status` because the former diff --git a/doc/development/testing_guide/ci.md b/doc/development/testing_guide/ci.md index 87d48726268..d9f66a827de 100644 --- a/doc/development/testing_guide/ci.md +++ b/doc/development/testing_guide/ci.md @@ -39,7 +39,6 @@ slowest test files and try to improve them. ## CI setup -- On CE and EE, the test suite runs both PostgreSQL and MySQL. - Rails logging to `log/test.log` is disabled by default in CI [for performance reasons][logging]. To override this setting, provide the `RAILS_ENABLE_TEST_LOG` environment variable. diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md index d6b944a3e74..3ae3ce183d9 100644 --- a/doc/development/testing_guide/end_to_end/index.md +++ b/doc/development/testing_guide/end_to_end/index.md @@ -45,11 +45,11 @@ Results are reported in the `#qa-staging` Slack channel. ### Testing code in merge requests -#### Using the `package-and-qa` job +#### Using the `package-and-qa-manual` job It is possible to run end-to-end tests for a merge request, eventually being run in a pipeline in the [`gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa/) project, -by triggering the `package-and-qa` manual action in the `test` stage (not +by triggering the `package-and-qa-manual` manual action in the `test` stage (not available for forks). **This runs end-to-end tests against a custom Omnibus package built from your @@ -71,7 +71,7 @@ graph LR B2[`Trigger-qa` stage<br>`Trigger:qa-test` job] -.->|2. Triggers a gitlab-qa pipeline and wait for it to be done| A3 subgraph "gitlab-ce/ee pipeline" - A1[`test` stage<br>`package-and-qa` job] + A1[`test` stage<br>`package-and-qa-manual` job] end subgraph "omnibus-gitlab pipeline" @@ -79,7 +79,7 @@ subgraph "omnibus-gitlab pipeline" end subgraph "gitlab-qa pipeline" - A3>QA jobs run] -.->|3. Reports back the pipeline result to the `package-and-qa` job<br>and post the result on the original commit tested| A1 + A3>QA jobs run] -.->|3. Reports back the pipeline result to the `package-and-qa-manual` job<br>and post the result on the original commit tested| A1 end ``` 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 47e58a425fd..850ea6b60ac 100644 --- a/doc/development/testing_guide/end_to_end/page_objects.md +++ b/doc/development/testing_guide/end_to_end/page_objects.md @@ -40,7 +40,7 @@ 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 change until our GitLab QA nightly pipeline fails, or until someone triggers -`package-and-qa` action in their merge request. +`package-and-qa-manual` action in their merge request. Obviously such a change would break all tests. We call this problem a _fragile tests problem_. diff --git a/doc/development/testing_guide/end_to_end/quick_start_guide.md b/doc/development/testing_guide/end_to_end/quick_start_guide.md index e1df8be8b6f..d52d6db38b9 100644 --- a/doc/development/testing_guide/end_to_end/quick_start_guide.md +++ b/doc/development/testing_guide/end_to_end/quick_start_guide.md @@ -10,7 +10,7 @@ It's important to understand that end-to-end tests of isolated features, such as If you don't exactly understand what we mean by **not everything needs to happen through the GUI,** please make sure you've read the [best practices](best_practices.md) before moving on. -## This document covers the following items: +## This document covers the following items - [0.](#0-are-end-to-end-tests-needed) Identifying if end-to-end tests are really needed - [1.](#1-identifying-the-devops-stage) Identifying the [DevOps stage](https://about.gitlab.com/stages-devops-lifecycle/) of the feature that you are going to cover with end-to-end tests diff --git a/doc/development/testing_guide/end_to_end/style_guide.md b/doc/development/testing_guide/end_to_end/style_guide.md index 97560e616a1..54ed3f34c89 100644 --- a/doc/development/testing_guide/end_to_end/style_guide.md +++ b/doc/development/testing_guide/end_to_end/style_guide.md @@ -141,4 +141,4 @@ Resource::MergeRequest.fabricate! do |merge_request_page| end ``` -> Besides the advantage of having a standard in place, by following this standard we also write shorter lines of code.
\ No newline at end of file +> Besides the advantage of having a standard in place, by following this standard we also write shorter lines of code. diff --git a/doc/development/testing_guide/flaky_tests.md b/doc/development/testing_guide/flaky_tests.md index 931cbc51cae..eb0bf6fc563 100644 --- a/doc/development/testing_guide/flaky_tests.md +++ b/doc/development/testing_guide/flaky_tests.md @@ -35,8 +35,8 @@ Once a test is in quarantine, there are 3 choices: Quarantined tests are run on the CI in dedicated jobs that are allowed to fail: -- `rspec-pg-quarantine` and `rspec-mysql-quarantine` (CE & EE) -- `rspec-pg-quarantine-ee` and `rspec-mysql-quarantine-ee` (EE only) +- `rspec-pg-quarantine` (CE & EE) +- `rspec-pg-quarantine-ee` (EE only) ## Automatic retries and flaky tests detection diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 2985278cc92..7dc89a3fcdb 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -232,7 +232,7 @@ module. GitLab has a custom `spyOnDependency` method which utilizes [babel-plugin-rewire](https://github.com/speedskater/babel-plugin-rewire) to achieve this. It can be used like so: -```js +```javascript // my_module.js import { visitUrl } from '~/lib/utils/url_utility'; @@ -241,7 +241,7 @@ export default function doSomething() { } ``` -```js +```javascript // my_module_spec.js import doSomething from '~/my_module'; @@ -593,6 +593,517 @@ end [capybara]: https://github.com/teamcapybara/capybara [jasmine]: https://jasmine.github.io/ +## Overview of Frontend Testing Levels + +Tests relevant for frontend development can be found at the following places: + +- `spec/javascripts/` which are run by Karma (command: `yarn karma`) and contain + - [frontend unit tests](#frontend-unit-tests) + - [frontend component tests](#frontend-component-tests) + - [frontend integration tests](#frontend-integration-tests) +- `spec/frontend/` which are run by Jest (command: `yarn jest`) and contain + - [frontend unit tests](#frontend-unit-tests) + - [frontend component tests](#frontend-component-tests) + - [frontend integration tests](#frontend-integration-tests) +- `spec/features/` which are run by RSpec and contain + - [feature tests](#feature-tests) + +All tests in `spec/javascripts/` will eventually be migrated to `spec/frontend/` (see also [#52483](https://gitlab.com/gitlab-org/gitlab-ce/issues/52483)). + +In addition, there used to be feature tests in `features/`, run by Spinach. +These were removed from the codebase in May 2018 ([#23036](https://gitlab.com/gitlab-org/gitlab-ce/issues/23036)). + +See also [Notes on testing Vue components](../fe_guide/vue.html#testing-vue-components). + +### Frontend unit tests + +Unit tests are on the lowest abstraction level and typically test functionality that is not directly perceivable by a user. + +```mermaid +graph RL + plain[Plain JavaScript]; + Vue[Vue Components]; + feature-flags[Feature Flags]; + license-checks[License Checks]; + + plain---Vuex; + plain---GraphQL; + Vue---plain; + Vue---Vuex; + Vue---GraphQL; + browser---plain; + browser---Vue; + plain---backend; + Vuex---backend; + GraphQL---backend; + Vue---backend; + backend---database; + backend---feature-flags; + backend---license-checks; + + class plain tested; + class Vuex tested; + + classDef node color:#909090,fill:#f0f0f0,stroke-width:2px,stroke:#909090 + classDef label stroke-width:0; + classDef tested color:#000000,fill:#a0c0ff,stroke:#6666ff,stroke-width:2px,stroke-dasharray: 5, 5; + + subgraph " " + tested; + mocked; + class tested tested; + end +``` + +#### When to use unit tests + +<details> + <summary>exported functions and classes</summary> + Anything that is exported can be reused at various places in a way you have no control over. + Therefore it is necessary to document the expected behavior of the public interface with tests. +</details> + +<details> + <summary>Vuex actions</summary> + Any Vuex action needs to work in a consistent way independent of the component it is triggered from. +</details> + +<details> + <summary>Vuex mutations</summary> + For complex Vuex mutations it helps to identify the source of a problem by separating the tests from other parts of the Vuex store. +</details> + +#### When *not* to use unit tests + +<details> + <summary>non-exported functions or classes</summary> + Anything that is not exported from a module can be considered private or an implementation detail and doesn't need to be tested. +</details> + +<details> + <summary>constants</summary> + Testing the value of a constant would mean to copy it. + This results in extra effort without additional confidence that the value is correct. +</details> + +<details> + <summary>Vue components</summary> + Computed properties, methods, and lifecycle hooks can be considered an implementation detail of components and don't need to be tested. + They are implicitly covered by component tests. + The <a href="https://vue-test-utils.vuejs.org/guides/#getting-started">official Vue guidelines</a> suggest the same. +</details> + +#### What to mock in unit tests + +<details> + <summary>state of the class under test</summary> + Modifying the state of the class under test directly rather than using methods of the class avoids side-effects in test setup. +</details> + +<details> + <summary>other exported classes</summary> + Every class needs to be tested in isolation to prevent test scenarios from growing exponentially. +</details> + +<details> + <summary>single DOM elements if passed as parameters</summary> + For tests that only operate on single DOM elements rather than a whole page, creating these elements is cheaper than loading a whole HTML fixture. +</details> + +<details> + <summary>all server requests</summary> + When running frontend unit tests, the backend may not be reachable. + Therefore all outgoing requests need to be mocked. +</details> + +<details> + <summary>asynchronous background operations</summary> + Background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects. +</details> + +#### What *not* to mock in unit tests + +<details> + <summary>non-exported functions or classes</summary> + Everything that is not exported can be considered private to the module and will be implicitly tested via the exported classes / functions. +</details> + +<details> + <summary>methods of the class under test</summary> + By mocking methods of the class under test, the mocks will be tested and not the real methods. +</details> + +<details> + <summary>utility functions (pure functions, or those that only modify parameters)</summary> + If a function has no side effects because it has no state, it is safe to not mock it in tests. +</details> + +<details> + <summary>full HTML pages</summary> + Loading the HTML of a full page slows down tests, so it should be avoided in unit tests. +</details> + +### Frontend component tests + +Component tests cover the state of a single component that is perceivable by a user depending on external signals such as user input, events fired from other components, or application state. + +```mermaid +graph RL + plain[Plain JavaScript]; + Vue[Vue Components]; + feature-flags[Feature Flags]; + license-checks[License Checks]; + + plain---Vuex; + plain---GraphQL; + Vue---plain; + Vue---Vuex; + Vue---GraphQL; + browser---plain; + browser---Vue; + plain---backend; + Vuex---backend; + GraphQL---backend; + Vue---backend; + backend---database; + backend---feature-flags; + backend---license-checks; + + class Vue tested; + + classDef node color:#909090,fill:#f0f0f0,stroke-width:2px,stroke:#909090 + classDef label stroke-width:0; + classDef tested color:#000000,fill:#a0c0ff,stroke:#6666ff,stroke-width:2px,stroke-dasharray: 5, 5; + + subgraph " " + tested; + mocked; + class tested tested; + end +``` + +#### When to use component tests + +- Vue components + +#### When *not* to use component tests + +<details> + <summary>Vue applications</summary> + Vue applications may contain many components. + Testing them on a component level requires too much effort. + Therefore they are tested on frontend integration level. +</details> + +<details> + <summary>HAML templates</summary> + HAML templates contain only Markup and no frontend-side logic. + Therefore they are not complete components. +</details> + +#### What to mock in component tests + +<details> + <summary>DOM</summary> + Operating on the real DOM is significantly slower than on the virtual DOM. +</details> + +<details> + <summary>properties and state of the component under test</summary> + Similarly to testing classes, modifying the properties directly (rather than relying on methods of the component) avoids side-effects. +</details> + +<details> + <summary>Vuex store</summary> + To avoid side effects and keep component tests simple, Vuex stores are replaced with mocks. +</details> + +<details> + <summary>all server requests</summary> + Similar to unit tests, when running component tests, the backend may not be reachable. + Therefore all outgoing requests need to be mocked. +</details> + +<details> + <summary>asynchronous background operations</summary> + Similar to unit tests, background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects. +</details> + +<details> + <summary>child components</summary> + Every component is tested individually, so child components are mocked. + See also <a href="https://vue-test-utils.vuejs.org/api/#shallowmount">shallowMount()</a> +</details> + +#### What *not* to mock in component tests + +<details> + <summary>methods or computed properties of the component under test</summary> + By mocking part of the component under test, the mocks will be tested and not the real component. +</details> + +<details> + <summary>functions and classes independent from Vue</summary> + All plain JavaScript code is already covered by unit tests and needs not to be mocked in component tests. +</details> + +### Frontend integration tests + +Integration tests cover the interaction between all components on a single page. +Their abstraction level is comparable to how a user would interact with the UI. + +```mermaid +graph RL + plain[Plain JavaScript]; + Vue[Vue Components]; + feature-flags[Feature Flags]; + license-checks[License Checks]; + + plain---Vuex; + plain---GraphQL; + Vue---plain; + Vue---Vuex; + Vue---GraphQL; + browser---plain; + browser---Vue; + plain---backend; + Vuex---backend; + GraphQL---backend; + Vue---backend; + backend---database; + backend---feature-flags; + backend---license-checks; + + class plain tested; + class Vue tested; + class Vuex tested; + class GraphQL tested; + class browser tested; + linkStyle 0,1,2,3,4,5,6 stroke:#6666ff,stroke-width:2px,stroke-dasharray: 5, 5; + + classDef node color:#909090,fill:#f0f0f0,stroke-width:2px,stroke:#909090 + classDef label stroke-width:0; + classDef tested color:#000000,fill:#a0c0ff,stroke:#6666ff,stroke-width:2px,stroke-dasharray: 5, 5; + + subgraph " " + tested; + mocked; + class tested tested; + end +``` + +#### When to use integration tests + +<details> + <summary>page bundles (<code>index.js</code> files in <code>app/assets/javascripts/pages/</code>)</summary> + Testing the page bundles ensures the corresponding frontend components integrate well. +</details> + +<details> + <summary>Vue applications outside of page bundles</summary> + Testing Vue applications as a whole ensures the corresponding frontend components integrate well. +</details> + +#### What to mock in integration tests + +<details> + <summary>HAML views (use fixtures instead)</summary> + Rendering HAML views requires a Rails environment including a running database which we cannot rely on in frontend tests. +</details> + +<details> + <summary>all server requests</summary> + Similar to unit and component tests, when running component tests, the backend may not be reachable. + Therefore all outgoing requests need to be mocked. +</details> + +<details> + <summary>asynchronous background operations that are not perceivable on the page</summary> + Background operations that affect the page need to be tested on this level. + All other background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects. +</details> + +#### What *not* to mock in integration tests + +<details> + <summary>DOM</summary> + Testing on the real DOM ensures our components work in the environment they are meant for. + Part of this will be delegated to <a href="https://gitlab.com/gitlab-org/quality/team-tasks/issues/45">cross-browser testing</a>. +</details> + +<details> + <summary>properties or state of components</summary> + On this level, all tests can only perform actions a user would do. + For example to change the state of a component, a click event would be fired. +</details> + +<details> + <summary>Vuex stores</summary> + When testing the frontend code of a page as a whole, the interaction between Vue components and Vuex stores is covered as well. +</details> + +### Feature tests + +In contrast to [frontend integration tests](#frontend-integration-tests), feature tests make requests against the real backend instead of using fixtures. +This also implies that database queries are executed which makes this category significantly slower. + +See also the [RSpec testing guidelines](../testing_guide/best_practices.md#rspec). + +```mermaid +graph RL + plain[Plain JavaScript]; + Vue[Vue Components]; + feature-flags[Feature Flags]; + license-checks[License Checks]; + + plain---Vuex; + plain---GraphQL; + Vue---plain; + Vue---Vuex; + Vue---GraphQL; + browser---plain; + browser---Vue; + plain---backend; + Vuex---backend; + GraphQL---backend; + Vue---backend; + backend---database; + backend---feature-flags; + backend---license-checks; + + class backend tested; + class plain tested; + class Vue tested; + class Vuex tested; + class GraphQL tested; + class browser tested; + linkStyle 0,1,2,3,4,5,6,7,8,9,10 stroke:#6666ff,stroke-width:2px,stroke-dasharray: 5, 5; + + classDef node color:#909090,fill:#f0f0f0,stroke-width:2px,stroke:#909090 + classDef label stroke-width:0; + classDef tested color:#000000,fill:#a0c0ff,stroke:#6666ff,stroke-width:2px,stroke-dasharray: 5, 5; + + subgraph " " + tested; + mocked; + class tested tested; + end +``` + +#### When to use feature tests + +- Use cases that require a backend and cannot be tested using fixtures. +- Behavior that is not part of a page bundle but defined globally. + +#### Relevant notes + +A `:js` flag is added to the test to make sure the full environment is loaded. + +```ruby +scenario 'successfully', :js do + sign_in(create(:admin)) +end +``` + +The steps of each test are written using capybara methods ([documentation](https://www.rubydoc.info/gems/capybara)). + +Bear in mind <abbr title="XMLHttpRequest">XHR</abbr> calls might require you to use `wait_for_requests` in between steps, like so: + +```ruby +find('.form-control').native.send_keys(:enter) + +wait_for_requests + +expect(page).not_to have_selector('.card') +``` + +## Test helpers + +### Vuex Helper: `testAction` + +We have a helper available to make testing actions easier, as per [official documentation](https://vuex.vuejs.org/guide/testing.html): + +```javascript +testAction( + actions.actionName, // action + { }, // params to be passed to action + state, // state + [ + { type: types.MUTATION}, + { type: types.MUTATION_1, payload: {}}, + ], // mutations committed + [ + { type: 'actionName', payload: {}}, + { type: 'actionName1', payload: {}}, + ] // actions dispatched + done, +); +``` + +Check an example in [spec/javascripts/ide/stores/actions_spec.jsspec/javascripts/ide/stores/actions_spec.js](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/javascripts/ide/stores/actions_spec.js). + +### Vue Helper: `mountComponent` + +To make mounting a Vue component easier and more readable, we have a few helpers available in `spec/helpers/vue_mount_component_helper`: + +- `createComponentWithStore` +- `mountComponentWithStore` + +Examples of usage: + +```javascript +beforeEach(() => { + vm = createComponentWithStore(Component, store); + + vm.$store.state.currentBranchId = 'master'; + + vm.$mount(); +}); +``` + +```javascript +beforeEach(() => { + vm = mountComponentWithStore(Component, { + el: '#dummy-element', + store, + props: { badge }, + }); +}); +``` + +Don't forget to clean up: + +```javascript +afterEach(() => { + vm.$destroy(); +}); +``` + +## Testing with older browsers + +Some regressions only affect a specific browser version. We can install and test in particular browsers with either Firefox or Browserstack using the following steps: + +### Browserstack + +[Browserstack](https://www.browserstack.com/) allows you to test more than 1200 mobile devices and browsers. +You can use it directly through the [live app](https://www.browserstack.com/live) or you can install the [chrome extension](https://chrome.google.com/webstore/detail/browserstack/nkihdmlheodkdfojglpcjjmioefjahjb) for easy access. +You can find the credentials on 1Password, under `frontendteam@gitlab.com`. + +### Firefox + +#### macOS + +You can download any older version of Firefox from the releases FTP server, <https://ftp.mozilla.org/pub/firefox/releases/>: + +1. From the website, select a version, in this case `50.0.1`. +1. Go to the mac folder. +1. Select your preferred language, you will find the dmg package inside, download it. +1. Drag and drop the application to any other folder but the `Applications` folder. +1. Rename the application to something like `Firefox_Old`. +1. Move the application to the `Applications` folder. +1. Open up a terminal and run `/Applications/Firefox_Old.app/Contents/MacOS/firefox-bin -profilemanager` to create a new profile specific to that Firefox version. +1. Once the profile has been created, quit the app, and run it again like normal. You now have a working older Firefox version. + --- [Return to Testing documentation](index.md) diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md index 96e8c30a679..173471e3af8 100644 --- a/doc/development/testing_guide/index.md +++ b/doc/development/testing_guide/index.md @@ -13,7 +13,7 @@ importance. GitLab is built on top of [Ruby on Rails](https://rubyonrails.org/), and we're using [RSpec] for all the backend tests, with [Capybara] for end-to-end integration testing. -On the frontend side, we're using [Karma] and [Jasmine] for JavaScript unit and +On the frontend side, we're using [Jest](https://jestjs.io/) and [Karma](http://karma-runner.github.io/)/[Jasmine](https://jasmine.github.io/) for JavaScript unit and integration testing. Following are two great articles that everyone should read to understand what @@ -64,6 +64,4 @@ Everything you should know about how to run end-to-end tests using [RSpec]: https://github.com/rspec/rspec-rails#feature-specs [Capybara]: https://github.com/teamcapybara/capybara -[Karma]: http://karma-runner.github.io/ -[Jasmine]: https://jasmine.github.io/ [gitlab-qa]: https://gitlab.com/gitlab-org/gitlab-qa diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index 7843fc4c874..28a60660995 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -132,7 +132,7 @@ to prevent other pods from being scheduled on this node pool. This is to ensure Tiller isn't affected by "noisy" neighbors that could put their node under pressure. -## How to: +## How to ### Log into my Review App @@ -255,8 +255,8 @@ that a machine will hit the "too many mount points" problem in the future. thousands of unused Docker images.** > We have to start somewhere and improve later. Also, we're using the - CNG-mirror project to store these Docker images so that we can just wipe out - the registry at some point, and use a new fresh, empty one. + > CNG-mirror project to store these Docker images so that we can just wipe out + > the registry at some point, and use a new fresh, empty one. **How do we secure this from abuse? Apps are open to the world so we need to find a way to limit it to only us.** diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index e1ce4d3b7d1..1aee306f492 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -63,10 +63,9 @@ They're useful to test permissions, redirections, what view is rendered etc. | Code path | Tests path | Testing engine | Notes | | --------- | ---------- | -------------- | ----- | -| `app/controllers/` | `spec/controllers/` | RSpec | | +| `app/controllers/` | `spec/controllers/` | RSpec | For N+1 tests, use [request specs](../query_recorder.md#use-request-specs-instead-of-controller-specs) | | `app/mailers/` | `spec/mailers/` | RSpec | | | `lib/api/` | `spec/requests/api/` | RSpec | | -| `lib/ci/api/` | `spec/requests/ci/api/` | RSpec | | | `app/assets/javascripts/` | `spec/javascripts/`, `spec/frontend/` | Karma & Jest | More details in the [Frontend Testing guide](frontend_testing.md) section. | ### About controller tests @@ -127,7 +126,7 @@ possible). | ---------- | -------------- | ----- | | `spec/features/` | [Capybara] + [RSpec] | If your test has the `:js` metadata, the browser driver will be [Poltergeist], otherwise it's using [RackTest]. | -### Consider **not** writing a system test! +### Consider **not** writing a system test If we're confident that the low-level components work well (and we should be if we have enough Unit & Integration tests), we shouldn't need to duplicate their diff --git a/doc/development/uploads.md b/doc/development/uploads.md new file mode 100644 index 00000000000..681ce9d9fe8 --- /dev/null +++ b/doc/development/uploads.md @@ -0,0 +1,270 @@ +# Uploads development documentation + +[GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) has special rules for handling uploads. +To prevent occupying a ruby process on I/O operations, we process the upload in workhorse, where is cheaper. +This process can also directly upload to object storage. + +## The problem description + +The following graph explains machine boundaries in a scalable GitLab installation. Without any workhorse optimization in place, we can expect incoming requests to follow the numbers on the arrows. + +```mermaid +graph TB + subgraph "load balancers" + LB(HA Proxy) + end + + subgraph "Shared storage" + nfs(NFS) + end + + subgraph "redis cluster" + r(persisted redis) + end + LB-- 1 -->workhorse + + subgraph "web or API fleet" + workhorse-- 2 -->rails + end + rails-- "3 (write files)" -->nfs + rails-- "4 (schedule a job)" -->r + + subgraph sidekiq + s(sidekiq) + end + s-- "5 (fetch a job)" -->r + s-- "6 (read files)" -->nfs +``` + +We have three challenges here: performance, availability, and scalability. + +### Performance + +Rails process are expensive in terms of both CPU and memory. Ruby [global interpreter lock](https://en.wikipedia.org/wiki/Global_interpreter_lock) adds to cost too because the ruby process will spend time on I/O operations on step 3 causing incoming requests to pile up. + +In order to improve this, [workhorse disk acceleration](#workhorse-disk-acceleration) was implemented. With this, Rails no longer deals with writing uploaded files to disk. + +```mermaid +graph TB + subgraph "load balancers" + LB(HA Proxy) + end + + subgraph "Shared storage" + nfs(NFS) + end + + subgraph "redis cluster" + r(persisted redis) + end + LB-- 1 -->workhorse + + subgraph "web or API fleet" + workhorse-- "3 (without files)" -->rails + end + workhorse -- "2 (write files)" -->nfs + rails-- "4 (schedule a job)" -->r + + subgraph sidekiq + s(sidekiq) + end + s-- "5 (fetch a job)" -->r + s-- "6 (read files)" -->nfs +``` + +### Availability + +There's also an availability problem in this setup, NFS is a [single point of failure](https://en.wikipedia.org/wiki/Single_point_of_failure). + +To address this problem an HA object storage can be used and it's supported by [workhorse object storage acceleration](#workhorse-object-storage-acceleration) + +### Scalability + +Scaling NFS is outside of our support scope, and NFS is not a part of cloud native installations. + +All features that require sidekiq and do not use object storage acceleration won't work without NFS. In Kubernetes, machine boundaries translate to PODs, and in this case the uploaded file will be written into the POD private disk. Since sidekiq POD cannot reach into other pods, the operation will fail to read it. + +## How to select the proper level of acceleration? + +Selecting the proper acceleration is a tradeoff between speed of development and operational costs. + +We can identify three major use-cases for an upload: + +1. **storage:** if we are uploading for storing a file (i.e. artifacts, packages, discussion attachments). In this case [object storage acceleration](#workhorse-object-storage-acceleration) is the proper level as it's the less resource-intensive operation. Additional information can be found on [File Storage in GitLab](file_storage.md). +1. **in-controller/synchronous processing:** if we allow processing **small files** synchronously, using [disk acceleration](#workhorse-disk-acceleration) may speed up development. +1. **sidekiq/asynchronous processing:** Async processing must implement [object storage acceleration](#workhorse-object-storage-acceleration), the reason being that it's the only way to support Cloud Native deployments without a shared NFS. + +For more details about currently broken feature see [epic &1802](https://gitlab.com/groups/gitlab-org/-/epics/1802). + +### Handling repository uploads + +Some features involves git repository uploads without using a regular git client. +Some examples are uploading a repository file from the web interface and [design management](../user/project/issues/design_management.md). + +Those uploads requires the rails controller to act as a git client in lieu of the user. +Those operation falls into _in-controller/synchronous processing_ category, but we have no warranties on the file size. + +In case of a LFS upload, the file pointer is committed synchronously, but file upload to object storage is performed asynchronously with sidekiq. + +## Upload encodings + +By upload encoding we mean how the file is included within the incoming request. + +We have three kinds of file encoding in our uploads: + +1. <i class="fa fa-check-circle"></i> **multipart**: `multipart/form-data` is the most common, a file is encoded as a part of a multipart encoded request. +1. <i class="fa fa-check-circle"></i> **body**: some APIs uploads files as the whole request body. +1. <i class="fa fa-times-circle"></i> **JSON**: some JSON API uploads files as base64 encoded strings. This requires [gitlab-workhorse#226](https://gitlab.com/gitlab-org/gitlab-workhorse/issues/226) to be implemented. + +## Uploading technologies + +By uploading technologies we mean how all the involved services interact with each other. + +GitLab supports 3 kinds of uploading technologies, here follows a brief description with a sequence diagram for each one. Diagrams are not meant to be exhaustive. + +### Regular rails upload + +This is the default kind of upload, and it's most expensive in terms of resources. + +In this case, workhorse is unaware of files being uploaded and acts as a regular proxy. + +When a multipart request reaches the rails application, `Rack::Multipart` leaves behind tempfiles in `/tmp` and uses valuable Ruby process time to copy files around. + +```mermaid +sequenceDiagram + participant c as Client + participant w as Workhorse + participant r as Rails + + activate c + c ->>+w: POST /some/url/upload + w->>+r: POST /some/url/upload + + r->>r: save the incoming file on /tmp + r->>r: read the file for processing + + r-->>-c: request result + deactivate c + deactivate w +``` + +### Workhorse disk acceleration + +This kind of upload avoids wasting resources caused by handling upload writes to `/tmp` in rails. + +This optimization is not active by default on REST API requests. + +When enabled, Workhorse looks for files in multipart MIME requests, uploading +any it finds to a temporary file on shared storage. The MIME data in the request +is replaced with the path to the corresponding file before it is forwarded to +Rails. + +To prevent abuse of this feature, Workhorse signs the modified request with a +special header, stating which entries it modified. Rails will ignore any +unsigned path entries. + +```mermaid +sequenceDiagram + participant c as Client + participant w as Workhorse + participant r as Rails + participant s as NFS + + activate c + c ->>+w: POST /some/url/upload + + w->>+s: save the incoming file on a temporary location + s-->>-w: + + w->>+r: POST /some/url/upload + Note over w,r: file was replaced with its location<br>and other metadata + + opt requires async processing + r->>+redis: schedule a job + redis-->>-r: + end + + r-->>-c: request result + deactivate c + w->>-w: cleanup + + opt requires async processing + activate sidekiq + sidekiq->>+redis: fetch a job + redis-->>-sidekiq: job + + sidekiq->>+s: read file + s-->>-sidekiq: file + + sidekiq->>sidekiq: process file + + deactivate sidekiq + end +``` + +### Workhorse object storage acceleration + +This is the more advanced acceleration technique we have in place. + +Workhorse asks rails for temporary pre-signed object storage URLs and directly uploads to object storage. + +In this setup an extra rails route needs to be implemented in order to handle authorization, +you can see an example of this in [`Projects::LfsStorageController`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/controllers/projects/lfs_storage_controller.rb) +and [its routes](https://gitlab.com/gitlab-org/gitlab-ce/blob/v12.2.0/config/routes/git_http.rb#L31-32). + +**note:** this will fallback to _Workhorse disk acceleration_ when object storage is not enabled in the gitlab instance. The answer to the `/authorize` call will only contain a file system path. + +```mermaid +sequenceDiagram + participant c as Client + participant w as Workhorse + participant r as Rails + participant os as Object Storage + + activate c + c ->>+w: POST /some/url/upload + + w ->>+r: POST /some/url/upload/authorize + Note over w,r: this request has an empty body + r-->>-w: presigned OS URL + + w->>+os: PUT file + Note over w,os: file is stored on a temporary location. Rails select the destination + os-->>-w: + + w->>+r: POST /some/url/upload + Note over w,r: file was replaced with its location<br>and other metadata + + r->>+os: move object to final destination + os-->>-r: + + opt requires async processing + r->>+redis: schedule a job + redis-->>-r: + end + + r-->>-c: request result + deactivate c + w->>-w: cleanup + + opt requires async processing + activate sidekiq + sidekiq->>+redis: fetch a job + redis-->>-sidekiq: job + + sidekiq->>+os: get object + os-->>-sidekiq: file + + sidekiq->>sidekiq: process file + + deactivate sidekiq + end +``` + +## What does the `direct_upload` setting mean? + +[Object storage setting](../administration/uploads.md#object-storage-settings) allows instance administators to enable `direct_upload`, this in an option that only affects the behavior of [workhorse object storage acceleration](#workhorse-object-storage-acceleration). + +This option affect the response to the `/authorize` call. When not enabled, the API response will not contain presigned URLs and workhorse will write the file the shared disk, on the path is provided by rails, acting like object storage was disabled. + +Once the request reachs rails, it will schedule an object storage upload as a sidekiq job. diff --git a/doc/development/ux_guide/animation.md b/doc/development/ux_guide/animation.md index a998ab74a96..0f7a24042bb 100644 --- a/doc/development/ux_guide/animation.md +++ b/doc/development/ux_guide/animation.md @@ -1,5 +1,5 @@ --- -redirect_to: 'https://design.gitlab.com/product-foundations/motion' +redirect_to: 'https://design.gitlab.com/product-foundations/motion/' --- -The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/product-foundations/motion). +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/product-foundations/motion/). diff --git a/doc/development/ux_guide/illustrations.md b/doc/development/ux_guide/illustrations.md index 3592d25c95d..815f870f8c5 100644 --- a/doc/development/ux_guide/illustrations.md +++ b/doc/development/ux_guide/illustrations.md @@ -1,5 +1,5 @@ --- -redirect_to: 'https://design.gitlab.com/product-foundations/illustration' +redirect_to: 'https://design.gitlab.com/product-foundations/illustration/' --- -The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/product-foundations/illustration). +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/product-foundations/illustration/). diff --git a/doc/development/verifying_database_capabilities.md b/doc/development/verifying_database_capabilities.md index ccec6f7d719..6b4995aebe2 100644 --- a/doc/development/verifying_database_capabilities.md +++ b/doc/development/verifying_database_capabilities.md @@ -1,15 +1,15 @@ # Verifying Database Capabilities -Sometimes certain bits of code may only work on a certain database and/or +Sometimes certain bits of code may only work on a certain database version. While we try to avoid such code as much as possible sometimes it is necessary to add database (version) specific behaviour. To facilitate this we have the following methods that you can use: -- `Gitlab::Database.postgresql?`: returns `true` if PostgreSQL is being used -- `Gitlab::Database.mysql?`: returns `true` if MySQL is being used +- `Gitlab::Database.postgresql?`: returns `true` if PostgreSQL is being used. + You can normally just assume this is the case. - `Gitlab::Database.version`: returns the PostgreSQL version number as a string - in the format `X.Y.Z`. This method does not work for MySQL + in the format `X.Y.Z`. This allows you to write code such as: diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md index f0da1cc2ddc..f4cee410066 100644 --- a/doc/development/what_requires_downtime.md +++ b/doc/development/what_requires_downtime.md @@ -7,9 +7,8 @@ downtime. ## Adding Columns -On PostgreSQL you can safely add a new column to an existing table as long as it -does **not** have a default value. For example, this query would not require -downtime: +You can safely add a new column to an existing table as long as it does **not** +have a default value. For example, this query would not require downtime: ```sql ALTER TABLE projects ADD COLUMN random_value int; @@ -27,11 +26,6 @@ This requires updating every single row in the `projects` table so that indexes in a table. This in turn acquires enough locks on the table for it to effectively block any other queries. -As of MySQL 5.6 adding a column to a table is still quite an expensive -operation, even when using `ALGORITHM=INPLACE` and `LOCK=NONE`. This means -downtime _may_ be required when modifying large tables as otherwise the -operation could potentially take hours to complete. - Adding a column with a default value _can_ be done without requiring downtime when using the migration helper method `Gitlab::Database::MigrationHelpers#add_column_with_default`. This method works @@ -51,15 +45,12 @@ rule. The first step is to ignore the column in the application code. This is necessary because Rails caches the columns and re-uses this cache in various -places. This can be done by including the `IgnorableColumn` module into the -model, followed by defining the columns to ignore. For example, to ignore +places. This can be done by defining the columns to ignore. For example, to ignore `updated_at` in the User model you'd use the following: ```ruby -class User < ActiveRecord::Base - include IgnorableColumn - - ignore_column :updated_at +class User < ApplicationRecord + self.ignored_columns += %i[updated_at] end ``` @@ -70,8 +61,7 @@ column. Both these changes should be submitted in the same merge request. Once the changes from step 1 have been released & deployed you can set up a separate merge request that removes the ignore rule. This merge request can -simply remove the `ignore_column` line, and the `include IgnorableColumn` line -if no other `ignore_column` calls remain. +simply remove the `self.ignored_columns` line. ## Renaming Columns @@ -311,8 +301,7 @@ migrations](background_migrations.md#cleaning-up). ## Adding Indexes Adding indexes is an expensive process that blocks INSERT and UPDATE queries for -the duration. When using PostgreSQL one can work around this by using the -`CONCURRENTLY` option: +the duration. You can work around this by using the `CONCURRENTLY` option: ```sql CREATE INDEX CONCURRENTLY index_name ON projects (column_name); @@ -336,17 +325,9 @@ end Note that `add_concurrent_index` can not be reversed automatically, thus you need to manually define `up` and `down`. -When running this on PostgreSQL the `CONCURRENTLY` option mentioned above is -used. On MySQL this method produces a regular `CREATE INDEX` query. - -MySQL doesn't really have a workaround for this. Supposedly it _can_ create -indexes without the need for downtime but only for variable width columns. The -details on this are a bit sketchy. Since it's better to be safe than sorry one -should assume that adding indexes requires downtime on MySQL. - ## Dropping Indexes -Dropping an index does not require downtime on both PostgreSQL and MySQL. +Dropping an index does not require downtime. ## Adding Tables @@ -370,7 +351,7 @@ transaction this means this approach would require downtime. GitLab allows you to work around this by using `Gitlab::Database::MigrationHelpers#add_concurrent_foreign_key`. This method -ensures that when PostgreSQL is used no downtime is needed. +ensures that no downtime is needed. ## Removing Foreign Keys diff --git a/doc/gitlab-basics/add-file.md b/doc/gitlab-basics/add-file.md index 41cc8bc4aeb..d547584bf80 100644 --- a/doc/gitlab-basics/add-file.md +++ b/doc/gitlab-basics/add-file.md @@ -70,7 +70,7 @@ git commit -m "DESCRIBE COMMIT IN A FEW WORDS" ``` Now you can push (send) your changes (in the branch `<branch-name>`) to GitLab -(the git remote named 'origin'): +(the Git remote named 'origin'): ```sh git push origin <branch-name> diff --git a/doc/gitlab-basics/add-merge-request.md b/doc/gitlab-basics/add-merge-request.md index 1a6a26152fa..28f32fefb95 100644 --- a/doc/gitlab-basics/add-merge-request.md +++ b/doc/gitlab-basics/add-merge-request.md @@ -12,8 +12,6 @@ check the [merge requests documentation](../user/project/merge_requests/index.md you can watch our [GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE) for a quick overview of working with merge requests. ---- - 1. Before you start, you should have already [created a branch](create-branch.md) and [pushed your changes](start-using-git.md#send-changes-to-gitlabcom) to GitLab. 1. Go to the project where you'd like to merge your changes and click on the diff --git a/doc/gitlab-basics/command-line-commands.md b/doc/gitlab-basics/command-line-commands.md index ed70d3ce598..74539b33642 100644 --- a/doc/gitlab-basics/command-line-commands.md +++ b/doc/gitlab-basics/command-line-commands.md @@ -10,7 +10,7 @@ learn, in order to make full use of the command line. ## Start working on your project -To work on a git project locally (from your own computer), with the command line, +To work on a Git project locally (from your own computer), with the command line, first you will need to [clone (copy) it](start-using-git.md#clone-a-repository) to your computer. diff --git a/doc/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md index 8bbaf5d1927..18565daa900 100644 --- a/doc/gitlab-basics/create-project.md +++ b/doc/gitlab-basics/create-project.md @@ -2,7 +2,7 @@ type: howto --- -# Creating projects +# Create a project Most work in GitLab is done within a [Project](../user/project/index.md). Files and code are saved in projects, and most features are used within the scope of projects. diff --git a/doc/gitlab-basics/create-your-ssh-keys.md b/doc/gitlab-basics/create-your-ssh-keys.md index 338b96374aa..98f2679c9d6 100644 --- a/doc/gitlab-basics/create-your-ssh-keys.md +++ b/doc/gitlab-basics/create-your-ssh-keys.md @@ -5,7 +5,7 @@ type: howto # Create and add your SSH public key It is best practice to use [Git over SSH instead of Git over HTTP](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols). -In order to use SSH, you will need to +In order to use SSH, you will need to: 1. [Create an SSH key pair](#creating-your-ssh-key-pair) on your local computer. 1. [Add the key to GitLab](#adding-your-ssh-public-key-to-gitlab). diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md index 3e3f96fb31f..a289b90b81b 100644 --- a/doc/gitlab-basics/start-using-git.md +++ b/doc/gitlab-basics/start-using-git.md @@ -63,8 +63,8 @@ git config --global user.email You'll need to do this only once, since you are using the `--global` option. It tells Git to always use this information for anything you do on that system. If you want -to override this with a different username or email address for specific projects, -you can run the command without the `--global` option when you’re in that project. +to override this with a different username or email address for specific projects or repositories, +you can run the command without the `--global` option when you’re in that project, and that will default to `--local`. You can read more on how Git manages configurations in the [Git Config](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration) documentation. ## Check your information @@ -102,8 +102,7 @@ files to your local computer, automatically preserving the Git connection with t remote repository. You can either clone it via HTTPS or [SSH](../ssh/README.md). If you chose to clone -it via HTTPS, you'll have to enter your credentials every time you pull and push. -With SSH, you enter your credentials only once. +it via HTTPS, you'll have to enter your credentials every time you pull and push. You can read more about credential storage in the [Git Credentials documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). With SSH, you enter your credentials only once. You can find both paths (HTTPS and SSH) by navigating to your project's landing page and clicking **Clone**. GitLab will prompt you with both paths, from which you can copy @@ -152,13 +151,15 @@ to get the main branch code, or the branch name of the branch you are currently in. ```bash -git pull REMOTE <name-of-branch> +git pull <REMOTE> <name-of-branch> ``` -When you first clone a repository, REMOTE is typically `origin`. This is where the +When you clone a repository, `REMOTE` is typically `origin`. This is where the repository was cloned from, and it indicates the SSH or HTTPS URL of the repository on the remote server. `<name-of-branch>` is usually `master`, but it may be any existing -branch. +branch. You can create additional named remotes and branches as necessary. + +You can learn more on how Git manages remote repositories in the [Git Remote documentation](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes). ### View your remote repositories @@ -168,6 +169,8 @@ To view your remote repositories, type: git remote -v ``` +The `-v` flag stands for verbose. + ### Add a remote repository To add a link to a remote repository: @@ -186,7 +189,7 @@ following (spaces won't be recognized in the branch name, so you will need to us hyphen or underscore): ```bash -git checkout -b <name-of-branch>> +git checkout -b <name-of-branch> ``` ### Work on an existing branch @@ -238,7 +241,7 @@ git commit -m "COMMENT TO DESCRIBE THE INTENTION OF THE COMMIT" ``` NOTE: **Note:** -The `.` character typically means _all_ in Git. +The `.` character means _all file changes in the current directory and all subdirectories_. ### Send changes to GitLab.com diff --git a/doc/install/README.md b/doc/install/README.md index af98791c8e9..fd91527ed4c 100644 --- a/doc/install/README.md +++ b/doc/install/README.md @@ -13,7 +13,7 @@ and cost of hosting. There are many ways you can install GitLab depending on your platform: -1. **Omnibus Gitlab**: The official deb/rpm packages that contain a bundle of GitLab +1. **Omnibus GitLab**: The official deb/rpm packages that contain a bundle of GitLab and the various components it depends on like PostgreSQL, Redis, Sidekiq, etc. 1. **GitLab Helm chart**: The cloud native Helm chart for installing GitLab and all its components on Kubernetes. diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index 543a222bd25..dfb1dbcf1ed 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -179,7 +179,7 @@ to make sure your VM is configured to use a _static_ public IP address (i.e. not or you will have to reconfigure the DNS `A` record each time Azure reassigns your VM a new public IP address. Read [IP address types and allocation methods in Azure][Azure-IP-Address-Types] to learn more. -## Let's open some ports! +## Let's open some ports At this stage you should have a running and fully operational VM. However, none of the services on your VM (e.g. GitLab) will be publicly accessible via the internet until you have opened up the @@ -333,6 +333,7 @@ If you're running Windows, you'll need to connect using [PuTTY] or an equivalent If you're running Linux or macOS, then you already have an SSH client installed. > **Note:** +> > - Remember that you will need to login with the username and password you specified > [when you created](#basics) your Azure VM > - If you need to reset your VM password, read @@ -407,7 +408,7 @@ on any cloud service you choose. ## Where to next? -Check out our other [Technical Articles](../../articles/index.md) or browse the [GitLab Documentation][GitLab-Docs](../../README.md) to learn more about GitLab. +Check out our other [Technical Articles](../../articles/index.md) or browse the [GitLab Documentation](../../README.md) to learn more about GitLab. ### Useful links diff --git a/doc/install/installation.md b/doc/install/installation.md index 295d9804497..6039ddc45ae 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -57,18 +57,18 @@ of this page: ``` - `/home/git/.ssh` - Contains OpenSSH settings. Specifically the `authorized_keys` - file managed by gitlab-shell. + file managed by GitLab Shell. - `/home/git/gitlab` - GitLab core software. - `/home/git/gitlab-shell` - Core add-on component of GitLab. Maintains SSH cloning and other functionality. - `/home/git/repositories` - Bare repositories for all projects organized by - namespace. This is where the git repositories which are pushed/pulled are + namespace. This is where the Git repositories which are pushed/pulled are maintained for all projects. **This area contains critical data for projects. [Keep a backup](../raketasks/backup_restore.md).** NOTE: **Note:** The default locations for repositories can be configured in `config/gitlab.yml` -of GitLab and `config.yml` of gitlab-shell. +of GitLab and `config.yml` of GitLab Shell. For a more in-depth overview, see the [GitLab architecture doc](../development/architecture.md). @@ -569,7 +569,7 @@ GitLab Shell application startup time can be greatly reduced by disabling RubyGe - Compile Ruby with `configure --disable-rubygems` to disable RubyGems by default. Not recommended for system-wide Ruby. - Omnibus GitLab [replaces the *shebang* line of the `gitlab-shell/bin/*` scripts](https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/1707). -### Install gitlab-workhorse +### Install GitLab Workhorse GitLab-Workhorse uses [GNU Make](https://www.gnu.org/software/make/). The following command-line will install GitLab-Workhorse in `/home/git/gitlab-workhorse` @@ -611,7 +611,7 @@ You can specify a different Git repository by providing it as an extra parameter sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,/home/git/repositories,https://example.com/gitaly.git]" RAILS_ENV=production ``` -Next, make sure gitaly configured: +Next, make sure that Gitaly is configured: ```sh # Restrict Gitaly socket access @@ -789,7 +789,7 @@ nginx: configuration file /etc/nginx/nginx.conf test failed` sudo service nginx restart ``` -## Done! +## Post-install ### Double-check Application Status @@ -833,7 +833,7 @@ To use GitLab with HTTPS: 1. In `gitlab.yml`: 1. Set the `port` option in section 1 to `443`. 1. Set the `https` option in section 1 to `true`. -1. In the `config.yml` of gitlab-shell: +1. In the `config.yml` of GitLab Shell: 1. Set `gitlab_url` option to the HTTPS endpoint of GitLab (e.g. `https://git.example.com`). 1. Set the certificates using either the `ca_file` or `ca_path` option. 1. Use the `gitlab-ssl` Nginx example config instead of the `gitlab` config. @@ -852,7 +852,7 @@ Using a self-signed certificate is discouraged but if you must use it, follow th sudo chmod o-r gitlab.key ``` -1. In the `config.yml` of gitlab-shell set `self_signed_cert` to `true`. +1. In the `config.yml` of GitLab Shell set `self_signed_cert` to `true`. ### Enable Reply by email @@ -950,8 +950,8 @@ To use GitLab with Puma: If you see this message when attempting to clone a repository hosted by GitLab, this is likely due to an outdated Nginx or Apache configuration, or a missing or -misconfigured gitlab-workhorse instance. Double-check that you've -[installed Go](#3-go), [installed gitlab-workhorse](#install-gitlab-workhorse), +misconfigured GitLab Workhorse instance. Double-check that you've +[installed Go](#3-go), [installed GitLab Workhorse](#install-gitlab-workhorse), and correctly [configured Nginx](#site-configuration). ### google-protobuf "LoadError: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.14' not found" diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md index bc6364f57f7..595304e27e2 100644 --- a/doc/install/relative_url.md +++ b/doc/install/relative_url.md @@ -110,7 +110,7 @@ Make sure to follow all steps below: **Note:** If you are using a custom init script, make sure to edit the above - gitlab-workhorse setting as needed. + GitLab Workhorse setting as needed. 1. [Restart GitLab][] for the changes to take effect. diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index 5061b863e79..2dd6fa3d5a2 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -30,7 +30,7 @@ application. 1. On your GitLab server, open the configuration file. - For omnibus package: + For Omnibus package: ```sh sudo editor /etc/gitlab/gitlab.rb @@ -48,7 +48,7 @@ application. 1. Add the provider configuration: - For omnibus package: + For Omnibus package: ```ruby gitlab_rails['omniauth_providers'] = [ diff --git a/doc/integration/azure.md b/doc/integration/azure.md index a9468f201ef..c30d79e3dab 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -32,7 +32,7 @@ To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your ap 1. On your GitLab server, open the configuration file. - For omnibus package: + For Omnibus package: ```sh sudo editor /etc/gitlab/gitlab.rb @@ -50,7 +50,7 @@ To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your ap 1. Add the provider configuration: - For omnibus package: + For Omnibus package: ```ruby gitlab_rails['omniauth_providers'] = [ diff --git a/doc/integration/cas.md b/doc/integration/cas.md index f99337376a8..83b64773c9f 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -4,7 +4,7 @@ To enable the CAS OmniAuth provider you must register your application with your 1. On your GitLab server, open the configuration file. - For omnibus package: + For Omnibus package: ```sh sudo editor /etc/gitlab/gitlab.rb @@ -22,7 +22,7 @@ To enable the CAS OmniAuth provider you must register your application with your 1. Add the provider configuration: - For omnibus package: + For Omnibus package: ```ruby gitlab_rails['omniauth_providers'] = [ diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index eee05eaef02..dc4aa9a5373 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -123,13 +123,15 @@ production instances, they recommend considerably more resources. Storage requirements also vary based on the installation side, but as a rule of thumb, you should allocate the total size of your production database, **plus** -two-thirds of the total size of your git repositories. Efforts to reduce this -total are being tracked in this epic: [gitlab-org&153](https://gitlab.com/groups/gitlab-org/-/epics/153). +two-thirds of the total size of your Git repositories. Efforts to reduce this +total are being tracked in [epic &153](https://gitlab.com/groups/gitlab-org/-/epics/153). ## Enabling Elasticsearch -In order to enable Elasticsearch, you need to have admin access. Go to -**Admin > Settings > Integrations** and find the "Elasticsearch" section. +In order to enable Elasticsearch, you need to have admin access. Navigate to +**Admin Area** (wrench icon), then **Settings > Integrations** and expand the **Elasticsearch** section. + +Click **Save changes** for the changes to take effect. The following Elasticsearch settings are available: @@ -171,197 +173,248 @@ from the Elasticsearch index as expected. To disable the Elasticsearch integration: -1. Navigate to the **Admin > Settings > Integrations** -1. Find the 'Elasticsearch' section and uncheck 'Search with Elasticsearch enabled' - and 'Elasticsearch indexing' -1. Click **Save** for the changes to take effect -1. (Optional) Delete the existing index by running the command `sudo gitlab-rake gitlab:elastic:delete_index` +1. Navigate to the **Admin Area** (wrench icon), then **Settings > Integrations**. +1. Expand the **Elasticsearch** section and uncheck **Elasticsearch indexing** + and **Search with Elasticsearch enabled**. +1. Click **Save changes** for the changes to take effect. +1. (Optional) Delete the existing index by running one of these commands: + + ```sh + # Omnibus installations + sudo gitlab-rake gitlab:elastic:delete_index + + # Installations from source + bundle exec rake gitlab:elastic:delete_index RAILS_ENV=production + ``` ## Adding GitLab's data to the Elasticsearch index -### Indexing small instances (database size less than 500 MiB, size of repos less than 5 GiB) +While Elasticsearch indexing is enabled, new changes in your GitLab instance will be automatically indexed as they happen. +To backfill existing data, you can use one of the methods below to index it in background jobs. -Configure Elasticsearch's host and port in **Admin > Settings**. Then index the data using one of the following commands: +### Indexing through the administration UI -```sh -# Omnibus installations -sudo gitlab-rake gitlab:elastic:index +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/15390) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. -# Installations from source -bundle exec rake gitlab:elastic:index RAILS_ENV=production -``` +To index via the admin area: + +1. Navigate to the **Admin Area** (wrench icon), then **Settings > Integrations** and expand the **Elasticsearch** section. +1. [Enable **Elasticsearch indexing** and configure your host and port](#enabling-elasticsearch). +1. Create empty indexes using one of the following commands: + + ```sh + # Omnibus installations + sudo gitlab-rake gitlab:elastic:create_empty_index + + # Installations from source + bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production + ``` + +1. Click **Index all projects**. +1. Click **Check progress** in the confirmation message to see the status of the background jobs. +1. Personal snippets need to be indexed manually by running one of these commands: + + ```sh + # Omnibus installations + sudo gitlab-rake gitlab:elastic:index_snippets + + # Installations from source + bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production + ``` + +1. After the indexing has completed, enable [**Search with Elasticsearch**](#enabling-elasticsearch). + +### Indexing through Rake tasks + +#### Indexing small instances + +CAUTION: **Warning**: +This will delete your existing indexes. + +If the database size is less than 500 MiB, and the size of all hosted repos is less than 5 GiB: + +1. [Enable **Elasticsearch indexing** and configure your host and port](#enabling-elasticsearch). +1. Index your data using one of the following commands: + + ```sh + # Omnibus installations + sudo gitlab-rake gitlab:elastic:index + + # Installations from source + bundle exec rake gitlab:elastic:index RAILS_ENV=production + ``` -After it completes the indexing process, [enable Elasticsearch searching](elasticsearch.md#enabling-elasticsearch). +1. After the indexing has completed, enable [**Search with Elasticsearch**](#enabling-elasticsearch). -### Indexing large instances +#### Indexing large instances -WARNING: **Warning**: -Performing asynchronous indexing, as this will describe, will generate a lot of sidekiq jobs. +CAUTION: **Warning**: +Performing asynchronous indexing will generate a lot of Sidekiq jobs. Make sure to prepare for this task by either [Horizontally Scaling](../administration/high_availability/README.md#basic-scaling) -or creating [extra sidekiq processes](../administration/operations/extra_sidekiq_processes.md) +or creating [extra Sidekiq processes](../administration/operations/extra_sidekiq_processes.md) -Configure Elasticsearch's host and port in **Admin > Settings > Integrations**. Then create empty indexes using one of the following commands: +1. [Enable **Elasticsearch indexing** and configure your host and port](#enabling-elasticsearch). +1. Create empty indexes using one of the following commands: -```sh -# Omnibus installations -sudo gitlab-rake gitlab:elastic:create_empty_index + ```sh + # Omnibus installations + sudo gitlab-rake gitlab:elastic:create_empty_index -# Installations from source -bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production -``` + # Installations from source + bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production + ``` -Indexing large Git repositories can take a while. To speed up the process, you -can temporarily disable auto-refreshing and replicating. In our experience, you can expect a 20% -decrease in indexing time. We'll enable them when indexing is done. This step is optional! +1. Indexing large Git repositories can take a while. To speed up the process, you + can temporarily disable auto-refreshing and replicating. In our experience, you can expect a 20% + decrease in indexing time. We'll enable them when indexing is done. This step is optional! -```bash -curl --request PUT localhost:9200/gitlab-production/_settings --data '{ - "index" : { - "refresh_interval" : "-1", - "number_of_replicas" : 0 - } }' -``` + ```bash + curl --request PUT localhost:9200/gitlab-production/_settings --data '{ + "index" : { + "refresh_interval" : "-1", + "number_of_replicas" : 0 + } }' + ``` -Then enable Elasticsearch indexing and run project indexing tasks: +1. Index projects and their associated data: -```sh -# Omnibus installations -sudo gitlab-rake gitlab:elastic:index_projects + ```sh + # Omnibus installations + sudo gitlab-rake gitlab:elastic:index_projects -# Installations from source -bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production -``` + # Installations from source + bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production + ``` -This enqueues a Sidekiq job for each project that needs to be indexed. -You can view the jobs in the admin panel (they are placed in the `elastic_indexer` -queue), or you can query indexing status using a rake task: + This enqueues a Sidekiq job for each project that needs to be indexed. + You can view the jobs in **Admin Area > Monitoring > Background Jobs > Queues Tab** + and click `elastic_indexer`, or you can query indexing status using a rake task: -```sh -# Omnibus installations -sudo gitlab-rake gitlab:elastic:index_projects_status + ```sh + # Omnibus installations + sudo gitlab-rake gitlab:elastic:index_projects_status -# Installations from source -bundle exec rake gitlab:elastic:index_projects_status RAILS_ENV=production + # Installations from source + bundle exec rake gitlab:elastic:index_projects_status RAILS_ENV=production -Indexing is 65.55% complete (6555/10000 projects) -``` + Indexing is 65.55% complete (6555/10000 projects) + ``` -If you want to limit the index to a range of projects you can provide the -`ID_FROM` and `ID_TO` parameters: + If you want to limit the index to a range of projects you can provide the + `ID_FROM` and `ID_TO` parameters: -```sh -# Omnibus installations -sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 + ```sh + # Omnibus installations + sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 -# Installations from source -bundle exec rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 RAILS_ENV=production -``` + # Installations from source + bundle exec rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 RAILS_ENV=production + ``` -Where `ID_FROM` and `ID_TO` are project IDs. Both parameters are optional. -The above examples will index all projects starting with ID `1001` up to (and including) ID `2000`. + Where `ID_FROM` and `ID_TO` are project IDs. Both parameters are optional. + The above example will index all projects from ID `1001` up to (and including) ID `2000`. -TIP: **Troubleshooting:** -Sometimes the project indexing jobs queued by `gitlab:elastic:index_projects` -can get interrupted. This may happen for many reasons, but it's always safe -to run the indexing task again - it will skip those repositories that have -already been indexed. + TIP: **Troubleshooting:** + Sometimes the project indexing jobs queued by `gitlab:elastic:index_projects` + can get interrupted. This may happen for many reasons, but it's always safe + to run the indexing task again. It will skip repositories that have + already been indexed. -As the indexer stores the last commit SHA of every indexed repository in the -database, you can run the indexer with the special parameter `UPDATE_INDEX` and -it will check every project repository again to make sure that every commit in -that repository is indexed, it can be useful in case if your index is outdated: + As the indexer stores the last commit SHA of every indexed repository in the + database, you can run the indexer with the special parameter `UPDATE_INDEX` and + it will check every project repository again to make sure that every commit in + a repository is indexed, which can be useful in case if your index is outdated: -```sh -# Omnibus installations -sudo gitlab-rake gitlab:elastic:index_projects UPDATE_INDEX=true ID_TO=1000 + ```sh + # Omnibus installations + sudo gitlab-rake gitlab:elastic:index_projects UPDATE_INDEX=true ID_TO=1000 -# Installations from source -bundle exec rake gitlab:elastic:index_projects UPDATE_INDEX=true ID_TO=1000 RAILS_ENV=production -``` + # Installations from source + bundle exec rake gitlab:elastic:index_projects UPDATE_INDEX=true ID_TO=1000 RAILS_ENV=production + ``` -You can also use the `gitlab:elastic:clear_index_status` Rake task to force the -indexer to "forget" all progress, so retrying the indexing process from the -start. + You can also use the `gitlab:elastic:clear_index_status` Rake task to force the + indexer to "forget" all progress, so it will retry the indexing process from the + start. -The `index_projects` command enqueues jobs to index all project and wiki -repositories, and most database content. However, snippets still need to be -indexed separately. To do so, run one of these commands: +1. Personal snippets are not associated with a project and need to be indexed separately + by running one of these commands: -```sh -# Omnibus installations -sudo gitlab-rake gitlab:elastic:index_snippets + ```sh + # Omnibus installations + sudo gitlab-rake gitlab:elastic:index_snippets -# Installations from source -bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production -``` + # Installations from source + bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production + ``` -Enable replication and refreshing again after indexing (only if you previously disabled it): +1. Enable replication and refreshing again after indexing (only if you previously disabled it): -```bash -curl --request PUT localhost:9200/gitlab-production/_settings --data '{ - "index" : { - "number_of_replicas" : 1, - "refresh_interval" : "1s" - } }' -``` + ```bash + curl --request PUT localhost:9200/gitlab-production/_settings --data '{ + "index" : { + "number_of_replicas" : 1, + "refresh_interval" : "1s" + } }' + ``` -A force merge should be called after enabling the refreshing above. + A force merge should be called after enabling the refreshing above. -For Elasticsearch 6.x, before proceeding with the force merge, the index should be in read-only mode: + For Elasticsearch 6.x, the index should be in read-only mode before proceeding with the force merge: -```bash -curl --request PUT localhost:9200/gitlab-production/_settings --data '{ - "settings": { - "index.blocks.write": true - } }' -``` + ```bash + curl --request PUT localhost:9200/gitlab-production/_settings --data '{ + "settings": { + "index.blocks.write": true + } }' + ``` -Then, initiate the force merge: + Then, initiate the force merge: -```bash -curl --request POST 'http://localhost:9200/gitlab-production/_forcemerge?max_num_segments=5' -``` + ```bash + curl --request POST 'http://localhost:9200/gitlab-production/_forcemerge?max_num_segments=5' + ``` -After this, if your index is in read-only, switch back to read-write: + After this, if your index is in read-only mode, switch back to read-write: -```bash -curl --request PUT localhost:9200/gitlab-production/_settings --data '{ - "settings": { - "index.blocks.write": false - } }' -``` + ```bash + curl --request PUT localhost:9200/gitlab-production/_settings --data '{ + "settings": { + "index.blocks.write": false + } }' + ``` -Enable Elasticsearch search in **Admin > Settings > Integrations**. That's it. Enjoy it! +1. After the indexing has completed, enable [**Search with Elasticsearch**](#enabling-elasticsearch). -### Index limit +### Indexing limitations -Currently for repository and snippet files, GitLab would only index up to 1 MB of content, in order to avoid indexing timeout. +For repository and snippet files, GitLab will only index up to 1 MiB of content, in order to avoid indexing timeouts. ## GitLab Elasticsearch Rake Tasks There are several rake tasks available to you via the command line: -- [sudo gitlab-rake gitlab:elastic:index](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) +- [`sudo gitlab-rake gitlab:elastic:index`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - This is a wrapper task. It does the following: - `sudo gitlab-rake gitlab:elastic:create_empty_index` - `sudo gitlab-rake gitlab:elastic:clear_index_status` - `sudo gitlab-rake gitlab:elastic:index_projects` - `sudo gitlab-rake gitlab:elastic:index_snippets` -- [sudo gitlab-rake gitlab:elastic:index_projects](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) +- [`sudo gitlab-rake gitlab:elastic:index_projects`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - This iterates over all projects and queues sidekiq jobs to index them in the background. -- [sudo gitlab-rake gitlab:elastic:index_projects_status](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) +- [`sudo gitlab-rake gitlab:elastic:index_projects_status`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - This determines the overall status of the indexing. It is done by counting the total number of indexed projects, dividing by a count of the total number of projects, then multiplying by 100. -- [sudo gitlab-rake gitlab:elastic:create_empty_index](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - This generates an empty index on the Elasticsearch side. -- [sudo gitlab-rake gitlab:elastic:clear_index_status](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) +- [`sudo gitlab-rake gitlab:elastic:create_empty_index`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) + - This generates an empty index on the Elasticsearch side, deleting the existing one if present. +- [`sudo gitlab-rake gitlab:elastic:clear_index_status`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - This deletes all instances of IndexStatus for all projects. -- [sudo gitlab-rake gitlab:elastic:delete_index](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) +- [`sudo gitlab-rake gitlab:elastic:delete_index`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - This removes the GitLab index on the Elasticsearch instance. -- [sudo gitlab-rake gitlab:elastic:recreate_index](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) +- [`sudo gitlab-rake gitlab:elastic:recreate_index`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - Does the same thing as `sudo gitlab-rake gitlab:elastic:create_empty_index` -- [sudo gitlab-rake gitlab:elastic:index_snippets](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) +- [`sudo gitlab-rake gitlab:elastic:index_snippets`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - Performs an Elasticsearch import that indexes the snippets data. -- [sudo gitlab-rake gitlab:elastic:projects_not_indexed](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) +- [`sudo gitlab-rake gitlab:elastic:projects_not_indexed`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - Displays which projects are not indexed. ### Environment Variables @@ -468,7 +521,7 @@ Here are some common pitfalls and how to overcome them: pp s.search_objects.to_a ``` - See [Elasticsearch Index Scopes](elasticsearch.md#elasticsearch-index-scopes) for more information on searching for specific types of data. + See [Elasticsearch Index Scopes](#elasticsearch-index-scopes) for more information on searching for specific types of data. - **I indexed all the repositories but then switched Elasticsearch servers and now I can't find anything** diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index 49b3d194a01..d46486ad888 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -49,7 +49,7 @@ To enable the Facebook OmniAuth provider you must register your application with 1. On your GitLab server, open the configuration file. - For omnibus package: + For Omnibus package: ```sh sudo editor /etc/gitlab/gitlab.rb @@ -67,7 +67,7 @@ To enable the Facebook OmniAuth provider you must register your application with 1. Add the provider configuration: - For omnibus package: + For Omnibus package: ```ruby gitlab_rails['omniauth_providers'] = [ diff --git a/doc/integration/github.md b/doc/integration/github.md index c8dbae65465..f19b3109d15 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -36,7 +36,7 @@ To get the credentials (a pair of Client ID and Client Secret), you must registe 1. On your GitLab server, open the configuration file. - For omnibus package: + For Omnibus package: ```sh sudo editor /etc/gitlab/gitlab.rb @@ -54,7 +54,7 @@ To get the credentials (a pair of Client ID and Client Secret), you must registe 1. Add the provider configuration: - For omnibus package: + For Omnibus package: For GitHub.com: @@ -124,7 +124,7 @@ certificate and the imports are failing, you will need to disable SSL verificati 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. -For omnibus package: +For Omnibus package: ```ruby gitlab_rails['omniauth_providers'] = [ diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 46da3d88d90..74f2d5cb403 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -30,7 +30,7 @@ GitLab.com will generate an application ID and secret key for you to use. 1. On your GitLab server, open the configuration file. - For omnibus package: + For Omnibus package: ```sh sudo editor /etc/gitlab/gitlab.rb @@ -48,7 +48,7 @@ GitLab.com will generate an application ID and secret key for you to use. 1. Add the provider configuration: - For omnibus package: + For Omnibus package: ```ruby gitlab_rails['omniauth_providers'] = [ diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 6755640d39c..d865f977799 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -35,7 +35,7 @@ and [Migrating from Jenkins to GitLab](https://www.youtube.com/watch?v=RlEVGOpYF For a real use case, read the blog post [Continuous integration: From Jenkins to GitLab using Docker](https://about.gitlab.com/2017/07/27/docker-my-precious/). -NOTE: **Moving from a traditional CI plug-in to a single application for the entire software development lifecycle can decrease hours spent on maintaining toolchains by 10% or more.** +NOTE: **Moving from a traditional CI plug-in to a single application for the entire software development lifecycle can decrease hours spent on maintaining toolchains by 10% or more.** Visit the ['GitLab vs. Jenkins' comparison page](https://about.gitlab.com/devops-tools/jenkins-vs-gitlab.html) to learn how our built-in CI compares to Jenkins. ## Requirements diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index bac89ae2dc6..3e437eb688a 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -14,12 +14,12 @@ Integration includes: Requirements: - [Jenkins GitLab Hook plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin) -- git clone access for Jenkins from GitLab repo (via ssh key) +- Git clone access for Jenkins from GitLab repo (via ssh key) ## Jenkins 1. Install [GitLab Hook plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin) -1. Set up jenkins project +1. Set up Jenkins project  diff --git a/doc/integration/jira.md b/doc/integration/jira.md index c09fde08326..37eba25fb5a 100644 --- a/doc/integration/jira.md +++ b/doc/integration/jira.md @@ -2,4 +2,4 @@ redirect_to: '../user/project/integrations/jira.md' --- -This document was moved to [integrations/jira](../user/project/integrations/jira.md). +This document was moved to [another location](../user/project/integrations/jira.md). diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md index 3e894371df9..c413e07ec93 100644 --- a/doc/integration/jira_development_panel.md +++ b/doc/integration/jira_development_panel.md @@ -23,7 +23,7 @@ or instance admin (in the case of self-hosted GitLab) set up the integration, in order to simplify administration. TIP: **Tip:** -Create and use a single-purpose "jira" user in GitLab, so that removing +Create and use a single-purpose `jira` user in GitLab, so that removing regular users won't impact your integration. ## Requirements diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index b791cbd428d..81a1e9b0067 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -46,7 +46,7 @@ sudo chmod 0600 /etc/http.keytab For source installations, make sure the `kerberos` gem group [has been installed](../install/installation.md#install-gems). -1. Edit the kerberos section of [gitlab.yml] to enable Kerberos ticket-based +1. Edit the `kerberos` section of [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example) to enable Kerberos ticket-based authentication. In most cases, you only need to enable Kerberos and specify the location of the keytab: @@ -153,7 +153,7 @@ keep offering only `basic` authentication. listen [::]:8443 ipv6only=on ssl; ``` -1. Update the Kerberos section of [gitlab.yml]: +1. Update the `kerberos` section of [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example): ```yaml kerberos: @@ -203,7 +203,7 @@ remove the OmniAuth provider named `kerberos` from your `gitlab.yml` / **For installations from source** -1. Edit [gitlab.yml] and remove the `- { name: 'kerberos' }` line under omniauth +1. Edit [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example) and remove the `- { name: 'kerberos' }` line under omniauth providers: ```yaml @@ -295,7 +295,6 @@ See also: [Git v2.11 release notes](https://github.com/git/git/blob/master/Docum - <http://blog.manula.org/2012/04/setting-up-kerberos-server-with-debian.html> - <http://www.roguelynn.com/words/explain-like-im-5-kerberos/> -[gitlab.yml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example [restart gitlab]: ../administration/restart_gitlab.md#installations-from-source [reconfigure gitlab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure [nginx]: http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index f4119b1d1ce..ad59592c45f 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -12,7 +12,7 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc 1. Strategy parses user information from the response, using a **configurable** format 1. GitLab finds or creates the returned user and logs them in -## Limitations of this Strategy: +## 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 (importing projects or users, etc) diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 7a92ed994c7..ef319f7f0ce 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -69,7 +69,7 @@ that are in common for all providers that we need to consider. To change these settings: -- **For omnibus package** +- **For Omnibus package** Open the configuration file: @@ -277,3 +277,24 @@ omniauth: sync_profile_from_provider: ['twitter', 'google_oauth2'] sync_profile_attributes: ['email', 'location'] ``` + +## Bypassing two factor authentication + +Starting with GitLab 12.3, this allows users to login with the specified +providers without two factor authentication. + +Define the allowed providers using an array, e.g. `["twitter", 'google_oauth2']`, or as +`true`/`false` to allow all providers or none. This option should only be configured +for providers which already have two factor authentication (default: false). +This configration dose not apply to SAML. + +```ruby +gitlab_rails['omniauth_allow_bypass_two_factor'] = ['twitter', 'google_oauth2'] +``` + +**For installations from source** + +```yaml +omniauth: + allow_bypass_two_factor: ['twitter', 'google_oauth2'] +``` diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 176622e8050..10ab9d3c126 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -29,7 +29,7 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create 1. On your GitLab server, open the configuration file. - For omnibus package: + For Omnibus package: ```sh sudo editor /etc/gitlab/gitlab.rb @@ -46,7 +46,7 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create 1. Add the provider configuration: - For omnibus package: + For Omnibus package: ```ruby gitlab_rails['omniauth_providers'] = [ diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 22e07594d6f..de160e72dda 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -17,7 +17,7 @@ in your SAML IdP: 1. On your GitLab server, open the configuration file. - For omnibus package: + For Omnibus package: ```sh sudo editor /etc/gitlab/gitlab.rb @@ -34,7 +34,7 @@ in your SAML IdP: 1. To allow your users to use SAML to sign up without having to manually create an account first, don't forget to add the following values to your configuration: - For omnibus package: + For Omnibus package: ```ruby gitlab_rails['omniauth_enabled'] = true @@ -54,7 +54,7 @@ in your SAML IdP: 1. You can also automatically link SAML users with existing GitLab users if their email addresses match by adding the following setting: - For omnibus package: + For Omnibus package: ```ruby gitlab_rails['omniauth_auto_link_saml_user'] = true @@ -68,7 +68,7 @@ in your SAML IdP: 1. Add the provider configuration: - For omnibus package: + For Omnibus package: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -342,7 +342,7 @@ You can add this setting to your GitLab configuration to automatically redirect to your SAML server for authentication, thus removing the need to click a button before actually signing in. -For omnibus package: +For Omnibus package: ```ruby gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml' diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index 27355d25266..ca5a8077e73 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -1,18 +1,18 @@ # Shibboleth OmniAuth Provider -This documentation is for enabling shibboleth with omnibus-gitlab package. +This documentation is for enabling Shibboleth with the Omnibus GitLab package. -In order to enable Shibboleth support in gitlab we need to use Apache instead of Nginx (It may be possible to use Nginx, however this is difficult to configure using the bundled Nginx provided in the omnibus-gitlab package). Apache uses mod_shib2 module for shibboleth authentication and can pass attributes as headers to omniauth-shibboleth provider. +In order to enable Shibboleth support in GitLab we need to use Apache instead of Nginx (It may be possible to use Nginx, however this is difficult to configure using the bundled Nginx provided in the Omnibus GitLab package). Apache uses mod_shib2 module for Shibboleth authentication and can pass attributes as headers to Omniauth Shibboleth provider. -To enable the Shibboleth OmniAuth provider you must configure Apache shibboleth module. +To enable the Shibboleth OmniAuth provider you must configure Apache Shibboleth module. The installation and configuration of the module itself is out of the scope of this document. Check <https://wiki.shibboleth.net/confluence/display/SP3/Apache> for more info. -You can find Apache config in gitlab-recipes (<https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache>). +You can find Apache config in [GitLab Recipes](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache). The following changes are needed to enable Shibboleth: -1. Protect omniauth-shibboleth callback URL: +1. Protect Omniauth Shibboleth callback URL: ``` <Location /users/auth/shibboleth/callback> @@ -32,7 +32,7 @@ The following changes are needed to enable Shibboleth: </Location> ``` -1. Exclude shibboleth URLs from rewriting. Add `RewriteCond %{REQUEST_URI} !/Shibboleth.sso` and `RewriteCond %{REQUEST_URI} !/shibboleth-sp`. Config should look like this: +1. Exclude Shibboleth URLs from rewriting. Add `RewriteCond %{REQUEST_URI} !/Shibboleth.sso` and `RewriteCond %{REQUEST_URI} !/shibboleth-sp`. Config should look like this: ``` # Apache equivalent of Nginx try files @@ -50,7 +50,7 @@ The following changes are needed to enable 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 to the [OmniAuth::Strategies::Shibboleth class](https://github.com/toyokazu/omniauth-shibboleth/blob/master/lib/omniauth/strategies/shibboleth.rb) - and are documented by the [omniauth-shibboleth gem](https://github.com/toyokazu/omniauth-shibboleth) + and are documented by the [`omniauth-shibboleth` gem](https://github.com/toyokazu/omniauth-shibboleth) (take care to note the version of the gem packaged with GitLab). If some of your users appear to be authenticated by Shibboleth and Apache, but GitLab rejects their account with a URI that contains "e-mail is invalid" then your @@ -94,7 +94,7 @@ On the sign in page, there should now be a "Sign in with: Shibboleth" icon below ## 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! +you will not get a Shibboleth session! ``` <Location /> diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index 71ea2e25533..86a66dc4569 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -15,6 +15,7 @@ Taking the trigger term as `project-name`, the commands are: | `/project-name help` | Shows all available slash commands | | `/project-name issue new <title> <shift+return> <description>` | Creates a new issue with title `<title>` and description `<description>` | | `/project-name issue show <id>` | Shows the issue with id `<id>` | +| `/project-name issue close <id>` | Closes the issue with id `<id>` | | `/project-name issue search <query>` | Shows up to 5 issues matching `<query>` | | `/project-name issue move <id> to <project>` | Moves issue ID `<id>` to `<project>` | | `/project-name deploy <from> to <to>` | Deploy from the `<from>` environment to the `<to>` environment | diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index d8096993885..b2bd1b57d0f 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -32,7 +32,7 @@ To enable the Twitter OmniAuth provider you must register your application with 1. On your GitLab server, open the configuration file. - For omnibus package: + For Omnibus package: ```sh sudo editor /etc/gitlab/gitlab.rb @@ -50,7 +50,7 @@ To enable the Twitter OmniAuth provider you must register your application with 1. Add the provider configuration: - For omnibus package: + For Omnibus package: ```ruby gitlab_rails['omniauth_providers'] = [ diff --git a/doc/integration/ultra_auth.md b/doc/integration/ultra_auth.md index 9ed1bdb4882..fb950ba989a 100644 --- a/doc/integration/ultra_auth.md +++ b/doc/integration/ultra_auth.md @@ -25,7 +25,7 @@ To get the credentials (a pair of Client ID and Client Secret), you must registe 1. Select **Register application**. 1. On your GitLab server, open the configuration file. - For omnibus package: + For Omnibus package: ```sh sudo editor /etc/gitlab/gitlab.rb @@ -41,7 +41,7 @@ To get the credentials (a pair of Client ID and Client Secret), you must registe 1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. 1. Add the provider configuration: - For omnibus package: + For Omnibus package: ```ruby gitlab_rails['omniauth_providers'] = [ diff --git a/doc/legal/corporate_contributor_license_agreement.md b/doc/legal/corporate_contributor_license_agreement.md index 8c1f4a126b1..c8782a2cfc2 100644 --- a/doc/legal/corporate_contributor_license_agreement.md +++ b/doc/legal/corporate_contributor_license_agreement.md @@ -16,7 +16,7 @@ You accept and agree to the following terms and conditions for Your present and Subject to the terms and conditions of this Agreement, You hereby grant to GitLab B.V. and to recipients of software distributed by GitLab B.V. a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed. - You represent that You are legally entitled to grant the above license. You represent further that each of Your employees is authorized to submit Contributions on Your behalf, but excluding employees that are designated in writing by You as "Not authorized to submit Contributions on behalf of (name of Your corporation here)." Such designations of exclusion for unauthorized employees are to be submitted via email to legal@gitlab.com. It is Your responsibility to notify GitLab B.V. when any change is required to the list of designated employees excluded from submitting Contributions on Your behalf. Such notification should also be sent via email to legal@gitlab.com. + You represent that You are legally entitled to grant the above license. You represent further that each of Your employees is authorized to submit Contributions on Your behalf, but excluding employees that are designated in writing by You as "Not authorized to submit Contributions on behalf of (name of Your corporation here)." Such designations of exclusion for unauthorized employees are to be submitted via email to `legal@gitlab.com`. It is Your responsibility to notify GitLab B.V. when any change is required to the list of designated employees excluded from submitting Contributions on Your behalf. Such notification should also be sent via email to `legal@gitlab.com`. - **Contributions:** diff --git a/doc/migrate_ci_to_ce/README.md b/doc/migrate_ci_to_ce/README.md index 9947c19a667..50e491f29a2 100644 --- a/doc/migrate_ci_to_ce/README.md +++ b/doc/migrate_ci_to_ce/README.md @@ -32,7 +32,7 @@ upgrade to 8.0 until you finish the migration procedure. ## Before upgrading -If you have GitLab CI installed using omnibus-gitlab packages but **you don't want to migrate your existing data**: +If you have GitLab CI installed using Omnibus GitLab packages but **you don't want to migrate your existing data**: ```bash mv /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/gitlab-ci/builds.$(date +%s) @@ -227,7 +227,7 @@ sudo mv /path/to/12345_gitlab_ci_backup.tar /var/opt/gitlab/backups/ sudo mv /path/to/12345_gitlab_ci_backup.tar /home/git/gitlab/tmp/backups/ ``` -### 5. Import the CI data into GitLab. +### 5. Import the CI data into GitLab This step will delete 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. @@ -353,7 +353,7 @@ Errno::EACCES: Permission denied @ rb_sysopen - config/secrets.yml This can happen if you are updating from versions prior to 7.13 straight to 8.0. The fix for this is to update to Omnibus 7.14 first and then update it to 8.0. -### Permission denied when accessing /var/opt/gitlab/gitlab-ci/builds +### Permission denied when accessing `/var/opt/gitlab/gitlab-ci/builds` To fix that issue you have to change builds/ folder permission before doing final backup: diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md index 018c273c51a..f7ba7c16a9e 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/maintenance.md @@ -86,6 +86,7 @@ Please see the table below for some examples: | 9.4.5 | 8.13.4 | `8.13.4` -> `8.17.7` -> `9.4.5` | `8.17.7` is the last version in version `8` | | 10.1.4 | 8.13.4 | `8.13.4 -> 8.17.7 -> 9.5.10 -> 10.1.4` | `8.17.7` is the last version in version `8`, `9.5.10` is the last version in version `9` | | 11.3.4 | 8.13.4 | `8.13.4` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.3.4` | `8.17.7` is the last version in version `8`, `9.5.10` is the last version in version `9`, `10.8.7` is the last version in version `10` | +| 12.0.2 | 11.3.4 | `11.3.4` -> `11.11.x` -> `12.0.2` | `11.11.x` is the last version in version `11` More information about the release procedures can be found in our [release documentation](https://gitlab.com/gitlab-org/release/docs). You may also want to read our diff --git a/doc/project_services/bamboo.md b/doc/project_services/bamboo.md index a1ff8909f87..b1d37898516 100644 --- a/doc/project_services/bamboo.md +++ b/doc/project_services/bamboo.md @@ -2,4 +2,4 @@ redirect_to: '../user/project/integrations/bamboo.md' --- -This document was moved to [user/project/integrations/bamboo.md](../user/project/integrations/bamboo.md). +This document was moved to [another location](../user/project/integrations/bamboo.md). diff --git a/doc/project_services/bugzilla.md b/doc/project_services/bugzilla.md index 1abf1b28939..17dff538c0e 100644 --- a/doc/project_services/bugzilla.md +++ b/doc/project_services/bugzilla.md @@ -2,4 +2,4 @@ redirect_to: '../user/project/integrations/bugzilla.md' --- -This document was moved to [user/project/integrations/bugzilla.md](../user/project/integrations/bugzilla.md). +This document was moved to [another location](../user/project/integrations/bugzilla.md). diff --git a/doc/project_services/emails_on_push.md b/doc/project_services/emails_on_push.md index c5ab8aa5c70..a7d91934ce9 100644 --- a/doc/project_services/emails_on_push.md +++ b/doc/project_services/emails_on_push.md @@ -2,4 +2,4 @@ redirect_to: '../user/project/integrations/emails_on_push.md' --- -This document was moved to [user/project/integrations/emails_on_push.md](../user/project/integrations/emails_on_push.md). +This document was moved to [another location](../user/project/integrations/emails_on_push.md). diff --git a/doc/project_services/hipchat.md b/doc/project_services/hipchat.md index 4ae9f6c6b2e..a2fbbd5cce5 100644 --- a/doc/project_services/hipchat.md +++ b/doc/project_services/hipchat.md @@ -1 +1,5 @@ -This document was moved to [user/project/integrations/hipchat.md](../user/project/integrations/hipchat.md). +--- +redirect_to: '../user/project/integrations/hipchat.md' +--- + +This document was moved to [another location](../user/project/integrations/hipchat.md). diff --git a/doc/project_services/irker.md b/doc/project_services/irker.md index af47abab117..70e46b1b364 100644 --- a/doc/project_services/irker.md +++ b/doc/project_services/irker.md @@ -2,4 +2,4 @@ redirect_to: '../user/project/integrations/irker.md' --- -This document was moved to [user/project/integrations/irker.md](../user/project/integrations/irker.md). +This document was moved to [another location](../user/project/integrations/irker.md). diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index 6a0108f400f..37eba25fb5a 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -2,4 +2,4 @@ redirect_to: '../user/project/integrations/jira.md' --- -This document was moved to [user/project/integrations/jira.md](../user/project/integrations/jira.md). +This document was moved to [another location](../user/project/integrations/jira.md). diff --git a/doc/project_services/kubernetes.md b/doc/project_services/kubernetes.md index cfe36fcd1b2..585c5ddb002 100644 --- a/doc/project_services/kubernetes.md +++ b/doc/project_services/kubernetes.md @@ -2,4 +2,4 @@ redirect_to: '../user/project/integrations/kubernetes.md' --- -This document was moved to [user/project/integrations/kubernetes.md](../user/project/integrations/kubernetes.md). +This document was moved to [another location](../user/project/integrations/kubernetes.md). diff --git a/doc/project_services/mattermost.md b/doc/project_services/mattermost.md index de9f4d14cf7..78888395031 100644 --- a/doc/project_services/mattermost.md +++ b/doc/project_services/mattermost.md @@ -2,4 +2,4 @@ redirect_to: '../user/project/integrations/mattermost.md' --- -This document was moved to [user/project/integrations/mattermost.md](../user/project/integrations/mattermost.md). +This document was moved to [another location](../user/project/integrations/mattermost.md). diff --git a/doc/project_services/mattermost_slash_commands.md b/doc/project_services/mattermost_slash_commands.md index 82ec34739c1..0c2774d95e0 100644 --- a/doc/project_services/mattermost_slash_commands.md +++ b/doc/project_services/mattermost_slash_commands.md @@ -2,4 +2,4 @@ redirect_to: '../user/project/integrations/mattermost_slash_commands.md' --- -This document was moved to [user/project/integrations/mattermost_slash_commands.md](../user/project/integrations/mattermost_slash_commands.md). +This document was moved to [another location](../user/project/integrations/mattermost_slash_commands.md). diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md index a355851a273..2ae7a0ce3ce 100644 --- a/doc/project_services/project_services.md +++ b/doc/project_services/project_services.md @@ -2,4 +2,4 @@ redirect_to: '../user/project/integrations/project_services.md' --- -This document was moved to [user/project/integrations/project_services.md](../user/project/integrations/project_services.md). +This document was moved to [another location](../user/project/integrations/project_services.md). diff --git a/doc/project_services/redmine.md b/doc/project_services/redmine.md index 05f28f00adc..141c72d6b6b 100644 --- a/doc/project_services/redmine.md +++ b/doc/project_services/redmine.md @@ -2,4 +2,4 @@ redirect_to: '../user/project/integrations/redmine.md' --- -This document was moved to [user/project/integrations/redmine.md](../user/project/integrations/redmine.md). +This document was moved to [another location](../user/project/integrations/redmine.md). diff --git a/doc/project_services/services_templates.md b/doc/project_services/services_templates.md index ac6b85cc801..8b2c85802de 100644 --- a/doc/project_services/services_templates.md +++ b/doc/project_services/services_templates.md @@ -2,4 +2,4 @@ redirect_to: '../user/project/integrations/services_templates.md' --- -This document was moved to [user/project/integrations/services_templates.md](../user/project/integrations/services_templates.md). +This document was moved to [another location](../user/project/integrations/services_templates.md). diff --git a/doc/project_services/slack.md b/doc/project_services/slack.md index 4c89ce92002..815032a08d5 100644 --- a/doc/project_services/slack.md +++ b/doc/project_services/slack.md @@ -2,4 +2,4 @@ redirect_to: '../user/project/integrations/slack.md' --- -This document was moved to [user/project/integrations/slack.md](../user/project/integrations/slack.md). +This document was moved to [another location](../user/project/integrations/slack.md). diff --git a/doc/project_services/slack_slash_commands.md b/doc/project_services/slack_slash_commands.md index ca0034256f1..caae4d2ba4b 100644 --- a/doc/project_services/slack_slash_commands.md +++ b/doc/project_services/slack_slash_commands.md @@ -2,4 +2,4 @@ redirect_to: '../user/project/integrations/slack_slash_commands.md' --- -This document was moved to [user/project/integrations/slack_slash_commands.md](../user/project/integrations/slack_slash_commands.md). +This document was moved to [another location](../user/project/integrations/slack_slash_commands.md). diff --git a/doc/public_access/public_access.md b/doc/public_access/public_access.md index 0142e5075cc..dc6ee9b2503 100644 --- a/doc/public_access/public_access.md +++ b/doc/public_access/public_access.md @@ -6,7 +6,7 @@ type: reference GitLab allows [Owners](../user/permissions.md) to set a projects' visibility as **public**, **internal** or **private**. These visibility levels affect who can see the project in the -public access directory (`/public` under your GitLab instance), like at [https://gitlab.com/public](). +public access directory (`/public` under your GitLab instance), like at <https://gitlab.com/public> ## Visibility of projects diff --git a/doc/push_rules/push_rules.md b/doc/push_rules/push_rules.md index b1754131e76..7455b577af7 100644 --- a/doc/push_rules/push_rules.md +++ b/doc/push_rules/push_rules.md @@ -10,7 +10,7 @@ regular expressions to reject pushes based on commit contents, branch names or f ## Overview GitLab already offers [protected branches][protected-branches], but there are -cases when you need some specific rules like preventing git tag removal or +cases when you need some specific rules like preventing Git tag removal or enforcing a special format for commit messages. Push rules are essentially [pre-receive Git hooks][hooks] that are easy to @@ -27,7 +27,7 @@ Every push rule could have its own use case, but let's consider some examples. Let's assume you have the following requirements for your workflow: - every commit should reference a Jira issue, for example: `Refactored css. Fixes JIRA-123.` -- users should not be able to remove git tags with `git push` +- users should not be able to remove Git tags with `git push` All you need to do is write a simple regular expression that requires the mention of a Jira issue in the commit message, like `JIRA\-\d+`. @@ -64,7 +64,7 @@ The following options are available. | Push rule | GitLab version | Description | | --------- | :------------: | ----------- | -| Removal of tags with `git push` | **Starter** 7.10 | Forbid users to remove git tags with `git push`. Tags will still be able to be deleted through the web UI. | +| Removal of tags with `git push` | **Starter** 7.10 | Forbid users to remove Git tags with `git push`. Tags will still be able to be deleted through the web UI. | | Check whether author is a GitLab user | **Starter** 7.10 | Restrict commits by author (email) to existing GitLab users. | | Committer restriction | **Premium** 10.2 | GitLab will reject any commit that was not committed by the current authenticated user | | Check whether commit is signed through GPG | **Premium** 10.1 | Reject commit when it is not signed through GPG. Read [signing commits with GPG][signing-commits]. | diff --git a/doc/raketasks/README.md b/doc/raketasks/README.md index dcc96507676..ad86555fc17 100644 --- a/doc/raketasks/README.md +++ b/doc/raketasks/README.md @@ -12,7 +12,7 @@ comments: false - [General Maintenance](../administration/raketasks/maintenance.md) and self-checks - [User management](user_management.md) - [Webhooks](web_hooks.md) -- [Import](import.md) of git repositories in bulk +- [Import](import.md) of Git repositories in bulk - [Rebuild authorized_keys file](../administration/raketasks/maintenance.md#rebuild-authorized_keys-file) task for administrators - [Migrate Uploads](../administration/raketasks/uploads/migrate.md) - [Sanitize Uploads](../administration/raketasks/uploads/sanitize.md) diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 51f04df27c7..336000f6cb9 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -94,7 +94,7 @@ docker exec -t <container name> gitlab-backup create If you are using the [GitLab helm chart](https://gitlab.com/charts/gitlab) on a Kubernetes cluster, you can run the backup task using `backup-utility` script on -the gitlab task runner pod via `kubectl`. Refer to [backing up a GitLab installation](https://gitlab.com/charts/gitlab/blob/master/doc/backup-restore/backup.md#backing-up-a-gitlab-installation) for more details: +the GitLab task runner pod via `kubectl`. Refer to [backing up a GitLab installation](https://gitlab.com/charts/gitlab/blob/master/doc/backup-restore/backup.md#backing-up-a-gitlab-installation) for more details: ```sh kubectl exec -it <gitlab task-runner pod> backup-utility @@ -458,7 +458,7 @@ You may also send backups to a mounted share (`NFS` / `CIFS` / `SMB` / etc.) by using the Fog [`Local`](https://github.com/fog/fog-local#usage) storage provider. The directory pointed to by the `local_root` key **must** be owned by the `git` user **when mounted** (mounting with the `uid=` of the `git` user for `CIFS` and -`SMB`) or the user that you are executing the backup tasks under (for omnibus +`SMB`) or the user that you are executing the backup tasks under (for Omnibus packages, this is the `git` user). The `backup_upload_remote_directory` **must** be set in addition to the @@ -507,7 +507,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. +will have 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. @@ -614,7 +614,7 @@ GitLab that you created it on, for example CE 9.1.0. You need to have a working GitLab installation before you can perform a restore. This is mainly because the system user performing the -restore actions ('git') is usually not allowed to create or delete +restore actions (`git`) is usually not allowed to create or delete the SQL database it needs to import data into ('gitlabhq_production'). All existing data will be either erased (SQL) or moved to a separate directory (repositories, uploads). @@ -773,14 +773,14 @@ In this case you can consider using filesystem snapshots as part of your backup Example: Amazon EBS -> A GitLab server using omnibus-gitlab hosted on Amazon AWS. +> A GitLab server using Omnibus GitLab hosted on Amazon AWS. > An EBS drive containing an ext4 filesystem is mounted at `/var/opt/gitlab`. > In this case you could make an application backup by taking an EBS snapshot. > The backup includes all repositories, uploads and Postgres data. Example: LVM snapshots + rsync -> A GitLab server using omnibus-gitlab, with an LVM logical volume mounted at `/var/opt/gitlab`. +> 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. @@ -804,7 +804,7 @@ will have all your repositories, but not any other data. ## Troubleshooting -### Restoring database backup using omnibus packages outputs warnings +### Restoring database backup using Omnibus packages outputs warnings If you are using backup restore procedures you might encounter the following warnings: @@ -923,6 +923,29 @@ backup beforehand. UPDATE ci_runners SET token = null, token_encrypted = null; ``` +#### Reset pending pipeline jobs + +1. Enter the DB console: + + For Omnibus GitLab packages: + + ```sh + sudo gitlab-rails dbconsole + ``` + + For installations from source: + + ```sh + sudo -u git -H bundle exec rails dbconsole RAILS_ENV=production + ``` + +1. Clear all the tokens for pending jobs: + + ```sql + -- Clear build tokens + UPDATE ci_builds SET token = null, token_encrypted = null; + ``` + A similar strategy can be employed for the remaining features - by removing the data that cannot be decrypted, GitLab can be brought back into working order, and the lost data can be manually replaced. @@ -978,4 +1001,3 @@ If this happens, check the following: 1. Confirm there is sufficent diskspace for the gzip operation. 1. If NFS is being used, check if the mount option `timeo` is set. The default is `600`, and changing this to smaller values have resulted in this error. - diff --git a/doc/raketasks/cleanup.md b/doc/raketasks/cleanup.md index 832078d23cb..f84d29cca9a 100644 --- a/doc/raketasks/cleanup.md +++ b/doc/raketasks/cleanup.md @@ -1,6 +1,10 @@ # Cleanup -## Remove garbage from filesystem. Important! Data loss! +## Remove garbage from filesystem + +DANGER: **Danger:** +The commands below will remove data permanently from your GitLab instance. Only use +these commands if you are 100% certain that it is safe to delete this data. Remove namespaces(dirs) from all repository storage paths if they don't exist in GitLab database. diff --git a/doc/raketasks/features.md b/doc/raketasks/features.md index 57c16f110e4..c06800a2aa3 100644 --- a/doc/raketasks/features.md +++ b/doc/raketasks/features.md @@ -6,7 +6,7 @@ This command will enable the namespaces feature introduced in v4.0. It will move Note: -- Because the **repository location will change**, you will need to **update all your git URLs** to point to the new location. +- Because the **repository location will change**, you will need to **update all your Git URLs** to point to the new location. - Username can be changed at **Profile ➔ Account**. **Example:** diff --git a/doc/raketasks/import.md b/doc/raketasks/import.md index 8f65fab366e..d93e7241fda 100644 --- a/doc/raketasks/import.md +++ b/doc/raketasks/import.md @@ -11,17 +11,17 @@ ## How to use -### Create a new folder to import your Git repositories from. +### Create a new folder to import your Git repositories from -The new folder needs to have git user ownership and read/write/execute access for git user and its group: +The new folder needs to have Git user ownership and read/write/execute access for Git user and its group: ``` sudo -u git mkdir -p /var/opt/gitlab/git-data/repository-import-<date>/new_group ``` -### Copy your bare repositories inside this newly created folder: +### Copy your bare repositories inside this newly created folder -- Any .git repositories found on any of the subfolders will be imported as projects +- 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. Example: If we copy the repos to `/var/opt/gitlab/git-data/repository-import-<date>`, and repo A needs to be under the groups G1 and G2, it will @@ -34,11 +34,11 @@ sudo cp -r /old/git/foo.git /var/opt/gitlab/git-data/repository-import-<date>/ne sudo chown -R git:git /var/opt/gitlab/git-data/repository-import-<date> ``` -`foo.git` needs to be owned by the git user and git users group. +`foo.git` needs to be owned by the `git` user and `git` users group. If you are using an installation from source, replace `/var/opt/gitlab/` with `/home/git`. -### Run the command below depending on your type of installation: +### Run the command below depending on your type of installation #### Omnibus Installation @@ -96,7 +96,7 @@ Importing bare repositories from hashed storage is unsupported. To support importing bare repositories from hashed storage, GitLab 10.4 and later stores the full project path with each repository, in a special section of -the git repository's config file. This section is formatted as follows: +the Git repository's config file. This section is formatted as follows: ``` [gitlab] diff --git a/doc/raketasks/web_hooks.md b/doc/raketasks/web_hooks.md index cc1166a04cc..d9a042ec8fe 100644 --- a/doc/raketasks/web_hooks.md +++ b/doc/raketasks/web_hooks.md @@ -1,6 +1,6 @@ # Webhooks administration **(CORE ONLY)** -## Add a webhook for **ALL** projects: +## Add a webhook for **ALL** projects ```sh # omnibus-gitlab @@ -9,7 +9,7 @@ sudo gitlab-rake gitlab:web_hook:add URL="http://example.com/hook" bundle exec rake gitlab:web_hook:add URL="http://example.com/hook" RAILS_ENV=production ``` -## Add a webhook for projects in a given **NAMESPACE**: +## Add a webhook for projects in a given **NAMESPACE** ```sh # omnibus-gitlab @@ -18,7 +18,7 @@ sudo gitlab-rake gitlab:web_hook:add URL="http://example.com/hook" NAMESPACE=acm bundle exec rake gitlab:web_hook:add URL="http://example.com/hook" NAMESPACE=acme RAILS_ENV=production ``` -## Remove a webhook from **ALL** projects using: +## Remove a webhook from **ALL** projects using ```sh # omnibus-gitlab @@ -27,7 +27,7 @@ sudo gitlab-rake gitlab:web_hook:rm URL="http://example.com/hook" bundle exec rake gitlab:web_hook:rm URL="http://example.com/hook" RAILS_ENV=production ``` -## Remove a webhook from projects in a given **NAMESPACE**: +## Remove a webhook from projects in a given **NAMESPACE** ```sh # omnibus-gitlab @@ -36,7 +36,7 @@ sudo gitlab-rake gitlab:web_hook:rm URL="http://example.com/hook" NAMESPACE=acme bundle exec rake gitlab:web_hook:rm URL="http://example.com/hook" NAMESPACE=acme RAILS_ENV=production ``` -## List **ALL** webhooks: +## List **ALL** webhooks ```sh # omnibus-gitlab @@ -45,7 +45,7 @@ sudo gitlab-rake gitlab:web_hook:list bundle exec rake gitlab:web_hook:list RAILS_ENV=production ``` -## List the webhooks from projects in a given **NAMESPACE**: +## List the webhooks from projects in a given **NAMESPACE** ```sh # omnibus-gitlab diff --git a/doc/security/README.md b/doc/security/README.md index 5d498ac7602..fe96f7f2846 100644 --- a/doc/security/README.md +++ b/doc/security/README.md @@ -5,6 +5,7 @@ type: index # Security +- [Password storage](password_storage.md) - [Password length limits](password_length_limits.md) - [Restrict SSH key technologies and minimum length](ssh_keys_restrictions.md) - [Rate limits](rate_limits.md) @@ -17,3 +18,4 @@ type: index - [Enforce Two-factor authentication](two_factor_authentication.md) - [Send email confirmation on sign-up](user_email_confirmation.md) - [Security of running jobs](https://docs.gitlab.com/runner/security/) +- [Proxying images](asset_proxy.md) diff --git a/doc/security/asset_proxy.md b/doc/security/asset_proxy.md new file mode 100644 index 00000000000..f25910d3db7 --- /dev/null +++ b/doc/security/asset_proxy.md @@ -0,0 +1,28 @@ +A possible security concern when managing a public facing GitLab instance is +the ability to steal a users IP address by referencing images in issues, comments, etc. + +For example, adding `` to +an issue description will cause the image to be loaded from the external +server in order to be displayed. However this also allows the external server +to log the IP address of the user. + +One way to mitigate this is by proxying any external images to a server you +control. GitLab handles this by allowing you to run the "Camo" server +[cactus/go-camo](https://github.com/cactus/go-camo#how-it-works). +The image request is sent to the Camo server, which then makes the request for +the original image. This way an attacker only ever seems the IP address +of your Camo server. + +Once you have your Camo server up and running, you can configure GitLab to +proxy image requests to it. The following settings are supported: + +| Attribute | Description | +| ------------------------ | ----------- | +| `asset_proxy_enabled` | (**If enabled, requires:** `asset_proxy_url`) Enable proxying of assets. | +| `asset_proxy_secret_key` | Shared secret with the asset proxy server. | +| `asset_proxy_url` | URL of the asset proxy server. | +| `asset_proxy_whitelist` | Assets that match these domain(s) will NOT be proxied. Wildcards allowed. Your GitLab installation URL is automatically whitelisted. | + +These can be set via the [Application setting API](../api/settings.md) + +Note that a GitLab restart is required to apply any changes. diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md index 749ccf924b5..7c3d7284f25 100644 --- a/doc/security/information_exclusivity.md +++ b/doc/security/information_exclusivity.md @@ -15,7 +15,7 @@ another project that is under their control, or onto another server. Therefore, it is impossible to build access controls that prevent the intentional sharing of source code by users that have access to the source code. -This is an inherent feature of a DVCS. All git management systems have this +This is an inherent feature of a DVCS. All Git management systems have this limitation. You can take steps to prevent unintentional sharing and information diff --git a/doc/security/password_storage.md b/doc/security/password_storage.md new file mode 100644 index 00000000000..f4e32f96f7b --- /dev/null +++ b/doc/security/password_storage.md @@ -0,0 +1,13 @@ +--- +type: reference +--- + +# Password Storage + +GitLab stores user passwords in a hashed format, to prevent passwords from being visible. + +GitLab uses the [Devise](https://github.com/plataformatec/devise) authentication library, which handles the hashing of user passwords. Password hashes are created with the following attributes: + +- **Hashing**: the [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) hashing function is used to generate the hash of the provided password. This is a strong, industry-standard cryptographic hashing function. +- **Stretching**: Password hashes are [stretched](https://en.wikipedia.org/wiki/Key_stretching) to harden against brute-force attacks. GitLab uses a stretching factor of 10 by default. +- **Salting**: A [cryptographic salt](https://en.wikipedia.org/wiki/Salt_(cryptography)) is added to each password to harden against pre-computed hash and dictionary attacks. Each salt is randomly generated for each password, so that no two passwords share a salt, to further increase security. diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md index b99bfb16829..09d29bf3446 100644 --- a/doc/security/rack_attack.md +++ b/doc/security/rack_attack.md @@ -77,9 +77,12 @@ authentication requests were received in a 3-minute period from a single IP addr This applies only to Git requests and container registry (`/jwt/auth`) requests (combined). -This limit is reset by requests that authenticate successfully. For example, 29 -failed authentication requests followed by 1 successful request, followed by 29 -more failed authentication requests would not trigger a ban. +This limit: + +- Is reset by requests that authenticate successfully. For example, 29 + failed authentication requests followed by 1 successful request, followed by 29 + more failed authentication requests would not trigger a ban. +- Does not apply to JWT requests authenticated by `gitlab-ci-token`. No response headers are provided. diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md index c80f2f264b2..80088da77a0 100644 --- a/doc/security/rate_limits.md +++ b/doc/security/rate_limits.md @@ -30,4 +30,3 @@ similarly mitigated by a rate limit. This method of rate limiting is cumbersome, but has some advantages. It allows throttling of specific paths, and is also integrated into Git and container registry requests. See [Rack Attack initializer](rack_attack.md). - diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 9c1258fa1aa..15fdb52ac00 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -65,7 +65,7 @@ project in a simple and automatic way: 1. [Auto Code Quality](#auto-code-quality-starter) **(STARTER)** 1. [Auto SAST (Static Application Security Testing)](#auto-sast-ultimate) **(ULTIMATE)** 1. [Auto Dependency Scanning](#auto-dependency-scanning-ultimate) **(ULTIMATE)** -1. [Auto License Management](#auto-license-management-ultimate) **(ULTIMATE)** +1. [Auto License Compliance](#auto-license-compliance-ultimate) **(ULTIMATE)** 1. [Auto Container Scanning](#auto-container-scanning-ultimate) **(ULTIMATE)** 1. [Auto Review Apps](#auto-review-apps) 1. [Auto DAST (Dynamic Application Security Testing)](#auto-dast-ultimate) **(ULTIMATE)** @@ -95,34 +95,45 @@ Auto DevOps. To make full use of Auto DevOps, you will need: -- **GitLab Runner** (needed for all stages) - Your Runner needs to be - configured to be able to run Docker. Generally this means using the - [Docker](https://docs.gitlab.com/runner/executors/docker.html) or [Kubernetes - executor](https://docs.gitlab.com/runner/executors/kubernetes.html), with +- **GitLab Runner** (for all stages) + + Your Runner needs to be configured to be able to run Docker. Generally this + means using the either the [Docker](https://docs.gitlab.com/runner/executors/docker.html) + or [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executors, with [privileged mode enabled](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode). + The Runners do not need to be installed in the Kubernetes cluster, but the Kubernetes executor is easy to use and is automatically autoscaling. Docker-based Runners can be configured to autoscale as well, using [Docker - Machine](https://docs.gitlab.com/runner/install/autoscaling.html). Runners - should be registered as [shared Runners](../../ci/runners/README.md#registering-a-shared-runner) + Machine](https://docs.gitlab.com/runner/install/autoscaling.html). + + Runners should be registered as [shared Runners](../../ci/runners/README.md#registering-a-shared-runner) for the entire GitLab instance, or [specific Runners](../../ci/runners/README.md#registering-a-specific-runner) that are assigned to specific projects. -- **Base domain** (needed for Auto Review Apps and Auto Deploy) - You will need - a domain configured with wildcard DNS which is going to be used by all of your - Auto DevOps applications. [Read the specifics](#auto-devops-base-domain). -- **Kubernetes** (needed for Auto Review Apps, Auto Deploy, and Auto Monitoring) - - To enable deployments, you will need Kubernetes 1.5+. You need a [Kubernetes cluster][kubernetes-clusters] - for the project, or a Kubernetes [default service template](../../user/project/integrations/services_templates.md) - for the entire GitLab installation. - - **A load balancer** - You can use NGINX ingress by deploying it to your - Kubernetes cluster using the - [`nginx-ingress`](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress) - Helm chart. -- **Prometheus** (needed for Auto Monitoring) - To enable Auto Monitoring, you +- **Base domain** (for Auto Review Apps and Auto Deploy) + + You will need a domain configured with wildcard DNS which is going to be used + by all of your Auto DevOps applications. + + Read the [specifics](#auto-devops-base-domain). +- **Kubernetes** (for Auto Review Apps, Auto Deploy, and Auto Monitoring) + + To enable deployments, you will need: + + - Kubernetes 1.5+. + - A [Kubernetes cluster][kubernetes-clusters] for the project. + - A load balancer. You can use NGINX ingress by deploying it to your + Kubernetes cluster by either: + - Using the [`nginx-ingress`](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress) Helm chart. + - Installing the Ingress [GitLab Managed App](../../user/clusters/applications.md#ingress). +- **Prometheus** (for Auto Monitoring) + + To enable Auto Monitoring, you will need Prometheus installed somewhere (inside or outside your cluster) and configured to scrape your Kubernetes cluster. To get response metrics (in addition to system metrics), you need to [configure Prometheus to monitor NGINX](../../user/project/integrations/prometheus_library/nginx_ingress.md#configuring-nginx-ingress-monitoring). + The [Prometheus service](../../user/project/integrations/prometheus.md) integration needs to be enabled for the project, or enabled as a [default service template](../../user/project/integrations/services_templates.md) @@ -401,13 +412,13 @@ check out. Any security warnings are also shown in the merge request widget. Read more about [Dependency Scanning](../../user/application_security/dependency_scanning/index.md). -### Auto License Management **(ULTIMATE)** +### Auto License Compliance **(ULTIMATE)** > Introduced in [GitLab Ultimate][ee] 11.0. -License Management uses the -[License Management Docker image](https://gitlab.com/gitlab-org/security-products/license-management) -to search the project dependencies for their license. The Auto License Management stage +License Compliance uses the +[License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/license-management) +to search the project dependencies for their license. The Auto License Compliance stage will be skipped on licenses other than Ultimate. Once the @@ -415,7 +426,7 @@ report is created, it's uploaded as an artifact which you can later download and check out. Any licenses are also shown in the merge request widget. Read more how -[License Management works](../../user/application_security/license_management/index.md). +[License Compliance works](../../user/application_security/license_compliance/index.md). ### Auto Container Scanning **(ULTIMATE)** @@ -584,6 +595,55 @@ Unless you have a `Dockerfile` in your repo, your image is built with Herokuish, and you must prefix commands run in these images with `/bin/herokuish procfile exec` to replicate the environment where your application will run. +#### Workers + +Some web applications need to run extra deployments for "worker processes". For +example, it is common in a Rails application to have a separate worker process +to run background tasks like sending emails. + +The [default Helm chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app) +used in Auto Deploy [has support for running worker +processes](https://gitlab.com/gitlab-org/charts/auto-deploy-app/merge_requests/9). + +In order to run a worker, you'll need to ensure that it is able to respond to +the standard health checks, which expect a successful HTTP response on port +`5000`. For [Sidekiq](https://github.com/mperham/sidekiq), you could make use of +the [`sidekiq_alive` gem](https://rubygems.org/gems/sidekiq_alive) to do this. + +In order to work with Sidekiq, you'll also need to ensure your deployments have +access to a Redis instance. Auto DevOps won't deploy this for you so you'll +need to: + +- Maintain your own Redis instance. +- Set a CI variable `K8S_SECRET_REDIS_URL`, which the URL of this instance to + ensure it's passed into your deployments. + +Once you have configured your worker to respond to health checks, you will +need to configure a CI variable `HELM_UPGRADE_EXTRA_ARGS` with the value +`--values helm-values.yaml`. + +Then you can, for example, run a Sidekiq worker for your Rails application +by adding a file named `helm-values.yaml` to your repository with the following +content: + +```yml +workers: + sidekiq: + replicaCount: 1 + command: + - /bin/herokuish + - procfile + - exec + - sidekiq + preStopCommand: + - /bin/herokuish + - procfile + - exec + - sidekiqctl + - quiet + terminationGracePeriodSeconds: 60 +``` + ### Auto Monitoring See the [requirements](#requirements) for Auto Monitoring to enable this stage. @@ -646,6 +706,34 @@ will build a Docker image based on the Dockerfile rather than using buildpacks. This can be much faster and result in smaller images, especially if your Dockerfile is based on [Alpine](https://hub.docker.com/_/alpine/). +### Passing arguments to `docker build` + +Arguments can be passed to the `docker build` command using the +`AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` project variable. + +For example, to build a Docker image based on based on the `ruby:alpine` +instead of the default `ruby:latest`: + +1. Set `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` to `--build-arg=RUBY_VERSION=alpine`. +1. Add the following to a custom `Dockerfile`: + + ```docker + ARG RUBY_VERSION=latest + FROM ruby:$RUBY_VERSION + + # ... put your stuff here + ``` + +NOTE: **Note:** +Passing in complex values (newlines and spaces, for example) will likely +cause escaping issues due to the way this argument is used in Auto DevOps. +Consider using Base64 encoding of such values to avoid this problem. + +CAUTION: **Warning:** +Avoid passing secrets as Docker build arguments if possible, as they may be +persisted in your image. See +[this discussion](https://github.com/moby/moby/issues/13490) for details. + ### Custom Helm Chart Auto DevOps uses [Helm](https://helm.sh/) to deploy your application to Kubernetes. @@ -734,6 +822,7 @@ applications. |-----------------------------------------|------------------------------------| | `ADDITIONAL_HOSTS` | Fully qualified domain names specified as a comma-separated list that are added to the ingress hosts. | | `<ENVIRONMENT>_ADDITIONAL_HOSTS` | For a specific environment, the fully qualified domain names specified as a comma-separated list that are added to the ingress hosts. This takes precedence over `ADDITIONAL_HOSTS`. | +| `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` | Extra arguments to be passed to the `docker build` command. Note that using quotes will not prevent word splitting. [More details](#passing-arguments-to-docker-build). | | `AUTO_DEVOPS_CHART` | Helm Chart used to deploy your apps. Defaults to the one [provided by GitLab](https://gitlab.com/gitlab-org/charts/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`. | diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 7ab59b80374..35a5aff6a60 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -167,7 +167,7 @@ In the **test** stage, GitLab runs various checks on the application: - The `sast` job runs static analysis on the current code to check for potential security issues and is allowed to fail([Auto SAST](index.md#auto-sast-ultimate)) **(ULTIMATE)** - The `license_management` job searches the application's dependencies to determine each of their - licenses and is allowed to fail ([Auto License Management](index.md#auto-license-management-ultimate)) **(ULTIMATE)** + licenses and is allowed to fail ([Auto License Compliance](index.md#auto-license-compliance-ultimate)) **(ULTIMATE)** NOTE: **Note:** As you might have noticed, all jobs except `test` are allowed to fail in the diff --git a/doc/topics/git/partial_clone.md b/doc/topics/git/partial_clone.md index ea4223355d8..c9a5430b2c6 100644 --- a/doc/topics/git/partial_clone.md +++ b/doc/topics/git/partial_clone.md @@ -112,7 +112,7 @@ enabled on the Git server: git init # Add the remote - git remote add origin git@gitlab.com/example/jumbo-repo + git remote add origin <url> # Enable partial clone support for the remote git config --local extensions.partialClone origin diff --git a/doc/university/README.md b/doc/university/README.md index b17f40b91a5..25f77906e68 100644 --- a/doc/university/README.md +++ b/doc/university/README.md @@ -57,7 +57,7 @@ The GitLab University curriculum is composed of GitLab videos, screencasts, pres 1. [Migrating from SVN](../user/project/import/svn.md) 1. [Migrating from Fogbugz](../user/project/import/fogbugz.md) -### 1.6. GitLab Inc. +### 1.6. The GitLab team 1. [About GitLab](https://about.gitlab.com/about/) 1. [GitLab Direction](https://about.gitlab.com/direction/) diff --git a/doc/university/process/README.md b/doc/university/process/README.md index b278e02ccd5..1a555f065ed 100644 --- a/doc/university/process/README.md +++ b/doc/university/process/README.md @@ -2,10 +2,6 @@ comments: false --- ---- -title: University | Process ---- - # Suggesting improvements If you would like to teach a class or participate or help in any way please diff --git a/doc/university/training/gitlab_flow.md b/doc/university/training/gitlab_flow.md index 0ce92be4994..66e645a0af8 100644 --- a/doc/university/training/gitlab_flow.md +++ b/doc/university/training/gitlab_flow.md @@ -23,8 +23,6 @@ type: reference as opposed to individual stable branches - Consider creating a tag for each version that gets deployed -## Production branch -  ## Release branch @@ -36,8 +34,6 @@ type: reference - Cherry-pick critical bug fixes to stable branch for patch release - Never commit bug fixes directly to stable branch -## Release branch -  ## More details diff --git a/doc/university/training/topics/git_intro.md b/doc/university/training/topics/git_intro.md index 845bb7f0a81..c9a1cbb7839 100644 --- a/doc/university/training/topics/git_intro.md +++ b/doc/university/training/topics/git_intro.md @@ -15,7 +15,7 @@ comments: false - Adapts to nearly any workflow - Fast, reliable and stable file format -## Help! +## Help Use the tools at your disposal when you get stuck. diff --git a/doc/university/training/user_training.md b/doc/university/training/user_training.md index e440652edfc..37107e13584 100644 --- a/doc/university/training/user_training.md +++ b/doc/university/training/user_training.md @@ -23,7 +23,7 @@ type: reference - Adapts to nearly any workflow. - Fast, reliable and stable file format. -## Help! +## Help Use the tools at your disposal when you get stuck. diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md index 0506d992d4b..3c9fcbf7c7d 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -41,7 +41,7 @@ sudo -u git -H git checkout -- Gemfile.lock db/schema.rb locale sudo -u git -H git checkout LATEST_TAG -b LATEST_TAG ``` -### 3. Install libs, migrations, etc. +### 3. Install libs, migrations, etc ```bash cd /home/git/gitlab @@ -64,7 +64,7 @@ sudo -u git -H bundle exec rake gettext:po_to_json RAILS_ENV=production sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile cache:clear RAILS_ENV=production NODE_ENV=production NODE_OPTIONS="--max_old_space_size=4096" ``` -### 4. Update gitlab-workhorse to the corresponding version +### 4. Update GitLab Workhorse to the corresponding version ```bash cd /home/git/gitlab @@ -80,7 +80,7 @@ cd /home/git/gitlab sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,/home/git/repositories]" RAILS_ENV=production ``` -### 6. Update gitlab-shell to the corresponding version +### 6. Update GitLab Shell to the corresponding version ```bash cd /home/git/gitlab-shell @@ -90,7 +90,7 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -b v$(</h sudo -u git -H sh -c 'if [ -x bin/compile ]; then bin/compile; fi' ``` -### 7. Update gitlab-pages to the corresponding version (skip if not using pages) +### 7. Update GitLab Pages to the corresponding version (skip if not using pages) ```bash cd /home/git/gitlab-pages diff --git a/doc/update/upgrading_from_ce_to_ee.md b/doc/update/upgrading_from_ce_to_ee.md index bea5bcd9dd7..9ac73725f87 100644 --- a/doc/update/upgrading_from_ce_to_ee.md +++ b/doc/update/upgrading_from_ce_to_ee.md @@ -17,7 +17,7 @@ GitLab edition you are using (Community or Enterprise), see the This guide assumes you have a correctly configured and tested installation of GitLab Community Edition. If you run into any trouble or if you have any -questions please contact us at [support@gitlab.com]. +questions please contact us at `support@gitlab.com`. In all examples, replace `EE_BRANCH` with the Enterprise Edition branch for the version you are using, and `CE_BRANCH` with the Community Edition branch. @@ -54,7 +54,7 @@ sudo -u git -H git remote add -f ee https://gitlab.com/gitlab-org/gitlab-ee.git sudo -u git -H git checkout EE_BRANCH ``` -### 3. Install libs, migrations, etc. +### 3. Install libs, migrations, etc ```sh cd /home/git/gitlab @@ -131,5 +131,4 @@ Example: Additional instructions here. --> -[support@gitlab.com]: mailto:support@gitlab.com [old-ee-upgrade-docs]: https://gitlab.com/gitlab-org/gitlab-ee/tree/11-8-stable-ee/doc/update diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index df35638cba2..890a5ec8698 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -118,7 +118,7 @@ sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ rm go1.11.10.linux-amd64.tar.gz ``` -### 6. Update git +### 6. Update Git NOTE: **Note:** GitLab 11.11 and higher only supports Git 2.21.x and newer, and @@ -186,7 +186,7 @@ cd /home/git/gitlab sudo -u git -H git checkout BRANCH-ee ``` -### 8. Update gitlab-shell +### 8. Update GitLab Shell ```bash cd /home/git/gitlab-shell @@ -196,9 +196,9 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) sudo -u git -H bin/compile ``` -### 9. Update gitlab-workhorse +### 9. Update GitLab Workhorse -Install and compile gitlab-workhorse. GitLab-Workhorse uses +Install and compile GitLab Workhorse. GitLab Workhorse uses [GNU Make](https://www.gnu.org/software/make/). If you are not using Linux you may have to run `gmake` instead of `make` below. @@ -222,11 +222,11 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) sudo -u git -H make ``` -### 11. Update gitlab-pages +### 11. Update GitLab Pages #### Only needed if you use GitLab Pages -Install and compile gitlab-pages. GitLab-Pages uses +Install and compile GitLab Pages. GitLab Pages uses [GNU Make](https://www.gnu.org/software/make/). If you are not using Linux you may have to run `gmake` instead of `make` below. @@ -273,8 +273,8 @@ longer handles setting it. If you are using Apache instead of NGINX please see the updated [Apache templates]. Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. +will need to let GitLab Workhorse listen on a TCP port. You can do this +via [`/etc/default/gitlab`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/init.d/gitlab.default.example#L38). #### SMTP configuration @@ -313,7 +313,7 @@ For Ubuntu 16.04.1 LTS: sudo systemctl daemon-reload ``` -### 13. Install libs, migrations, etc. +### 13. Install libs, migrations, etc ```bash cd /home/git/gitlab @@ -404,4 +404,3 @@ If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of [gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/init.d/gitlab.default.example [smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/initializers/smtp_settings.rb.sample#L13 [Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/init.d/gitlab.default.example#L38 diff --git a/doc/update/upgrading_postgresql_using_slony.md b/doc/update/upgrading_postgresql_using_slony.md index 835166837a8..cf3a389b149 100644 --- a/doc/update/upgrading_postgresql_using_slony.md +++ b/doc/update/upgrading_postgresql_using_slony.md @@ -77,7 +77,7 @@ make make install ``` -This assumes you have installed GitLab into /opt/gitlab. +This assumes you have installed GitLab into `/opt/gitlab`. To test if Slony is installed properly, run the following commands: diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md index 0c5d2f81e25..cd8dc7bcbf6 100644 --- a/doc/user/admin_area/abuse_reports.md +++ b/doc/user/admin_area/abuse_reports.md @@ -2,7 +2,7 @@ type: reference, howto --- -# Abuse reports +# Abuse reports **(CORE ONLY)** View and resolve abuse reports from GitLab users. diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 01b6558bdbe..b0491499f88 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -2,7 +2,7 @@ type: reference, howto --- -# Broadcast Messages +# Broadcast Messages **(CORE ONLY)** GitLab can display messages to all users of a GitLab instance in a banner that appears in the UI. diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index 4063c40a751..9fe4b50a991 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.md @@ -2,7 +2,7 @@ type: reference --- -# Diff limits administration +# Diff limits administration **(CORE ONLY)** You can set a maximum size for display of diff files (patches). diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index f5864e1f828..dbcf250bc57 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -117,4 +117,4 @@ questions that you know someone might ask. Each scenario can be a third-level heading, e.g. `### Getting error message X`. If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. -->
\ No newline at end of file +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 35e7b6fb541..52f24c602df 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -2,7 +2,7 @@ type: concepts, howto --- -# Health Check +# Health Check **(CORE ONLY)** > - Liveness and readiness probes were [introduced][ce-10416] in GitLab 9.1. > - The `health_check` endpoint was [introduced][ce-3888] in GitLab 8.8 and was @@ -21,28 +21,63 @@ traffic until the system is ready or restart the container as needed. To access monitoring resources, the requesting client IP needs to be included in a whitelist. For details, see [how to add IPs to a whitelist for the monitoring endpoints](../../../administration/monitoring/ip_whitelist.md). -## Using the endpoints +## Using the endpoints locally With default whitelist settings, the probes can be accessed from localhost using the following URLs: -- `http://localhost/-/health` -- `http://localhost/-/readiness` -- `http://localhost/-/liveness` +```text +GET http://localhost/-/health +``` + +```text +GET http://localhost/-/readiness +``` + +```text +GET http://localhost/-/liveness +``` + +## Health -The first endpoint, `health`, only checks whether the application server is running. It does not verify the database or other services are running. A successful response will return a 200 status code with the following message: +Checks whether the application server is running. It does not verify the database or other services are running. + +```text +GET /-/health +``` + +Example request: + +```sh +curl 'https://gitlab.example.com/-/health' +``` + +Example response: ```text GitLab OK ``` -The readiness and liveness probes will provide a report of system health in JSON format. +## Readiness + +The readiness probe checks whether the Gitlab instance is ready to use. It checks the dependent services (Database, Redis, Gitaly etc.) and gives a status for each. + +```text +GET /-/readiness +``` + +Example request: -`readiness` probe example output: +```sh +curl 'https://gitlab.example.com/-/readiness' +``` + +Example response: ```json { "db_check":{ - "status":"ok" + "status":"failed", + "message": "unexpected Db check result: 0" }, "redis_check":{ "status":"ok" @@ -65,7 +100,23 @@ The readiness and liveness probes will provide a report of system health in JSON } ``` -`liveness` probe example output: +## Liveness + +The liveness probe checks whether the application server is alive. Unlike the [`health`](#health) check, this check hits the database. + +```text +GET /-/liveness +``` + +Example request: + +```sh +curl 'https://gitlab.example.com/-/liveness' +``` + +Example response: + +On success, the endpoint will return a valid successful HTTP status code, and a response like below. ```json { @@ -90,10 +141,7 @@ The readiness and liveness probes will provide a report of system health in JSON } ``` -## Status - -On failure, the endpoint will return a `500` HTTP status code. On success, the endpoint -will return a valid successful HTTP status code, and a `success` message. +On failure, the endpoint will return a `500` HTTP status code. ## Access token (Deprecated) diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 6faab685b26..5e385b7216d 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -2,7 +2,7 @@ type: reference --- -# Account and limit settings +# Account and limit settings **(CORE ONLY)** ## Max attachment size diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index bd76b052422..fa14ecdf7cb 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -127,7 +127,7 @@ but commented out to help encourage others to add to it in the future. --> GitLab administrators can force a pipeline configuration to run on every pipeline. -The configuration applies to all pipelines for a GitLab instance and is +The configuration applies to all pipelines for a GitLab instance and is sourced from: - The [instance template repository](instance_template_repository.md). diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 490163c1816..ddf989d0181 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -2,7 +2,7 @@ type: reference --- -# Email +# Email **(CORE ONLY)** You can customize some of the content in emails sent from your GitLab instance. 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 b2d56be154b..6d2f74af660 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 @@ -6,10 +6,10 @@ type: reference > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30829) in GitLab 12.2. -This setting allows you to rate limit the requests to raw endpoints, defaults to `300` requests per minute. +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 > Network > Performance Optimization**. -For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/controllers/application_controller.rb` will be blocked. +For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/controllers/application_controller.rb` will be blocked. Access to the raw file will be released after 1 minute.  @@ -18,3 +18,5 @@ This limit is: - Applied independently per project, per commit and per file path. - Not applied per IP address. - Active by default. To disable, set the option to `0`. + +Requests over the rate limit are logged into `auth.log`. diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index 1b1bcbcd6e8..aea717e806d 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -2,7 +2,7 @@ type: reference --- -# Sign-up restrictions +# Sign-up restrictions **(CORE ONLY)** You can use sign-up restrictions to require user email confirmation, as well as to blacklist or whitelist email addresses belonging to specific domains. diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index a1bce5a6c69..0b5f9a13b03 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -2,10 +2,9 @@ type: reference --- -# Enforce accepting Terms of Service +# Enforce accepting Terms of Service **(CORE ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18570) -> in [GitLab Core](https://about.gitlab.com/pricing/) 10.8 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18570) in [GitLab Core](https://about.gitlab.com/pricing/) 10.8. An admin can enforce acceptance of a terms of service and privacy policy. When this option is enabled, new and existing users must accept the terms. diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index d3c9cf7d8ff..50dea8f50a2 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -2,10 +2,9 @@ type: reference --- -# Third party offers +# Third party offers **(CORE ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/20379) -> in [GitLab Core](https://about.gitlab.com/pricing/) 11.1 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/20379) in [GitLab Core](https://about.gitlab.com/pricing/) 11.1. Within GitLab, we inform users of available third-party offers they might find valuable in order to enhance the development of their projects. An example is the Google Cloud Platform free credit diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 516600c9d99..efac7e699f3 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -2,7 +2,7 @@ type: reference --- -# Usage statistics +# Usage statistics **(CORE ONLY)** GitLab Inc. will periodically collect information about your instance in order to perform various actions. 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 e3a495750f2..b9d93bf3671 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 @@ -2,7 +2,7 @@ type: reference --- -# User and IP rate limits +# User and IP rate limits **(CORE ONLY)** Rate limiting is a common technique used to improve the security and durability of a web application. For more details, see diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index bf59f49b993..1e2f5705728 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -2,7 +2,7 @@ type: reference --- -# Visibility and access controls +# Visibility and access controls **(CORE ONLY)** GitLab allows administrators to: diff --git a/doc/user/analytics/cycle_analytics.md b/doc/user/analytics/cycle_analytics.md new file mode 100644 index 00000000000..b7389c8689d --- /dev/null +++ b/doc/user/analytics/cycle_analytics.md @@ -0,0 +1,182 @@ +# Cycle Analytics + +> - Introduced prior to GitLab 12.2 at the project level. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12077) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2 at the group level (enabled by feature flag `analytics`). + +Cycle Analytics measures the time spent to go from an [idea to production] - also known +as cycle time - for each of your projects. Cycle Analytics displays the median time for an idea to +reach production, along with the time typically spent in each DevOps stage along the way. + +Cycle Analytics is useful in order to quickly determine the velocity of a given +project. It points to bottlenecks in the development process, enabling management +to uncover, triage, and identify the root cause of slowdowns in the software development life cycle. + +Cycle Analytics is tightly coupled with the [GitLab flow] and +calculates a separate median for each stage. + +## Overview + +Cycle Analytics is available: + +- From GitLab 12.2, at the group level in the analytics workspace at + **Analytics > Cycle Analytics**. **(PREMIUM)** + + In the future, multiple groups will be selectable which will effectively make this an + instance-level feature. + + NOTE: **Note:** + Requires the [analytics workspace](index.md) to be enabled. + +- At the project level via **Project > Cycle Analytics**. + +There are seven stages that are tracked as part of the Cycle Analytics calculations. + +- **Issue** (Tracker) + - Time to schedule an issue (by milestone or by adding it to an issue board) +- **Plan** (Board) + - Time to first commit +- **Code** (IDE) + - Time to create a merge request +- **Test** (CI) + - Time it takes GitLab CI/CD to test your code +- **Review** (Merge Request/MR) + - Time spent on code review +- **Staging** (Continuous Deployment) + - Time between merging and deploying to production +- **Production** (Total) + - Total lifecycle time; i.e. the velocity of the project or team + +## How the data is measured + +Cycle Analytics records cycle time and data based on the project issues with the +exception of the staging and production stages, where only data deployed to +production are measured. + +Specifically, if your CI is not set up and you have not defined a `production` +or `production/*` [environment], then you will not have any data for those stages. + +Each stage of Cycle Analytics is further described in the table below. + +| **Stage** | **Description** | +| --------- | --------------- | +| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label will be tracked only if it already has an [Issue Board list](../project/issue_board.md#creating-a-new-list) created for it. | +| Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (e.g., `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. | +| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the issue closing pattern is not present in the merge request description, the MR is not considered to the measurement time of the stage. | +| Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | +| Review | Measures the median time taken to review the merge request that has closing issue pattern, between its creation and until it's merged. | +| Staging | Measures the median time between merging the merge request with closing issue pattern until the very first deployment to production. It's tracked by the [environment] set to `production` or matching `production/*` (case-sensitive, `Production` won't work) in your GitLab CI configuration. If there isn't a production environment, this is not tracked. | +| Production| The sum of all time (medians) taken to run the entire process, from issue creation to deploying the code to production. | + +--- + +How this works, behind the scenes: + +1. Issues and merge requests are grouped together in pairs, such that for each + `<issue, merge request>` pair, the merge request has the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) + for the corresponding issue. All other issues and merge requests are **not** + considered. +1. Then the `<issue, merge request>` pairs are filtered out by last XX days (specified + by the UI - default is 90 days). So it prohibits these pairs from being considered. +1. For the remaining `<issue, merge request>` pairs, we check the information that + we need for the stages, like issue creation date, merge request merge time, + etc. + +To sum up, anything that doesn't follow [GitLab flow] will not be tracked and the +Cycle Analytics dashboard will not present any data for: + +- merge requests that do not close an issue. +- issues not labeled with a label present in the Issue Board or for issues not assigned a milestone. +- staging and production stages, if the project has no `production` or `production/*` + environment. + +## Example workflow + +Below is a simple fictional workflow of a single cycle that happens in a +single day passing through all seven stages. Note that if a stage does not have +a start and a stop mark, it is not measured and hence not calculated in the median +time. It is assumed that milestones are created and CI for testing and setting +environments is configured. + +1. Issue is created at 09:00 (start of **Issue** stage). +1. Issue is added to a milestone at 11:00 (stop of **Issue** stage / start of + **Plan** stage). +1. Start working on the issue, create a branch locally and make one commit at + 12:00. +1. Make a second commit to the branch which mentions the issue number at 12.30 + (stop of **Plan** stage / start of **Code** stage). +1. Push branch and create a merge request that contains the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) + in its description at 14:00 (stop of **Code** stage / start of **Test** and + **Review** stages). +1. The CI starts running your scripts defined in [`.gitlab-ci.yml`][yml] and + takes 5min (stop of **Test** stage). +1. Review merge request, ensure that everything is OK and merge the merge + request at 19:00. (stop of **Review** stage / start of **Staging** stage). +1. Now that the merge request is merged, a deployment to the `production` + environment starts and finishes at 19:30 (stop of **Staging** stage). +1. The cycle completes and the sum of the median times of the previous stages + is recorded to the **Production** stage. That is the time between creating an + issue and deploying its relevant merge request to production. + +From the above example you can conclude the time it took each stage to complete +as long as their total time: + +- **Issue**: 2h (11:00 - 09:00) +- **Plan**: 1h (12:00 - 11:00) +- **Code**: 2h (14:00 - 12:00) +- **Test**: 5min +- **Review**: 5h (19:00 - 14:00) +- **Staging**: 30min (19:30 - 19:00) +- **Production**: Since this stage measures the sum of median time off all + previous stages, we cannot calculate it if we don't know the status of the + stages before. In case this is the very first cycle that is run in the project, + then the **Production** time is 10h 30min (19:30 - 09:00) + +A few notes: + +- In the above example we demonstrated that it doesn't matter if your first + commit doesn't mention the issue number, you can do this later in any commit + of the branch you are working on. +- You can see that the **Test** stage is not calculated to the overall time of + the cycle since it is included in the **Review** process (every MR should be + tested). +- The example above was just **one cycle** of the seven stages. Add multiple + cycles, calculate their median time and the result is what the dashboard of + Cycle Analytics is showing. + +## Permissions + +The current permissions on the Project Cycle Analytics dashboard are: + +- Public projects - anyone can access +- Internal projects - any authenticated user can access +- Private projects - any member Guest and above can access + +You can [read more about permissions][permissions] in general. + +NOTE: **Note:** +As of GitLab 12.2, the project-level page is deprecated. You should access +project-level Cycle Analytics from **Analytics > Cycle Analytics** in the top +navigation bar. We will ensure that the same project-level functionality is available +to CE users in the new analytics space. + +For Cycle Analytics functionality introduced in GitLab 12.2 and later: + +- Users must have Reporter access or above. +- Features are available only on + [Premium or Silver tiers](https://about.gitlab.com/pricing/) and above. + +## More resources + +Learn more about Cycle Analytics in the following resources: + +- [Cycle Analytics feature page](https://about.gitlab.com/features/cycle-analytics/) +- [Cycle Analytics feature preview](https://about.gitlab.com/2016/09/16/feature-preview-introducing-cycle-analytics/) +- [Cycle Analytics feature highlight](https://about.gitlab.com/2016/09/21/cycle-analytics-feature-highlight/) + +[ce-5986]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5986 +[ce-20975]: https://gitlab.com/gitlab-org/gitlab-ce/issues/20975 +[environment]: ../../ci/yaml/README.md#environment +[GitLab flow]: ../../workflow/gitlab_flow.md +[idea to production]: https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab +[permissions]: ../permissions.md +[yml]: ../../ci/yaml/README.md diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md new file mode 100644 index 00000000000..ec719c0b4a1 --- /dev/null +++ b/doc/user/analytics/index.md @@ -0,0 +1,22 @@ +# Analytics workspace + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12077) in GitLab 12.2 (enabled using `analytics` feature flag). + +The Analytics workspace will make it possible to aggregate analytics across +GitLab, so that users can view information across multiple projects and groups +in one place. + +To access the centralized analytics workspace: + +1. Ensure it's enabled. Requires a GitLab administrator to enable it with the `analytics` feature + flag. +1. Once enabled, click on **Analytics** from the top navigation bar. + +## Available analytics + +From the centralized analytics workspace, the following analytics are available: + +- [Cycle Analytics](cycle_analytics.md). + +NOTE: **Note:** +Project-level Cycle Analytics are still available at a project's **Project > Cycle Analytics**. diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 86491c7d74e..a030f8d96ef 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -94,6 +94,36 @@ If you want to whitelist some specific vulnerabilities, you can do so by definin them in a YAML file named `clair-whitelist.yml`. Read more in the [Clair documentation](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file). +## Example + +The following is a sample `.gitlab-ci.yml` that will build your Docker Image, push it to the container registry and run Container Scanning. + +```yaml +variables: + DOCKER_DRIVER: overlay2 + +services: + - docker:stable-dind + +stages: + - build + - test + +include: + - template: Container-Scanning.gitlab-ci.yml + +build: + image: docker:stable + stage: build + variables: + IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA + script: + - docker info + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + - docker build -t $IMAGE . + - docker push $IMAGE +``` + ## Security Dashboard The Security Dashboard is a good place to get an overview of all the security diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 3148ec63c79..b40392e12d5 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -141,22 +141,22 @@ dependency_scanning: Dependency Scanning can be [configured](#customizing-the-dependency-scanning-settings) using environment variables. -| Environment variable | Function | -|-------------------------------- |----------| -| `DS_ANALYZER_IMAGES` | Comma separated list of custom images. The official default images are still enabled. Read more about [customizing analyzers](analyzers.md). | -| `DS_ANALYZER_IMAGE_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | -| `DS_ANALYZER_IMAGE_TAG` | Override the Docker tag of the official default images. Read more about [customizing analyzers](analyzers.md). | -| `DS_PYTHON_VERSION` | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12296) in GitLab 12.1)| -| `DS_PIP_DEPENDENCY_PATH` | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12412) in GitLab 12.2) | -| `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | -| `DS_DISABLE_REMOTE_CHECKS` | Do not send any data to GitLab. Used in the [Gemnasium analyzer](#remote-checks). | -| `DS_PULL_ANALYZER_IMAGES` | Pull the images from the Docker registry (set to `0` to disable). | -| `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, file or folder paths. Parent directories will also match patterns. | -| `DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | -| `DS_PULL_ANALYZER_IMAGE_TIMEOUT` | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | -| `DS_RUN_ANALYZER_TIMEOUT` | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | -| `PIP_INDEX_URL` | Base URL of Python Package Index (default `https://pypi.org/simple`). | -| `PIP_EXTRA_INDEX_URL` | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma separated. | +| Environment variable | Description | Example usage | +|-------------------------------- |-------------| | +| `DS_ANALYZER_IMAGES` | Comma separated list of custom images. The official default images are still enabled. Read more about [customizing analyzers](analyzers.md). | | +| `DS_ANALYZER_IMAGE_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | | +| `DS_ANALYZER_IMAGE_TAG` | Override the Docker tag of the official default images. Read more about [customizing analyzers](analyzers.md). | | +| `DS_PYTHON_VERSION` | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12296) in GitLab 12.1)| | +| `DS_PIP_DEPENDENCY_PATH` | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12412) in GitLab 12.2) | | +| `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | | +| `DS_DISABLE_REMOTE_CHECKS` | Do not send any data to GitLab. Used in the [Gemnasium analyzer](#remote-checks). | | +| `DS_PULL_ANALYZER_IMAGES` | Pull the images from the Docker registry (set to `0` to disable). | | +| `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, file or folder paths. Parent directories will also match patterns. | `DS_EXCLUDED_PATHS=doc,spec` | +| `DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | | +| `DS_PULL_ANALYZER_IMAGE_TIMEOUT` | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | | +| `DS_RUN_ANALYZER_TIMEOUT` | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | | +| `PIP_INDEX_URL` | Base URL of Python Package Index (default `https://pypi.org/simple`). | | +| `PIP_EXTRA_INDEX_URL` | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma separated. | | ## Reports JSON format @@ -276,8 +276,8 @@ it highlighted: Here is the description of the report file structure nodes and their meaning. All fields are mandatory to be present in the report JSON unless stated otherwise. Presence of optional fields depends on the underlying analyzers being used. -| Report JSON node | Function | -|------------------------------------------------------|----------| +| Report JSON node | Description | +|------------------------------------------------------|-------------| | `version` | Report syntax version used to generate this JSON. | | `vulnerabilities` | Array of vulnerability objects. | | `vulnerabilities[].category` | Where this vulnerability belongs (SAST, Dependency Scanning etc.). For Dependency Scanning, it will always be `dependency_scanning`. | diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 83ea0ea3386..5a1cc0561fc 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -28,7 +28,7 @@ GitLab can scan and report any vulnerabilities found in your project. | [Dependency List](dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. | | [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | | [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | -| [License Management](license_management/index.md) **(ULTIMATE)** | Search your project's dependencies for their licenses. | +| [License Compliance](license_management/index.md) **(ULTIMATE)** | Search your project's dependencies for their licenses. | | [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)** | View vulnerabilities in all your projects and groups. | | [Static Application Security Testing (SAST)](sast/index.md) **(ULTIMATE)** | Analyze source code for known vulnerabilities. | @@ -153,7 +153,7 @@ Clicking on this button will create a merge request to apply the solution onto t > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing) 12.2. -Merge Request Approvals can be configured to require approval from a member +Merge Request Approvals can be configured to require approval from a member of your security team when a vulnerability would be introduced by a merge request. This threshold is defined as `high`, `critical`, or `unknown` diff --git a/doc/user/application_security/license_management/img/license_management.png b/doc/user/application_security/license_compliance/img/license_compliance.png Binary files differindex cdce6b5fe38..cdce6b5fe38 100644 --- a/doc/user/application_security/license_management/img/license_management.png +++ b/doc/user/application_security/license_compliance/img/license_compliance.png diff --git a/doc/user/application_security/license_management/img/license_management_add_license.png b/doc/user/application_security/license_compliance/img/license_compliance_add_license.png Binary files differindex c9a5dc14c57..c9a5dc14c57 100644 --- a/doc/user/application_security/license_management/img/license_management_add_license.png +++ b/doc/user/application_security/license_compliance/img/license_compliance_add_license.png diff --git a/doc/user/application_security/license_management/img/license_management_decision.png b/doc/user/application_security/license_compliance/img/license_compliance_decision.png Binary files differindex fbf90bec7fd..fbf90bec7fd 100644 --- a/doc/user/application_security/license_management/img/license_management_decision.png +++ b/doc/user/application_security/license_compliance/img/license_compliance_decision.png diff --git a/doc/user/application_security/license_management/img/license_management_pipeline_tab.png b/doc/user/application_security/license_compliance/img/license_compliance_pipeline_tab.png Binary files differindex 80ffca815b9..80ffca815b9 100644 --- a/doc/user/application_security/license_management/img/license_management_pipeline_tab.png +++ b/doc/user/application_security/license_compliance/img/license_compliance_pipeline_tab.png diff --git a/doc/user/application_security/license_management/img/license_management_search.png b/doc/user/application_security/license_compliance/img/license_compliance_search.png Binary files differindex b3ffd8d95a1..b3ffd8d95a1 100644 --- a/doc/user/application_security/license_management/img/license_management_search.png +++ b/doc/user/application_security/license_compliance/img/license_compliance_search.png diff --git a/doc/user/application_security/license_management/img/license_management_settings.png b/doc/user/application_security/license_compliance/img/license_compliance_settings.png Binary files differindex 2e3e8888e93..2e3e8888e93 100644 --- a/doc/user/application_security/license_management/img/license_management_settings.png +++ b/doc/user/application_security/license_compliance/img/license_compliance_settings.png diff --git a/doc/user/application_security/license_compliance/index.md b/doc/user/application_security/license_compliance/index.md new file mode 100644 index 00000000000..f74b958cf67 --- /dev/null +++ b/doc/user/application_security/license_compliance/index.md @@ -0,0 +1,243 @@ +--- +type: reference, howto +--- + +# License Compliance **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5483) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. + +## Overview + +If you are using [GitLab CI/CD](../../../ci/README.md), you can search your project dependencies for their licenses +using License Compliance. + +You can take advantage of License Compliance by either [including the job](#configuration) +in your existing `.gitlab-ci.yml` file or by implicitly using +[Auto License Compliance](../../../topics/autodevops/index.md#auto-license-compliance-ultimate) +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. +Blacklisted licenses will be clearly visible with an `x` red icon next to them +as well as new licenses which need a decision from you. In addition, you can +[manually approve or blacklist](#project-policies-for-license-compliance) +licenses in your project's settings. + +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 +`license_management` 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. + + + +If you are a project or group Maintainer, you can click on a license to be given +the choice to approve it or blacklist it. + + + +## Use cases + +It helps you find what licenses your project uses in its dependencies, and decide for each of then +whether to allow it or forbid it. For example, your application is using an external (open source) +library whose license is incompatible with yours. + +## Supported languages and package managers + +The following languages and package managers are supported. + +| Language | Package managers | Scan Tool | +|------------|-------------------------------------------------------------------|----------------------------------------------------------| +| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Go | [Godep](https://github.com/tools/godep), go get ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), gvt ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), glide ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), dep ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), trash ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) and govendor ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), [go mod](https://github.com/golang/go/wiki/Modules) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| .NET | [Nuget](https://www.nuget.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Python | [pip](https://pip.pypa.io/en/stable/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Ruby | [gem](https://rubygems.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Erlang | [rebar](https://www.rebar3.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| +| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage) , [CocoaPods v0.39 and below](https://cocoapods.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Elixir | [mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| C++/C | [conan](https://conan.io/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| +| Scala | [sbt](https://www.scala-sbt.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| +| Rust | [cargo](https://crates.io/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| +| PHP | [composer](https://getcomposer.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| + +## Requirements + +To run a License Compliance scanning job, you need GitLab Runner with the +[`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). + +## Configuration + +For GitLab 11.9 and later, to enable License Compliance, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`License-Management.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml) +that's provided as a part of your GitLab installation. +For GitLab versions earlier than 11.9, you can copy and use the job as defined +that template. + +Add the following to your `.gitlab-ci.yml` file: + +```yaml +include: + template: License-Management.gitlab-ci.yml +``` + +The included template will create a `license_management` job in your CI/CD pipeline +and scan your dependencies to find their licenses. + +The results will be saved as a +[License Compliance report artifact](../../../ci/yaml/README.md#artifactsreportslicense_management-ultimate) +that you can later download and analyze. Due to implementation limitations, we +always take the latest License Compliance artifact available. Behind the scenes, the +[GitLab License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/license-management) +is used to detect the languages/frameworks and in turn analyzes the licenses. + +The License Compliance settings can be changed through environment variables by using the +[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. These variables are documented in the [License Compliance documentation](https://gitlab.com/gitlab-org/security-products/license-management#settings). + +### Installing custom dependencies + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. + +The `license_management` image already embeds many auto-detection scripts, languages, +and packages. Nevertheless, it's almost impossible to cover all cases for all projects. +That's why sometimes it's necessary to install extra packages, or to have extra steps +in the project automated setup, like the download and installation of a certificate. +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 +of your application (e.g.: for a project with a `Gemfile`, the setup step could be +`bundle install`). + +For example: + +```yaml +include: + template: License-Management.gitlab-ci.yml + +variables: + LICENSE_MANAGEMENT_SETUP_CMD: sh my-custom-install-script.sh +``` + +In this example, `my-custom-install-script.sh` is a shell script at the root +directory of your project. + +### Overriding the template + +If you want to override the job definition (for example, change properties like +`variables` or `dependencies`), you need to declare a `license_management` job +after the template inclusion and specify any additional keys under it. For example: + +```yaml +include: + template: License-Management.gitlab-ci.yml + +license_management: + variables: + CI_DEBUG_TRACE: "true" +``` + +### Configuring Maven projects + +The License Compliance tool provides a `MAVEN_CLI_OPTS` environment variable which can hold +the command line arguments to pass to the `mvn install` command which is executed under the hood. +Feel free to use it for the customization of Maven execution. For example: + +```yaml +include: + template: License-Management.gitlab-ci.yml + +license_management: + variables: + MAVEN_CLI_OPTS: --debug +``` + +`mvn install` runs through all of the [build life cycle](http://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html) +stages prior to `install`, including `test`. Running unit tests is not directly +necessary for the license scanning purposes and consumes time, so it's skipped +by having the default value of `MAVEN_CLI_OPTS` as `-DskipTests`. If you want +to supply custom `MAVEN_CLI_OPTS` and skip tests at the same time, don't forget +to explicitly add `-DskipTests` to your options. +If you still need to run tests during `mvn install`, add `-DskipTests=false` to +`MAVEN_CLI_OPTS`. + +### Selecting the version of Python + +> - [Introduced](https://gitlab.com/gitlab-org/security-products/license-management/merge_requests/36) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> - In GitLab 12.2, Python 3.5 became the default. + +License Compliance uses Python 3.5 and pip 19.1 by default. +If your project requires Python 2, you can switch to Python 2.7 and pip 10.0 +by setting the `LM_PYTHON_VERSION` environment variable to `2`. + +```yaml +include: + template: License-Management.gitlab-ci.yml + +license_management: + variables: + LM_PYTHON_VERSION: 2 +``` + +## Project policies for License Compliance + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5940) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. + +From the project's settings: + +- The list of licenses and their status can be managed. +- Licenses can be manually approved or blacklisted. + +To approve or blacklist a license: + +1. Either use the **Manage licenses** button in the merge request widget, or + navigate to the project's **Settings > CI/CD** and expand the + **License Compliance** section. +1. Click the **Add a license** button. + +  + +1. In the **License name** dropdown, either: + - Select one of the available licenses. You can search for licenses in the field + at the top of the list. + - Enter arbitrary text in the field at the top of the list. This will cause the text to be + added as a license name to the list. +1. Select the **Approve** or **Blacklist** radio button to approve or blacklist respectively + the selected license. + +To modify an existing license: + +1. In the **License Compliance** list, click the **Approved/Declined** dropdown to change it to the desired status. + +  + +Searching for Licenses: + +1. Use the **Search** box to search for a specific license. + +  + +## License Compliance report under pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5491) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2. + +From your project's left sidebar, navigate to **CI/CD > Pipelines** and click on the +pipeline ID that has a `license_management` job to see the Licenses tab with the listed +licenses (if any). + + + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/application_security/license_management/index.md b/doc/user/application_security/license_management/index.md index c324848c703..319da2c3a6e 100644 --- a/doc/user/application_security/license_management/index.md +++ b/doc/user/application_security/license_management/index.md @@ -1,245 +1,5 @@ --- -type: reference, howto +redirect_to: ../license_compliance/index.md --- -# License Management **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5483) -in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. - -## Overview - -If you are using [GitLab CI/CD](../../../ci/README.md), you can search your project dependencies for their licenses -using License Management. - -You can take advantage of License Management by either [including the job](#configuration) -in your existing `.gitlab-ci.yml` file or by implicitly using -[Auto License Management](../../../topics/autodevops/index.md#auto-license-management-ultimate) -that is provided by [Auto DevOps](../../../topics/autodevops/index.md). - -GitLab checks the License Management report, compares the licenses between the -source and target branches, and shows the information right on the merge request. -Blacklisted licenses will be clearly visible with an `x` red icon next to them -as well as new licenses which need a decision from you. In addition, you can -[manually approve or blacklist](#project-policies-for-license-management) -licenses in your project's settings. - -NOTE: **Note:** -If the license management 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 -`license_management` job in your `.gitlab-ci.yml` for the first time. -Consecutive merge requests will have something to compare to and the license -management report will be shown properly. - - - -If you are a project or group Maintainer, you can click on a license to be given -the choice to approve it or blacklist it. - - - -## Use cases - -It helps you find what licenses your project uses in its dependencies, and decide for each of then -whether to allow it or forbid it. For example, your application is using an external (open source) -library whose license is incompatible with yours. - -## Supported languages and package managers - -The following languages and package managers are supported. - -| Language | Package managers | Scan Tool | -|------------|-------------------------------------------------------------------|----------------------------------------------------------| -| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Go | [Godep](https://github.com/tools/godep), go get ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), gvt ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), glide ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), dep ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), trash ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) and govendor ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), [go mod](https://github.com/golang/go/wiki/Modules) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| .NET | [Nuget](https://www.nuget.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Python | [pip](https://pip.pypa.io/en/stable/) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Ruby | [gem](https://rubygems.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Erlang | [rebar](https://www.rebar3.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| -| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage) , [CocoaPods v0.39 and below](https://cocoapods.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Elixir | [mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| C++/C | [conan](https://conan.io/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| -| Scala | [sbt](https://www.scala-sbt.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| -| Rust | [cargo](https://crates.io/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| -| PHP | [composer](https://getcomposer.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| - -## Requirements - -To run a License Management scanning job, you need GitLab Runner with the -[`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). - -## Configuration - -For GitLab 11.9 and later, to enable License Management, you must -[include](../../../ci/yaml/README.md#includetemplate) the -[`License-Management.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml) -that's provided as a part of your GitLab installation. -For GitLab versions earlier than 11.9, you can copy and use the job as defined -that template. - -Add the following to your `.gitlab-ci.yml` file: - -```yaml -include: - template: License-Management.gitlab-ci.yml -``` - -The included template will create a `license_management` job in your CI/CD pipeline -and scan your dependencies to find their licenses. - -The results will be saved as a -[License Management report artifact](../../../ci/yaml/README.md#artifactsreportslicense_management-ultimate) -that you can later download and analyze. Due to implementation limitations, we -always take the latest License Management artifact available. Behind the scenes, the -[GitLab License Management Docker image](https://gitlab.com/gitlab-org/security-products/license-management) -is used to detect the languages/frameworks and in turn analyzes the licenses. - -The License Management settings can be changed through environment variables by using the -[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. These variables are documented in the [License Management documentation](https://gitlab.com/gitlab-org/security-products/license-management#settings). - -### Installing custom dependencies - -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. - -The `license_management` image already embeds many auto-detection scripts, languages, -and packages. Nevertheless, it's almost impossible to cover all cases for all projects. -That's why sometimes it's necessary to install extra packages, or to have extra steps -in the project automated setup, like the download and installation of a certificate. -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 -of your application (e.g.: for a project with a `Gemfile`, the setup step could be -`bundle install`). - -For example: - -```yaml -include: - template: License-Management.gitlab-ci.yml - -variables: - LICENSE_MANAGEMENT_SETUP_CMD: sh my-custom-install-script.sh -``` - -In this example, `my-custom-install-script.sh` is a shell script at the root -directory of your project. - -### Overriding the template - -If you want to override the job definition (for example, change properties like -`variables` or `dependencies`), you need to declare a `license_management` job -after the template inclusion and specify any additional keys under it. For example: - -```yaml -include: - template: License-Management.gitlab-ci.yml - -license_management: - variables: - CI_DEBUG_TRACE: "true" -``` - -### Configuring Maven projects - -The License Management tool provides a `MAVEN_CLI_OPTS` environment variable which can hold -the command line arguments to pass to the `mvn install` command which is executed under the hood. -Feel free to use it for the customization of Maven execution. For example: - -```yaml -include: - template: License-Management.gitlab-ci.yml - -license_management: - variables: - MAVEN_CLI_OPTS: --debug -``` - -`mvn install` runs through all of the [build life cycle](http://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html) -stages prior to `install`, including `test`. Running unit tests is not directly -necessary for the license scanning purposes and consumes time, so it's skipped -by having the default value of `MAVEN_CLI_OPTS` as `-DskipTests`. If you want -to supply custom `MAVEN_CLI_OPTS` and skip tests at the same time, don't forget -to explicitly add `-DskipTests` to your options. -If you still need to run tests during `mvn install`, add `-DskipTests=false` to -`MAVEN_CLI_OPTS`. - -### Selecting the version of Python - -> [Introduced](https://gitlab.com/gitlab-org/security-products/license-management/merge_requests/36) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. - -License Management uses Python 2.7 and pip 10.0 by default. -If your project requires Python 3, you can switch to Python 3.5 and pip 19.1 -by setting the `LM_PYTHON_VERSION` environment variable to `3`. - -```yaml -include: - template: License-Management.gitlab-ci.yml - -license_management: - variables: - LM_PYTHON_VERSION: 3 -``` - -## Project policies for License Management - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5940) -in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. - -From the project's settings: - -- The list of licenses and their status can be managed. -- Licenses can be manually approved or blacklisted. - -To approve or blacklist a license: - -1. Either use the **Manage licenses** button in the merge request widget, or - navigate to the project's **Settings > CI/CD** and expand the - **License Management** section. -1. Click the **Add a license** button. - -  - -1. In the **License name** dropdown, either: - - Select one of the available licenses. You can search for licenses in the field - at the top of the list. - - Enter arbitrary text in the field at the top of the list. This will cause the text to be - added as a license name to the list. -1. Select the **Approve** or **Blacklist** radio button to approve or blacklist respectively - the selected license. - -To modify an existing license: - -1. In the **License Management** list, click the **Approved/Declined** dropdown to change it to the desired status. - -  - -Searching for Licenses: - -1. Use the **Search** box to search for a specific license. - -  - -## License Management report under pipelines - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5491) -in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2. - -From your project's left sidebar, navigate to **CI/CD > Pipelines** and click on the -pipeline ID that has a `license_management` job to see the Licenses tab with the listed -licenses (if any). - - - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +This document was moved to [another location](../license_compliance/index.md). diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index f730a25a9fc..a1bd00f34e3 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -128,7 +128,7 @@ custom analyzer can scan the source code. | Start column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | | End column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | 𐄂 | | External id (e.g. CVE) | 𐄂 | 𐄂 | ⚠ | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| URLs | ✓ | 𐄂 | ✓ | 𐄂 | ⚠ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| URLs | ✓ | 𐄂 | ✓ | 𐄂 | ⚠ | 𐄂 | ⚠ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Internal doc/explanation | ✓ | ⚠ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | | Solution | ✓ | 𐄂 | 𐄂 | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Confidence | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 2f15d997b5b..3eead6ccd3f 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -160,17 +160,21 @@ The following are Docker image-related variables. Some analyzers make it possible to filter out vulnerabilities under a given threshold. -| `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) | -| `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | -| `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. | -| `SAST_GITLEAKS_ENTROPY_LEVEL` | 8.0 | Minimum entropy for secret detection. Float, 0.0 = low, 8.0 = high. | -| `SAST_GOSEC_LEVEL` | 0 | Ignore gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. | -| `SAST_EXCLUDED_PATHS` | - | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, file or folder paths. Parent directories will also match patterns. | +| Environment variable | Default value | Description | Example usage | +|----------------------|---------------|-------------|---| +| `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) | | +| `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | | +| `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. | | +| `SAST_GITLEAKS_ENTROPY_LEVEL` | 8.0 | Minimum entropy for secret detection. Float, 0.0 = low, 8.0 = high. | | +| `SAST_GOSEC_LEVEL` | 0 | Ignore gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. | | +| `SAST_EXCLUDED_PATHS` | - | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, file or folder paths. Parent directories will also match patterns. | `SAST_EXCLUDED_PATHS=doc,spec` | ### Timeouts The following variables configure timeouts. +| Environment variable | Default value | Description | +|----------------------|---------------|-------------| | `SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | 2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m". | | `SAST_PULL_ANALYZER_IMAGE_TIMEOUT` | 5m | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m". | | `SAST_RUN_ANALYZER_TIMEOUT` | 20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m".| diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard.png Binary files differdeleted file mode 100644 index 85ab124f74c..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v12_3.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v12_3.png Binary files differnew file mode 100644 index 00000000000..61f683c1335 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v12_3.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index ac8c1ac0354..e7cda35eb98 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -62,16 +62,14 @@ Once you're on the dashboard, at the top you should see a series of filters for: - Report type - Project - +NOTE: **Note:** +The dashboard only shows projects with [security reports](#supported-reports) enabled in a group. + + Selecting one or more filters will filter the results in this page. -The first section is an overview of all the vulnerabilities, grouped by severity. -Underneath this overview is a timeline chart that shows how many open -vulnerabilities your projects had at various points in time. You can filter among 30, 60, and -90 days, with the default being 90. Hover over the chart to get more details about -the open vulnerabilities at a specific time. -Finally, there is a list of all the vulnerabilities in the group, sorted by severity. +The main section is a list of all the vulnerabilities in the group, sorted by severity. In that list, you can see the severity of the vulnerability, its name, its confidence (likelihood of the vulnerability to be a positive one), and the project it's from. @@ -82,6 +80,11 @@ If you hover over a row, there will appear some actions you can take: - "Create issue" - "Dismiss vulnerability" +Next to the list is a timeline chart that shows how many open +vulnerabilities your projects had at various points in time. You can filter among 30, 60, and +90 days, with the default being 90. Hover over the chart to get more details about +the open vulnerabilities at a specific time. + Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). ## Keeping the dashboards up to date diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 096730f800c..40ed0db4c57 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -103,7 +103,7 @@ implications](../project/clusters/index.md#security-implications) before doing s NOTE: **Note:** The -[runner/gitlab-runner](https://gitlab.com/charts/gitlab-runner) +[runner/gitlab-runner](https://gitlab.com/gitlab-org/charts/gitlab-runner) chart is used to install this application with a [`values.yaml`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/vendor/runner/values.yaml) file. @@ -225,8 +225,7 @@ file. ## Upgrading applications -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24789) -in GitLab 11.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24789) in GitLab 11.8. The applications below can be upgraded. diff --git a/doc/user/discussions/img/make_suggestion.png b/doc/user/discussions/img/make_suggestion.png Binary files differindex 20acc1417da..a24e29770aa 100644 --- a/doc/user/discussions/img/make_suggestion.png +++ b/doc/user/discussions/img/make_suggestion.png diff --git a/doc/user/discussions/img/suggestion.png b/doc/user/discussions/img/suggestion.png Binary files differindex 68a67e6ae5e..f7962305a15 100644 --- a/doc/user/discussions/img/suggestion.png +++ b/doc/user/discussions/img/suggestion.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 6891682141c..6b748981106 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -452,7 +452,7 @@ Replying to a non-thread comment will convert the non-thread comment to a thread once the reply is submitted. This conversion is considered an edit to the original comment, so a note about when it was last edited will appear underneath it. -This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff threads are +This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff threads are not supported yet. [ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022 diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index c9fbd7effa0..ca9450f94b9 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -43,13 +43,15 @@ Host gitlab.com Below are the settings for [GitLab Pages]. -| Setting | GitLab.com | Default | -| ----------------------- | ---------------- | ------------- | -| Domain name | `gitlab.io` | - | -| IP address | `35.185.44.232` | - | -| Custom domains support | yes | no | -| TLS certificates support| yes | no | +| Setting | GitLab.com | Default | +| --------------------------- | ---------------- | ------------- | +| Domain name | `gitlab.io` | - | +| IP address | `35.185.44.232` | - | +| Custom domains support | yes | no | +| TLS certificates support | yes | no | +| Maximum size (uncompressed) | 1G | 100M | +NOTE: **Note:** The maximum size of your Pages site is regulated by the artifacts maximum size which is part of [GitLab CI/CD](#gitlab-cicd). @@ -59,7 +61,7 @@ Below are the current settings regarding [GitLab CI/CD](../../ci/README.md). | Setting | GitLab.com | Default | | ----------- | ----------------- | ------------- | -| Artifacts maximum size | 1G | 100M | +| Artifacts maximum size (uncompressed) | 1G | 100M | | Artifacts [expiry time](../../ci/yaml/README.md#artifactsexpire_in) | kept forever | deleted after 30 days unless otherwise specified | ## Repository size limit @@ -112,57 +114,6 @@ Below are the shared Runners settings. The full contents of our `config.toml` are: -**DigitalOcean** - -```toml -concurrent = X -check_interval = 1 -metrics_server = "X" -sentry_dsn = "X" - -[[runners]] - name = "docker-auto-scale" - request_concurrency = X - url = "https://gitlab.com/" - token = "SHARED_RUNNER_TOKEN" - executor = "docker+machine" - environment = [ - "DOCKER_DRIVER=overlay2" - ] - limit = X - [runners.docker] - image = "ruby:2.5" - privileged = true - [runners.machine] - IdleCount = 20 - IdleTime = 1800 - OffPeakPeriods = ["* * * * * sat,sun *"] - OffPeakTimezone = "UTC" - OffPeakIdleCount = 5 - OffPeakIdleTime = 1800 - MaxBuilds = 1 - MachineName = "srm-%s" - MachineDriver = "digitalocean" - MachineOptions = [ - "digitalocean-image=X", - "digitalocean-ssh-user=core", - "digitalocean-region=nyc1", - "digitalocean-size=s-2vcpu-2gb", - "digitalocean-private-networking", - "digitalocean-tags=shared_runners,gitlab_com", - "engine-registry-mirror=http://INTERNAL_IP_OF_OUR_REGISTRY_MIRROR", - "digitalocean-access-token=DIGITAL_OCEAN_ACCESS_TOKEN", - ] - [runners.cache] - Type = "s3" - BucketName = "runner" - Insecure = true - Shared = true - ServerAddress = "INTERNAL_IP_OF_OUR_CACHE_SERVER" - AccessKey = "ACCESS_KEY" - SecretKey = "ACCESS_SECRET_KEY" -``` - **Google Cloud Platform** ```toml @@ -178,20 +129,25 @@ sentry_dsn = "X" token = "SHARED_RUNNER_TOKEN" executor = "docker+machine" environment = [ - "DOCKER_DRIVER=overlay2" + "DOCKER_DRIVER=overlay2", + "DOCKER_TLS_CERTDIR=" ] limit = X [runners.docker] image = "ruby:2.5" privileged = true + volumes = [ + "/certs/client", + "/dummy-sys-class-dmi-id:/sys/class/dmi/id:ro" # Make kaniko builds work on GCP. + ] [runners.machine] - IdleCount = 20 - IdleTime = 1800 + IdleCount = 50 + IdleTime = 3600 OffPeakPeriods = ["* * * * * sat,sun *"] OffPeakTimezone = "UTC" - OffPeakIdleCount = 5 - OffPeakIdleTime = 1800 - MaxBuilds = 1 + OffPeakIdleCount = 15 + OffPeakIdleTime = 3600 + MaxBuilds = 1 # For security reasons we delete the VM after job has finished so it's not reused. MachineName = "srm-%s" MachineDriver = "google" MachineOptions = [ @@ -202,17 +158,18 @@ sentry_dsn = "X" "google-tags=gitlab-com,srm", "google-use-internal-ip", "google-zone=us-east1-d", + "engine-opt=mtu=1460", # Set MTU for container interface, for more information check https://gitlab.com/gitlab-org/gitlab-runner/issues/3214#note_82892928 "google-machine-image=PROJECT/global/images/IMAGE", - "engine-registry-mirror=http://INTERNAL_IP_OF_OUR_REGISTRY_MIRROR" + "engine-opt=ipv6", # This will create IPv6 interfaces in the containers. + "engine-opt=fixed-cidr-v6=fc00::/7", + "google-operation-backoff-initial-interval=2" # Custom flag from forked docker-machine, for more information check https://github.com/docker/machine/pull/4600 ] [runners.cache] - Type = "s3" - BucketName = "runner" - Insecure = true + Type = "gcs" Shared = true - ServerAddress = "INTERNAL_IP_OF_OUR_CACHE_SERVER" - AccessKey = "ACCESS_KEY" - SecretKey = "ACCESS_SECRET_KEY" + [runners.cache.gcs] + CredentialsFile = "/path/to/file" + BucketName = "bucket-name" ``` ## Sidekiq @@ -357,27 +314,34 @@ Source: #### Git and container registry failed authentication ban -GitLab.com responds with HTTP status code 403 for 1 hour, if 30 failed +GitLab.com responds with HTTP status code `403` for 1 hour, if 30 failed authentication requests were received in a 3-minute period from a single IP address. This applies only to Git requests and container registry (`/jwt/auth`) requests (combined). -This limit is reset by requests that authenticate successfully. For example, 29 -failed authentication requests followed by 1 successful request, followed by 29 -more failed authentication requests would not trigger a ban. +This limit: + +- Is reset by requests that authenticate successfully. For example, 29 + failed authentication requests followed by 1 successful request, followed by 29 + more failed authentication requests would not trigger a ban. +- Does not apply to JWT requests authenticated by `gitlab-ci-token`. No response headers are provided. ### Admin Area settings -GitLab.com does not currently use these settings. +GitLab.com: + +- Has [rate limits on raw endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md) + set to the default. +- Does not have the user and IP rate limits settings enabled. ## GitLab.com at scale In addition to the GitLab Enterprise Edition Omnibus install, GitLab.com uses the following applications and settings to achieve scale. All settings are -located publicly available [chef cookbooks](https://gitlab.com/gitlab-cookbooks). +publicly available at [chef cookbooks](https://gitlab.com/gitlab-cookbooks). ### ELK diff --git a/doc/user/group/index.md b/doc/user/group/index.md index d1d4f3740b0..86fb7533e70 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -150,8 +150,11 @@ side of your screen.  -Group owners and maintainers will be notified of your request and will be able to approve or -decline it on the members page. +Once access is requested: + +- Up to ten group owners are notified of your request via email. + Email is sent to the most recently active group owners. +- Any group owner can approve or decline your request on the members page.  @@ -342,11 +345,11 @@ underlying projects, issues, etc, by IP address. This can help ensure that particular content doesn't leave the premises, while not blocking off access to the entire instance. -Add whitelisted IP subnet using CIDR notation to the group settings and anyone +Add one or more whitelisted IP subnets using CIDR notation in comma separated format to the group settings and anyone coming from a different IP address won't be able to access the restricted content. -Restriction currently applies to UI, API access is not restricted. +Restriction currently applies to UI and API access, Git actions via ssh are not restricted. To avoid accidental lock-out, admins and group owners are are able to access the group regardless of the IP restriction. @@ -358,7 +361,7 @@ the group regardless of the IP restriction. You can restrict access to groups and their underlying projects by allowing only users with email addresses in particular domains to be added to the group. -Add email domains you want to whitelist and users with emails from different +Add email domains you want to whitelist and users with emails from different domains won't be allowed to be added to this group. Some domains cannot be restricted. These are the most popular public email domains, such as: @@ -417,7 +420,7 @@ You can disable all email notifications related to the group, which also include it's subgroups and projects. To enable this feature: - + 1. Navigate to the group's **Settings > General** page. 1. Expand the **Permissions, LFS, 2FA** section, and select **Disable email notifications**. 1. Click **Save changes**. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index e3f657af564..bd50367681e 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -39,6 +39,25 @@ However, users will not be prompted to log via SSO on each visit. GitLab will ch We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab-ee/issues/9152) in the future. +#### Group-managed accounts + +[Introduced in GitLab 12.1](https://gitlab.com/groups/gitlab-org/-/epics/709). + +When SSO is being enforced, groups can enable an additional level of protection by enforcing the creation of dedicated user accounts to access the group. + +Without group-managed accounts, users can link their SAML identity with any existing user on the instance. With group-managed accounts enabled, users are required to create a new, dedicated user linked to the group. The notification email address associated with the user is locked to the email address received from the configured identity provider. + +When this option is enabled: + +- All existing and new users in the group will be required to log in via the SSO URL associated with the group. +- On successfully authenticating, GitLab will prompt the user to create a new, dedicated account using the email address received from the configured identity provider. +- After the group managed account has been created, group activity will require the use of this user account. + +Since use of the group managed account requires the use of SSO, users of group managed accounts will lose access to these accounts when they are no longer able to authenticate with the connected identity provider. In the case of an offboarded employee who has been removed from your identity provider: + +- The user will be unable to access the group (their credentials will no longer work on the identity provider when prompted to SSO). +- Contributions in the group (e.g. issues, merge requests) will remain intact. + ### NameID GitLab.com uses the SAML NameID to identify users. The NameID element: diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index f8bef8b8a6a..5d136ad62da 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -59,15 +59,14 @@ Once [Single sign-on](index.md) has been configured, we can: ### Azure -First, double check the [Single sign-on](index.md) configuration for your group and ensure that **Name identifier value** (NameID) points to `user.objectid` or another unique identifier. This will match the `extern_uid` used on GitLab. +The SAML application that was created during [Single sign-on](index.md) setup now needs to be set up for SCIM. - +1. Check the configuration for your GitLab SAML app and ensure that **Name identifier value** (NameID) points to `user.objectid` or another unique identifier. This will match the `extern_uid` used on GitLab. -#### Set up admin credentials +  -Next, configure your GitLab application in Azure by following the -[Provisioning users and groups to applications that support SCIM](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups#provisioning-users-and-groups-to-applications-that-support-scim) -section in Azure's SCIM setup documentation. +1. Set up automatic provisioning and administrative credentials by following the + [Provisioning users and groups to applications that support SCIM](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups#provisioning-users-and-groups-to-applications-that-support-scim) section in Azure's SCIM setup documentation. During this configuration, note the following: @@ -97,6 +96,7 @@ You can then test the connection by clicking on **Test Connection**. If the conn NOTE: **Note:** If you used a unique identifier **other than** `objectId`, be sure to map it instead to both `id` and `externalId`. 1. Below the mapping list click on **Show advanced options > Edit attribute list for AppName**. + 1. Leave the `id` as the primary and only required field. NOTE: **Note:** @@ -129,8 +129,7 @@ When testing the connection, you may encounter an error: **You appear to have en When checking the Audit Logs for the Provisioning, you can sometimes see the error `Namespace can't be blank, Name can't be blank, and User can't be blank.` -This is likely caused because not all required fields (such as first name and -last name) are present for all users being mapped. +This is likely caused because not all required fields (such as first name and last name) are present for all users being mapped. As a workaround, try an alternate mapping: diff --git a/doc/user/index.md b/doc/user/index.md index c93f64cd528..27e75189fc3 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -53,7 +53,7 @@ With GitLab Enterprise Edition, you can also: - Improve collaboration with [Merge Request Approvals](project/merge_requests/index.md#merge-request-approvals-starter), [Multiple Assignees for Issues](project/issues/multiple_assignees_for_issues.md), - and [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards-starter). + and [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards). - Create formal relationships between issues with [Related Issues](project/issues/related_issues.md). - Use [Burndown Charts](project/milestones/burndown_charts.md) to track progress during a sprint or while working on a new version of their software. - Leverage [Elasticsearch](../integration/elasticsearch.md) with [Advanced Global Search](search/advanced_global_search.md) and [Advanced Syntax Search](search/advanced_search_syntax.md) for faster, more advanced code search across your entire GitLab instance. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 6cfc8b6429b..edf2fedab3c 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -57,12 +57,6 @@ render incorrectly: - milk ``` -1. Chocolate - - dark - - milk - ---- - Simply add a space to each nested item to align the `-` with the first character of the top list item (`C` in this case): @@ -187,9 +181,6 @@ graph TD; #### Subgraphs -NOTE: **Note:** GitLab 12.1 and up now [requires quotes around subgraph -titles that contain multiple words](https://github.com/knsv/mermaid/pull/845). - Subgraphs can also be included: ~~~ @@ -265,8 +256,7 @@ this font installed by default. ### Front matter -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23331) - in GitLab 11.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23331) in GitLab 11.6. Front matter is metadata included at the beginning of a markdown document, preceding its content. This data can be used by static site generators such as [Jekyll](https://jekyllrb.com/docs/front-matter/), @@ -866,18 +856,6 @@ or underscores ___ ``` -Three or more hyphens, - ---- - -asterisks, - -*** - -or underscores - -___ - ### Images Examples: @@ -1170,7 +1148,7 @@ GFM will autolink almost any URL you put into your text: - https://google.com/ - ftp://ftp.us.debian.org/debian/ - smb://foo/bar/baz -- irc://irc.freenode.net/gitlab +- irc://irc.freenode.net/ - http://localhost:3000 ``` @@ -1178,7 +1156,7 @@ GFM will autolink almost any URL you put into your text: - <https://google.com/> - <ftp://ftp.us.debian.org/debian/> - <smb://foo/bar/baz> -- <irc://irc.freenode.net/gitlab> +- <irc://irc.freenode.net/> - <http://localhost:3000> ### Lists diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 4fd7c5abf78..c28a5e49ec4 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -45,7 +45,7 @@ The following table depicts the various user permission levels in a project. | Leave comments | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | View Insights charts **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View approved/blacklisted licenses **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View license management reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| View License Compliance reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | View Security reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | View Dependency list **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | View [Design Management](project/issues/design_management.md) pages **(PREMIUM)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | @@ -162,7 +162,7 @@ to learn more. ### Cycle Analytics permissions Find the current permissions on the Cycle Analytics dashboard on -the [documentation on Cycle Analytics permissions](project/cycle_analytics.md#permissions). +the [documentation on Cycle Analytics permissions](analytics/cycle_analytics.md#permissions). ### Issue Board permissions @@ -204,27 +204,29 @@ Any user can remove themselves from a group, unless they are the last Owner of the group. The following table depicts the various user permission levels in a group. -| Action | Guest | Reporter | Developer | Maintainer | Owner | -|-------------------------------------------------|-------|----------|-----------|------------|-------| -| Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Insights charts **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View group epic **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| Create/edit group epic **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| Manage group labels | | ✓ | ✓ | ✓ | ✓ | -| Create project in group | | | ✓ | ✓ | ✓ | -| Create/edit/delete group milestones | | | ✓ | ✓ | ✓ | -| Enable/disable a dependency proxy **(PREMIUM)** | | | ✓ | ✓ | ✓ | -| Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| Create subgroup | | | | ✓ (1) | ✓ | -| Edit group | | | | | ✓ | -| Manage group members | | | | | ✓ | -| Remove group | | | | | ✓ | -| Delete group epic **(ULTIMATE)** | | | | | ✓ | -| View group Audit Events | | | | | ✓ | -| Disable notification emails | | | | | ✓ | +| Action | Guest | Reporter | Developer | Maintainer | Owner | +|--------------------------------------------------------|-------|----------|-----------|------------|-------| +| Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | +| View Insights charts **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| View group epic **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| Create/edit group epic **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| Manage group labels | | ✓ | ✓ | ✓ | ✓ | +| Create project in group | | | ✓ | ✓ | ✓ | +| Create/edit/delete group milestones | | | ✓ | ✓ | ✓ | +| Enable/disable a dependency proxy **(PREMIUM)** | | | ✓ | ✓ | ✓ | +| Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| Create subgroup | | | | ✓ (1) | ✓ | +| Edit group | | | | | ✓ | +| Manage group members | | | | | ✓ | +| Remove group | | | | | ✓ | +| Delete group epic **(ULTIMATE)** | | | | | ✓ | +| Edit epic comments (posted by any user) **(ULTIMATE)** | | | | ✓ (2) | ✓ (2) | +| View group Audit Events | | | | | ✓ | +| Disable notification emails | | | | | ✓ | - (1): Groups can be set to [allow either Owners or Owners and Maintainers to create subgroups](group/subgroups/index.md#creating-a-subgroup) +- (2): Introduced in GitLab 12.2. ### Subgroup permissions @@ -237,13 +239,16 @@ To learn more, read through the documentation on ## Guest User -Create a user and assign to a project with a role as `Guest` user, this user -will be considered as guest user by GitLab and will not take up the license. -There is no specific `Guest` role for newly created users. If this user will -be assigned a higher role to any of the projects and groups then this user will -take a license seat. If a user creates a project this user becomes a maintainer, -therefore, takes up a license seat as well, in order to prevent this you have -to go and edit user profile and mark the user as External. +When a user is given `Guest` permissions on a project and/or group, and holds no +higher permission level on any other project or group on the instance, the user +is considered a guest user by GitLab and will not consume a license seat. +There is no other specific "guest" designation for newly created users. + +If the user is assigned a higher role on any projects or groups, the user will +take a license seat. If a user creates a project, the user becomes a `Maintainer` +on the project, resulting in the use of a license seat. To prevent a guest user +from creating projects, you can edit the user profile to mark the user as +[External](#external-users-permissions). ## External users permissions diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index e2b1a20a605..f7ba921aa7d 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -48,6 +48,7 @@ To enable 2FA: - [andOTP](https://github.com/andOTP/andOTP): feature rich open source app for Android which supports PGP encrypted backups. - [FreeOTP](https://freeotp.github.io/): open source app for Android. - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en): proprietary app for iOS and Android. + - [SailOTP](https://openrepos.net/content/seiichiro0185/sailotp): open source app for SailFish OS. 1. In the application, add a new entry in one of two ways: - Scan the code presented in GitLab with your device's camera to add the entry automatically. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index cf3a3fef79f..3bde0a375c6 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -199,7 +199,7 @@ To add an existing Kubernetes cluster to your project: kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' ``` - - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the EKS cluster. We will use the certificate created by default. + - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We will use the certificate created by default. - List the secrets with `kubectl get secrets`, and one should named similar to `default-token-xxxxx`. Copy that token name for use below. - Get the certificate by running this command: diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 96c4f16fe04..79f0bb4db72 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -58,7 +58,7 @@ Example `CODEOWNERS` file: \#file_with_pound.rb @owner-file-with-pound # Multiple codeowners can be specified, separated by spaces or tabs -CODEOWNERS @multiple @code @owners +CODEOWNERS @multiple @code @owners # Both usernames or email addresses can be used to match # users. Everything else will be ignored. For example this will diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md index 424bee6e9f1..87577c9ec88 100644 --- a/doc/user/project/cycle_analytics.md +++ b/doc/user/project/cycle_analytics.md @@ -1,181 +1,5 @@ -# Cycle Analytics - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12077) at a group level in [GitLab Premium and Silver](https://about.gitlab.com/pricing/) 12.2 (enabled by feature flag `analytics`). - -Cycle Analytics measures the time spent to go from an [idea to production] - also known -as cycle time - for each of your projects. Cycle Analytics displays the median time for an idea to -reach production, along with the time typically spent in each DevOps stage along the way. - -Cycle Analytics is useful in order to quickly determine the velocity of a given -project. It points to bottlenecks in the development process, enabling management -to uncover, triage, and root-cause slowdowns in the software development life cycle. - -Cycle Analytics is tightly coupled with the [GitLab flow] and -calculates a separate median for each stage. - -## Overview - -Cycle Analytics are available at a: - -- Group level from the top navigation bar **Analytics > Cycle Analytics**. **(PREMIUM)** - - In the future, multiple groups will be selectable which will effectively make this an - instance-level feature. - -- Project level from a project's **Project > Cycle Analytics**. - -  - -There are seven stages that are tracked as part of the Cycle Analytics calculations. - -- **Issue** (Tracker) - - Time to schedule an issue (by milestone or by adding it to an issue board) -- **Plan** (Board) - - Time to first commit -- **Code** (IDE) - - Time to create a merge request -- **Test** (CI) - - Time it takes GitLab CI/CD to test your code -- **Review** (Merge Request/MR) - - Time spent on code review -- **Staging** (Continuous Deployment) - - Time between merging and deploying to production -- **Production** (Total) - - Total lifecycle time; i.e. the velocity of the project or team - -## How the data is measured - -Cycle Analytics records cycle time and data based on the project issues with the -exception of the staging and production stages, where only data deployed to -production are measured. - -Specifically, if your CI is not set up and you have not defined a `production` -or `production/*` [environment], then you will not have any data for those stages. - -Below you can see in more detail what the various stages of Cycle Analytics mean. - -| **Stage** | **Description** | -| --------- | --------------- | -| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label will be tracked only if it already has an [Issue Board list][board] created for it. | -| Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (e.g., `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. | -| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern] to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the issue closing pattern is not present in the merge request description, the MR is not considered to the measurement time of the stage. | -| Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | -| Review | Measures the median time taken to review the merge request that has closing issue pattern, between its creation and until it's merged. | -| Staging | Measures the median time between merging the merge request with closing issue pattern until the very first deployment to production. It's tracked by the [environment] set to `production` or matching `production/*` (case-sensitive, `Production` won't work) in your GitLab CI configuration. If there isn't a production environment, this is not tracked. | -| Production| The sum of all time (medians) taken to run the entire process, from issue creation to deploying the code to production. | - +--- +redirect_to: '../analytics/cycle_analytics.md' --- -Here's a little explanation of how this works behind the scenes: - -1. Issues and merge requests are grouped together in pairs, such that for each - `<issue, merge request>` pair, the merge request has the [issue closing pattern] - for the corresponding issue. All other issues and merge requests are **not** - considered. -1. Then the `<issue, merge request>` pairs are filtered out by last XX days (specified - by the UI - default is 90 days). So it prohibits these pairs from being considered. -1. For the remaining `<issue, merge request>` pairs, we check the information that - we need for the stages, like issue creation date, merge request merge time, - etc. - -To sum up, anything that doesn't follow the [GitLab flow] won't be tracked at all. -So, the Cycle Analytics dashboard won't present any data: - -- For merge requests that do not close an issue. -- For issues not labeled with a label present in the Issue Board or for issues not assigned a milestone. -- For staging and production stages, if the project has no `production` or `production/*` - environment. - -## Example workflow - -Below is a simple fictional workflow of a single cycle that happens in a -single day passing through all seven stages. Note that if a stage does not have -a start and a stop mark, it is not measured and hence not calculated in the median -time. It is assumed that milestones are created and CI for testing and setting -environments is configured. - -1. Issue is created at 09:00 (start of **Issue** stage). -1. Issue is added to a milestone at 11:00 (stop of **Issue** stage / start of - **Plan** stage). -1. Start working on the issue, create a branch locally and make one commit at - 12:00. -1. Make a second commit to the branch which mentions the issue number at 12.30 - (stop of **Plan** stage / start of **Code** stage). -1. Push branch and create a merge request that contains the [issue closing pattern] - in its description at 14:00 (stop of **Code** stage / start of **Test** and - **Review** stages). -1. The CI starts running your scripts defined in [`.gitlab-ci.yml`][yml] and - takes 5min (stop of **Test** stage). -1. Review merge request, ensure that everything is OK and merge the merge - request at 19:00. (stop of **Review** stage / start of **Staging** stage). -1. Now that the merge request is merged, a deployment to the `production` - environment starts and finishes at 19:30 (stop of **Staging** stage). -1. The cycle completes and the sum of the median times of the previous stages - is recorded to the **Production** stage. That is the time between creating an - issue and deploying its relevant merge request to production. - -From the above example you can conclude the time it took each stage to complete -as long as their total time: - -- **Issue**: 2h (11:00 - 09:00) -- **Plan**: 1h (12:00 - 11:00) -- **Code**: 2h (14:00 - 12:00) -- **Test**: 5min -- **Review**: 5h (19:00 - 14:00) -- **Staging**: 30min (19:30 - 19:00) -- **Production**: Since this stage measures the sum of median time off all - previous stages, we cannot calculate it if we don't know the status of the - stages before. In case this is the very first cycle that is run in the project, - then the **Production** time is 10h 30min (19:30 - 09:00) - -A few notes: - -- In the above example we demonstrated that it doesn't matter if your first - commit doesn't mention the issue number, you can do this later in any commit - of the branch you are working on. -- You can see that the **Test** stage is not calculated to the overall time of - the cycle since it is included in the **Review** process (every MR should be - tested). -- The example above was just **one cycle** of the seven stages. Add multiple - cycles, calculate their median time and the result is what the dashboard of - Cycle Analytics is showing. - -## Permissions - -The current permissions on the Project Cycle Analytics dashboard are: - -- Public projects - anyone can access -- Internal projects - any authenticated user can access -- Private projects - any member Guest and above can access - -You can [read more about permissions][permissions] in general. - -NOTE: **Note:** -As of GitLab 12.2, the project-level page is deprecated. You should access -project-level Cycle Analytics from **Analytics > Cycle Analytics** in the top -navigation bar. We will ensure that the same project-level functionality is available -to CE users in the new analytics space. - -For Cycle Analytics functionality introduced in GitLab 12.2 and later: - -- Users must have Reporter access or above. -- Features are available only on - [Premium or Silver tiers](https://about.gitlab.com/pricing/) and above. - -## More resources - -Learn more about Cycle Analytics in the following resources: - -- [Cycle Analytics feature page](https://about.gitlab.com/features/cycle-analytics/) -- [Cycle Analytics feature preview](https://about.gitlab.com/2016/09/16/feature-preview-introducing-cycle-analytics/) -- [Cycle Analytics feature highlight](https://about.gitlab.com/2016/09/21/cycle-analytics-feature-highlight/) - -[board]: issue_board.md#creating-a-new-list -[ce-5986]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5986 -[ce-20975]: https://gitlab.com/gitlab-org/gitlab-ce/issues/20975 -[environment]: ../../ci/yaml/README.md#environment -[GitLab flow]: ../../workflow/gitlab_flow.md -[idea to production]: https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab -[issue closing pattern]: issues/managing_issues.md#closing-issues-automatically -[permissions]: ../permissions.md -[yml]: ../../ci/yaml/README.md +This document was moved to [another location](../analytics/cycle_analytics.md) diff --git a/doc/user/project/img/cycle_analytics_landing_page.png b/doc/user/project/img/cycle_analytics_landing_page.png Binary files differdeleted file mode 100644 index c0c07e84a82..00000000000 --- a/doc/user/project/img/cycle_analytics_landing_page.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_devs_can_push.png b/doc/user/project/img/protected_branches_devs_can_push.png Binary files differdeleted file mode 100644 index b537839c00b..00000000000 --- a/doc/user/project/img/protected_branches_devs_can_push.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_devs_can_push_v12_3.png b/doc/user/project/img/protected_branches_devs_can_push_v12_3.png Binary files differnew file mode 100644 index 00000000000..adc03a41abb --- /dev/null +++ b/doc/user/project/img/protected_branches_devs_can_push_v12_3.png diff --git a/doc/user/project/img/protected_branches_list.png b/doc/user/project/img/protected_branches_list.png Binary files differdeleted file mode 100644 index 495ce4d7b6f..00000000000 --- a/doc/user/project/img/protected_branches_list.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_list_v12_3.png b/doc/user/project/img/protected_branches_list_v12_3.png Binary files differnew file mode 100644 index 00000000000..365d8d99e5a --- /dev/null +++ b/doc/user/project/img/protected_branches_list_v12_3.png diff --git a/doc/user/project/img/protected_branches_page.png b/doc/user/project/img/protected_branches_page.png Binary files differdeleted file mode 100644 index 9b10991f62e..00000000000 --- a/doc/user/project/img/protected_branches_page.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_page_v12_3.png b/doc/user/project/img/protected_branches_page_v12_3.png Binary files differnew file mode 100644 index 00000000000..17f19642552 --- /dev/null +++ b/doc/user/project/img/protected_branches_page_v12_3.png diff --git a/doc/user/project/img/protected_tags_list.png b/doc/user/project/img/protected_tags_list.png Binary files differdeleted file mode 100644 index 6c5295e0f4b..00000000000 --- a/doc/user/project/img/protected_tags_list.png +++ /dev/null diff --git a/doc/user/project/img/protected_tags_list_v12_3.png b/doc/user/project/img/protected_tags_list_v12_3.png Binary files differnew file mode 100644 index 00000000000..6a30f615f2f --- /dev/null +++ b/doc/user/project/img/protected_tags_list_v12_3.png diff --git a/doc/user/project/img/protected_tags_page.png b/doc/user/project/img/protected_tags_page.png Binary files differdeleted file mode 100644 index 5f8a2106cd1..00000000000 --- a/doc/user/project/img/protected_tags_page.png +++ /dev/null diff --git a/doc/user/project/img/protected_tags_page_v12_3.png b/doc/user/project/img/protected_tags_page_v12_3.png Binary files differnew file mode 100644 index 00000000000..841e19af8a7 --- /dev/null +++ b/doc/user/project/img/protected_tags_page_v12_3.png diff --git a/doc/user/project/img/protected_tags_permissions_dropdown.png b/doc/user/project/img/protected_tags_permissions_dropdown.png Binary files differdeleted file mode 100644 index 77098eeb591..00000000000 --- a/doc/user/project/img/protected_tags_permissions_dropdown.png +++ /dev/null diff --git a/doc/user/project/img/protected_tags_permissions_dropdown_v12_3.png b/doc/user/project/img/protected_tags_permissions_dropdown_v12_3.png Binary files differnew file mode 100644 index 00000000000..913d4725d53 --- /dev/null +++ b/doc/user/project/img/protected_tags_permissions_dropdown_v12_3.png diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index f48a158e2d3..2f87f257754 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -1,21 +1,21 @@ # Project importing from GitLab.com to your private GitLab instance -You can import your existing GitLab.com projects to your GitLab instance. But keep in mind that it is possible only if -GitLab.com integration is enabled on your GitLab instance. +You can import your existing GitLab.com projects to your GitLab instance, but keep in +mind that it is possible only if GitLab.com integration is enabled on your GitLab instance. [Read more about GitLab.com integration for self-managed GitLab instances](../../../integration/gitlab.md). To get to the importer page you need to go to "New project" page. >**Note:** -If you are interested in importing Wiki and Merge Request data to your new -instance, you'll need to follow the instructions for [project export](../settings/import_export.md) +If you are interested in importing Wiki and Merge Request data to your new instance, +you'll need to follow the instructions for [exporting a project](../settings/import_export.md#exporting-a-project-and-its-data) - + -Click on the "Import projects from GitLab.com" link and you will be redirected to GitLab.com +Go to the **Import Projects** tab, then click on **GitLab.com**, and you will be redirected to GitLab.com for permission to access your projects. After accepting, you'll be automatically redirected to the importer.  -To import a project, you can simple click "Import". The importer will import your repository and issues. +To import a project, click "Import". The importer will import your repository and issues. Once the importer is done, a new GitLab project will be created with your imported data. diff --git a/doc/user/project/import/img/gitlab_new_project_page.png b/doc/user/project/import/img/gitlab_new_project_page.png Binary files differdeleted file mode 100644 index c673724f436..00000000000 --- a/doc/user/project/import/img/gitlab_new_project_page.png +++ /dev/null diff --git a/doc/user/project/import/img/gitlab_new_project_page_v12_2.png b/doc/user/project/import/img/gitlab_new_project_page_v12_2.png Binary files differnew file mode 100644 index 00000000000..e79c27f32c0 --- /dev/null +++ b/doc/user/project/import/img/gitlab_new_project_page_v12_2.png diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index 375522b77d0..9b148224e10 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -6,7 +6,7 @@ type: concepts Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/services/devops/server/) in 2019, is a set of tools developed by Microsoft which also includes -[Team Foundation Version Control](https://docs.microsoft.com/en-us/azure/devops/repos/tfvc/overview) +[Team Foundation Version Control](https://docs.microsoft.com/en-us/azure/devops/repos/tfvc/overview?view=azure-devops) (TFVC), a centralized version control system similar to Git. In this document, we focus on the TFVC to Git migration. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 30ff0e9ff07..c63d5308536 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -17,7 +17,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Issue tracker](issues/index.md): Discuss implementations with your team within issues - [Issue Boards](issue_board.md): Organize and prioritize your workflow - - [Multiple Issue Boards](issue_board.md#multiple-issue-boards-starter): Allow your teams to create their own workflows (Issue Boards) for the same project **(STARTER)** + - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project - [Repositories](repository/index.md): Host your code in a fully integrated platform - [Branches](repository/branches/index.md): use Git branching strategies to @@ -34,7 +34,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Issue tracker](issues/index.md): Discuss implementations with your team within issues - [Issue Boards](issue_board.md): Organize and prioritize your workflow - - [Multiple Issue Boards](issue_board.md#multiple-issue-boards-starter): Allow your teams to create their own workflows (Issue Boards) for the same project **(STARTER)** + - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project - [Merge Requests](merge_requests/index.md): Apply your branching strategy and get reviewed by your team - [Merge Request Approvals](merge_requests/merge_request_approvals.md): Ask for approval before @@ -98,7 +98,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Maven packages](packages/maven_repository.md): your private Maven repository in GitLab. **(PREMIUM)** - [NPM packages](packages/npm_registry.md): your private NPM package registry in GitLab. **(PREMIUM)** - [Code owners](code_owners.md): specify code owners for certain files **(STARTER)** -- [License Management](../application_security/license_management/index.md): approve and blacklist licenses for projects. **(ULTIMATE)** +- [License Compliance](../application_security/license_compliance/index.md): approve and blacklist licenses for projects. **(ULTIMATE)** - [Dependency List](../application_security/dependency_list/index.md): view project dependencies. **(ULTIMATE)** ### Project integrations diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 3206a39dc08..94e0c9fd886 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -57,5 +57,5 @@ service in GitLab. If builds are not triggered, ensure you entered the right GitLab IP address in Bamboo under 'Trigger IP addresses'. -> **Note:** -> - Starting with GitLab 8.14.0, builds are triggered on push events. +NOTE: **Note:** +Starting with GitLab 8.14.0, builds are triggered on push events. diff --git a/doc/user/project/integrations/img/download_as_csv.png b/doc/user/project/integrations/img/download_as_csv.png Binary files differnew file mode 100644 index 00000000000..0ed5ab8db89 --- /dev/null +++ b/doc/user/project/integrations/img/download_as_csv.png diff --git a/doc/user/project/integrations/img/generate_link_to_chart.png b/doc/user/project/integrations/img/generate_link_to_chart.png Binary files differnew file mode 100644 index 00000000000..03e018969b1 --- /dev/null +++ b/doc/user/project/integrations/img/generate_link_to_chart.png diff --git a/doc/user/project/integrations/img/grafana_live_embed.png b/doc/user/project/integrations/img/grafana_live_embed.png Binary files differnew file mode 100644 index 00000000000..91970cd379a --- /dev/null +++ b/doc/user/project/integrations/img/grafana_live_embed.png diff --git a/doc/user/project/integrations/img/jira_service_page.png b/doc/user/project/integrations/img/jira_service_page.png Binary files differdeleted file mode 100644 index 76fd5f4641c..00000000000 --- a/doc/user/project/integrations/img/jira_service_page.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_service_page_v12_2.png b/doc/user/project/integrations/img/jira_service_page_v12_2.png Binary files differnew file mode 100644 index 00000000000..ba7dad9b438 --- /dev/null +++ b/doc/user/project/integrations/img/jira_service_page_v12_2.png diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index ca990ee6c32..61f6f6c9412 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -93,7 +93,7 @@ even if the status you are changing to is the same. After saving the configuration, your GitLab project will be able to interact with all Jira projects in your Jira instance and you'll see the Jira link on the GitLab project pages that takes you to the appropriate Jira project. - + ## Jira issues diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 6e0f39956d3..c240b6cb6b4 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -13,8 +13,13 @@ To enable Mattermost integration you must create an incoming webhook integration 1. Choose a display name, description and channel, those can be overridden on GitLab. 1. Save it, copy the **Webhook URL**, we'll need this later for GitLab. -There might be some cases that Incoming Webhooks are blocked by admin, ask your mattermost admin to enable -it on **Mattermost System Console > Integrations > Integration Management**, or on **Mattermost System Console > Integrations > Custom Integrations** in Mattermost versions 5.11 and earlier. +Incoming Webhooks might be blocked on your Mattermost instance. Ask your Mattermost admin +to enable it on: + +- **Mattermost System Console > Integrations > Integration Management** in Mattermost + versions 5.12 and later. +- **Mattermost System Console > Integrations > Custom Integrations** in Mattermost + versions 5.11 and earlier. Display name override is not enabled by default, you need to ask your admin to enable it on that same section. diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 886094a6531..b06ccda8287 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -6,7 +6,7 @@ To set up the mock CI service server, respond to the following endpoints - `commit_status`: `#{project.namespace.path}/#{project.path}/status/#{sha}.json` - Have your service return `200 { status: ['failed'|'canceled'|'running'|'pending'|'success'|'success-with-warnings'|'skipped'|'not_found'] }` - - If the service returns a 404, it is interpreted as `pending` + - If the service returns a 404, it is interpreted as `pending` - `build_page`: `#{project.namespace.path}/#{project.path}/status/#{sha}` - Just where the build is linked to, doesn't matter if implemented diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index aa7db97c413..3583c0554ee 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -19,7 +19,7 @@ Once enabled, GitLab will automatically detect metrics from known services in th ### Managed Prometheus on Kubernetes -> **Note**: [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28916) in GitLab 10.5 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28916) in GitLab 10.5. GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cluster](../clusters/index.md), making monitoring of your apps easy. @@ -194,7 +194,7 @@ The following tables outline the details of expected properties. | Property | Type | Required | Description | | ------ | ------ | ------ | ------- | -| `type` | enum | no, defaults to `area-chart` | Specifies the chart type to use. | +| `type` | enum | no, defaults to `area-chart` | Specifies the chart type to use, can be `area-chart` or `line-chart` | | `title` | string | yes | Heading for the panel. | | `y_label` | string | no, but highly encouraged | Y-Axis label for the panel. | | `weight` | number | no, defaults to order in file | Order to appear within the grouping. Lower number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | @@ -269,6 +269,12 @@ Note the following properties:  +### Downloading data as CSV + +Data from Prometheus charts on the metrics dashboard can be downloaded as CSV. + + + ### Setting up alerts for Prometheus metrics **(ULTIMATE)** #### Managed Prometheus instances @@ -336,15 +342,21 @@ If the metric exceeds the threshold of the alert for over 5 minutes, an email wi ## Determining the performance impact of a merge -> [Introduced][ce-10408] in GitLab 9.2. -> GitLab 9.3 added the [numeric comparison](https://gitlab.com/gitlab-org/gitlab-ce/issues/27439) of the 30 minute averages. -> Requires [Kubernetes](prometheus_library/kubernetes.md) metrics +> - [Introduced][ce-10408] in GitLab 9.2. +> - GitLab 9.3 added the [numeric comparison](https://gitlab.com/gitlab-org/gitlab-ce/issues/27439) of the 30 minute averages. Developers can view the performance impact of their changes within the merge -request workflow. When a source branch has been deployed to an environment, a sparkline and numeric comparison of the average memory consumption will appear. 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. +request workflow. + +NOTE: **Note:** +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 +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 to show the new environments this revision has been deployed to. @@ -354,15 +366,21 @@ Prometheus server.  -## Embedding metric charts within Gitlab Flavored Markdown +## Embedding metric charts within GitLab Flavored Markdown > [Introduced][ce-29691] in GitLab 12.2. -> Requires [Kubernetes](prometheus_library/kubernetes.md) metrics. It is possible to display metrics charts within [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). +NOTE: **Note:** +Requires [Kubernetes](prometheus_library/kubernetes.md) metrics. + To display a metric chart, include a link of the form `https://<root_url>/<project>/environments/<environment_id>/metrics`. +A single chart may also be embedded. You can generate a link to the chart via the dropdown located on the right side of the chart: + + + The following requirements must be met for the metric to unfurl: - The `<environment_id>` must correspond to a real environment. @@ -375,6 +393,27 @@ The following requirements must be met for the metric to unfurl:  +### Embedding live Grafana charts + +It is also possible to embed live [Grafana](https://docs.gitlab.com/omnibus/settings/grafana.html) charts within issues, as a [Direct Linked Rendered Image](https://grafana.com/docs/reference/sharing/#direct-link-rendered-image). + +The sharing dialog within Grafana provides the link, as highlighted below. + + + +NOTE: **Note:** +For this embed to display correctly the Grafana instance must be available to the target user, either as a public dashboard or on the same network. + +Copy the link and add an image tag as [inline HTML](../../markdown.md#inline-html) in your markdown. You may tweak the query parameters as required. For instance, removing the `&from=` and `&to=` parameters will give you a live chart. Here is example markup for a live chart from GitLab's public dashboard: + +```html +<img src="https://dashboards.gitlab.com/render/d-solo/RZmbBr7mk/gitlab-triage?orgId=1&refresh=30s&var-env=gprd&var-environment=gprd&var-prometheus=prometheus-01-inf-gprd&var-prometheus_app=prometheus-app-01-inf-gprd&var-backend=All&var-type=All&var-stage=main&panelId=1247&width=1000&height=300"/> +``` + +This will render like so: + +<img src="https://dashboards.gitlab.com/render/d-solo/RZmbBr7mk/gitlab-triage?orgId=1&refresh=30s&var-env=gprd&var-environment=gprd&var-prometheus=prometheus-01-inf-gprd&var-prometheus_app=prometheus-app-01-inf-gprd&var-backend=All&var-type=All&var-stage=main&panelId=1247&width=1000&height=300"/> + ## Troubleshooting If the "No data found" screen continues to appear, it could be due to: diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 84adb9637fc..f5bc6cbd988 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -2,6 +2,7 @@ > **Note:** > Starting from GitLab 8.5: +> > - the `repository` key is deprecated in favor of the `project` key > - the `project.ssh_url` key is deprecated in favor of the `project.git_ssh_url` key > - the `project.http_url` key is deprecated in favor of the `project.git_http_url` key @@ -12,6 +13,7 @@ > > **Note:** > Starting from GitLab 11.2: +> > - The `description` field for issues, merge requests, comments, and wiki pages > is rewritten so that simple Markdown image references (like > ``) have their target URL changed to an absolute URL. See @@ -98,11 +100,12 @@ Below are described the supported events. Triggered when you push to the repository except when pushing tags. -> **Note:** When more than 20 commits are pushed at once, the `commits` webhook - attribute will only contain the first 20 for performance reasons. Loading - detailed commit data is expensive. Note that despite only 20 commits being - present in the `commits` attribute, the `total_commits_count` attribute will - contain the actual total. +NOTE: **Note:** +When more than 20 commits are pushed at once, the `commits` webhook +attribute will only contain the first 20 for performance reasons. Loading +detailed commit data is expensive. Note that despite only 20 commits being +present in the `commits` attribute, the `total_commits_count` attribute will +contain the actual total. **Request header**: @@ -1181,20 +1184,20 @@ X-Gitlab-Event: Job Hook ```json { - "object_kind": "job", + "object_kind": "build", "ref": "gitlab-script-trigger", "tag": false, "before_sha": "2293ada6b400935a1378653304eaf6221e0fdb8f", "sha": "2293ada6b400935a1378653304eaf6221e0fdb8f", - "job_id": 1977, - "job_name": "test", - "job_stage": "test", - "job_status": "created", - "job_started_at": null, - "job_finished_at": null, - "job_duration": null, - "job_allow_failure": false, - "job_failure_reason": "script_failure", + "build_id": 1977, + "build_name": "test", + "build_stage": "test", + "build_status": "created", + "build_started_at": null, + "build_finished_at": null, + "build_duration": null, + "build_allow_failure": false, + "build_failure_reason": "script_failure", "project_id": 380, "project_name": "gitlab-org/gitlab-test", "user": { diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index eaca5f8cfb8..519c02cf0ad 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -13,7 +13,7 @@ keeping everything in the same place, so that you don't need to jump between different platforms to organize your workflow. With GitLab Issue Boards, you organize your issues in lists that correspond to -their assigned labels, visualizing issues designed as cards throughout that lists. +their assigned labels, visualizing issues designed as cards throughout those lists. You define your process and GitLab organizes it for you. You add your labels then create the corresponding list to pull in your existing issues. When @@ -27,12 +27,9 @@ Issue Boards** (version introduced in GitLab 8.11 - August 2016). ### Advanced features of Issue Boards -With [GitLab Starter](https://about.gitlab.com/pricing/), you can create -[multiple issue boards](#multiple-issue-boards-starter) for a given project. **(STARTER)** - -With [GitLab Premium](https://about.gitlab.com/pricing/), you can also create multiple -issue boards for your groups, and add lists for [assignees](#assignee-lists-premium) and -[milestones](#milestone-lists-premium). **(PREMIUM)** +- Create multiple issue boards per project. +- Create multiple issue boards per group. **(PREMIUM)** +- Add lists for [assignees](#assignee-lists-premium) and [milestones](#milestone-lists-premium). **(PREMIUM)** Check all the [advanced features of Issue Boards](#gitlab-enterprise-features-for-issue-boards) below. @@ -58,8 +55,7 @@ You create issues, host code, perform reviews, build, test, and deploy from one single platform. Issue Boards help you to visualize and manage the entire process _in_ GitLab. -With [Multiple Issue Boards](#use-cases-for-multiple-issue-boards), available -only in [different tiers of GitLab Enterprise Edition](#gitlab-enterprise-features-for-issue-boards), +With [Multiple Issue Boards](#use-cases-for-multiple-issue-boards), you go even further, as you can not only keep yourself and your project organized from a broader perspective with one Issue Board per project, but also allow your team members to organize their own workflow by creating @@ -88,7 +84,7 @@ If we have the labels "**backend**", "**frontend**", "**staging**", and "**production**", and an Issue Board with a list for each, we can: - Visualize the entire flow of implementations since the - beginning of the development lifecycle until deployed to production + beginning of the development life cycle until deployed to production - Prioritize the issues in a list by moving them vertically - Move issues between lists to organize them according to the labels you've set - Add multiple issues to lists in the board by selecting one or more existing issues @@ -97,8 +93,7 @@ If we have the labels "**backend**", "**frontend**", "**staging**", and ### Use cases for Multiple Issue Boards -With [Multiple Issue Boards](#multiple-issue-boards-starter), available only in -[GitLab Enterprise Edition](https://about.gitlab.com/pricing/), +With [Multiple Issue Boards](#multiple-issue-boards), each team can have their own board to organize their workflow individually. #### Scrum team @@ -159,13 +154,14 @@ Issue Board, that is, create or delete lists and drag issues from one list to an GitLab Issue Boards are available on GitLab Core and GitLab.com Free, but some advanced functionalities are only present in higher tiers: GitLab.com Bronze, Silver, or Gold, or GitLab self-managed Starter, Premium, and Ultimate, as described -on the following sections. +in the following sections. For a collection of [features per tier](#summary-of-features-per-tier), check the summary below. -### Multiple Issue Boards **(STARTER)** +### Multiple Issue Boards -> Introduced in [GitLab Enterprise Edition 8.13](https://about.gitlab.com/2016/10/22/gitlab-8-13-released/#multiple-issue-boards-ee). +> - Multiple Issue Boards per project [moved](https://gitlab.com/gitlab-org/gitlab-ce/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. +> - Multiple Issue Boards per group is available in [GitLab Premium Edition](https://about.gitlab.com/pricing/). Multiple Issue Boards, as the name suggests, allow for more than one Issue Board for a given project or group. This is great for large projects with more than one team @@ -184,10 +180,6 @@ These are shortcuts to your last 4 visited boards. When you're revisiting an issue board in a project or group with multiple boards, GitLab will automatically load the last board you visited. -NOTE: **Note:** -The Multiple Issue Boards feature is available for -**projects in GitLab Starter Edition** and for **groups in GitLab Premium Edition**. - ### Configurable Issue Boards **(STARTER)** > Introduced in [GitLab Starter Edition 10.2](https://about.gitlab.com/2017/11/22/gitlab-10-2-released/#issue-boards-configuration). diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index bffbcb544e3..1324a90e00b 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -35,9 +35,19 @@ to be enabled: ## Limitations -- Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tiff` or `ico`. The [`svg` extension is not yet supported](https://gitlab.com/gitlab-org/gitlab-ee/issues/12771). +- Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tiff` or `ico`. + The [`svg` extension is not yet supported](https://gitlab.com/gitlab-org/gitlab-ee/issues/12771). +- Design uploads are limited to 10 files at a time. - [Designs cannot yet be deleted](https://gitlab.com/gitlab-org/gitlab-ee/issues/11089). -- Design Management is [not yet supported in the project export](https://gitlab.com/gitlab-org/gitlab-ee/issues/11090). +- Design Management is + [not yet supported in the project export](https://gitlab.com/gitlab-org/gitlab-ee/issues/11090). +- Design Management data + [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab-ee/issues/13429) yet. +- Design Management data [won't be moved](https://gitlab.com/gitlab-org/gitlab-ee/issues/13426) + when an issue is moved, nor [deleted](https://gitlab.com/gitlab-org/gitlab-ee/issues/13427) + when an issue is deleted. +- Design Management + [isn't supported by Geo](https://gitlab.com/groups/gitlab-org/-/epics/1633) yet. ## The Design Management page diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index d7d168710ef..41a7ed09281 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -192,7 +192,7 @@ You can also click the `+` to add more related issues. #### 19. Related Merge Requests -Merge requests that were mentioned in that issue's description or in the issue thread +Merge requests that were mentioned in that issue's description or in the issue thread are listed as [related merge requests](crosslinking_issues.md#from-merge-requests) here. Also, if the current issue was mentioned as related in another merge request, that merge request will be listed here. diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 0fe86e6f410..6e31acf80bc 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -15,14 +15,14 @@ When you select **Manual** sorting, you can change the order by dragging and dropping the issues. The changed order will persist. Everyone who visits the same list will see the reordered list, with some exceptions. Each issue is assigned a relative order value, representing its relative -order with respect to the other issues in the list. When you drag-and-drop reorder +order with respect to the other issues in the list. When you drag-and-drop reorder an issue, its relative order value changes accordingly. In addition, any time that issue appears in a manually sorted list, the updated relative order value will be used for the ordering. This means that if issue `A` is drag-and-drop reordered to be above issue `B` by any user in a given list inside your GitLab instance, any time those two issues are subsequently -loaded in any list in the same instance (could be a different project issue list or a +loaded in any list in the same instance (could be a different project issue list or a different group issue list, for example), that ordering will be maintained. This ordering also affects [issue boards](../issue_board.md#issue-ordering-in-a-list). diff --git a/doc/user/project/members/img/access_requests_management.png b/doc/user/project/members/img/access_requests_management.png Binary files differindex 8996d9564d7..9a1c9621e41 100644 --- a/doc/user/project/members/img/access_requests_management.png +++ b/doc/user/project/members/img/access_requests_management.png diff --git a/doc/user/project/members/img/request_access_button.png b/doc/user/project/members/img/request_access_button.png Binary files differindex e8b490b91b8..e693f9a9ac2 100644 --- a/doc/user/project/members/img/request_access_button.png +++ b/doc/user/project/members/img/request_access_button.png diff --git a/doc/user/project/members/img/withdraw_access_request_button.png b/doc/user/project/members/img/withdraw_access_request_button.png Binary files differindex 6a3172dfcdb..e5a8fe0b356 100644 --- a/doc/user/project/members/img/withdraw_access_request_button.png +++ b/doc/user/project/members/img/withdraw_access_request_button.png diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index e343fd45488..21016dca358 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -79,8 +79,15 @@ side of your screen.  -Project owners & maintainers will be notified of your request and will be able to approve or -decline it on the members page. +Once access is requested: + +- Up to ten project maintainers are notified of your request via email. + Email is sent to the most recently active project maintainers. +- Any project maintainer can approve or decline your request on the members page. + +NOTE: **Note:** +If a project does not have any maintainers, the notification is sent to the +most recently active owners of the project's group.  diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index e94125e658d..a88fb4fc6f8 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -4,8 +4,7 @@ type: reference, howto # Allow collaboration on merge requests across forks -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17395) - in GitLab 10.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17395) in GitLab 10.6. When a user opens a merge request from a fork, they are given the option to allow upstream members to collaborate with them on the source branch. This allows diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index 4f3c68090e4..2d59e535ce1 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -15,7 +15,7 @@ to accept merge requests without creating merge commits. When the fast-forward merge ([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting is enabled, no merge commits will be created and all merges are fast-forwarded, -which means that merging is only allowed if the branch could be fast-forwarded. +which means that merging is only allowed if the branch can be fast-forwarded. When a fast-forward merge is not possible, the user is given the option to rebase. @@ -28,9 +28,15 @@ When a fast-forward merge is not possible, the user is given the option to rebas Now, when you visit the merge request page, you will be able to accept it **only if a fast-forward merge is possible**. + + +If a fast-forward merge is not possible but a conflict free rebase is possible, +a rebase button will be offered. +  -If the target branch is ahead of the source branch, you need to rebase the +If the target branch is ahead of the source branch and a conflict free rebase is +not possible, you need to rebase the source branch locally before you will be able to do a fast-forward merge.  diff --git a/doc/user/project/merge_requests/img/approvals_premium_project_edit.png b/doc/user/project/merge_requests/img/approvals_premium_project_edit.png Binary files differdeleted file mode 100644 index 6a09412533f..00000000000 --- a/doc/user/project/merge_requests/img/approvals_premium_project_edit.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_3.png b/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_3.png Binary files differnew file mode 100644 index 00000000000..bbb131e86e9 --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_3.png diff --git a/doc/user/project/merge_requests/img/cross-project-dependencies-edit-inaccessible.png b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_inaccessible_v12_2.png Binary files differindex 2dc02634fd8..2dc02634fd8 100644 --- a/doc/user/project/merge_requests/img/cross-project-dependencies-edit-inaccessible.png +++ b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_inaccessible_v12_2.png diff --git a/doc/user/project/merge_requests/img/cross-project-dependencies-edit.png b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_v12_2.png Binary files differindex 362e7e0ead2..362e7e0ead2 100644 --- a/doc/user/project/merge_requests/img/cross-project-dependencies-edit.png +++ b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_v12_2.png diff --git a/doc/user/project/merge_requests/img/cross-project-dependencies-view.png b/doc/user/project/merge_requests/img/cross_project_dependencies_view_v12_2.png Binary files differindex e00231c839b..e00231c839b 100644 --- a/doc/user/project/merge_requests/img/cross-project-dependencies-view.png +++ b/doc/user/project/merge_requests/img/cross_project_dependencies_view_v12_2.png diff --git a/doc/user/project/merge_requests/img/ff_merge_mr.png b/doc/user/project/merge_requests/img/ff_merge_mr.png Binary files differnew file mode 100644 index 00000000000..241cc990343 --- /dev/null +++ b/doc/user/project/merge_requests/img/ff_merge_mr.png diff --git a/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png b/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png Binary files differnew file mode 100644 index 00000000000..ee94dbdea5c --- /dev/null +++ b/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 8a82b163481..a94057dc3a1 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -41,7 +41,7 @@ With **[GitLab Enterprise Edition][ee]**, you can also: - View the deployment process across projects with [Multi-Project Pipelines](../../../ci/multi_project_pipelines.md) **(PREMIUM)** - Request [approvals](merge_request_approvals.md) from your managers **(STARTER)** - Analyze the impact of your changes with [Code Quality reports](code_quality.md) **(STARTER)** -- Manage the licenses of your dependencies with [License Management](../../application_security/license_management/index.md) **(ULTIMATE)** +- Manage the licenses of your dependencies with [License Compliance](../../application_security/license_compliance/index.md) **(ULTIMATE)** - Analyze your source code for vulnerabilities with [Static Application Security Testing](../../application_security/sast/index.md) **(ULTIMATE)** - Analyze your running web applications for vulnerabilities with [Dynamic Application Security Testing](../../application_security/dast/index.md) **(ULTIMATE)** - Analyze your dependencies for vulnerabilities with [Dependency Scanning](../../application_security/dependency_scanning/index.md) **(ULTIMATE)** @@ -57,7 +57,7 @@ A. Consider you are a software developer working in a team: 1. You gather feedback from your team 1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md) **(STARTER)** 1. You verify your changes with [JUnit test reports](../../../ci/junit_test_reports.md) in GitLab CI/CD -1. You avoid using dependencies whose license is not compatible with your project with [License Management reports](license_management.md) **(ULTIMATE)** +1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../application_security/license_compliance/index.md) **(ULTIMATE)** 1. You request the [approval](#merge-request-approvals-starter) from your manager 1. Your manager pushes a commit with their final review, [approves the merge request](merge_request_approvals.md), and set it to [merge when pipeline succeeds](#merge-when-pipeline-succeeds) (Merge Request Approvals are available in GitLab Starter) 1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD @@ -497,6 +497,15 @@ list.  +### Incrementally expand merge request diffs + +By default, the diff shows only the parts of a file which are changed. +To view more unchanged lines above or below a change click on the +**Expand up** or **Expand down** icons. You can also click on **Show all lines** +to expand the entire file. + + + ## Ignore whitespace changes in Merge Request diff view If you click the **Hide whitespace changes** button, you can see the diff diff --git a/doc/user/project/merge_requests/license_management.md b/doc/user/project/merge_requests/license_management.md index 93116ebd7c6..df5bd073ade 100644 --- a/doc/user/project/merge_requests/license_management.md +++ b/doc/user/project/merge_requests/license_management.md @@ -1,5 +1,5 @@ --- -redirect_to: '../../application_security/license_management/index.md' +redirect_to: '../../application_security/license_compliance/index.md' --- -This document was moved to [another location](../../application_security/license_management/index.md). +This document was moved to [another location](../../application_security/license_compliance/index.md). diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 5161b25de99..ca9ddd91e0d 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -83,7 +83,7 @@ request approval rules: 1. Give the approval rule a name that describes the set of approvers selected. 1. Click **Add approvers** to submit the new rule. -  +  ## Multiple approval rules **(PREMIUM)** @@ -330,7 +330,7 @@ the dropdown) `approver` and select the user. Merge Request Approvals can be configured to require approval from a member of your security team when a vulnerability would be introduced by a merge request. -For more information, see +For more information, see [Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests-ultimate). <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index e046b3466c4..b30e24b2386 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -2,9 +2,9 @@ type: reference, concepts --- -# Cross-project merge request dependencies **(PREMIUM)** +# Cross-project Merge Request dependencies **(PREMIUM)** -> Introduced in GitLab Premium 12.2 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9688) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. Cross-project merge request dependencies allows a required order of merging between merge requests in different projects to be expressed. If a @@ -24,11 +24,11 @@ merge requests in the same project cannot depend on each other. ## Use cases - Ensure changes to a library are merged before changes to a project that - imports the library + imports the library. - Prevent a documentation-only merge request from being merged before the merge request - implementing the feature to be documented + implementing the feature to be documented. - Require an merge request updating a permissions matrix to be merged before merging an - merge request from someone who hasn't yet been granted permissions + merge request from someone who hasn't yet been granted permissions. It is common for a single logical change to span several merge requests, spread out across multiple projects, and the order in which they are merged can be @@ -60,33 +60,33 @@ new merge request in `awesome-project` (or by editing it, if it already exists). The dependency needs to be configured on the **dependent** merge request. There is a "Cross-project dependencies" section in the form: - + Anyone who can edit a merge request can change the list of dependencies. New dependencies can be added by reference, or by URL. To remove a dependency, -press the "X" by its reference. +press the **X** by its reference. As dependencies are specified across projects, it's possible that someone else has added a dependency for a merge request in a project you don't have access to. These are shown as a simple count: - + -If necessary, you can remove all the dependencies like this by pressing the "X", -just as you would for a single, visible dependency. +If necessary, you can remove all the dependencies like this by pressing the +**X**, just as you would for a single, visible dependency. -Once you're finished, press the "Save changes" button to submit the request, or -"Cancel" to return without making any changes. +Once you're finished, press the **Save changes** button to submit the request, +or **Cancel** to return without making any changes. The list of configured dependencies, and the status of each one, is shown in the merge request widget: - + -Until all dependencies have, themselves, been merged, the "Merge" +Until all dependencies have, themselves, been merged, the **Merge** button will be disabled for the dependent merge request. In -particular, note that **closed** merge request still prevent their +particular, note that **closed merge requests** still prevent their dependents from being merged - it is impossible to automatically determine whether the dependency expressed by a closed merge request has been satisfied in some other way or not. diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 03ae24242e3..8606d92f20c 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -28,13 +28,13 @@ 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 -as created be the pusher (local push or via the UI) and any job created in this +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. This allows us to make it really easy to evaluate the access for all projects that have [Git submodules][gitsub] or are using container images that the pusher -would have access too. **The permission is granted only for time that job is -running. The access is revoked after the job is finished.** +would have access too. **The permission is granted only for the time that the job +is running. The access is revoked after the job is finished.** ## Types of users @@ -74,7 +74,7 @@ We try to make sure that this token doesn't leak by: 1. Securing all API endpoints to not expose the job token. 1. Masking the job token from job logs. -1. Allowing to use the job token **only** when job is running. +1. Granting permissions to the job token **only** when the job is running. However, this brings a question about the Runners security. To make sure that this token doesn't leak, you should also make sure that you configure @@ -86,12 +86,6 @@ your Runners in the most possible secure way, by avoiding the following: By using an insecure GitLab Runner configuration, you allow the rogue developers to steal the tokens of other jobs. -## Pipeline triggers - -Since 9.0 [pipeline triggers][triggers] do support the new permission model. -The new triggers do impersonate their associated user including their access -to projects and their project permissions. - ## Before GitLab 8.12 In versions before GitLab 8.12, all CI jobs would use the CI Runner's token @@ -203,7 +197,7 @@ Container Registries for private projects. > **Notes:** > > - GitLab Runner versions prior to 1.8 don't incorporate the introduced changes -> for permissions. This makes the `image:` directive to not work with private +> for permissions. This makes the `image:` directive not work with private > projects automatically and it needs to be configured manually on Runner's host > with a predefined account (for example administrator's personal account with > access token created explicitly for this purpose). This issue is resolved with @@ -227,11 +221,22 @@ test: - docker run $CI_REGISTRY/group/other-project:latest ``` +### Pipeline triggers + +Since 9.0 [pipeline triggers][triggers] do support the new permission model. +The new triggers do impersonate their associated user including their access +to projects and their project permissions. + +### API + +GitLab API cannot be used via `CI_JOB_TOKEN` but there is a [proposal](https://gitlab.com/gitlab-org/gitlab-ce/issues/29566) +to support it. + [job permissions]: ../permissions.md#job-permissions [comment]: https://gitlab.com/gitlab-org/gitlab-ce/issues/22484#note_16648302 [gitsub]: ../../ci/git_submodules.md [https]: ../admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols -[triggers]: ../../ci/triggers/README.md +[triggers]: ../../ci/triggers/README.md#ci-job-token [update-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update [workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse [jobenv]: ../../ci/variables/README.md#predefined-environment-variables diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md index 19ccde6e16a..6536a1a0a4b 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -85,7 +85,7 @@ NOTE: **NOTE** We'd highly recommend you to use the [Environment](../../../ci/environments.md) feature in order to quickly assess which flag is enabled per environment. -## Rollout Strategy +## Rollout strategy > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8240) in GitLab 12.2. @@ -97,20 +97,38 @@ However, a feature will be enabled for 50% of logged-in users if the matching en ### All users -Enables the feature for all users. - -**All users** is implemented using the Unleash [default](https://unleash.github.io/docs/activation_strategy#default) activation strategy. +Enables the feature for all users. It is implemented using the Unleash +[`default`](https://unleash.github.io/docs/activation_strategy#default) +activation strategy. ### Percent rollout (logged in users) -**Percent rollout (logged in users)** enables the feature for a percentage of authenticated users. Set a value of 15%, for example, to enable the feature for 15% of authenticated users. +Enables the feature for a percentage of authenticated users. It is +implemented using the Unleash +[`gradualRolloutUserId`](https://unleash.github.io/docs/activation_strategy#gradualrolloutuserid) +activation strategy. + +Set a value of 15%, for example, to enable the feature for 15% of authenticated users. A rollout percentage may be between 0% and 100%. CAUTION: **Caution:** -If this strategy is selected, then the Unleash client **must** be given a user id for the feature to be enabled. See the [Ruby example](#ruby-application-example) below. +If this strategy is selected, then the Unleash client **must** be given a user +ID for the feature to be enabled. See the [Ruby example](#ruby-application-example) below. + +## Target users + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8240) in GitLab 12.2. + +A feature flag may be enabled for a list of target users. It is implemented +using the Unleash [`userWithId`](https://unleash.github.io/docs/activation_strategy#userwithid) +activation strategy. -**Percent rollout (logged in users)** is implemented using the Unleash [gradualRolloutUserId](https://unleash.github.io/docs/activation_strategy#gradualrolloutuserid) activation strategy. + + +CAUTION: **Caution:** +The Unleash client **must** be given a user ID for the feature to be enabled for +target users. See the [Ruby example](#ruby-application-example) below. ## Integrating with your application @@ -207,7 +225,7 @@ func main() { Here's an example of how to integrate the feature flags in a Ruby application. -The Unleash client is given a user id for use with a **Percent rollout (logged in users)** rollout strategy. +The Unleash client is given a user id for use with a **Percent rollout (logged in users)** rollout strategy or a list of **Target Users**. ```ruby #!/usr/bin/env ruby diff --git a/doc/user/project/operations/img/target_users_v12_2.png b/doc/user/project/operations/img/target_users_v12_2.png Binary files differnew file mode 100644 index 00000000000..c88d2b7be97 --- /dev/null +++ b/doc/user/project/operations/img/target_users_v12_2.png diff --git a/doc/user/project/operations/tracing.md b/doc/user/project/operations/tracing.md index b92d2e49839..3fb3be3c21f 100644 --- a/doc/user/project/operations/tracing.md +++ b/doc/user/project/operations/tracing.md @@ -17,8 +17,8 @@ systems. ### Deploying Jaeger To learn more about deploying Jaeger, read the official -[Getting Started documentation](https://www.jaegertracing.io/docs/1.13/getting-started/). -There is an easy to use [all-in-one Docker image](https://www.jaegertracing.io/docs/1.13/getting-started/#AllinoneDockerimage), +[Getting Started documentation](https://www.jaegertracing.io/docs/latest/getting-started/). +There is an easy to use [all-in-one Docker image](https://www.jaegertracing.io/docs/latest/getting-started/#AllinoneDockerimage), as well as deployment options for [Kubernetes](https://github.com/jaegertracing/jaeger-kubernetes) and [OpenShift](https://github.com/jaegertracing/jaeger-openshift). @@ -27,7 +27,7 @@ and [OpenShift](https://github.com/jaegertracing/jaeger-openshift). GitLab provides an easy way to open the Jaeger UI from within your project: 1. [Set up Jaeger](#deploying-jaeger) and configure your application using one of the - [client libraries](https://www.jaegertracing.io/docs/1.13/client-libraries/). + [client libraries](https://www.jaegertracing.io/docs/latest/client-libraries/). 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 diff --git a/doc/user/project/packages/maven_repository.md b/doc/user/project/packages/maven_repository.md index c61402afb2c..491ebc0c068 100644 --- a/doc/user/project/packages/maven_repository.md +++ b/doc/user/project/packages/maven_repository.md @@ -1,7 +1,6 @@ # GitLab Maven Repository **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5811) in - [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5811) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. With the GitLab [Maven](https://maven.apache.org) Repository, every project can have its own space to store its Maven artifacts. diff --git a/doc/user/project/packages/npm_registry.md b/doc/user/project/packages/npm_registry.md index e01bac6b26f..48186688da9 100644 --- a/doc/user/project/packages/npm_registry.md +++ b/doc/user/project/packages/npm_registry.md @@ -1,7 +1,6 @@ # GitLab NPM Registry **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5934) - in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. With the GitLab NPM Registry, every project can have its own space to store NPM packages. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 3b80370d4a9..dc75eb450a3 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -92,4 +92,4 @@ You can have one DNS record or more than one combined: - `example.com` => `A` => `192.192.192.192` - `www` => `CNAME` => `example.com` - `MX` => `mail.example.com` -- `example.com`=> TXT => `"google-site-verification=6P08Ow5E-8Q0m6vQ7FMAqAYIDprkVV8fUf_7hZ4Qvc8"`
\ No newline at end of file +- `example.com`=> TXT => `"google-site-verification=6P08Ow5E-8Q0m6vQ7FMAqAYIDprkVV8fUf_7hZ4Qvc8"` diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 255d535645d..ffd9bc04c3e 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -21,6 +21,9 @@ such as [#64870](https://gitlab.com/gitlab-org/gitlab-ce/issues/64870). See all the related issues linked from this [issue's description](https://gitlab.com/gitlab-org/gitlab-ce/issues/28996) for more information. +Note: **Note:** +Using this feature requires **2 IP addresses** to be configured to the machine. + ## Requirements Before you can enable automatic provisioning of a SSL certificate for your domain, make sure you have: diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 6d538ca2455..45fdab1ca3a 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -100,4 +100,4 @@ _Read on about [Projects for GitLab Pages and URL structure](getting_started_par - Read through this technical overview on [Static versus Dynamic Websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) - Understand [how modern Static Site Generators work](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/) and what you can add to your static site - You can use [any SSG with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) -- Fork an [example project](https://gitlab.com/pages) to build your website based upon
\ No newline at end of file +- Fork an [example project](https://gitlab.com/pages) to build your website based upon diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index a0bc10b0ed7..a9fd6544e64 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -106,12 +106,14 @@ To get started with GitLab Pages, you can either: 1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your site to the server. -1. Once the pipeline has finished successfully, find the link to visit your - website from your project's **Settings > Pages**. +1. After the pipeline has finished successfully, wait approximately 30 minutes + for your website to be visible. After waiting 30 minutes, find the link to + visit your website from your project's **Settings > Pages**. If the link + leads to a 404 page, wait a few minutes and try again. -Your website is then visible on your domain, and you can modify yourfiles +Your website is then visible on your domain and you can modify your files as you wish. For every modification pushed to your repository, GitLab CI/CD -will run a new pipeline to publish your changes to the server. +will run a new pipeline to immediately publish your changes to the server. _Advanced options:_ diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index 456209c2180..78b6d202b32 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -107,11 +107,11 @@ in the pipelines settings page. ### Removing color codes Some test coverage tools output with ANSI color codes that won't be -parsed correctly by the regular expression and will cause coverage -parsing to fail. +parsed correctly by the regular expression and will cause coverage +parsing to fail. If your coverage tool doesn't provide an option to disable color -codes in the output, you can pipe the output of the coverage tool through a +codes in the output, you can pipe the output of the coverage tool through a small one line script that will strip the color codes off. For example: diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 7a79cdbcaee..8423b962948 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -34,11 +34,11 @@ that the `master` branch is protected by default. 1. From the **Branch** dropdown menu, select the branch you want to protect and click **Protect**. In the screenshot below, we chose the `develop` branch. -  +  1. Once done, the protected branch will appear in the "Protected branches" list. -  +  ## Using the Allowed to merge and Allowed to push settings @@ -65,7 +65,7 @@ You can set the "Allowed to push" and "Allowed to merge" options while creating a protected branch or afterwards by selecting the option you want from the dropdown list in the "Already protected" area. - + If you don't choose any of those options while creating a protected branch, they are set to "Maintainers" by default. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 5cc3b8a7fc3..9651c8824ab 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -24,15 +24,15 @@ To protect a tag, you need to have at least Maintainer permission level. 1. From the **Tag** dropdown menu, select the tag you want to protect or type and click **Create wildcard**. In the screenshot below, we chose to protect all tags matching `v*`: -  +  1. From the **Allowed to create** dropdown, select who will have permission to create matching tags and then click **Protect**: -  +  1. Once done, the protected tag will appear in the **Protected tags** list: -  +  ## Wildcard protected tags diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 6758adf2b43..647250bd02a 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -40,18 +40,20 @@ discussions, and descriptions: | `/label ~label1 ~label2` | Add label(s). Label names can also start without ~ but mixed syntax is not supported. | ✓ | ✓ | | `/unlabel ~label1 ~label2` | Remove all or specific label(s)| ✓ | ✓ | | `/relabel ~label1 ~label2` | Replace existing label(s) with those specified | ✓ | ✓ | -| `/copy_metadata <#issue | !merge_request>` | Copy labels and milestone from other issue or merge request in the project | ✓ | ✓ | +| `/copy_metadata <#issue>` | Copy labels and milestone from another issue in the project | ✓ | ✓ | +| `/copy_metadata <!merge_request>` | Copy labels and milestone from another merge request in the project | ✓ | ✓ | | `/estimate <1w 3d 2h 14m>` | Set time estimate | ✓ | ✓ | | `/remove_estimate` | Remove time estimate | ✓ | ✓ | -| `/spend <time(1h 30m | -1h 5m)> <date(YYYY-MM-DD)>` | Add or subtract spent time; optionally, specify the date that time was spent on | ✓ | ✓ | +| `/spend <time(1h 30m)> <date(YYYY-MM-DD)>` | Add spent time; optionally, specify the date that time was spent on | ✓ | ✓ | +| `/spend <time(-1h 5m)> <date(YYYY-MM-DD)>` | Subtract spent time; optionally, specify the date that time was spent on | ✓ | ✓ | | `/remove_time_spent` | Remove time spent | ✓ | ✓ | | `/lock` | Lock the thread | ✓ | ✓ | | `/unlock` | Unlock the thread | ✓ | ✓ | -| `/due <in 2 days | this Friday | December 31st>`| Set due date | ✓ | | +| `/due <date>` | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | ✓ | | | `/remove_due_date` | Remove due date | ✓ | | -| `/weight <0 | 1 | 2 | ...>` | Set weight **(STARTER)** | ✓ | | +| `/weight <value>` | Set weight. Valid options for `<value>` include `0`, `1`, `2`, etc. **(STARTER)** | ✓ | | | `/clear_weight` | Clears weight **(STARTER)** | ✓ | | -| `/epic <&epic | group&epic | Epic URL>` | Add to epic **(ULTIMATE)** | ✓ | | +| `/epic <epic>` | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic` or `epic-URL`. **(ULTIMATE)** | ✓ | | | `/remove_epic` | Removes from epic **(ULTIMATE)** | ✓ | | | `/promote` | Promote issue to epic **(ULTIMATE)** | ✓ | | | `/confidential` | Make confidential | ✓ | | @@ -110,9 +112,9 @@ The following quick actions are applicable for epics threads and description: | `/label ~label1 ~label2` | Add label(s) | | `/unlabel ~label1 ~label2` | Remove all or specific label(s) | | `/relabel ~label1 ~label2` | Replace existing label(s) with those specified | -| `/child_epic <&epic | group&epic | Epic URL>` | Adds child epic to epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-ee/issues/7330)) | -| `/remove_child_epic <&epic | group&epic | Epic URL>` | Removes child epic from epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-ee/issues/7330)) | -| `/parent_epic <&epic | group&epic | Epic URL>` | Sets parent epic to epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ee/issues/10556)) | +| `/child_epic <epic>` | Adds child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic` or `epic-URL`. ([Introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-ee/issues/7330)) **(ULTIMATE)**| +| `/remove_child_epic <epic>` | Removes child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic` or `epic-URL`. ([Introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-ee/issues/7330)) **(ULTIMATE)** | +| `/parent_epic <epic>` | Sets parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic` or `epic-URL`. ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ee/issues/10556)) **(ULTIMATE)** | | `/remove_parent_epic` | Removes parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ee/issues/10556)) | <!-- ## Troubleshooting diff --git a/doc/user/project/repository/img/repository_languages.png b/doc/user/project/repository/img/repository_languages.png Binary files differdeleted file mode 100644 index 5977ad7faae..00000000000 --- a/doc/user/project/repository/img/repository_languages.png +++ /dev/null diff --git a/doc/user/project/repository/img/repository_languages_v12_2.gif b/doc/user/project/repository/img/repository_languages_v12_2.gif Binary files differnew file mode 100644 index 00000000000..d0a0e57c919 --- /dev/null +++ b/doc/user/project/repository/img/repository_languages_v12_2.gif diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 84d63d29929..a838f06b2fd 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -73,7 +73,7 @@ according to the markup language. | [Markdown](../../markdown.md) | `mdown`, `mkd`, `mkdn`, `md`, `markdown` | | [reStructuredText](http://docutils.sourceforge.net/rst.html) | `rst` | | [AsciiDoc](../../asciidoc.md) | `adoc`, `ad`, `asciidoc` | -| [Textile](https://txstyle.org/) | `textile` | +| [Textile](https://textile-lang.com/) | `textile` | | [rdoc](http://rdoc.sourceforge.net/doc/index.html) | `rdoc` | | [Orgmode](https://orgmode.org/) | `org` | | [creole](http://www.wikicreole.org/) | `creole` | @@ -182,7 +182,7 @@ were used and display this on the projects pages. If this information is missing be added after updating the default branch on the project. This process can take up to 5 minutes. - + Not all files are detected, among others; documentation, vendored code, and most markup languages are excluded. This behaviour can be diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 4e3db95b6d6..58ccd8bf2ae 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -34,7 +34,7 @@ Issues or Merge Requests, both of which use Labels and Milestones, then you shou #### Disabling email notifications -You can disable all email notifications related to the project by selecting the +You can disable all email notifications related to the project by selecting the **Disable email notifications** checkbox. Only the project owner is allowed to change this setting. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index e3c6cd6d6ff..d1bab47de25 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -28,11 +28,12 @@ NOTE: **Note:** Requires Developer [permissions](../../permissions.md). Create a new page by clicking the **New page** button that can be found -in all wiki pages. You will be asked to fill in the page name from which GitLab -will create the path to the page. You can specify a full path for the new file -and any missing directories will be created automatically. +in all wiki pages. - +You will be asked to fill in a title for your new wiki page. Wiki titles +also determine the path to the wiki page. You can specify a full path +(using "`/`" for subdirectories) for the new title and any missing +directories will be created automatically. Once you enter the page name, it's time to fill in its content. GitLab wikis support Markdown, RDoc and AsciiDoc. For Markdown based pages, all the diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index 68532ccee65..45ece5f048e 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -14,27 +14,27 @@ For a list of words that are not allowed to be used as group or project names, s It is currently not possible to create a project with the following names: -- \- -- badges -- blame -- blob -- builds -- commits -- create -- create_dir -- edit -- environments/folders -- files -- find_file -- gitlab-lfs/objects -- info/lfs/objects -- new -- preview -- raw -- refs -- tree -- update -- wikis +- `\-` +- `badges` +- `blame` +- `blob` +- `builds` +- `commits` +- `create` +- `create_dir` +- `edit` +- `environments/folders` +- `files` +- `find_file` +- `gitlab-lfs/objects` +- `info/lfs/objects` +- `new` +- `preview` +- `raw` +- `refs` +- `tree` +- `update` +- `wikis` ## Reserved group names diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md index c3d22e4fd29..d65dd32fe11 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search_syntax.md @@ -1,6 +1,7 @@ # Advanced Syntax Search **(STARTER ONLY)** > **Notes:** +> > - Introduced in [GitLab Enterprise Starter][ee] 9.2 > - This is the user documentation. To install and configure Elasticsearch, > visit the [administrator documentation](../../integration/elasticsearch.md). diff --git a/doc/workflow/forking/branch_select.png b/doc/workflow/forking/branch_select.png Binary files differindex 77236137190..0ea5410f832 100644 --- a/doc/workflow/forking/branch_select.png +++ b/doc/workflow/forking/branch_select.png diff --git a/doc/workflow/forking/merge_request.png b/doc/workflow/forking/merge_request.png Binary files differindex 407ddfb4799..43851203f3f 100644 --- a/doc/workflow/forking/merge_request.png +++ b/doc/workflow/forking/merge_request.png diff --git a/doc/workflow/forking_workflow.md b/doc/workflow/forking_workflow.md index 869a0a621c3..82c2709143d 100644 --- a/doc/workflow/forking_workflow.md +++ b/doc/workflow/forking_workflow.md @@ -10,8 +10,7 @@ document more information about using branches to work together. Forking a project is in most cases a two-step process. -1. Click on the fork button located in the middle of the page or a project's - home page right next to the stars button. +1. Click on the fork button located located in between the star and clone buttons on the project's home page.  @@ -25,7 +24,7 @@ Forking a project is in most cases a two-step process. **Note:** If the namespace you chose to fork the project to has another project with the same path name, you will be presented with a warning that the forking - could not be completed. Try to resolve the error and repeat the forking + could not be completed. Try to resolve the error before repeating the forking process.  @@ -44,7 +43,7 @@ create the [merge request](merge_requests.md).  You can then assign the merge request to someone to have them review -your changes. Upon pressing the 'Accept Merge Request' button, your +your changes. Upon pressing the 'Submit Merge Request' button, your changes will be added to the repository and branch you're merging into.  diff --git a/doc/workflow/git_annex.md b/doc/workflow/git_annex.md index 9543859f86f..c3865aa953b 100644 --- a/doc/workflow/git_annex.md +++ b/doc/workflow/git_annex.md @@ -2,7 +2,7 @@ > **Warning:** GitLab has [completely removed][deprecate-annex-issue] in GitLab 9.0 (2017/03/22). -Read through the [migration guide from git-annex to git-lfs][guide]. +Read through the [migration guide from git-annex to Git LFS][guide]. The biggest limitation of Git, compared to some older centralized version control systems, has been the maximum size of the repositories. @@ -51,7 +51,7 @@ sudo yum install epel-release && sudo yum install git-annex ### Configuration for Omnibus packages -For omnibus-gitlab packages, only one configuration setting is needed. +For Omnibus GitLab packages, only one configuration setting is needed. The Omnibus package will internally set the correct options in all locations. 1. In `/etc/gitlab/gitlab.rb` add the following line: @@ -67,7 +67,7 @@ The Omnibus package will internally set the correct options in all locations. There are 2 settings to enable git-annex on your GitLab server. One is located in `config/gitlab.yml` of the GitLab repository and the other -one is located in `config.yml` of gitlab-shell. +one is located in `config.yml` of GitLab Shell. 1. In `config/gitlab.yml` add or edit the following lines: @@ -76,7 +76,7 @@ one is located in `config.yml` of gitlab-shell. git_annex_enabled: true ``` -1. In `config.yml` of gitlab-shell add or edit the following lines: +1. In `config.yml` of GitLab Shell add or edit the following lines: ```yaml git_annex_enabled: true @@ -184,7 +184,7 @@ access files of projects you have access to (developer, maintainer, or owner rol Internally GitLab uses [GitLab Shell] to handle SSH access and this was a great integration point for `git-annex`. -There is a setting in gitlab-shell so you can disable GitLab Annex support +There is a setting in GitLab Shell so you can disable GitLab Annex support if you want to. ## Troubleshooting tips @@ -200,7 +200,7 @@ searching for your distribution. Although there is no general guide for `git-annex` errors, there are a few tips on how to go around the warnings. -### git-annex-shell: Not a git-annex or gcrypt repository. +### `git-annex-shell: Not a git-annex or gcrypt repository` This warning can appear on the initial `git annex sync --content` and is caused by differences in `git-annex-shell`. You can read more about it diff --git a/doc/workflow/img/forking_workflow_choose_namespace.png b/doc/workflow/img/forking_workflow_choose_namespace.png Binary files differindex b34b12090a1..eb023ca85f2 100644 --- a/doc/workflow/img/forking_workflow_choose_namespace.png +++ b/doc/workflow/img/forking_workflow_choose_namespace.png diff --git a/doc/workflow/img/forking_workflow_fork_button.png b/doc/workflow/img/forking_workflow_fork_button.png Binary files differindex 941d5363c35..7fb07529b6d 100644 --- a/doc/workflow/img/forking_workflow_fork_button.png +++ b/doc/workflow/img/forking_workflow_fork_button.png diff --git a/doc/workflow/img/forking_workflow_path_taken_error.png b/doc/workflow/img/forking_workflow_path_taken_error.png Binary files differindex df938da5677..ef62d0ab6a9 100644 --- a/doc/workflow/img/forking_workflow_path_taken_error.png +++ b/doc/workflow/img/forking_workflow_path_taken_error.png diff --git a/doc/workflow/issue_weight.md b/doc/workflow/issue_weight.md index a80519f0748..291646a430e 100644 --- a/doc/workflow/issue_weight.md +++ b/doc/workflow/issue_weight.md @@ -1,7 +1,6 @@ -# Issue Weight **(STARTER)** +# Issue weight **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/76) -> in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/76) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. When you have a lot of issues, it can be hard to get an overview. By adding a weight to each issue, you can get a better idea of how much time, diff --git a/doc/workflow/lfs/lfs_administration.md b/doc/workflow/lfs/lfs_administration.md index 3160b0c4deb..7e880b3009d 100644 --- a/doc/workflow/lfs/lfs_administration.md +++ b/doc/workflow/lfs/lfs_administration.md @@ -46,8 +46,7 @@ In `config/gitlab.yml`: ## Storing LFS objects in remote object storage -> [Introduced][ee-2760] in [GitLab Premium][eep] 10.0. Brought to GitLab Core -in 10.7. +> [Introduced][ee-2760] in [GitLab Premium][eep] 10.0. Brought to GitLab Core in 10.7. It is possible to store LFS objects in remote object storage which allows you to offload local hard disk R/W operations, and free up disk space significantly. @@ -91,7 +90,7 @@ Here is a configuration example with S3. | `aws_access_key_id` | AWS credentials, or compatible | `ABC123DEF456` | | `aws_secret_access_key` | AWS credentials, or compatible | `ABC123DEF456ABC123DEF456ABC123DEF456` | | `aws_signature_version` | AWS signature version to use. 2 or 4 are valid options. Digital Ocean Spaces and other providers may need 2. | 4 | -| `enable_signature_v4_streaming` | Set to true to enable HTTP chunked transfers with AWS v4 signatures (https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html). Oracle Cloud S3 needs this to be false | true +| `enable_signature_v4_streaming` | Set to true to enable HTTP chunked transfers with [AWS v4 signatures](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html). Oracle Cloud S3 needs this to be false | true | | `region` | AWS region | us-east-1 | | `host` | S3 compatible host for when not using AWS, e.g. `localhost` or `storage.example.com` | s3.amazonaws.com | | `endpoint` | Can be used when configuring an S3 compatible service such as [Minio](https://www.minio.io), by entering a URL such as `http://127.0.0.1:9000` | (optional) | @@ -107,7 +106,9 @@ Here is a configuration example with GCS. | `google_client_email` | The email address of the service account | `foo@gcp-project-12345.iam.gserviceaccount.com` | | `google_json_key_location` | The json key path | `/path/to/gcp-project-12345-abcde.json` | -_NOTE: The service account must have permission to access the bucket. [See more](https://cloud.google.com/storage/docs/authentication)_ +NOTE: **Note:** +The service account must have permission to access the bucket. +[See more](https://cloud.google.com/storage/docs/authentication) Here is a configuration example with Rackspace Cloud Files. @@ -119,7 +120,13 @@ Here is a configuration example with Rackspace Cloud Files. | `rackspace_region` | The Rackspace storage region to use, a three letter code from the [list of service access endpoints](https://developer.rackspace.com/docs/cloud-files/v1/general-api-info/service-access/) | `iad` | | `rackspace_temp_url_key` | The private key you have set in the Rackspace API for temporary URLs. Read more [here](https://developer.rackspace.com/docs/cloud-files/v1/use-cases/public-access-to-your-cloud-files-account/#tempurl) | `ABC123DEF456ABC123DEF456ABC123DE` | -_NOTES: Regardless of whether the container has public access enabled or disabled, Fog will use the TempURL method to grant access to LFS objects. If you see errors in logs referencing instantiating storage with a temp-url-key, ensure that you have set they key properly on the Rackspace API and in gitlab.rb. You can verify the value of the key Rackspace has set by sending a GET request with token header to the service access endpoint URL and comparing the output of the returned headers._ +NOTE: **Note:** +Regardless of whether the container has public access enabled or disabled, Fog will +use the TempURL method to grant access to LFS objects. If you see errors in logs referencing +instantiating storage with a temp-url-key, ensure that you have set they key properly +on the Rackspace API and in gitlab.rb. You can verify the value of the key Rackspace +has set by sending a GET request with token header to the service access endpoint URL +and comparing the output of the returned headers. ### Manual uploading to an object storage @@ -167,13 +174,13 @@ On Omnibus installations, the settings are prefixed by `lfs_object_store_`: 1. Save the file and [reconfigure GitLab]s for the changes to take effect. 1. Migrate any existing local LFS objects to the object storage: - ```bash - gitlab-rake gitlab:lfs:migrate - ``` + ```bash + gitlab-rake gitlab:lfs:migrate + ``` - This will migrate existing LFS objects to object storage. New LFS objects - will be forwarded to object storage unless - `gitlab_rails['lfs_object_store_background_upload']` is set to false. + This will migrate existing LFS objects to object storage. New LFS objects + will be forwarded to object storage unless + `gitlab_rails['lfs_object_store_background_upload']` is set to false. ### S3 for installations from source @@ -203,13 +210,13 @@ For source installations the settings are nested under `lfs:` and then 1. Save the file and [restart GitLab][] for the changes to take effect. 1. Migrate any existing local LFS objects to the object storage: - ```bash - sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production - ``` + ```bash + sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production + ``` - This will migrate existing LFS objects to object storage. New LFS objects - will be forwarded to object storage unless `background_upload` is set to - false. + This will migrate existing LFS objects to object storage. New LFS objects + will be forwarded to object storage unless `background_upload` is set to + false. ## Storage statistics diff --git a/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md b/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md index 264372a512d..f5593927cc2 100644 --- a/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md +++ b/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md @@ -35,9 +35,10 @@ Documentation for GitLab instance administrators is under [LFS administration do - Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have to add the URL to Git config manually (see [troubleshooting](#troubleshooting)) ->**Note**: With 8.12 GitLab added LFS support to SSH. The Git LFS communication - still goes over HTTP, but now the SSH client passes the correct credentials - to the Git LFS client, so no action is required by the user. +NOTE: **Note:** +With 8.12 GitLab added LFS support to SSH. The Git LFS communication +still goes over HTTP, but now the SSH client passes the correct credentials +to the Git LFS client, so no action is required by the user. ## Using Git LFS @@ -61,12 +62,13 @@ git commit -am "Added Debian iso" # commit the file meta data git push origin master # sync the git repo and large file to the GitLab server ``` -> **Note**: Make sure that `.gitattributes` is tracked by git. Otherwise Git -> LFS will not be working properly for people cloning the project. -> -> ```bash -> git add .gitattributes -> ``` +NOTE: **Note:** +**Make sure** that `.gitattributes` is tracked by Git. Otherwise Git +LFS will not be working properly for people cloning the project. + +```bash +git add .gitattributes +``` Cloning the repository works the same as before. Git automatically detects the LFS-tracked files and clones them via HTTP. If you performed the git clone @@ -216,9 +218,10 @@ git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs" ### Credentials are always required when pushing an object ->**Note**: With 8.12 GitLab added LFS support to SSH. The Git LFS communication - still goes over HTTP, but now the SSH client passes the correct credentials - to the Git LFS client, so no action is required by the user. +NOTE: **Note:** +With 8.12 GitLab added LFS support to SSH. The Git LFS communication +still goes over HTTP, but now the SSH client passes the correct credentials +to the Git LFS client, so no action is required by the user. Given that Git LFS uses HTTP Basic Authentication to authenticate the user pushing the LFS object on every push for every object, user HTTPS credentials are required. diff --git a/doc/workflow/lfs/migrate_from_git_annex_to_git_lfs.md b/doc/workflow/lfs/migrate_from_git_annex_to_git_lfs.md index 75673d23799..5ceeb3253f1 100644 --- a/doc/workflow/lfs/migrate_from_git_annex_to_git_lfs.md +++ b/doc/workflow/lfs/migrate_from_git_annex_to_git_lfs.md @@ -76,7 +76,7 @@ Here you'll find a guide on Since Annex files are stored as objects with symlinks and cannot be directly modified, we need to first remove those symlinks. ->**Note:** +NOTE: **Note:** Make sure the you read about the [`direct` mode][annex-direct] as it contains useful information that may fit in your use case. Note that `annex direct` is deprecated in Git Annex version 6, so you may need to upgrade your repository diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md index ccb8844aea3..5abae929355 100644 --- a/doc/workflow/notifications.md +++ b/doc/workflow/notifications.md @@ -53,7 +53,7 @@ These settings can be configured on group page under the name of the group. It w The group owner can disable email notifications for a group, which also includes it's subgroups and projects. If this is the case, you will not receive any corresponding notifications, -and the notification button will be disabled with an explanatory tooltip. +and the notification button will be disabled with an explanatory tooltip. ### Project Settings @@ -66,7 +66,7 @@ These settings can be configured on project page under the name of the project. The project owner (or it's group owner) can disable email notifications for the project. If this is the case, you will not receive any corresponding notifications, and the notification -button will be disabled with an explanatory tooltip. +button will be disabled with an explanatory tooltip. ## Notification events diff --git a/doc/workflow/releases.md b/doc/workflow/releases.md index 00cddda24a4..1fd63a556c6 100644 --- a/doc/workflow/releases.md +++ b/doc/workflow/releases.md @@ -3,20 +3,20 @@ NOTE: In GitLab 11.7, we introduced the full fledged [Releases](../user/project/releases/index.md) feature. You can still create release notes on this page, but the new method is preferred. -You can add release notes to any git tag using the notes feature. Release notes +You can add release notes to any Git tag using the notes feature. Release notes behave like any other markdown form in GitLab so you can write text and drag-n-drop files to it. Release notes are stored in GitLab's database. There are several ways to add release notes: -- In the interface, when you create a new git tag -- In the interface, by adding a note to an existing git tag +- In the interface, when you create a new Git tag +- In the interface, by adding a note to an existing Git tag - Using the GitLab API ## New tag page with release notes text area  -## Tags page with button to add or edit release notes for existing git tag +## Tags page with button to add or edit release notes for existing Git tag  diff --git a/doc/workflow/repository_mirroring.md b/doc/workflow/repository_mirroring.md index 0b8e7d851b0..753518d0424 100644 --- a/doc/workflow/repository_mirroring.md +++ b/doc/workflow/repository_mirroring.md @@ -37,8 +37,7 @@ The following are some possible use cases for repository mirroring: ## Pushing to a remote repository **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/249) in GitLab Enterprise -> Edition 8.7. [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715) in 10.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/249) in GitLab Enterprise Edition 8.7. [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715) in 10.8. For an existing project, you can set up push mirroring as follows: @@ -67,8 +66,7 @@ section. ### Push only protected branches **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3350) in -> [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715) in 10.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3350) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715) in 10.8. You can choose to only push your protected branches from GitLab to your remote repository. @@ -98,8 +96,7 @@ The repository will push soon. To force a push, click the appropriate button. ## Pulling from a remote repository **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/51) in GitLab Enterprise Edition 8.2. -> [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab-ee/issues/10871) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.11. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/51) in GitLab Enterprise Edition 8.2. [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab-ee/issues/10871) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.11. NOTE: **Note:** This feature [is available for free](https://gitlab.com/gitlab-org/gitlab-ee/issues/10361) to GitLab.com users until September 22nd, 2019. @@ -157,8 +154,7 @@ Repository mirrors are updated as Sidekiq becomes available to process them. If ### SSH authentication -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2551) for Pull mirroring in [GitLab Starter](https://about.gitlab.com/pricing/) 9.5. -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22982) for Push mirroring in [GitLab Core](https://about.gitlab.com/pricing/) 11.6 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2551) for Pull mirroring in [GitLab Starter](https://about.gitlab.com/pricing/) 9.5. [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22982) for Push mirroring in [GitLab Core](https://about.gitlab.com/pricing/) 11.6 SSH authentication is mutual: @@ -245,8 +241,7 @@ key to keep the mirror running. ### Overwrite diverged branches **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4559) in -> [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4559) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. You can choose to always update your local branches with remote versions, even if they have diverged from the remote. @@ -258,8 +253,7 @@ To use this option, check the **Overwrite diverged branches** box when creating ### Only mirror protected branches **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3326) in -> [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3326) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. You can choose to pull mirror only the protected branches from your remote repository to GitLab. Non-protected branches are not mirrored and can diverge. @@ -268,8 +262,7 @@ To use this option, check the **Only mirror protected branches** box when creati ### Hard failure **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3117) in -> [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3117) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. Once the mirroring process is unsuccessfully retried 14 times in a row, it will get marked as hard failed. This will become visible in either the: @@ -282,8 +275,7 @@ project mirroring again by [Forcing an update](#forcing-an-update-core). ### Trigger update using API **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3453) in -[GitLab Starter](https://about.gitlab.com/pricing/) 10.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3453) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. Pull mirroring uses polling to detect new branches and commits added upstream, often minutes afterwards. If you notify GitLab by [API](../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter), @@ -325,9 +317,10 @@ protected branches. ### Preventing conflicts using a `pre-receive` hook -> **Warning:** The solution proposed will negatively impact the performance of -> Git push operations because they will be proxied to the upstream Git -> repository. +CAUTION: **Warning:** +The solution proposed will negatively impact the performance of +Git push operations because they will be proxied to the upstream Git +repository. A server-side `pre-receive` hook can be used to prevent the race condition described above by only accepting the push after first pushing the commit to diff --git a/doc/workflow/time_tracking.md b/doc/workflow/time_tracking.md index fad853f8a44..3d9f015b1fe 100644 --- a/doc/workflow/time_tracking.md +++ b/doc/workflow/time_tracking.md @@ -84,4 +84,4 @@ With this option enabled, `75h` is displayed instead of `1w 4d 3h`. ## Other interesting links -- [Time Tracking landing page on about.gitlab.com](https://about.gitlab.com/solutions/time-tracking/) +- [Time Tracking landing page in the GitLab handbook](https://about.gitlab.com/solutions/time-tracking/) diff --git a/doc/workflow/timezone.md b/doc/workflow/timezone.md index 60a4d0f19de..4101f891484 100644 --- a/doc/workflow/timezone.md +++ b/doc/workflow/timezone.md @@ -17,7 +17,7 @@ For Omnibus installations, run `gitlab-rake time:zones:all`. NOTE: **Note:** Currently, this rake task does not list timezones in TZInfo format required by GitLab Omnibus during a reconfigure: [#58672](https://gitlab.com/gitlab-org/gitlab-ce/issues/58672). -## Changing time zone in omnibus installations +## Changing time zone in Omnibus installations GitLab defaults its time zone to UTC. It has a global timezone configuration parameter in `/etc/gitlab/gitlab.rb`. diff --git a/doc/workflow/todos.md b/doc/workflow/todos.md index 0432c406f31..211d242e2d3 100644 --- a/doc/workflow/todos.md +++ b/doc/workflow/todos.md @@ -35,8 +35,8 @@ A To Do displays on your To-Do List when: - You are `@mentioned` in a comment on a commit - A job in the CI pipeline running for your merge request failed, but this job is not allowed to fail -- An open merge request becomes unmergeable due to conflict, and you are either: - - The author +- An open merge request becomes unmergeable due to conflict, and you are either: + - The author - Have set it to automatically merge once the pipeline succeeds To-do triggers are not affected by [GitLab Notification Email settings](notifications.md). |
