diff options
| author | Filipa Lacerda <filipa@gitlab.com> | 2018-10-08 10:40:10 +0100 |
|---|---|---|
| committer | Filipa Lacerda <filipa@gitlab.com> | 2018-10-08 10:40:10 +0100 |
| commit | fa875ba7a9441df6827ef1d6b05405c66ee0c579 (patch) | |
| tree | 23d0cf911c9bf6a73fec9bb1f3de1bf61bedeacd /doc | |
| parent | ecefe090460687a078e3d1aacf621fd5bff07fb5 (diff) | |
| parent | 838c1076694d24d180e19625d663749c8b5c1a1c (diff) | |
| download | gitlab-ce-fa875ba7a9441df6827ef1d6b05405c66ee0c579.tar.gz | |
Merge branch 'master' into 42611-removed-branch-link
* master: (1252 commits)
Render log artifact files in GitLab
Check disabled_services when finding a service
Fix invalid parent path on group settings page
Backport CE changes for: [Frontend only] Batch comments on merge requests
Add button to insert table in markdown editor
Update GITALY_SERVER_VERSION
Updates Laravel.gitlab-ci.yml template
Update operations metrics empty state
Fix LFS uploaded images not being rendered
Prepare admin/projects/show view to allow EE specific feature
Add timed incremental rollout to Auto DevOps
Update spec comment to point to correct issue
Fix documentation for variables
Document Security and Licence Management features permissions
Fix time dependent jobs spec
Use a CTE to remove the query timeout
Backport changes from gitlab-ee!7538
Fix CE to EE merge (backport)
Add changelog entry
Refactor Feature.flipper method
...
Diffstat (limited to 'doc')
274 files changed, 6550 insertions, 3913 deletions
diff --git a/doc/README.md b/doc/README.md index 4248f62c08c..7548240bfef 100644 --- a/doc/README.md +++ b/doc/README.md @@ -191,7 +191,7 @@ instant how code changes impact your production environment. ### User account - [User account](user/profile/index.md): Manage your account - - [Authentication](topics/authentication/index.md): Account security with two-factor authentication, setup your ssh keys and deploy keys for secure access to your projects. + - [Authentication](topics/authentication/index.md): Account security with two-factor authentication, set up your ssh keys and deploy keys for secure access to your projects. - [Profile settings](user/profile/index.md#profile-settings): Manage your profile settings, two factor authentication and more. - [User permissions](user/permissions.md): Learn what each role in a project (external/guest/reporter/developer/maintainer/owner) can do. diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md index 3c98d683924..54ded25291a 100644 --- a/doc/administration/auth/ldap.md +++ b/doc/administration/auth/ldap.md @@ -111,7 +111,7 @@ main: uid: 'sAMAccountName' # This should be the attribute, not the value that maps to uid. ## - ## Examples: 'america\\momo' or 'CN=Gitlab Git,CN=Users,DC=mydomain,DC=com' + ## Examples: 'america\momo' or 'CN=Gitlab Git,CN=Users,DC=mydomain,DC=com' ## bind_dn: '_the_full_dn_of_the_user_you_will_bind_with' password: '_the_password_of_the_bind_user' @@ -132,7 +132,7 @@ main: ## Enables SSL certificate verification if encryption method is ## "start_tls" or "simple_tls". Defaults to true since GitLab 10.0 for ## security. This may break installations upon upgrade to 10.0, that did - ## not know their LDAP SSL certificates were not setup properly. + ## not know their LDAP SSL certificates were not set up properly. ## verify_certificates: true @@ -382,29 +382,30 @@ the configuration option `lowercase_usernames`. By default, this configuration o 1. Edit `/etc/gitlab/gitlab.rb`: - ```ruby - gitlab_rails['ldap_servers'] = YAML.load <<-EOS - main: - # snip... - lowercase_usernames: true - EOS - ``` + ```ruby + gitlab_rails['ldap_servers'] = YAML.load <<-EOS + main: + # snip... + lowercase_usernames: true + EOS + ``` -2. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. **Source configuration** 1. Edit `config/gitlab.yaml`: - ```yaml - production: - ldap: - servers: - main: - # snip... - lowercase_usernames: true - ``` -2. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. + ```yaml + production: + ldap: + servers: + main: + # snip... + lowercase_usernames: true + ``` + +1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. ## Encryption diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md index 2441ff85783..890b780fe80 100644 --- a/doc/administration/container_registry.md +++ b/doc/administration/container_registry.md @@ -1,11 +1,11 @@ # GitLab Container Registry administration > **Notes:** -- [Introduced][ce-4040] in GitLab 8.8. -- Container Registry manifest `v1` support was added in GitLab 8.9 to support - Docker versions earlier than 1.10. -- This document is about the admin guide. To learn how to use GitLab Container - Registry [user documentation](../user/project/container_registry.md). +> - [Introduced][ce-4040] in GitLab 8.8. +> - Container Registry manifest `v1` support was added in GitLab 8.9 to support +> Docker versions earlier than 1.10. +> - This document is about the admin guide. To learn how to use GitLab Container +> Registry [user documentation](../user/project/container_registry.md). With the Container Registry integrated into GitLab, every project can have its own space to store its Docker images. @@ -203,10 +203,10 @@ If you have a [wildcard certificate][], you need to specify the path to the certificate in addition to the URL, in this case `/etc/gitlab/gitlab.rb` will look like: > -```ruby -registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem" -registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key" -``` +> ```ruby +> registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem" +> registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key" +> ``` --- @@ -375,7 +375,7 @@ Read more about the individual driver's config options in the > **Warning** GitLab will not backup Docker images that are not stored on the filesystem. Remember to enable backups with your object storage provider if desired. - +> > **Important** Enabling storage driver other than `filesystem` would mean that your Docker client needs to be able to access the storage backend directly. So you must use an address that resolves and is accessible outside GitLab server. @@ -598,11 +598,11 @@ thus the error above. While GitLab doesn't support using self-signed certificates with Container Registry out of the box, it is possible to make it work if you follow -[Docker's documentation][docker-insecure]. You may find some additional +[Docker's documentation][docker-insecure-self-signed]. You may find some additional information in [issue 18239][ce-18239]. [ce-18239]: https://gitlab.com/gitlab-org/gitlab-ce/issues/18239 -[docker-insecure]: https://docs.docker.com/registry/insecure/#using-self-signed-certificates +[docker-insecure-self-signed]: https://docs.docker.com/registry/insecure/#use-self-signed-certificates [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure [restart gitlab]: restart_gitlab.md#installations-from-source [wildcard certificate]: https://en.wikipedia.org/wiki/Wildcard_certificate diff --git a/doc/administration/custom_hooks.md b/doc/administration/custom_hooks.md index 1c508c77ffa..9b0fabb9259 100644 --- a/doc/administration/custom_hooks.md +++ b/doc/administration/custom_hooks.md @@ -1,7 +1,6 @@ # Custom Git Hooks -> -**Note:** Custom Git hooks must be configured on the filesystem of the GitLab +> **Note:** Custom Git hooks must be configured on the filesystem of the GitLab server. Only GitLab server administrators will be able to complete these tasks. Please explore [webhooks] and [CI] as an option if you do not have filesystem access. For a user configurable Git hook interface, see diff --git a/doc/administration/external_database.md b/doc/administration/external_database.md index 31199f2cdc7..ec2d30c82d1 100644 --- a/doc/administration/external_database.md +++ b/doc/administration/external_database.md @@ -9,7 +9,7 @@ separate from the GitLab Omnibus package. If you use a cloud-managed service, or provide your own PostgreSQL instance: -1. Setup PostgreSQL according to the +1. Set up PostgreSQL according to the [database requirements document](../install/requirements.md#database). 1. Set up a `gitlab` username with a password of your choice. The `gitlab` user needs privileges to create the `gitlabhq_production` database. diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 6d7e408d41b..b5e2b5448f7 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -101,8 +101,13 @@ documentation on configuring Gitaly authentication](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/configuration/README.md#authentication) . -> -**NOTE:** In most or all cases the storage paths below end in `/repositories` which is +Gitaly must trigger some callbacks to GitLab via GitLab Shell. As a result, +the GitLab Shell secret must be the same between the other GitLab servers and +the Gitaly server. The easiest way to accomplish this is to copy `/etc/gitlab/gitlab-secrets.json` +from an existing GitLab server to the Gitaly server. Without this shared secret, +Git operations in GitLab will result in an API error. + +> **NOTE:** In most or all cases the storage paths below end in `/repositories` which is different than `path` in `git_data_dirs` of Omnibus installations. Check the directory layout on your Gitaly server to be sure. @@ -149,7 +154,7 @@ listen_addr = '0.0.0.0:8075' [auth] token = 'abc123secret' -[[storage] +[[storage]] name = 'default' path = '/mnt/gitlab/default/repositories' @@ -214,7 +219,7 @@ repository from your GitLab server over HTTP. If you are running Gitaly [as a remote service](#running-gitaly-on-its-own-server) you may want to disable -the local Gitaly service that runs on your Gitlab server by default. +the local Gitaly service that runs on your GitLab server by default. > 'Disabling Gitaly' only makes sense when you run GitLab in a custom cluster configuration, where different services run on different diff --git a/doc/administration/high_availability/README.md b/doc/administration/high_availability/README.md index ea8077f0623..49fe80fb2a6 100644 --- a/doc/administration/high_availability/README.md +++ b/doc/administration/high_availability/README.md @@ -37,7 +37,7 @@ Follow the steps below to configure an active/active setup: 1. [Configure the database](database.md) 1. [Configure Redis](redis.md) - 1. [Configure Redis for GitLab source installations](redis_source.md) + 1. [Configure Redis for GitLab source installations](redis_source.md) 1. [Configure NFS](nfs.md) 1. [Configure the GitLab application servers](gitlab.md) 1. [Configure the load balancers](load_balancer.md) diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md index b5124b1d540..c1eeb40b98f 100644 --- a/doc/administration/high_availability/database.md +++ b/doc/administration/high_availability/database.md @@ -13,7 +13,7 @@ Database Service (RDS) that runs PostgreSQL. If you use a cloud-managed service, or provide your own PostgreSQL: -1. Setup PostgreSQL according to the +1. Set up PostgreSQL according to the [database requirements document](../../install/requirements.md#database). 1. Set up a `gitlab` username with a password of your choice. The `gitlab` user needs privileges to create the `gitlabhq_production` database. diff --git a/doc/administration/high_availability/gitlab.md b/doc/administration/high_availability/gitlab.md index b74554a5598..f16ae835ced 100644 --- a/doc/administration/high_availability/gitlab.md +++ b/doc/administration/high_availability/gitlab.md @@ -84,7 +84,7 @@ for each GitLab application server in your environment. 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 above, GitLab assumes you have SSL certificates in `/etc/gitlab/ssl/`. If certificates are not present, Nginx will fail to start. See diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md index cd2284f5f2a..95e2caf0cad 100644 --- a/doc/administration/high_availability/nfs.md +++ b/doc/administration/high_availability/nfs.md @@ -47,7 +47,7 @@ there because this will also affect performance. We recommend that the log files stored on a local volume. For more details on another person's experience with EFS, see -[Amazon's Elastic File System: Burst Credits](https://www.rawkode.io/2017/04/amazons-elastic-file-system-burst-credits/) +[Amazon's Elastic File System: Burst Credits](https://rawkode.com/2017/04/16/amazons-elastic-file-system-burst-credits/) ## NFS Client mount options diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md index 031fb31ca4f..b5d1ff698c6 100644 --- a/doc/administration/high_availability/redis.md +++ b/doc/administration/high_availability/redis.md @@ -1,7 +1,6 @@ # Configuring Redis for GitLab HA -> -Experimental Redis Sentinel support was [Introduced][ce-1877] in GitLab 8.11. +> Experimental Redis Sentinel support was [Introduced][ce-1877] in GitLab 8.11. Starting with 8.14, Redis Sentinel is no longer experimental. If you've used it with versions `< 8.14` before, please check the updated documentation here. @@ -15,20 +14,20 @@ a hosted cloud solution or you can use the one that comes bundled with Omnibus GitLab packages. > **Notes:** -- Redis requires authentication for High Availability. See - [Redis Security](http://redis.io/topics/security) documentation for more - information. We recommend using a combination of a Redis password and tight - firewall rules to secure your Redis service. -- You are highly encouraged to read the [Redis Sentinel][sentinel] documentation - before configuring Redis HA with GitLab to fully understand the topology and - architecture. -- This is the documentation for the Omnibus GitLab packages. For installations - from source, follow the [Redis HA source installation](redis_source.md) guide. -- Redis Sentinel daemon is bundled with Omnibus GitLab Enterprise Edition only. - For configuring Sentinel with the Omnibus GitLab Community Edition and - installations from source, read the - [Available configuration setups](#available-configuration-setups) section - below. +> - Redis requires authentication for High Availability. See +> [Redis Security](http://redis.io/topics/security) documentation for more +> information. We recommend using a combination of a Redis password and tight +> firewall rules to secure your Redis service. +> - You are highly encouraged to read the [Redis Sentinel][sentinel] documentation +> before configuring Redis HA with GitLab to fully understand the topology and +> architecture. +> - This is the documentation for the Omnibus GitLab packages. For installations +> from source, follow the [Redis HA source installation](redis_source.md) guide. +> - Redis Sentinel daemon is bundled with Omnibus GitLab Enterprise Edition only. +> For configuring Sentinel with the Omnibus GitLab Community Edition and +> installations from source, read the +> [Available configuration setups](#available-configuration-setups) section +> below. ## Overview @@ -55,11 +54,11 @@ components below. ### High Availability with Sentinel ->**Notes:** -- Starting with GitLab `8.11`, you can configure a list of Redis Sentinel - servers that will monitor a group of Redis servers to provide failover support. -- Starting with GitLab `8.14`, the Omnibus GitLab Enterprise Edition package - comes with Redis Sentinel daemon built-in. +> **Notes:** +> - Starting with GitLab `8.11`, you can configure a list of Redis Sentinel +> servers that will monitor a group of Redis servers to provide failover support. +> - Starting with GitLab `8.14`, the Omnibus GitLab Enterprise Edition package +> comes with Redis Sentinel daemon built-in. High Availability with Redis requires a few things: @@ -82,7 +81,7 @@ When a **Master** fails to respond, it's the application's responsibility (in our case GitLab) to handle timeout and reconnect (querying a **Sentinel** for a new **Master**). -To get a better understanding on how to correctly setup Sentinel, please read +To get a better understanding on how to correctly set up Sentinel, please read the [Redis Sentinel documentation](http://redis.io/topics/sentinel) first, as failing to configure it correctly can lead to data loss or can bring your whole cluster down, invalidating the failover effort. @@ -218,7 +217,7 @@ Pick the one that suits your needs. and configure Sentinel, jump directly to the Sentinel section in the [Redis HA installation from source](redis_source.md#step-3-configuring-the-redis-sentinel-instances) documentation. - [Omnibus GitLab **Enterprise Edition** (EE) package][ee]: Both Redis and Sentinel - are bundled in the package, so you can use the EE package to setup the whole + are bundled in the package, so you can use the EE package to set up the whole Redis HA infrastructure (master, slave and Sentinel) which is described in this document. - If you have installed GitLab using the Omnibus GitLab packages (CE or EE), @@ -229,15 +228,15 @@ Pick the one that suits your needs. ## Configuring Redis HA -This is the section where we install and setup the new Redis instances. +This is the section where we install and set up the new Redis instances. ->**Notes:** -- We assume that you have installed GitLab and all HA components from scratch. If you - already have it installed and running, read how to - [switch from a single-machine installation to Redis HA](#switching-from-an-existing-single-machine-installation-to-redis-ha). -- Redis nodes (both master and slaves) will need the same password defined in - `redis['password']`. At any time during a failover the Sentinels can - reconfigure a node and change its status from master to slave and vice versa. +> **Notes:** +> - We assume that you have installed GitLab and all HA components from scratch. If you +> already have it installed and running, read how to +> [switch from a single-machine installation to Redis HA](#switching-from-an-existing-single-machine-installation-to-redis-ha). +> - Redis nodes (both master and slaves) will need the same password defined in +> `redis['password']`. At any time during a failover the Sentinels can +> reconfigure a node and change its status from master to slave and vice versa. ### Prerequisites @@ -371,7 +370,7 @@ You must have at least `3` Redis Sentinel servers, and they need to be each in an independent machine. You can configure them in the same machines where you've configured the other Redis servers. -With GitLab Enterprise Edition, you can use the Omnibus package to setup +With GitLab Enterprise Edition, you can use the Omnibus package to set up multiple machines with the Sentinel daemon. --- @@ -383,9 +382,9 @@ multiple machines with the Sentinel daemon. [Download/install](https://about.gitlab.com/downloads-ee) the Omnibus GitLab Enterprise Edition package using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - the GitLab application is running. - - Do not complete any other steps on the download page. + - Make sure you select the correct Omnibus package, with the same version + the GitLab application is running. + - Do not complete any other steps on the download page. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents (if you are installing the Sentinels in the same node as the other Redis instances, some values might @@ -536,7 +535,7 @@ In this example we consider that all servers have an internal network interface with IPs in the `10.0.0.x` range, and that they can connect to each other using these IPs. -In a real world usage, you would also setup firewall rules to prevent +In a real world usage, you would also set up firewall rules to prevent unauthorized access from other machines and block traffic from the outside (Internet). diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md index 8b7a515a076..5823c575251 100644 --- a/doc/administration/high_availability/redis_source.md +++ b/doc/administration/high_availability/redis_source.md @@ -24,7 +24,7 @@ the Omnibus Redis HA documentation. ## Configuring your own Redis server -This is the section where we install and setup the new Redis instances. +This is the section where we install and set up the new Redis instances. ### Prerequisites @@ -204,7 +204,7 @@ In this example we consider that all servers have an internal network interface with IPs in the `10.0.0.x` range, and that they can connect to each other using these IPs. -In a real world usage, you would also setup firewall rules to prevent +In a real world usage, you would also set up firewall rules to prevent unauthorized access from other machines, and block traffic from the outside ([Internet][it]). diff --git a/doc/administration/index.md b/doc/administration/index.md index 837a04f3e88..d713247983b 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -47,6 +47,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Enforcing Terms of Service](../user/admin_area/settings/terms.md) - [Third party offers](../user/admin_area/settings/third_party_offers.md) - [Compliance](compliance.md): A collection of features from across the application that you may configure to help ensure that your GitLab instance and DevOps workflow meet compliance standards. +- [Diff limits](../user/admin_area/diff_limits.md): Configure the diff rendering size limits of branch comparison pages. #### Customizing GitLab's appearance @@ -60,7 +61,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Raketasks](../raketasks/README.md): Perform various tasks for maintenance, backups, automatic webhooks setup, etc. - [Backup and restore](../raketasks/backup_restore.md): Backup and restore your GitLab instance. -- [Operations](operations/index.md): Keeping GitLab up and running (clean up Redis sessions, moving repositories, Sidekiq Job throttling, Sidekiq MemoryKiller, Unicorn). +- [Operations](operations/index.md): Keeping GitLab up and running (clean up Redis sessions, moving repositories, Sidekiq MemoryKiller, Unicorn). - [Restart GitLab](restart_gitlab.md): Learn how to restart GitLab and its components. #### Updating GitLab @@ -135,15 +136,15 @@ created in snippets, wikis, and repos. - [Monitoring GitLab](monitoring/index.md): - [Monitoring uptime](../user/admin_area/monitoring/health_check.md): Check the server status using the health check endpoint. - - [IP whitelist](monitoring/ip_whitelist.md): Monitor endpoints that provide health check information when probed. - - [Monitoring GitHub imports](monitoring/github_imports.md): GitLab's GitHub Importer displays Prometheus metrics to monitor the health and progress of the importer. + - [IP whitelist](monitoring/ip_whitelist.md): Monitor endpoints that provide health check information when probed. + - [Monitoring GitHub imports](monitoring/github_imports.md): GitLab's GitHub Importer displays Prometheus metrics to monitor the health and progress of the importer. ### Performance Monitoring - [GitLab Performance Monitoring](monitoring/performance/index.md): - [Enable Performance Monitoring](monitoring/performance/gitlab_configuration.md): Enable GitLab Performance Monitoring. - [GitLab performance monitoring with InfluxDB](monitoring/performance/influxdb_configuration.md): Configure GitLab and InfluxDB for measuring performance metrics. - - [InfluxDB Schema](monitoring/performance/influxdb_schema.md): Measurements stored in InfluxDB. + - [InfluxDB Schema](monitoring/performance/influxdb_schema.md): Measurements stored in InfluxDB. - [GitLab performance monitoring with Prometheus](monitoring/prometheus/index.md): Configure GitLab and Prometheus for measuring performance metrics. - [GitLab performance monitoring with Grafana](monitoring/performance/grafana_configuration.md): Configure GitLab to visualize time series metrics through graphs and dashboards. - [Request Profiling](monitoring/performance/request_profiling.md): Get a detailed profile on slow requests. diff --git a/doc/administration/integration/koding.md b/doc/administration/integration/koding.md index 6c1ec3028cc..def0add0061 100644 --- a/doc/administration/integration/koding.md +++ b/doc/administration/integration/koding.md @@ -1,10 +1,10 @@ # Koding & GitLab ->**Notes:** -- **As of GitLab 10.0, the Koding integration is deprecated and will be removed - in a future version. The option to configure it is removed from GitLab's admin - area.** -- [Introduced][ce-5909] in GitLab 8.11. +> **Notes:** +> - **As of GitLab 10.0, the Koding integration is deprecated and will be removed +> in a future version. The option to configure it is removed from GitLab's admin +> area.** +> - [Introduced][ce-5909] in GitLab 8.11. This document will guide you through installing and configuring Koding with GitLab. @@ -117,12 +117,11 @@ requests. You need to enable Koding integration from Settings under Admin Area. To do that login with an Admin account and do followings; - - open [http://127.0.0.1:3000/admin/application_settings](http://127.0.0.1:3000/admin/application_settings) - - scroll to bottom of the page until Koding section - - check `Enable Koding` checkbox - - provide GitLab team page for running Koding instance as `Koding URL`* - -* For `Koding URL` you need to provide the gitlab integration enabled team on +- open [http://127.0.0.1:3000/admin/application_settings](http://127.0.0.1:3000/admin/application_settings) +- scroll to bottom of the page until Koding section +- check `Enable Koding` checkbox +- provide GitLab team page for running Koding instance as `Koding URL`* + * For `Koding URL` you need to provide the gitlab integration enabled team on your Koding installation. Team called `gitlab` has integration on Koding out of the box, so if you didn't change anything your team on Koding should be `gitlab`. diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index d978d1dca53..293036f2f4b 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -74,28 +74,27 @@ our AsciiDoc snippets, wikis and repos using delimited blocks: ```plantuml Bob -> Alice : hello Alice -> Bob : Go Away - ``` - </pre> + ```</pre> - **AsciiDoc** - <pre> + ``` [plantuml, format="png", id="myDiagram", width="200px"] -- Bob->Alice : hello Alice -> Bob : Go Away -- - </pre> + ``` - **reStructuredText** - <pre> + ``` .. plantuml:: :caption: Caption with **bold** and *italic* Bob -> Alice: hello Alice -> Bob: Go Away - </pre> + ``` You can also use the `uml::` directive for compatibility with [sphinxcontrib-plantuml](https://pypi.python.org/pypi/sphinxcontrib-plantuml), but please note that we currently only support the `caption` option. diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index e11ed58eb91..fa58d0ef15f 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -1,7 +1,6 @@ # Web terminals -> -[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7690) +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7690) in GitLab 8.15. Only project maintainers and owners can access web terminals. With the introduction of the [Kubernetes integration](../../user/project/clusters/index.md), diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md index 466bb1f851e..35f25e55414 100644 --- a/doc/administration/issue_closing_pattern.md +++ b/doc/administration/issue_closing_pattern.md @@ -28,7 +28,7 @@ Because Rubular doesn't understand `%{issue_ref}`, you can replace this by expression of your liking: ```ruby - gitlab_rails['gitlab_issue_closing_pattern'] = "((?:[Cc]los(?:e[sd]|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)" + 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. @@ -38,7 +38,7 @@ Because Rubular doesn't understand `%{issue_ref}`, you can replace this by 1. Change the value of `issue_closing_pattern`: ```yaml - issue_closing_pattern: "((?:[Cc]los(?:e[sd]|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)" + 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. diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 8c55c8c4298..757865ea2c5 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -87,13 +87,13 @@ _The artifacts are stored by default in ### Using object storage ->**Notes:** -- [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1762) in - [GitLab Premium](https://about.gitlab.com/pricing/) 9.4. -- Since version 9.5, artifacts are [browsable](../user/project/pipelines/job_artifacts.md#browsing-artifacts), - when object storage is enabled. 9.4 lacks this feature. -- Since version 10.6, available in [GitLab Core](https://about.gitlab.com/pricing/) -- Since version 11.0, we support `direct_upload` to S3. +> **Notes:** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1762) in +> [GitLab Premium](https://about.gitlab.com/pricing/) 9.4. +> - Since version 9.5, artifacts are [browsable](../user/project/pipelines/job_artifacts.md#browsing-artifacts), +> when object storage is enabled. 9.4 lacks this feature. +> - Since version 10.6, available in [GitLab Core](https://about.gitlab.com/pricing/) +> - Since version 11.0, we support `direct_upload` to S3. If you don't want to use the local disk where GitLab is installed to store the artifacts, you can use an object storage like AWS S3 instead. @@ -127,6 +127,7 @@ The connection settings match those provided by [Fog](https://github.com/fog), a | `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) | | `path_style` | Set to true to use `host/bucket_name/object` style paths instead of `bucket_name.host/object`. Leave as false for AWS S3 | false | +| `use_iam_profile` | Set to true to use IAM profile instead of access keys | false **In Omnibus installations:** @@ -162,15 +163,15 @@ _The artifacts are stored by default in 1. Save the file and [reconfigure GitLab][] for the changes to take effect. 1. Migrate any existing local artifacts to the object storage: - ```bash - gitlab-rake gitlab:artifacts:migrate - ``` + ```bash + gitlab-rake gitlab:artifacts:migrate + ``` - Currently this has to be executed manually and it will allow you to - migrate the existing artifacts to the object storage, but all new - artifacts will still be stored on the local disk. In the future - you will be given an option to define a default storage artifacts for all - new files. + Currently this has to be executed manually and it will allow you to + migrate the existing artifacts to the object storage, but all new + artifacts will still be stored on the local disk. In the future + you will be given an option to define a default storage artifacts for all + new files. --- @@ -190,7 +191,7 @@ _The artifacts are stored by default in remote_directory: "artifacts" # The bucket name connection: provider: AWS # Only AWS supported at the moment - aws_access_key_id: AWS_ACESS_KEY_ID + aws_access_key_id: AWS_ACCESS_KEY_ID aws_secret_access_key: AWS_SECRET_ACCESS_KEY region: eu-central-1 ``` @@ -198,15 +199,15 @@ _The artifacts are stored by default in 1. Save the file and [restart GitLab][] for the changes to take effect. 1. Migrate any existing local artifacts to the object storage: - ```bash - sudo -u git -H bundle exec rake gitlab:artifacts:migrate RAILS_ENV=production - ``` + ```bash + sudo -u git -H bundle exec rake gitlab:artifacts:migrate RAILS_ENV=production + ``` - Currently this has to be executed manually and it will allow you to - migrate the existing artifacts to the object storage, but all new - artifacts will still be stored on the local disk. In the future - you will be given an option to define a default storage artifacts for all - new files. + Currently this has to be executed manually and it will allow you to + migrate the existing artifacts to the object storage, but all new + artifacts will still be stored on the local disk. In the future + you will be given an option to define a default storage artifacts for all + new files. ## Expiring artifacts @@ -266,6 +267,7 @@ you can flip the feature flag from a Rails console. ```ruby Feature.enable('ci_disable_validates_dependencies') ``` + --- **In installations from source:** diff --git a/doc/administration/job_traces.md b/doc/administration/job_traces.md index 6e2f67f61bc..63945506f3c 100644 --- a/doc/administration/job_traces.md +++ b/doc/administration/job_traces.md @@ -12,8 +12,8 @@ In the following table you can see the phases a trace goes through. | ----- | ----- | --------- | --------- | ----------- | | 1: patching | Live trace | When a job is running | GitLab Runner => Unicorn => file storage |`#{ROOT_PATH}/builds/#{YYYY_mm}/#{project_id}/#{job_id}.log`| | 2: overwriting | Live trace | When a job is finished | GitLab Runner => Unicorn => file storage |`#{ROOT_PATH}/builds/#{YYYY_mm}/#{project_id}/#{job_id}.log`| -| 3: archiving | Archived trace | After a job is finished | Sidekiq moves live trace to artifacts folder |`#{ROOT_PATH}/shared/artifacts/#{disk_hash}/#{YYYY_mm_dd}/#{job_id}/#{job_artifact_id}/trace.log`| -| 4: uploading | Archived trace | After a trace is archived | Sidekiq moves archived trace to [object storage](#uploading-traces-to-object-storage) (if configured) |`#{bucket_name}/#{disk_hash}/#{YYYY_mm_dd}/#{job_id}/#{job_artifact_id}/trace.log`| +| 3: archiving | Archived trace | After a job is finished | Sidekiq moves live trace to artifacts folder |`#{ROOT_PATH}/shared/artifacts/#{disk_hash}/#{YYYY_mm_dd}/#{job_id}/#{job_artifact_id}/job.log`| +| 4: uploading | Archived trace | After a trace is archived | Sidekiq moves archived trace to [object storage](#uploading-traces-to-object-storage) (if configured) |`#{bucket_name}/#{disk_hash}/#{YYYY_mm_dd}/#{job_id}/#{job_artifact_id}/job.log`| The `ROOT_PATH` varies per your environment. For Omnibus GitLab it would be `/var/opt/gitlab/gitlab-ci`, whereas for installations from source @@ -67,35 +67,37 @@ To archive those legacy job traces, please follow the instruction below. 1. Execute the following command - ```bash - gitlab-rake gitlab:traces:archive - ``` + ```bash + gitlab-rake gitlab:traces:archive + ``` - After you executed this task, GitLab instance queues up Sidekiq jobs (asynchronous processes) - for migrating job trace files from local storage to object storage. - It could take time to complete the all migration jobs. You can check the progress by the following command + After you executed this task, GitLab instance queues up Sidekiq jobs (asynchronous processes) + for migrating job trace files from local storage to object storage. + It could take time to complete the all migration jobs. You can check the progress by the following command - ```bash - sudo gitlab-rails console - ``` + ```bash + sudo gitlab-rails console + ``` - ```bash - [1] pry(main)> Sidekiq::Stats.new.queues['pipeline_background:archive_trace'] - => 100 - ``` + ```bash + [1] pry(main)> Sidekiq::Stats.new.queues['pipeline_background:archive_trace'] + => 100 + ``` - If the count becomes zero, the archiving processes are done + If the count becomes zero, the archiving processes are done ## How to migrate archived job traces to object storage +> [Introduced][ce-21193] in GitLab 11.3. + If job traces have already been archived into local storage, and you want to migrate those traces to object storage, please follow the instruction below. 1. Ensure [Object storage integration for Job Artifacts](job_artifacts.md#object-storage-settings) is enabled 1. Execute the following command - ```bash - gitlab-rake gitlab:traces:migrate - ``` + ```bash + gitlab-rake gitlab:traces:migrate + ``` ## How to remove job traces @@ -183,15 +185,15 @@ with the legacy architecture. In some cases, having data stored on Redis could incur data loss: 1. **Case 1: When all data in Redis are accidentally flushed** - - On going live traces could be recovered by re-sending traces (this is - supported by all versions of the GitLab Runner). - - Finished jobs which have not archived live traces will lose the last part - (~128KB) of trace data. + - On going live traces could be recovered by re-sending traces (this is + supported by all versions of the GitLab Runner). + - Finished jobs which have not archived live traces will lose the last part + (~128KB) of trace data. 1. **Case 2: When Sidekiq workers fail to archive (e.g., there was a bug that prevents archiving process, Sidekiq inconsistency, etc.)** - - Currently all trace data in Redis will be deleted after one week. If the - Sidekiq workers can't finish by the expiry date, the part of trace data will be lost. + - Currently all trace data in Redis will be deleted after one week. If the + Sidekiq workers can't finish by the expiry date, the part of trace data will be lost. Another issue that might arise is that it could consume all memory on the Redis instance. If the number of jobs is 1000, 128MB (128KB * 1000) is consumed. @@ -201,4 +203,5 @@ indicate that we have trace chunk. `UPDATE`s with 128KB of data is issued once w receive multiple chunks. [ce-18169]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18169 +[ce-21193]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21193 [ce-46097]: https://gitlab.com/gitlab-org/gitlab-ce/issues/46097 diff --git a/doc/administration/logs.md b/doc/administration/logs.md index c8a3ef80e8f..a8cdd20581d 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -13,7 +13,7 @@ This guide talks about how to read and use these system log files. This file lives in `/var/log/gitlab/gitlab-rails/production_json.log` for Omnibus GitLab packages or in `/home/git/gitlab/log/production_json.log` for -installations from source. (When Gitlab is running in an environment +installations from source. (When GitLab is running in an environment other than production, the corresponding logfile is shown here.) It contains a structured log for Rails controller requests received from @@ -42,7 +42,7 @@ In addition, the log contains the IP address from which the request originated This file lives in `/var/log/gitlab/gitlab-rails/production.log` for Omnibus GitLab packages or in `/home/git/gitlab/log/production.log` for -installations from source. (When Gitlab is running in an environment +installations from source. (When GitLab is running in an environment other than production, the corresponding logfile is shown here.) It contains information about all performed requests. You can see the @@ -113,6 +113,19 @@ October 07, 2014 11:25: User "Claudie Hodkiewicz" (nasir_stehr@olson.co.uk) was October 07, 2014 11:25: Project "project133" was removed ``` +## `integrations_json.log` + +This file lives in `/var/log/gitlab/gitlab-rails/integrations_json.log` for +Omnibus GitLab packages or in `/home/git/gitlab/log/integrations_json.log` for +installations from source. + +It contains information about [integrations](../user/project/integrations/project_services.md) activities such as JIRA, Asana and Irker services. It uses JSON format like the example below: + +``` json +{"severity":"ERROR","time":"2018-09-06T14:56:20.439Z","service_class":"JiraService","project_id":8,"project_path":"h5bp/html5-boilerplate","message":"Error sending message","client_url":"http://jira.gitlap.com:8080","error":"execution expired"} +{"severity":"INFO","time":"2018-09-06T17:15:16.365Z","service_class":"JiraService","project_id":3,"project_path":"namespace2/project2","message":"Successfully posted","client_url":"http://jira.example.net"} +``` + ## `githost.log` This file lives in `/var/log/gitlab/gitlab-rails/githost.log` for @@ -174,7 +187,7 @@ This file lives in `/var/log/gitlab/gitlab-shell/gitlab-shell.log` for Omnibus GitLab packages or in `/home/git/gitlab-shell/gitlab-shell.log` for installations from source. -GitLab shell is used by Gitlab for executing Git commands and provide +GitLab shell is used by GitLab for executing Git commands and provide SSH access to Git repositories. For example: ``` @@ -219,6 +232,15 @@ installations from source. It logs information whenever a [repository check is run][repocheck] on a project. +## `importer.log` + +Introduced in GitLab 11.3. This file lives in `/var/log/gitlab/gitlab-rails/importer.log` for +Omnibus GitLab packages or in `/home/git/gitlab/log/importer.log` for +installations from source. + +Currently it logs the progress of project imports from the Bitbucket Server +importer. Future importers may use this file. + ## Reconfigure Logs Reconfigure log files live in `/var/log/gitlab/reconfigure` for Omnibus GitLab diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index 1c79e86dcb4..b1b670c3b42 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -1,13 +1,13 @@ # GitLab Prometheus ->**Notes:** -- Prometheus and the various exporters listed in this page are bundled in the - Omnibus GitLab package. Check each exporter's documentation for the timeline - they got added. For installations from source you will have to install them - yourself. Over subsequent releases additional GitLab metrics will be captured. -- Prometheus services are on by default with GitLab 9.0. -- Prometheus and its exporters do not authenticate users, and will be available - to anyone who can access them. +> **Notes:** +> - Prometheus and the various exporters listed in this page are bundled in the +> Omnibus GitLab package. Check each exporter's documentation for the timeline +> they got added. For installations from source you will have to install them +> yourself. Over subsequent releases additional GitLab metrics will be captured. +> - Prometheus services are on by default with GitLab 9.0. +> - Prometheus and its exporters do not authenticate users, and will be available +> to anyone who can access them. [Prometheus] is a powerful time-series monitoring service, providing a flexible platform for monitoring GitLab and other software products. @@ -97,17 +97,17 @@ For a more fully featured dashboard, Grafana can be used and has Sample Prometheus queries: -- **% Memory used:** `(1 - ((node_memory_MemFree + node_memory_Cached) / node_memory_MemTotal)) * 100` -- **% CPU load:** `1 - rate(node_cpu{mode="idle"}[5m])` -- **Data transmitted:** `irate(node_network_transmit_bytes[5m])` -- **Data received:** `irate(node_network_receive_bytes[5m])` +- **% Memory available:** `((node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes) or ((node_memory_MemFree_bytes + node_memory_Buffers_bytes + node_memory_Cached_bytes) / node_memory_MemTotal_bytes)) * 100` +- **% CPU utilization:** `1 - avg without (mode,cpu) (rate(node_cpu_seconds_total{mode="idle"}[5m]))` +- **Data transmitted:** `rate(node_network_transmit_bytes_total{device!="lo"}[5m])` +- **Data received:** `rate(node_network_receive_bytes_total{device!="lo"}[5m])` ## Configuring Prometheus to monitor Kubernetes > Introduced in GitLab 9.0. > Pod monitoring introduced in GitLab 9.4. -If your GitLab server is running within Kubernetes, Prometheus will collect metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/operating/configuration/#<kubernetes_sd_config>) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration][] to monitor them. +If your GitLab server is running within Kubernetes, Prometheus will collect metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/operating/configuration/#kubernetes_sd_config) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration][] to monitor them. To disable the monitoring of Kubernetes: diff --git a/doc/administration/operations/img/sidekiq_job_throttling.png b/doc/administration/operations/img/sidekiq_job_throttling.png Binary files differdeleted file mode 100644 index abd09f3b115..00000000000 --- a/doc/administration/operations/img/sidekiq_job_throttling.png +++ /dev/null diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index e9cad99c4b0..dea98cb8197 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/index.md @@ -9,8 +9,6 @@ GitLab 7.3 we recommend cleaning up stale sessions to compact the Redis database after you upgrade to GitLab 7.3. - [Moving repositories](moving_repositories.md): Moving all repositories managed by GitLab to another file system or another server. -- [Sidekiq job throttling](sidekiq_job_throttling.md): Throttle Sidekiq queues -that to prioritize important jobs. - [Sidekiq MemoryKiller](sidekiq_memory_killer.md): Configure Sidekiq MemoryKiller to restart Sidekiq. - [Unicorn](unicorn.md): Understand Unicorn and unicorn-worker-killer. diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index 54adb99386a..ec11a92db1b 100644 --- a/doc/administration/operations/moving_repositories.md +++ b/doc/administration/operations/moving_repositories.md @@ -22,9 +22,8 @@ However, it is not possible to resume an interrupted tar pipe: if that happens then all data must be copied again. ``` -# As the git user -tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ - tar -C /mnt/gitlab/repositories -xf - +sudo -u git sh -c 'tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ + tar -C /mnt/gitlab/repositories -xf -' ``` If you want to see progress, replace `-xf` with `-xvf`. @@ -36,9 +35,8 @@ You can also use a tar pipe to copy data to another server. If your can pipe the data through SSH. ``` -# As the git user -tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ - ssh git@newserver tar -C /mnt/gitlab/repositories -xf - +sudo -u git sh -c 'tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ + ssh git@newserver tar -C /mnt/gitlab/repositories -xf -' ``` If you want to compress the data before it goes over the network @@ -53,9 +51,8 @@ is either already installed on your system or easily installable via apt, yum etc. ``` -# As the 'git' user -rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ - /mnt/gitlab/repositories +sudo -u git sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ + /mnt/gitlab/repositories' ``` The `/.` in the command above is very important, without it you can @@ -68,9 +65,8 @@ If the 'git' user on your source system has SSH access to the target server you can send the repositories over the network with rsync. ``` -# As the 'git' user -rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ - git@newserver:/mnt/gitlab/repositories +sudo -u git sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ + git@newserver:/mnt/gitlab/repositories' ``` ## Thousands of Git repositories: use one rsync per repository @@ -125,7 +121,7 @@ sudo -u git -H sh -c 'bundle exec rake gitlab:list_repos > /home/git/transfer-lo Now we can start the transfer. The command below is idempotent, and the number of jobs done by GNU Parallel should converge to zero. If it -does not some repositories listed in all-repos-1234.txt may have been +does not, some repositories listed in `all-repos-1234.txt` may have been deleted/renamed before they could be copied. ``` @@ -155,8 +151,8 @@ cat /home/git/transfer-logs/* | sort | uniq -u |\ Suppose you have already done one sync that started after 2015-10-1 12:00 UTC. Then you might only want to sync repositories that were changed via GitLab -_after_ that time. You can use the 'SINCE' variable to tell 'rake -gitlab:list_repos' to only print repositories with recent activity. +_after_ that time. You can use the `SINCE` variable to tell `rake +gitlab:list_repos` to only print repositories with recent activity. ``` # Omnibus diff --git a/doc/administration/operations/sidekiq_job_throttling.md b/doc/administration/operations/sidekiq_job_throttling.md deleted file mode 100644 index ddeaa22e288..00000000000 --- a/doc/administration/operations/sidekiq_job_throttling.md +++ /dev/null @@ -1,33 +0,0 @@ -# Sidekiq Job throttling - -> Note: Introduced with GitLab 8.14 - -When your GitLab installation needs to handle tens of thousands of background -jobs, it can be convenient to throttle queues that do not need to be executed -immediately, e.g. long running jobs like Pipelines, thus allowing jobs that do -need to be executed immediately to have access to more resources. - -In order to accomplish this, you can limit the amount of workers that certain -slow running queues can have available. This is what we call Sidekiq Job -Throttling. Depending on your infrastructure, you might have different slow -running queues, which is why you can choose which queues you want to throttle -and by how much you want to throttle them. - -These settings are available in the Application Settings of your GitLab -installation. - - - -The throttle factor determines the maximum number of workers a queue can run on. -This value gets multiplied by `:concurrency` value set in the Sidekiq settings -and rounded up to the closest full integer. - -So, for example, you set the `:concurrency` to 25 and the `Throttling factor` to -0.1, the maximum workers assigned to the selected queues would be 3. - -```ruby -queue_limit = (factor * Sidekiq.options[:concurrency]).ceil -``` - -After enabling the job throttling, you will need to restart your GitLab -instance, in order for the changes to take effect.
\ No newline at end of file diff --git a/doc/administration/operations/ssh_certificates.md b/doc/administration/operations/ssh_certificates.md index 9edccd25ced..b00301fec1c 100644 --- a/doc/administration/operations/ssh_certificates.md +++ b/doc/administration/operations/ssh_certificates.md @@ -31,7 +31,7 @@ uploading user SSH keys to GitLab entirely. ## Setting up SSH certificate lookup via GitLab Shell -How to fully setup SSH certificates is outside the scope of this +How to fully set up SSH certificates is outside the scope of this document. See [OpenSSH's PROTOCOL.certkeys](https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.bin/ssh/PROTOCOL.certkeys?annotate=HEAD) for how it works, and e.g. [RedHat's documentation about @@ -132,7 +132,7 @@ message about this being an invalid user. ## Interaction with the `authorized_keys` file SSH certificates can be used in conjunction with the `authorized_keys` -file, and if setup as configured above the `authorized_keys` file will +file, and if set up as configured above the `authorized_keys` file will still serve as a fallback. This is because if the `AuthorizedPrincipalsCommand` can't diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index eefa86f8e42..2952a98626a 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -5,12 +5,13 @@ description: 'Learn how to administer GitLab Pages.' # GitLab Pages administration > **Notes:** -- [Introduced][ee-80] in GitLab EE 8.3. -- Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5. -- GitLab Pages [were ported][ce-14605] to Community Edition in GitLab 8.17. -- This guide is for Omnibus GitLab installations. If you have installed - GitLab from source, follow the [Pages source installation document](source.md). -- To learn how to use GitLab Pages, read the [user documentation][pages-userguide]. +> - [Introduced][ee-80] in GitLab EE 8.3. +> - Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5. +> - GitLab Pages [were ported][ce-14605] to Community Edition in GitLab 8.17. +> - This guide is for Omnibus GitLab installations. If you have installed +> GitLab from source, follow the [Pages source installation document](source.md). +> - To learn how to use GitLab Pages, read the [user documentation][pages-userguide]. +> - Does NOT support subgroups. See [this issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) for more information and status. This document describes how to set up the _latest_ GitLab Pages feature. Make sure to read the [changelog](#changelog) if you are upgrading to a new GitLab @@ -73,8 +74,8 @@ among other things. Follow [these instructions](https://publicsuffix.org/submit/) to submit your GitLab Pages subdomain. For instance, if your domain is `example.io`, you should -request that `*.example.io` is added to the Public Suffix List. GitLab.com -added `*.gitlab.io` [in 2016](https://gitlab.com/gitlab-com/infrastructure/issues/230). +request that `example.io` is added to the Public Suffix List. GitLab.com +added `gitlab.io` [in 2016](https://gitlab.com/gitlab-com/infrastructure/issues/230). ### DNS configuration @@ -91,9 +92,8 @@ where `example.io` is the domain under which GitLab Pages will be served and `192.0.2.1` is the IPv4 address of your GitLab instance and `2001::1` is the IPv6 address. If you don't have IPv6, you can omit the AAAA record. -> **Note:** -You should not use the GitLab domain to serve user pages. For more information -see the [security section](#security). +NOTE: **Note:** +You should not use the GitLab domain to serve user pages. For more information see the [security section](#security). [wiki-wildcard-dns]: https://en.wikipedia.org/wiki/Wildcard_DNS_record @@ -106,11 +106,12 @@ since that is needed in all configurations. ### Wildcard domains ->**Requirements:** +**Requirements:** + - [Wildcard DNS setup](#dns-configuration) -> ->--- -> + +--- + URL scheme: `http://page.example.io` This is the minimum setup that you can use Pages with. It is the base for all @@ -125,17 +126,17 @@ The Pages daemon doesn't listen to the outside world. 1. [Reconfigure GitLab][reconfigure] - Watch the [video tutorial][video-admin] for this configuration. ### Wildcard domains with TLS support ->**Requirements:** +**Requirements:** + - [Wildcard DNS setup](#dns-configuration) - Wildcard TLS certificate -> ->--- -> + +--- + URL scheme: `https://page.example.io` Nginx will proxy all requests to the daemon. Pages daemon doesn't listen to the @@ -167,12 +168,13 @@ you have IPv6 as well as IPv4 addresses, you can use them both. ### Custom domains ->**Requirements:** +**Requirements:** + - [Wildcard DNS setup](#dns-configuration) - Secondary IP -> + --- -> + URL scheme: `http://page.example.io` and `http://domain.com` In that case, the Pages daemon is running, Nginx still proxies requests to @@ -196,13 +198,14 @@ world. Custom domains are supported, but no TLS. ### Custom domains with TLS support ->**Requirements:** +**Requirements:** + - [Wildcard DNS setup](#dns-configuration) - Wildcard TLS certificate - Secondary IP -> + --- -> + URL scheme: `https://page.example.io` and `https://domain.com` In that case, the Pages daemon is running, Nginx still proxies requests to @@ -250,9 +253,9 @@ Follow the steps below to configure verbose logging of GitLab Pages daemon. If you wish to make it log events with level `DEBUG` you must configure this in `/etc/gitlab/gitlab.rb`: - ```shell - gitlab_pages['log_verbose'] = true - ``` + ```shell + gitlab_pages['log_verbose'] = true + ``` 1. [Reconfigure GitLab][reconfigure] @@ -265,9 +268,9 @@ are stored. If you wish to store them in another location you must set it up in `/etc/gitlab/gitlab.rb`: - ```shell - gitlab_rails['pages_path'] = "/mnt/storage/pages" - ``` + ```shell + gitlab_rails['pages_path'] = "/mnt/storage/pages" + ``` 1. [Reconfigure GitLab][reconfigure] @@ -278,19 +281,19 @@ Omnibus GitLab 11.1. 1. By default the listener is configured to listen for requests on `localhost:8090`. - If you wish to disable it you must configure this in - `/etc/gitlab/gitlab.rb`: + If you wish to disable it you must configure this in + `/etc/gitlab/gitlab.rb`: - ```shell - gitlab_pages['listen_proxy'] = nil - ``` + ```shell + gitlab_pages['listen_proxy'] = nil + ``` - If you wish to make it listen on a different port you must configure this also in - `/etc/gitlab/gitlab.rb`: + If you wish to make it listen on a different port you must configure this also in + `/etc/gitlab/gitlab.rb`: - ```shell - gitlab_pages['listen_proxy'] = "localhost:10080" - ``` + ```shell + gitlab_pages['listen_proxy'] = "localhost:10080" + ``` 1. [Reconfigure GitLab][reconfigure] @@ -319,12 +322,12 @@ latest previous version. --- -**GitLab 8.17 ([documentation][8-17-docs])** +**GitLab 8.17 ([documentation](https://gitlab.com/gitlab-org/gitlab-ce/blob/8-17-stable/doc/administration/pages/index.md))** - GitLab Pages were ported to Community Edition in GitLab 8.17. - Documentation was refactored to be more modular and easy to follow. -**GitLab 8.5 ([documentation][8-5-docs])** +**GitLab 8.5 ([documentation](https://gitlab.com/gitlab-org/gitlab-ee/blob/8-5-stable-ee/doc/pages/administration.md))** - In GitLab 8.5 we introduced the [gitlab-pages][] daemon which is now the recommended way to set up GitLab Pages. @@ -333,13 +336,10 @@ latest previous version. - Custom CNAME and TLS certificates support. - Documentation was moved to one place. -**GitLab 8.3 ([documentation][8-3-docs])** +**GitLab 8.3 ([documentation](https://gitlab.com/gitlab-org/gitlab-ee/blob/8-3-stable-ee/doc/pages/administration.md))** - GitLab Pages feature was introduced. -[8-3-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-3-stable-ee/doc/pages/administration.md -[8-5-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-5-stable-ee/doc/pages/administration.md -[8-17-docs]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-17-stable-ce/doc/administration/pages/index.md [backup]: ../../raketasks/backup_restore.md [ce-14605]: https://gitlab.com/gitlab-org/gitlab-ce/issues/14605 [ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80 diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 4e40a7cb18d..295905a7625 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -89,11 +89,11 @@ since that is needed in all configurations. ### Wildcard domains >**Requirements:** -- [Wildcard DNS setup](#dns-configuration) +> - [Wildcard DNS setup](#dns-configuration) > ->--- +> --- > -URL scheme: `http://page.example.io` +> URL scheme: `http://page.example.io` This is the minimum setup that you can use Pages with. It is the base for all other setups as described below. Nginx will proxy all requests to the daemon. @@ -111,24 +111,24 @@ The Pages daemon doesn't listen to the outside world. 1. Go to the GitLab installation directory: - ```bash - cd /home/git/gitlab - ``` + ```bash + cd /home/git/gitlab + ``` 1. Edit `gitlab.yml` and under the `pages` setting, set `enabled` to `true` and the `host` to the FQDN under which GitLab Pages will be served: - ```yaml - ## GitLab Pages - pages: - enabled: true - # The location where pages are stored (default: shared/pages). - # path: shared/pages + ```yaml + ## GitLab Pages + pages: + enabled: true + # The location where pages are stored (default: shared/pages). + # path: shared/pages - host: example.io - port: 80 - https: false - ``` + host: example.io + port: 80 + https: false + ``` 1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in order to enable the pages daemon. In `gitlab_pages_options` the @@ -151,13 +151,13 @@ The Pages daemon doesn't listen to the outside world. ### Wildcard domains with TLS support ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -- Wildcard TLS certificate +> **Requirements:** +> - [Wildcard DNS setup](#dns-configuration) +> - Wildcard TLS certificate > ->--- +> --- > -URL scheme: `https://page.example.io` +> URL scheme: `https://page.example.io` Nginx will proxy all requests to the daemon. Pages daemon doesn't listen to the outside world. @@ -174,17 +174,17 @@ outside world. 1. In `gitlab.yml`, set the port to `443` and https to `true`: - ```bash - ## GitLab Pages - pages: - enabled: true - # The location where pages are stored (default: shared/pages). - # path: shared/pages - - host: example.io - port: 443 - https: true - ``` + ```bash + ## GitLab Pages + pages: + enabled: true + # The location where pages are stored (default: shared/pages). + # path: shared/pages + + host: example.io + port: 443 + https: true + ``` 1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in order to enable the pages daemon. In `gitlab_pages_options` the @@ -216,13 +216,13 @@ that without TLS certificates. ### Custom domains ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -- Secondary IP +> **Requirements:** +> - [Wildcard DNS setup](#dns-configuration) +> - Secondary IP > ---- +> --- > -URL scheme: `http://page.example.io` and `http://domain.com` +> URL scheme: `http://page.example.io` and `http://domain.com` In that case, the pages daemon is running, Nginx still proxies requests to the daemon but the daemon is also able to receive requests from the outside @@ -243,18 +243,18 @@ world. Custom domains are supported, but no TLS. `external_http` to the secondary IP on which the pages daemon will listen for connections: - ```yaml - pages: - enabled: true - # The location where pages are stored (default: shared/pages). - # path: shared/pages + ```yaml + pages: + enabled: true + # The location where pages are stored (default: shared/pages). + # path: shared/pages - host: example.io - port: 80 - https: false + host: example.io + port: 80 + https: false - external_http: 192.0.2.2:80 - ``` + external_http: 192.0.2.2:80 + ``` 1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in order to enable the pages daemon. In `gitlab_pages_options` the @@ -281,14 +281,14 @@ world. Custom domains are supported, but no TLS. ### Custom domains with TLS support ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -- Wildcard TLS certificate -- Secondary IP +> **Requirements:** +> - [Wildcard DNS setup](#dns-configuration) +> - Wildcard TLS certificate +> - Secondary IP > ---- +> --- > -URL scheme: `https://page.example.io` and `https://domain.com` +> URL scheme: `https://page.example.io` and `https://domain.com` In that case, the pages daemon is running, Nginx still proxies requests to the daemon but the daemon is also able to receive requests from the outside @@ -309,20 +309,20 @@ world. Custom domains and TLS are supported. `external_http` and `external_https` to the secondary IP on which the pages daemon will listen for connections: - ```yaml - ## GitLab Pages - pages: - enabled: true - # The location where pages are stored (default: shared/pages). - # path: shared/pages + ```yaml + ## GitLab Pages + pages: + enabled: true + # The location where pages are stored (default: shared/pages). + # path: shared/pages - host: example.io - port: 443 - https: true + host: example.io + port: 443 + https: true - external_http: 192.0.2.2:80 - external_https: 192.0.2.2:443 - ``` + external_http: 192.0.2.2:80 + external_https: 192.0.2.2:443 + ``` 1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in order to enable the pages daemon. In `gitlab_pages_options` the @@ -358,9 +358,9 @@ are stored. 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" - ``` + ```ruby + gitlab_rails['pages_path'] = "/mnt/storage/pages" + ``` 1. [Reconfigure GitLab][reconfigure] @@ -400,12 +400,12 @@ are stored. If you wish to store them in another location you must set it up in `gitlab.yml` under the `pages` section: - ```yaml - pages: - enabled: true - # The location where pages are stored (default: shared/pages). - path: /mnt/storage/pages - ``` + ```yaml + pages: + enabled: true + # The location where pages are stored (default: shared/pages). + path: /mnt/storage/pages + ``` 1. [Restart GitLab][restart] diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index 2b4252a7b1d..29af07d12dc 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.md @@ -56,11 +56,11 @@ Runs the following rake tasks: - `gitlab:sidekiq:check` - `gitlab:app:check` -It will check that each component was setup according to the installation guide and suggest fixes for issues found. +It will check that each component was set up according to the installation guide and suggest fixes for issues found. -You may also have a look at our Trouble Shooting Guides: -- [Trouble Shooting Guide (GitLab)](http://docs.gitlab.com/ee/README.html#troubleshooting) -- [Trouble Shooting Guide (Omnibus Gitlab)](http://docs.gitlab.com/omnibus/README.html#troubleshooting) +You may also have a look at our Troubleshooting Guides: +- [Troubleshooting Guide (GitLab)](http://docs.gitlab.com/ee/README.html#troubleshooting) +- [Troubleshooting Guide (Omnibus Gitlab)](http://docs.gitlab.com/omnibus/README.html#troubleshooting) **Omnibus Installation** diff --git a/doc/administration/raketasks/project_import_export.md b/doc/administration/raketasks/project_import_export.md index 7bd765a35e0..f43bba0a7a7 100644 --- a/doc/administration/raketasks/project_import_export.md +++ b/doc/administration/raketasks/project_import_export.md @@ -9,6 +9,7 @@ > application settings (`/admin/application_settings`) under 'Import sources'. > - The exports are stored in a temporary [shared directory][tmp] and are deleted > every 24 hours by a specific worker. +> - ImportExport can use object storage automatically starting from GitLab 11.3 The GitLab Import/Export version can be checked by using: @@ -30,12 +31,6 @@ sudo gitlab-rake gitlab:import_export:data bundle exec rake gitlab:import_export:data RAILS_ENV=production ``` -In order to enable Object Storage on the Export, you can use the [feature flag][feature-flags]: - -``` -import_export_object_storage -``` - [ce-3050]: https://gitlab.com/gitlab-org/gitlab-ce/issues/3050 [feature-flags]: https://docs.gitlab.com/ee/api/features.html [tmp]: ../../development/shared_files.md diff --git a/doc/administration/raketasks/uploads/migrate.md b/doc/administration/raketasks/uploads/migrate.md index 0cd33ffc122..b5c40478ea5 100644 --- a/doc/administration/raketasks/uploads/migrate.md +++ b/doc/administration/raketasks/uploads/migrate.md @@ -7,10 +7,32 @@ After [configuring the object storage](../../uploads.md#using-object-storage) fo >**Note:** All of the processing will be done in a background worker and requires **no downtime**. -This tasks uses 3 parameters to find uploads to migrate. +### All-in-one rake task + +GitLab provides a wrapper rake task that migrates all uploaded files - avatars, +logos, attachments, favicon, etc. - to object storage in one go. Under the hood, +it invokes individual rake tasks to migrate files falling under each of this +category one by one. The specifications of these individual rake tasks are +described in the next section. + +**Omnibus Installation** + +```bash +gitlab-rake "gitlab:uploads:migrate:all" +``` + +**Source Installation** + +```bash +sudo RAILS_ENV=production -u git -H bundle exec rake gitlab:uploads:migrate:all +``` + +### Individual rake tasks >**Note:** -These parameters are mainly internal to GitLab's structure, you may want to refer to the task list instead below. +If you already ran the rake task mentioned above, no need to run these individual rake tasks as that has been done automatically. + +The rake task uses 3 parameters to find uploads to migrate. Parameter | Type | Description --------- | ---- | ----------- @@ -18,6 +40,9 @@ Parameter | Type | Description `model_class` | string | Type of the model to migrate from `mount_point` | string/symbol | Name of the model's column on which the uploader is mounted on. +>**Note:** +These parameters are mainly internal to GitLab's structure, you may want to refer to the task list instead below. + This task also accepts some environment variables which you can use to override certain values: @@ -25,7 +50,7 @@ Variable | Type | Description -------- | ---- | ----------- `BATCH` | integer | Specifies the size of the batch. Defaults to 200. -** Omnibus Installation** +**Omnibus Installation** ```bash # gitlab-rake gitlab:uploads:migrate[uploader_class, model_class, mount_point] @@ -40,6 +65,9 @@ gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Note, :attachment]" gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :logo]" gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :header_logo]" +# Favicon +gitlab-rake "gitlab:uploads:migrate[FaviconUploader, Appearance, :favicon]" + # Markdown gitlab-rake "gitlab:uploads:migrate[FileUploader, Project]" gitlab-rake "gitlab:uploads:migrate[PersonalFileUploader, Snippet]" @@ -65,6 +93,9 @@ sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Note sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :logo]" sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :header_logo]" +# Favicon +sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FaviconUploader, Appearance, :favicon]" + # Markdown sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, Project]" sudo -u git -H bundle exec rake "gitlab:uploads:migrate[PersonalFileUploader, Snippet]" diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md index 426245c7aca..6d7069dd461 100644 --- a/doc/administration/reply_by_email.md +++ b/doc/administration/reply_by_email.md @@ -5,7 +5,7 @@ replying to notification emails. ## Requirement -Make sure [incoming email](incoming_email.md) is setup. +Make sure [incoming email](incoming_email.md) is set up. ## How it works? diff --git a/doc/administration/reply_by_email_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md index 3e8b78e56d5..d1a03219542 100644 --- a/doc/administration/reply_by_email_postfix_setup.md +++ b/doc/administration/reply_by_email_postfix_setup.md @@ -245,7 +245,7 @@ Courier, which we will install later to add IMAP authentication, requires mailbo 220 gitlab.example.com ESMTP Postfix (Ubuntu) ``` - If you get a `Connection refused` error instead, make sure your firewall is setup to allow inbound traffic on port 25. + If you get a `Connection refused` error instead, make sure your firewall is set up to allow inbound traffic on port 25. 1. Send the `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt: diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index efeec9db517..715bc0cd08c 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -18,7 +18,8 @@ repositories and wiki repositories in order to detect data corruption. A project will be checked no more than once per month. If any projects fail their repository checks all GitLab administrators will receive an email notification of the situation. This notification is sent out once a week, -by default, midnight at the start of Sunday. +by default, midnight at the start of Sunday. Repositories with known check +failures can be found at `/admin/projects?last_repository_check_failed=1`. ## Disabling periodic checks diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index 96f436fa7c3..7ea7ed48850 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -5,36 +5,36 @@ GitLab allows you to define multiple repository storage paths to distribute the storage load between several mount points. ->**Notes:** +> **Notes:** > -- You must have at least one storage path called `default`. -- The paths are defined in key-value pairs. The key is an arbitrary name you - can pick to name the file path. -- The target directories and any of its subpaths must not be a symlink. +> - You must have at least one storage path called `default`. +> - The paths are defined in key-value pairs. The key is an arbitrary name you +> can pick to name the file path. +> - The target directories and any of its subpaths must not be a symlink. ## Configure GitLab ->**Warning:** -In order for [backups] to work correctly, the storage path must **not** be a -mount point and the GitLab user should have correct permissions for the parent -directory of the path. In Omnibus GitLab this is taken care of automatically, -but for source installations you should be extra careful. +> **Warning:** +> In order for [backups] to work correctly, the storage path must **not** be a +> mount point and the GitLab user should have correct permissions for the parent +> directory of the path. In Omnibus GitLab this is taken care of automatically, +> but for source installations you should be extra careful. > -The thing is that for compatibility reasons `gitlab.yml` has a different -structure than Omnibus. In `gitlab.yml` you indicate the path for the -repositories, for example `/home/git/repositories`, while in Omnibus you -indicate `git_data_dirs`, which for the example above would be `/home/git`. -Then, Omnibus will create a `repositories` directory under that path to use with -`gitlab.yml`. +> The thing is that for compatibility reasons `gitlab.yml` has a different +> structure than Omnibus. In `gitlab.yml` you indicate the path for the +> repositories, for example `/home/git/repositories`, while in Omnibus you +> indicate `git_data_dirs`, which for the example above would be `/home/git`. +> Then, Omnibus will create a `repositories` directory under that path to use with +> `gitlab.yml`. > -This little detail matters because while restoring a backup, the current -contents of `/home/git/repositories` [are moved to][raketask] `/home/git/repositories.old`, -so if `/home/git/repositories` is the mount point, then `mv` would be moving -things between mount points, and bad things could happen. Ideally, -`/home/git` would be the mount point, so then things would be moving within the -same mount point. This is guaranteed with Omnibus installations (because they -don't specify the full repository path but the parent path), but not for source -installations. +> This little detail matters because while restoring a backup, the current +> contents of `/home/git/repositories` [are moved to][raketask] `/home/git/repositories.old`, +> so if `/home/git/repositories` is the mount point, then `mv` would be moving +> things between mount points, and bad things could happen. Ideally, +> `/home/git` would be the mount point, so then things would be moving within the +> same mount point. This is guaranteed with Omnibus installations (because they +> don't specify the full repository path but the parent path), but not for source +> installations. --- diff --git a/doc/administration/troubleshooting/sidekiq.md b/doc/administration/troubleshooting/sidekiq.md index 9d157720ad2..7067958ecb4 100644 --- a/doc/administration/troubleshooting/sidekiq.md +++ b/doc/administration/troubleshooting/sidekiq.md @@ -8,15 +8,15 @@ may not show up and merge requests may not be updated. The following are some troubleshooting steps that will help you diagnose the bottleneck. > **Note:** GitLab administrators/users should consider working through these -debug steps with GitLab Support so the backtraces can be analyzed by our team. -It may reveal a bug or necessary improvement in GitLab. - +> debug steps with GitLab Support so the backtraces can be analyzed by our team. +> It may reveal a bug or necessary improvement in GitLab. +> > **Note:** In any of the backtraces, be wary of suspecting cases where every - thread appears to be waiting in the database, Redis, or waiting to acquire - a mutex. This **may** mean there's contention in the database, for example, - but look for one thread that is different than the rest. This other thread - may be using all available CPU, or have a Ruby Global Interpreter Lock, - preventing other threads from continuing. +> thread appears to be waiting in the database, Redis, or waiting to acquire +> a mutex. This **may** mean there's contention in the database, for example, +> but look for one thread that is different than the rest. This other thread +> may be using all available CPU, or have a Ruby Global Interpreter Lock, +> preventing other threads from continuing. ## Thread dump diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index 77e73b23021..aec9a359ada 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -18,7 +18,7 @@ below. >**Notes:** For historical reasons, uploads are stored into a base directory, which by default is `uploads/-/system`. It is strongly discouraged to change this configuration option on an existing GitLab installation. -_The uploads are stored by default in `/var/opt/gitlab/gitlab-rails/public/uploads/-/system`._ +_The uploads are stored by default in `/var/opt/gitlab/gitlab-rails/uploads/-/system`._ 1. To change the storage path for example to `/mnt/storage/uploads`, edit `/etc/gitlab/gitlab.rb` and add the following line: @@ -50,9 +50,10 @@ _The uploads are stored by default in ### Using object storage ->**Notes:** -- [Introduced][ee-3867] in [GitLab Enterprise Edition Premium][eep] 10.5. -- Since version 11.1, we support direct_upload to S3. +> **Notes:** +> +> - [Introduced][ee-3867] in [GitLab Enterprise Edition Premium][eep] 10.5. +> - Since version 11.1, we support direct_upload to S3. If you don't want to use the local disk where GitLab is installed to store the uploads, you can use an object storage provider like AWS S3 instead. @@ -85,6 +86,7 @@ The connection settings match those provided by [Fog](https://github.com/fog), a | `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) | | `path_style` | Set to true to use `host/bucket_name/object` style paths instead of `bucket_name.host/object`. Leave as false for AWS S3 | false | +| `use_iam_profile` | Set to true to use IAM profile instead of access keys | false **In Omnibus installations:** @@ -105,8 +107,8 @@ _The uploads are stored by default in } ``` ->**Note:** -If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs. + >**Note:** + If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs. ```ruby gitlab_rails['uploads_object_store_connection'] = { @@ -119,28 +121,28 @@ If you are using AWS IAM profiles, be sure to omit the AWS access key and secret 1. Save the file and [reconfigure GitLab][] for the changes to take effect. 1. Migrate any existing local uploads to the object storage: ->**Notes:** -These task complies with the `BATCH` environment variable to process uploads in batch (200 by default). All of the processing will be done in a background worker and requires **no downtime**. - - ```bash - # gitlab-rake gitlab:uploads:migrate[uploader_class, model_class, mount_point] - - # Avatars - gitlab-rake "gitlab:uploads:migrate[AvatarUploader, Project, :avatar]" - gitlab-rake "gitlab:uploads:migrate[AvatarUploader, Group, :avatar]" - gitlab-rake "gitlab:uploads:migrate[AvatarUploader, User, :avatar]" - - # Attachments - gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Note, :attachment]" - gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :logo]" - gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :header_logo]" - - # Markdown - gitlab-rake "gitlab:uploads:migrate[FileUploader, Project]" - gitlab-rake "gitlab:uploads:migrate[PersonalFileUploader, Snippet]" - gitlab-rake "gitlab:uploads:migrate[NamespaceFileUploader, Snippet]" - gitlab-rake "gitlab:uploads:migrate[FileUploader, MergeRequest]" - ``` + > **Notes:** + > These task complies with the `BATCH` environment variable to process uploads in batch (200 by default). All of the processing will be done in a background worker and requires **no downtime**. + + ```bash + # gitlab-rake gitlab:uploads:migrate[uploader_class, model_class, mount_point] + + # Avatars + gitlab-rake "gitlab:uploads:migrate[AvatarUploader, Project, :avatar]" + gitlab-rake "gitlab:uploads:migrate[AvatarUploader, Group, :avatar]" + gitlab-rake "gitlab:uploads:migrate[AvatarUploader, User, :avatar]" + + # Attachments + gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Note, :attachment]" + gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :logo]" + gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :header_logo]" + + # Markdown + gitlab-rake "gitlab:uploads:migrate[FileUploader, Project]" + gitlab-rake "gitlab:uploads:migrate[PersonalFileUploader, Snippet]" + gitlab-rake "gitlab:uploads:migrate[NamespaceFileUploader, Snippet]" + gitlab-rake "gitlab:uploads:migrate[FileUploader, MergeRequest]" + ``` --- @@ -167,32 +169,30 @@ _The uploads are stored by default in 1. Save the file and [restart GitLab][] for the changes to take effect. 1. Migrate any existing local uploads to the object storage: ->**Notes:** - -- These task comply with the `BATCH` environment variable to process uploads in batch (200 by default). All of the processing will be done in a background worker and requires **no downtime**. - -- To migrate in production use `RAILS_ENV=production` environment variable. - - ```bash - # sudo -u git -H bundle exec rake gitlab:uploads:migrate - - # Avatars - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, Project, :avatar]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, Group, :avatar]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, User, :avatar]" - - # Attachments - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Note, :attachment]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :logo]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :header_logo]" - - # Markdown - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, Project]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[PersonalFileUploader, Snippet]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[NamespaceFileUploader, Snippet]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, MergeRequest]" - - ``` + > **Notes:** + > - These task comply with the `BATCH` environment variable to process uploads in batch (200 by default). All of the processing will be done in a background worker and requires **no downtime**. + > - To migrate in production use `RAILS_ENV=production` environment variable. + + ```bash + # sudo -u git -H bundle exec rake gitlab:uploads:migrate + + # Avatars + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, Project, :avatar]" + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, Group, :avatar]" + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, User, :avatar]" + + # Attachments + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Note, :attachment]" + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :logo]" + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :header_logo]" + + # Markdown + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, Project]" + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[PersonalFileUploader, Snippet]" + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[NamespaceFileUploader, Snippet]" + sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, MergeRequest]" + + ``` [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab" [restart gitlab]: restart_gitlab.md#installations-from-source "How to restart GitLab" diff --git a/doc/api/README.md b/doc/api/README.md index e2a6e87a2c3..a351db99bbd 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -3,6 +3,8 @@ Automate GitLab via a simple and powerful API. All definitions can be found under [`/lib/api`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api). +The main GitLab API is a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API. Therefore, documentation in this section assumes knowledge of REST concepts. + ## Resources Documentation for various API resources can be found separately in the @@ -18,10 +20,11 @@ following locations: - [Custom Attributes](custom_attributes.md) - [Deployments](deployments.md) - [Deploy Keys](deploy_keys.md) +- [Dockerfile templates](templates/dockerfiles.md) - [Environments](environments.md) - [Events](events.md) - [Feature flags](features.md) -- [Gitignores templates](templates/gitignores.md) +- [Gitignore templates](templates/gitignores.md) - [GitLab CI Config templates](templates/gitlab_ci_ymls.md) - [Groups](groups.md) - [Group Access Requests](access_requests.md) @@ -40,6 +43,7 @@ following locations: - [Namespaces](namespaces.md) - [Notes](notes.md) (comments) - [Discussions](discussions.md) (threaded comments) +- [Resource Label Events](resource_label_events.md) - [Notification settings](notification_settings.md) - [Open source license templates](templates/licenses.md) - [Pages Domains](pages_domains.md) @@ -52,6 +56,7 @@ following locations: - [Project import/export](project_import_export.md) - [Project Members](members.md) - [Project Snippets](project_snippets.md) +- [Project Templates](project_templates.md) - [Protected Branches](protected_branches.md) - [Protected Tags](protected_tags.md) - [Repositories](repositories.md) @@ -77,8 +82,8 @@ Going forward, we will start on moving to controller-specific endpoints. GraphQL has a number of benefits: 1. We avoid having to maintain two different APIs. -2. Callers of the API can request only what they need. -3. It is versioned by default. +1. Callers of the API can request only what they need. +1. It is versioned by default. It will co-exist with the current v4 REST API. If we have a v5 API, this should be a compatibility layer on top of GraphQL. @@ -139,8 +144,9 @@ There are three ways to authenticate with the GitLab API: 1. [Session cookie](#session-cookie) 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: + 1. [Impersonation tokens](#impersonation-tokens) -2. [Sudo](#sudo) +1. [Sudo](#sudo) If authentication information is invalid or omitted, an error message will be returned with status code `401`: @@ -219,7 +225,8 @@ Impersonation tokens are used exactly like regular personal access tokens, and c ### Sudo -> Needs admin permissions. +NOTE: **Note:** +Only available to [administrators](../user/permissions.md). All API requests support performing an API call as if you were another user, provided you are authenticated as an administrator with an OAuth or Personal Access Token that has the `sudo` scope. @@ -445,28 +452,23 @@ curl --request POST --header "PRIVATE-TOKEN: ********************" \ ## `id` vs `iid` -When you work with the API, you may notice two similar fields in API entities: -`id` and `iid`. The main difference between them is scope. + Some resources have two similarly-named fields. For example, [issues](issues.md), [merge requests](merge_requests.md), and [project milestones](merge_requests.md). The fields are: -For example, an issue might have `id: 46` and `iid: 5`. +- `id`: ID that is unique across all projects. +- `iid`: additional, internal ID that is unique in the scope of a single project. -| Parameter | Description | -| --------- | ----------- | -| `id` | Is unique across all issues and is used for any API call | -| `iid` | Is unique only in scope of a single project. When you browse issues or merge requests with the Web UI, you see the `iid` | +NOTE: **Note:** +The `iid` is displayed in the web UI. -That means that if you want to get an issue via the API you should use the `id`: +If a resource has the `iid` field and the `id` field, the `iid` field is usually used instead of `id` to fetch the resource. -``` -GET /projects/42/issues/:id -``` +For example, suppose a project with `id: 42` has an issue with `id: 46` and `iid: 5`. In this case: -On the other hand, if you want to create a link to a web page you should use -the `iid`: +- A valid API call to retrieve the issue is `GET /projects/42/issues/5` +- An invalid API call to retrieve the issue is `GET /projects/42/issues/46`. -``` -GET /projects/42/issues/:iid -``` +NOTE: **Note:** +Not all resources with the `iid` field are fetched by `iid`. For guidance on which field to use, see the documentation for the specific resource. ## Data validation and error reporting diff --git a/doc/api/branches.md b/doc/api/branches.md index bfb21608d28..4abf0639eb0 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -27,6 +27,7 @@ Example response: "name": "master", "merged": false, "protected": true, + "default": true, "developers_can_push": false, "developers_can_merge": false, "can_push": true, @@ -75,6 +76,7 @@ Example response: "name": "master", "merged": false, "protected": true, + "default": true, "developers_can_push": false, "developers_can_merge": false, "can_push": true, @@ -141,6 +143,7 @@ Example response: "name": "master", "merged": false, "protected": true, + "default": true, "developers_can_push": true, "developers_can_merge": true, "can_push": true @@ -190,6 +193,7 @@ Example response: "name": "master", "merged": false, "protected": false, + "default": true, "developers_can_push": false, "developers_can_merge": false, "can_push": true @@ -234,6 +238,7 @@ Example response: "name": "newbranch", "merged": false, "protected": false, + "default": false, "developers_can_push": false, "developers_can_merge": false, "can_push": true diff --git a/doc/api/commits.md b/doc/api/commits.md index d07b9d5614a..9b7ca4b6e70 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -79,16 +79,18 @@ POST /projects/:id/repository/commits | `actions[]` | array | yes | An array of action hashes to commit as a batch. See the next table for what attributes it can take. | | `author_email` | string | no | Specify the commit author's email address | | `author_name` | string | no | Specify the commit author's name | +| `stats` | boolean | no | Include commit stats. Default is true | | `actions[]` Attribute | Type | Required | Description | | --------------------- | ---- | -------- | ----------- | -| `action` | string | yes | The action to perform, `create`, `delete`, `move`, `update` | +| `action` | string | yes | The action to perform, `create`, `delete`, `move`, `update`, `chmod`| | `file_path` | string | yes | Full path to the file. Ex. `lib/class.rb` | -| `previous_path` | string | no | Original full path to the file being moved. Ex. `lib/class1.rb` | -| `content` | string | no | File content, required for all except `delete`. Optional for `move` | +| `previous_path` | string | no | Original full path to the file being moved. Ex. `lib/class1.rb`. Only considered for `move` action. | +| `content` | string | no | File content, required for all except `delete` and `chmod`. Optional for `move` | | `encoding` | string | no | `text` or `base64`. `text` is default. | | `last_commit_id` | string | no | Last known file commit id. Will be only considered in update, move and delete actions. | +| `execute_filemode` | boolean | no | When `true/false` enables/disables the execute flag on the file. Only considered for `chmod` action. | ```bash PAYLOAD=$(cat << 'JSON' @@ -115,6 +117,11 @@ PAYLOAD=$(cat << 'JSON' "action": "update", "file_path": "foo/bar5", "content": "new content" + }, + { + "action": "chmod", + "file_path": "foo/bar5", + "execute_filemode": true } ] } @@ -464,7 +471,7 @@ Example response: }, { "started_at" : null, - "name" : "flay", + "name" : "test", "allow_failure" : false, "status" : "pending", "created_at" : "2016-01-19T08:40:25.832Z", diff --git a/doc/api/deployments.md b/doc/api/deployments.md index fd11894ea8f..1963b0a21de 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -46,19 +46,21 @@ Example of response "status": "success", "tag": false, "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://gitlab.dev/root", + "created_at": "2015-12-21T13:14:24.077Z", "bio": null, - "created_at": "2016-08-11T07:09:20.351Z", - "id": 1, - "linkedin": "", "location": null, - "name": "Administrator", + "public_email": "", "skype": "", - "state": "active", + "linkedin": "", "twitter": "", - "username": "root", - "web_url": "http://localhost:3000/root", - "website_url": "" + "website_url": "", + "organization": "" } }, "environment": { @@ -103,19 +105,21 @@ Example of response "status": "success", "tag": false, "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://gitlab.dev/root", + "created_at": "2015-12-21T13:14:24.077Z", "bio": null, - "created_at": "2016-08-11T07:09:20.351Z", - "id": 1, - "linkedin": "", "location": null, - "name": "Administrator", + "public_email": "", "skype": "", - "state": "active", + "linkedin": "", "twitter": "", - "username": "root", - "web_url": "http://localhost:3000/root", - "website_url": "" + "website_url": "", + "organization": "" } }, "environment": { @@ -188,19 +192,20 @@ Example of response "started_at": null, "finished_at": "2016-08-11T11:32:35.145Z", "user": { + "id": 1, "name": "Administrator", "username": "root", - "id": 1, "state": "active", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "web_url": "http://localhost:3000/root", - "created_at": "2016-08-11T07:09:20.351Z", + "web_url": "http://gitlab.dev/root", + "created_at": "2015-12-21T13:14:24.077Z", "bio": null, "location": null, "skype": "", "linkedin": "", "twitter": "", - "website_url": "" + "website_url": "", + "organization": "" }, "commit": { "id": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", diff --git a/doc/api/groups.md b/doc/api/groups.md index 64e0d78788d..be75c363a40 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -82,7 +82,7 @@ You can filter by [custom attributes](custom_attributes.md) with: GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_value ``` -## List a groups's subgroups +## List a group's subgroups > [Introduced][ce-15142] in GitLab 10.3. diff --git a/doc/api/issues.md b/doc/api/issues.md index f4c0f4ea65b..cc1d6834a20 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -37,7 +37,7 @@ GET /issues?my_reaction_emoji=star | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `milestone` | string | no | The milestone title. `No+Milestone` lists all issues with no milestone | +| `milestone` | string | no | The milestone title. `No+Milestone` lists all issues with no milestone. `Any+Milestone` lists all issues that have an assigned milestone | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 4bf65a8fafd..aa290ff4cf8 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -33,7 +33,9 @@ Example of response }, "coverage": null, "created_at": "2015-12-24T15:51:21.727Z", + "started_at": "2015-12-24T17:54:24.729Z", "finished_at": "2015-12-24T17:54:24.921Z", + "duration": 0.192, "artifacts_expire_at": "2016-01-23T17:54:24.921Z", "id": 6, "name": "rspec:other", @@ -47,23 +49,25 @@ Example of response "artifacts": [], "runner": null, "stage": "test", - "started_at": "2015-12-24T17:54:24.729Z", "status": "failed", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/6", "user": { - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "bio": null, - "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "linkedin": "", "name": "Administrator", - "skype": "", - "state": "active", - "twitter": "", "username": "root", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", "web_url": "http://gitlab.dev/root", - "website_url": "" + "created_at": "2015-12-21T13:14:24.077Z", + "bio": null, + "location": null, + "public_email": "", + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": "" } }, { @@ -78,6 +82,9 @@ Example of response }, "coverage": null, "created_at": "2015-12-24T15:51:21.802Z", + "started_at": "2015-12-24T17:54:27.722Z", + "finished_at": "2015-12-24T17:54:27.895Z", + "duration": 0.173, "artifacts_file": { "filename": "artifacts.zip", "size": 1000 @@ -88,7 +95,6 @@ Example of response {"file_type": "trace", "size": 1500, "filename": "job.log", "file_format": "raw"}, {"file_type": "junit", "size": 750, "filename": "junit.xml.gz", "file_format": "gzip"} ], - "finished_at": "2015-12-24T17:54:27.895Z", "artifacts_expire_at": "2016-01-23T17:54:27.895Z", "id": 7, "name": "teaspoon", @@ -102,23 +108,25 @@ Example of response "artifacts": [], "runner": null, "stage": "test", - "started_at": "2015-12-24T17:54:27.722Z", "status": "failed", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/7", "user": { - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "bio": null, - "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "linkedin": "", "name": "Administrator", - "skype": "", - "state": "active", - "twitter": "", "username": "root", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", "web_url": "http://gitlab.dev/root", - "website_url": "" + "created_at": "2015-12-21T13:14:24.077Z", + "bio": null, + "location": null, + "public_email": "", + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": "" } } ] @@ -158,7 +166,9 @@ Example of response }, "coverage": null, "created_at": "2015-12-24T15:51:21.727Z", + "started_at": "2015-12-24T17:54:24.729Z", "finished_at": "2015-12-24T17:54:24.921Z", + "duration": 0.192, "artifacts_expire_at": "2016-01-23T17:54:24.921Z", "id": 6, "name": "rspec:other", @@ -172,23 +182,25 @@ Example of response "artifacts": [], "runner": null, "stage": "test", - "started_at": "2015-12-24T17:54:24.729Z", "status": "failed", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/6", "user": { - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "bio": null, - "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "linkedin": "", "name": "Administrator", - "skype": "", - "state": "active", - "twitter": "", "username": "root", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", "web_url": "http://gitlab.dev/root", - "website_url": "" + "created_at": "2015-12-21T13:14:24.077Z", + "bio": null, + "location": null, + "public_email": "", + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": "" } }, { @@ -203,6 +215,9 @@ Example of response }, "coverage": null, "created_at": "2015-12-24T15:51:21.802Z", + "started_at": "2015-12-24T17:54:27.722Z", + "finished_at": "2015-12-24T17:54:27.895Z", + "duration": 0.173, "artifacts_file": { "filename": "artifacts.zip", "size": 1000 @@ -213,7 +228,6 @@ Example of response {"file_type": "trace", "size": 1500, "filename": "job.log", "file_format": "raw"}, {"file_type": "junit", "size": 750, "filename": "junit.xml.gz", "file_format": "gzip"} ], - "finished_at": "2015-12-24T17:54:27.895Z", "artifacts_expire_at": "2016-01-23T17:54:27.895Z", "id": 7, "name": "teaspoon", @@ -227,23 +241,25 @@ Example of response "artifacts": [], "runner": null, "stage": "test", - "started_at": "2015-12-24T17:54:27.722Z", "status": "failed", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/7", "user": { - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "bio": null, - "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "linkedin": "", "name": "Administrator", - "skype": "", - "state": "active", - "twitter": "", "username": "root", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", "web_url": "http://gitlab.dev/root", - "website_url": "" + "created_at": "2015-12-21T13:14:24.077Z", + "bio": null, + "location": null, + "public_email": "", + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": "" } } ] @@ -281,7 +297,9 @@ Example of response }, "coverage": null, "created_at": "2015-12-24T15:51:21.880Z", + "started_at": "2015-12-24T17:54:30.733Z", "finished_at": "2015-12-24T17:54:31.198Z", + "duration": 0.465, "artifacts_expire_at": "2016-01-23T17:54:31.198Z", "id": 8, "name": "rubocop", @@ -295,23 +313,25 @@ Example of response "artifacts": [], "runner": null, "stage": "test", - "started_at": "2015-12-24T17:54:30.733Z", "status": "failed", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/8", "user": { - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "bio": null, - "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "linkedin": "", "name": "Administrator", - "skype": "", - "state": "active", - "twitter": "", "username": "root", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", "web_url": "http://gitlab.dev/root", - "website_url": "" + "created_at": "2015-12-21T13:14:24.077Z", + "bio": null, + "location": null, + "public_email": "", + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": "" } } ``` @@ -319,7 +339,8 @@ Example of response ## Get job artifacts > **Notes**: -- [Introduced][ce-2893] in GitLab 8.5. +> +> - [Introduced][ce-2893] in GitLab 8.5. Get job artifacts of a project. @@ -350,7 +371,8 @@ Response: ## Download the artifacts archive > **Notes**: -- [Introduced][ce-5347] in GitLab 8.10. +> +> - [Introduced][ce-5347] in GitLab 8.10. Download the artifacts archive from the given reference name and job provided the job finished successfully. @@ -472,14 +494,15 @@ Example of response }, "coverage": null, "created_at": "2016-01-11T10:13:33.506Z", - "finished_at": "2016-01-11T10:14:09.526Z", + "started_at": "2016-01-11T10:14:09.526Z", + "finished_at": null, + "duration": 8, "id": 42, "name": "rubocop", "ref": "master", "artifacts": [], "runner": null, "stage": "test", - "started_at": null, "status": "canceled", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/42", @@ -519,14 +542,15 @@ Example of response }, "coverage": null, "created_at": "2016-01-11T10:13:33.506Z", + "started_at": null, "finished_at": null, + "duration": null, "id": 42, "name": "rubocop", "ref": "master", "artifacts": [], "runner": null, "stage": "test", - "started_at": null, "status": "pending", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/42", @@ -579,6 +603,7 @@ Example of response "created_at": "2016-01-11T10:13:33.506Z", "started_at": "2016-01-11T10:13:33.506Z", "finished_at": "2016-01-11T10:15:10.506Z", + "duration": 97.0, "status": "failed", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/42", @@ -631,6 +656,7 @@ Example response: "created_at": "2016-01-11T10:13:33.506Z", "started_at": "2016-01-11T10:13:33.506Z", "finished_at": "2016-01-11T10:15:10.506Z", + "duration": 97.0, "status": "failed", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/42", @@ -670,14 +696,15 @@ Example of response }, "coverage": null, "created_at": "2016-01-11T10:13:33.506Z", + "started_at": null, "finished_at": null, + "duration": null, "id": 42, "name": "rubocop", "ref": "master", "artifacts": [], "runner": null, "stage": "test", - "started_at": null, "status": "started", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/42", diff --git a/doc/api/keys.md b/doc/api/keys.md index ddcf7830621..06b31a67d6a 100644 --- a/doc/api/keys.md +++ b/doc/api/keys.md @@ -27,10 +27,16 @@ Parameters: "web_url": "http://localhost:3000/john_smith", "created_at": "2015-09-03T07:24:01.670Z", "bio": null, + "location": null, + "public_email": "john@example.com", "skype": "", "linkedin": "", "twitter": "", "website_url": "", + "organization": null, + "last_sign_in_at": "2015-09-03T07:24:01.670Z", + "confirmed_at": "2015-09-03T07:24:01.670Z", + "last_activity_on": "2015-09-03", "email": "john@example.com", "theme_id": 2, "color_scheme_id": 1, @@ -40,6 +46,8 @@ Parameters: "can_create_group": true, "can_create_project": true, "two_factor_enabled": false + "external": false, + "private_profile": null } } ``` diff --git a/doc/api/members.md b/doc/api/members.md index 7b228b92594..bb4fae35f52 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -15,6 +15,7 @@ The access levels are defined in the `Gitlab::Access` module. Currently, these l ## List all members of a group or project Gets a list of group or project members viewable by the authenticated user. +Returns only direct members and not inherited members through ancestors groups. ``` GET /groups/:id/members @@ -61,6 +62,7 @@ Example response: ## List all members of a group or project including inherited members Gets a list of group or project members viewable by the authenticated user, including inherited members through ancestor groups. +Returns multiple times the same user (with different member attributes) when the user is a member of the project/group and of one or more ancestor group. ``` GET /groups/:id/members/all diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 58d05a70d05..862ee398a84 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -47,41 +47,45 @@ Parameters: | `source_branch` | string | no | Return merge requests with the given source branch | | `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | +| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests | ```json [ { "id": 1, "iid": 1, - "target_branch": "master", - "source_branch": "test1", "project_id": 3, "title": "test1", + "description": "fixed login page css paddings", "state": "opened", "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 2, "target_project_id": 3, - "labels": [ ], - "description": "fixed login page css paddings", + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, @@ -92,23 +96,28 @@ Parameters: "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", + "allow_collaboration": false, + "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "squash": false } ] ``` @@ -168,35 +177,38 @@ Parameters: { "id": 1, "iid": 1, - "target_branch": "master", - "source_branch": "test1", "project_id": 3, "title": "test1", + "description": "fixed login page css paddings", "state": "opened", "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 2, "target_project_id": 3, - "labels": [ ], - "description": "fixed login page css paddings", + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, @@ -207,24 +219,28 @@ Parameters: "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", - "discussion_locked": false, + "allow_collaboration": false, + "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "squash": false } ] ``` @@ -274,35 +290,38 @@ Parameters: { "id": 1, "iid": 1, - "target_branch": "master", - "source_branch": "test1", "project_id": 3, "title": "test1", + "description": "fixed login page css paddings", "state": "opened", "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 2, "target_project_id": 3, - "labels": [ ], - "description": "fixed login page css paddings", + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, @@ -313,23 +332,26 @@ Parameters: "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-10-22", + "start_date": "2018-09-08", + "web_url": "gitlab.example.com/my-group/my-project/milestones/1" }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "web_url": "http://example.com/example/example/merge_requests/1", - "discussion_locked": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "squash": false } ] ``` @@ -352,40 +374,44 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The internal ID of the merge request - `render_html` (optional) - If `true` response includes rendered HTML for title and description +- `include_diverged_commits_count` (optional) - If `true` response includes the commits behind the target branch ```json { "id": 1, "iid": 1, - "target_branch": "master", - "source_branch": "test1", "project_id": 3, "title": "test1", - "state": "merged", + "description": "fixed login page css paddings", + "state": "opened", "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { - "state" : "active", - "web_url" : "https://gitlab.example.com/root", - "avatar_url" : null, - "username" : "root", - "id" : 1, - "name" : "Administrator" + "id": 1, + "name": "Administrator", + "username": "admin", + "state": "active", + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "assignee": { - "state" : "active", - "web_url" : "https://gitlab.example.com/root", - "avatar_url" : null, - "username" : "root", - "id" : 1, - "name" : "Administrator" + "id": 1, + "name": "Administrator", + "username": "admin", + "state": "active", + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 2, "target_project_id": 3, - "labels": [ ], - "description": "fixed login page css paddings", + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, @@ -396,46 +422,57 @@ Parameters: "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", - "subscribed" : true, "sha": "8888888888888888888888888888888888888888", - "merge_commit_sha": "9999999999999999999999999999999999999999", + "merge_commit_sha": null, "user_notes_count": 1, - "changes_count": "1", + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", - "discussion_locked": false, + "allow_collaboration": false, + "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null }, - "closed_at": "2018-01-19T14:36:11.086Z", - "latest_build_started_at": null, - "latest_build_finished_at": null, + "squash": false, + "subscribed": false, + "changes_count": "1", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, + "latest_build_started_at": "2018-09-07T07:27:38.472Z", + "latest_build_finished_at": "2018-09-07T08:07:06.012Z", "first_deployed_to_production_at": null, "pipeline": { - "id": 8, - "ref": "master", - "sha": "2dc6aa325a317eda67812f05600bdf0fcdc70ab0", - "status": "created" + "id": 29626725, + "sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "ref": "patch-28", + "status": "success", + "web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725" }, - "merged_by": null, - "merged_at": null, - "closed_by": { - "state" : "active", - "web_url" : "https://gitlab.example.com/root", - "avatar_url" : null, - "username" : "root", - "id" : 1, - "name" : "Administrator" - } + "diff_refs": { + "base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00", + "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" + }, + "diverged_commits_count": 2 } ``` @@ -655,65 +692,99 @@ POST /projects/:id/merge_requests { "id": 1, "iid": 1, - "target_branch": "master", - "source_branch": "test1", - "project_id": 4, + "project_id": 3, "title": "test1", + "description": "fixed login page css paddings", "state": "opened", + "created_at": "2017-04-29T08:46:00Z", + "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, - "source_project_id": 3, - "target_project_id": 4, - "labels": [ ], - "description": "fixed login page css paddings", + "source_project_id": 2, + "target_project_id": 3, + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, "iid": 1, - "project_id": 4, + "project_id": 3, "title": "v2.0", "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", - "subscribed" : true, "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, - "user_notes_count": 0, - "changes_count": "1", + "user_notes_count": 1, + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", - "discussion_locked": false, "allow_collaboration": false, "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "squash": false, + "subscribed": false, + "changes_count": "1", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, + "latest_build_started_at": "2018-09-07T07:27:38.472Z", + "latest_build_finished_at": "2018-09-07T08:07:06.012Z", + "first_deployed_to_production_at": null, + "pipeline": { + "id": 29626725, + "sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "ref": "patch-28", + "status": "success", + "web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725" + }, + "diff_refs": { + "base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00", + "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" + }, + "diverged_commits_count": 2 } ``` @@ -748,64 +819,99 @@ Must include at least one non-required attribute from above. { "id": 1, "iid": 1, - "target_branch": "master", - "project_id": 4, + "project_id": 3, "title": "test1", + "description": "fixed login page css paddings", "state": "opened", + "created_at": "2017-04-29T08:46:00Z", + "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, - "source_project_id": 3, - "target_project_id": 4, - "labels": [ ], - "description": "description1", + "source_project_id": 2, + "target_project_id": 3, + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, "iid": 1, - "project_id": 4, + "project_id": 3, "title": "v2.0", "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", - "subscribed" : true, "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, - "changes_count": "1", + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", - "discussion_locked": false, "allow_collaboration": false, "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "squash": false, + "subscribed": false, + "changes_count": "1", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, + "latest_build_started_at": "2018-09-07T07:27:38.472Z", + "latest_build_finished_at": "2018-09-07T08:07:06.012Z", + "first_deployed_to_production_at": null, + "pipeline": { + "id": 29626725, + "sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "ref": "patch-28", + "status": "success", + "web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725" + }, + "diff_refs": { + "base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00", + "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" + }, + "diverged_commits_count": 2 } ``` @@ -849,70 +955,106 @@ Parameters: - `merge_request_iid` (required) - Internal ID of MR - `merge_commit_message` (optional) - Custom merge commit message - `should_remove_source_branch` (optional) - if `true` removes the source branch -- `merge_when_pipeline_succeeds` (optional) - if `true` the MR is merged when the pipeline succeeds +- `merge_when_pipeline_succeeds` (optional) - if `true` the MR is merged when the pipeline succeeds - `sha` (optional) - if present, then this SHA must match the HEAD of the source branch, otherwise the merge will fail ```json { "id": 1, "iid": 1, - "target_branch": "master", - "source_branch": "test1", "project_id": 3, "title": "test1", - "state": "merged", + "description": "fixed login page css paddings", + "state": "opened", + "created_at": "2017-04-29T08:46:00Z", + "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, - "source_project_id": 4, - "target_project_id": 4, - "labels": [ ], - "description": "fixed login page css paddings", + "source_project_id": 2, + "target_project_id": 3, + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, "iid": 1, - "project_id": 4, + "project_id": 3, "title": "v2.0", "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", - "subscribed" : true, "sha": "8888888888888888888888888888888888888888", - "merge_commit_sha": "9999999999999999999999999999999999999999", + "merge_commit_sha": null, "user_notes_count": 1, - "changes_count": "1", + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", - "discussion_locked": false, + "allow_collaboration": false, + "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "squash": false, + "subscribed": false, + "changes_count": "1", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, + "latest_build_started_at": "2018-09-07T07:27:38.472Z", + "latest_build_finished_at": "2018-09-07T08:07:06.012Z", + "first_deployed_to_production_at": null, + "pipeline": { + "id": 29626725, + "sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "ref": "patch-28", + "status": "success", + "web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725" + }, + "diff_refs": { + "base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00", + "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" + }, + "diverged_commits_count": 2 } ``` @@ -929,69 +1071,105 @@ PUT /projects/:id/merge_requests/:merge_request_iid/cancel_merge_when_pipeline_s Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `merge_request_iid` (required) - Internal ID of MR +- `merge_request_iid` (required) - Internal ID of MR ```json { "id": 1, "iid": 1, - "target_branch": "master", - "source_branch": "test1", "project_id": 3, "title": "test1", + "description": "fixed login page css paddings", "state": "opened", + "created_at": "2017-04-29T08:46:00Z", + "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, - "source_project_id": 4, - "target_project_id": 4, - "labels": [ ], - "description": "fixed login page css paddings", + "source_project_id": 2, + "target_project_id": 3, + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, "iid": 1, - "project_id": 4, + "project_id": 3, "title": "v2.0", "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, - "merge_when_pipeline_succeeds": true, + "merge_when_pipeline_succeeds": false, "merge_status": "can_be_merged", - "subscribed" : true, "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, - "changes_count": "1", + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", - "discussion_locked": false, + "allow_collaboration": false, + "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "squash": false, + "subscribed": false, + "changes_count": "1", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, + "latest_build_started_at": "2018-09-07T07:27:38.472Z", + "latest_build_finished_at": "2018-09-07T08:07:06.012Z", + "first_deployed_to_production_at": null, + "pipeline": { + "id": 29626725, + "sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "ref": "patch-28", + "status": "success", + "web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725" + }, + "diff_refs": { + "base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00", + "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" + }, + "diverged_commits_count": 2 } ``` @@ -1059,7 +1237,7 @@ Example response when the GitLab issue tracker is used: "labels" : [], "user_notes_count": 1, "changes_count": "1" - }, + } ] ``` @@ -1096,54 +1274,101 @@ Example response: ```json { - "id": 17, + "id": 1, "iid": 1, - "project_id": 5, - "title": "Et et sequi est impedit nulla ut rem et voluptatem.", - "description": "Consequatur velit eos rerum optio autem. Quia id officia quaerat dolorum optio. Illo laudantium aut ipsum dolorem.", + "project_id": 3, + "title": "test1", + "description": "fixed login page css paddings", "state": "opened", - "created_at": "2016-04-05T21:42:23.233Z", - "updated_at": "2016-04-05T22:11:52.900Z", - "target_branch": "ui-dev-kit", - "source_branch": "version-1-9", + "created_at": "2017-04-29T08:46:00Z", + "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { - "name": "Eileen Skiles", - "username": "leila", - "id": 19, + "id": 1, + "name": "Administrator", + "username": "admin", "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/39ce4a2822cc896933ffbd68c1470e55?s=80&d=identicon", - "web_url": "https://gitlab.example.com/leila" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "assignee": { - "name": "Celine Wehner", - "username": "carli", - "id": 16, + "id": 1, + "name": "Administrator", + "username": "admin", "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/f4cd5605b769dd2ce405a27c6e6f2684?s=80&d=identicon", - "web_url": "https://gitlab.example.com/carli" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, - "source_project_id": 5, - "target_project_id": 5, - "labels": [], + "source_project_id": 2, + "target_project_id": 3, + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { - "id": 7, + "id": 5, "iid": 1, - "project_id": 5, + "project_id": 3, "title": "v2.0", - "description": "Corrupti eveniet et velit occaecati dolorem est rerum aut.", + "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", "state": "closed", - "created_at": "2016-04-05T21:41:40.905Z", - "updated_at": "2016-04-05T21:41:40.905Z", - "due_date": null + "created_at": "2015-02-02T19:49:26.013Z", + "updated_at": "2015-02-02T19:49:26.013Z", + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, - "merge_when_pipeline_succeeds": false, - "merge_status": "cannot_be_merged", - "subscribed": true, + "merge_when_pipeline_succeeds": true, + "merge_status": "can_be_merged", "sha": "8888888888888888888888888888888888888888", - "merge_commit_sha": null + "merge_commit_sha": null, + "user_notes_count": 1, + "discussion_locked": null, + "should_remove_source_branch": true, + "force_remove_source_branch": false, + "allow_collaboration": false, + "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, + "squash": false, + "subscribed": false, + "changes_count": "1", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, + "latest_build_started_at": "2018-09-07T07:27:38.472Z", + "latest_build_finished_at": "2018-09-07T08:07:06.012Z", + "first_deployed_to_production_at": null, + "pipeline": { + "id": 29626725, + "sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "ref": "patch-28", + "status": "success", + "web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725" + }, + "diff_refs": { + "base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00", + "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" + }, + "diverged_commits_count": 2 } ``` @@ -1170,54 +1395,101 @@ Example response: ```json { - "id": 17, + "id": 1, "iid": 1, - "project_id": 5, - "title": "Et et sequi est impedit nulla ut rem et voluptatem.", - "description": "Consequatur velit eos rerum optio autem. Quia id officia quaerat dolorum optio. Illo laudantium aut ipsum dolorem.", + "project_id": 3, + "title": "test1", + "description": "fixed login page css paddings", "state": "opened", - "created_at": "2016-04-05T21:42:23.233Z", - "updated_at": "2016-04-05T22:11:52.900Z", - "target_branch": "ui-dev-kit", - "source_branch": "version-1-9", + "created_at": "2017-04-29T08:46:00Z", + "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { - "name": "Eileen Skiles", - "username": "leila", - "id": 19, + "id": 1, + "name": "Administrator", + "username": "admin", "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/39ce4a2822cc896933ffbd68c1470e55?s=80&d=identicon", - "web_url": "https://gitlab.example.com/leila" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "assignee": { - "name": "Celine Wehner", - "username": "carli", - "id": 16, + "id": 1, + "name": "Administrator", + "username": "admin", "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/f4cd5605b769dd2ce405a27c6e6f2684?s=80&d=identicon", - "web_url": "https://gitlab.example.com/carli" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, - "source_project_id": 5, - "target_project_id": 5, - "labels": [], + "source_project_id": 2, + "target_project_id": 3, + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { - "id": 7, + "id": 5, "iid": 1, - "project_id": 5, + "project_id": 3, "title": "v2.0", - "description": "Corrupti eveniet et velit occaecati dolorem est rerum aut.", + "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", "state": "closed", - "created_at": "2016-04-05T21:41:40.905Z", - "updated_at": "2016-04-05T21:41:40.905Z", - "due_date": null + "created_at": "2015-02-02T19:49:26.013Z", + "updated_at": "2015-02-02T19:49:26.013Z", + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, - "merge_when_pipeline_succeeds": false, - "merge_status": "cannot_be_merged", - "subscribed": false, + "merge_when_pipeline_succeeds": true, + "merge_status": "can_be_merged", "sha": "8888888888888888888888888888888888888888", - "merge_commit_sha": null + "merge_commit_sha": null, + "user_notes_count": 1, + "discussion_locked": null, + "should_remove_source_branch": true, + "force_remove_source_branch": false, + "allow_collaboration": false, + "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, + "squash": false, + "subscribed": false, + "changes_count": "1", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, + "latest_build_started_at": "2018-09-07T07:27:38.472Z", + "latest_build_finished_at": "2018-09-07T08:07:06.012Z", + "first_deployed_to_production_at": null, + "pipeline": { + "id": 29626725, + "sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "ref": "patch-28", + "status": "success", + "web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725" + }, + "diff_refs": { + "base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00", + "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" + }, + "diverged_commits_count": 2 } ``` diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 07e66f89443..8f1a5c8e19b 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -19,7 +19,7 @@ Parameters: | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | Array[integer] | optional | Return only the milestones having the given `iid` | -| `state` | string | optional | Return only `active` or `closed` milestones` | +| `state` | string | optional | Return only `active` or `closed` milestones | | `search` | string | optional | Return only milestones with a title or description matching the provided string | ```bash diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index 77bb7a55d8c..8a1e6b52092 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -1,6 +1,6 @@ # GitLab as an OAuth2 provider -This document covers using the [OAuth2](https://oauth.net/2/) protocol to allow other services access Gitlab resources on user's behalf. +This document covers using the [OAuth2](https://oauth.net/2/) protocol to allow other services access GitLab resources on user's behalf. If you want GitLab to be an OAuth authentication service provider to sign into other services please see the [OAuth2 provider](../integration/oauth_provider.md) documentation. @@ -9,7 +9,7 @@ This functionality is based on [doorkeeper gem](https://github.com/doorkeeper-ge ## Supported OAuth2 Flows -Gitlab currently supports following authorization flows: +GitLab currently supports following authorization flows: * *Web Application Flow* - Most secure and common type of flow, designed for the applications with secure server-side. * *Implicit Flow* - This flow is designed for user-agent only apps (e.g. single page web application running on GitLab Pages). @@ -76,7 +76,7 @@ Check [RFC spec](http://tools.ietf.org/html/rfc6749#section-4.2) for a detailed Unlike the web flow, the client receives an `access token` immediately as a result of the authorization request. The flow does not use client secret or authorization code because all of the application code and storage is easily accessible, therefore __secrets__ can leak easily. ->**Important:** Avoid using this flow for applications that store data outside of the Gitlab instance. If you do, make sure to verify `application id` +>**Important:** Avoid using this flow for applications that store data outside of the GitLab instance. If you do, make sure to verify `application id` associated with access token before granting access to the data (see [/oauth/token/info](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples#get----oauthtokeninfo)). @@ -146,7 +146,7 @@ access_token = client.password.get_token('user@example.com', 'secret') puts access_token.token ``` -## Access Gitlab API with `access token` +## Access GitLab API with `access token` The `access token` allows you to make requests to the API on a behalf of a user. You can pass the token either as GET parameter ``` diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md new file mode 100644 index 00000000000..ebdfa975849 --- /dev/null +++ b/doc/api/project_templates.md @@ -0,0 +1,135 @@ +# Project templates API + +This API is a project-specific implementation of these endpoints: + +- [Dockerfile templates](templates/dockerfiles.md) +- [Gitignore templates](templates/gitignores.md) +- [GitLab CI Config templates](templates/gitlab_ci_ymls.md) +- [Open source license templates](templates/licenses.md) + +It deprecates those endpoints, which will be removed for API version 5. + +Project-specific templates will be added to this API in time. This includes, but +is not limited to: + +- [Issue and Merge Request templates](../user/project/description_templates.html) +- [Group level file templates](https://gitlab.com/gitlab-org/gitlab-ee/issues/5987) **(Premium)** + +## Get all templates of a particular type + +``` +GET /projects/:id/templates/:type +``` + +| Attribute | Type | Required | Description | +| ---------- | ------ | -------- | ----------- | +| `id ` | integer / string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `type` | string | yes| The type `(dockerfiles|gitignores|gitlab_ci_ymls|licenses)` of the template | + +Example response (licenses): + +```json +[ + { + "key": "epl-1.0", + "name": "Eclipse Public License 1.0" + }, + { + "key": "lgpl-3.0", + "name": "GNU Lesser General Public License v3.0" + }, + { + "key": "unlicense", + "name": "The Unlicense" + }, + { + "key": "agpl-3.0", + "name": "GNU Affero General Public License v3.0" + }, + { + "key": "gpl-3.0", + "name": "GNU General Public License v3.0" + }, + { + "key": "bsd-3-clause", + "name": "BSD 3-clause \"New\" or \"Revised\" License" + }, + { + "key": "lgpl-2.1", + "name": "GNU Lesser General Public License v2.1" + }, + { + "key": "mit", + "name": "MIT License" + }, + { + "key": "apache-2.0", + "name": "Apache License 2.0" + }, + { + "key": "bsd-2-clause", + "name": "BSD 2-clause \"Simplified\" License" + }, + { + "key": "mpl-2.0", + "name": "Mozilla Public License 2.0" + }, + { + "key": "gpl-2.0", + "name": "GNU General Public License v2.0" + } +] +``` + +## Get one template of a particular type + +``` +GET /projects/:id/templates/:type/:key +``` + +| Attribute | Type | Required | Description | +| ---------- | ------ | -------- | ----------- | +| `id ` | integer / string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `type` | string | yes| The type `(dockerfiles|gitignores|gitlab_ci_ymls|licenses)` of the template | +| `key` | string | yes | The key of the template, as obtained from the collection endpoint | +| `project` | string | no | The project name to use when expanding placeholders in the template. Only affects licenses | +| `fullname` | string | no | The full name of the copyright holder to use when expanding placeholders in the template. Only affects licenses | + +Example response (Dockerfile): + + +```json +{ + "name": "Binary", + "content": "# This file is a template, and might need editing before it works on your project.\n# This Dockerfile installs a compiled binary into a bare system.\n# You must either commit your compiled binary into source control (not recommended)\n# or build the binary first as part of a CI/CD pipeline.\n\nFROM buildpack-deps:jessie\n\nWORKDIR /usr/local/bin\n\n# Change `app` to whatever your binary is called\nAdd app .\nCMD [\"./app\"]\n" +} + +``` + +Example response (license): + +```json +{ + "key": "mit", + "name": "MIT License", + "nickname": null, + "popular": true, + "html_url": "http://choosealicense.com/licenses/mit/", + "source_url": "https://opensource.org/licenses/MIT", + "description": "A short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code.", + "conditions": [ + "include-copyright" + ], + "permissions": [ + "commercial-use", + "modifications", + "distribution", + "private-use" + ], + "limitations": [ + "liability", + "warranty" + ], + "content": "MIT License\n\nCopyright (c) 2018 [fullname]\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" +} +``` diff --git a/doc/api/projects.md b/doc/api/projects.md index 0936ff52dae..947e7db9c52 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -661,6 +661,7 @@ POST /projects | `avatar` | mixed | no | Image file for avatar of the project | | `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line | | `ci_config_path` | string | no | The path to CI config file | +| `initialize_with_readme` | boolean | no | `false` by default | ## Create project for user @@ -710,7 +711,7 @@ PUT /projects/:id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `name` | string | yes | The name of the project | +| `name` | string | no | The name of the project | | `path` | string | no | Custom repository name for the project. By default generated based on name | | `default_branch` | string | no | `master` by default | | `description` | string | no | Short project description | @@ -1334,6 +1335,7 @@ GET /projects/:id/hooks/:hook_id "url": "http://example.com/hook", "project_id": 3, "push_events": true, + "push_events_branch_filter": "", "issues_events": true, "confidential_issues_events": true, "merge_requests_events": true, @@ -1360,6 +1362,7 @@ POST /projects/:id/hooks | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `url` | string | yes | The hook URL | | `push_events` | boolean | no | Trigger hook on push events | +| `push_events_branch_filter` | string | no | Trigger hook on push events for matching branches only | | `issues_events` | boolean | no | Trigger hook on issues events | | `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events | | `merge_requests_events` | boolean | no | Trigger hook on merge requests events | @@ -1385,6 +1388,7 @@ PUT /projects/:id/hooks/:hook_id | `hook_id` | integer | yes | The ID of the project hook | | `url` | string | yes | The hook URL | | `push_events` | boolean | no | Trigger hook on push events | +| `push_events_branch_filter` | string | no | Trigger hook on push events for matching branches only | | `issues_events` | boolean | no | Trigger hook on issues events | | `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events | | `merge_requests_events` | boolean | no | Trigger hook on merge requests events | diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index f6813f27dc0..ed8837574a0 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -4,7 +4,7 @@ **Valid access levels** -The access levels are defined in the `ProtectedRefAccess::ALLOWED_ACCESS_LEVELS` constant. Currently, these levels are recognized: +The access levels are defined in the `ProtectedRefAccess.allowed_access_levels` method. Currently, these levels are recognized: ``` 0 => No access 30 => Developer access diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index 49fb9bc141d..0623a6b02ae 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -90,6 +90,8 @@ Like [Get file from repository](repository_files.md#get-file-from-repository) yo ## Create new file in repository +This allows you to create a single file. For creating multiple files with a single request see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions). + ``` POST /projects/:id/repository/files/:file_path ``` @@ -120,6 +122,8 @@ Parameters: ## Update existing file in repository +This allows you to update a single file. For updating multiple files with a single request see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions). + ``` PUT /projects/:id/repository/files/:file_path ``` @@ -160,6 +164,8 @@ Currently gitlab-shell has a boolean return code, preventing GitLab from specify ## Delete existing file in repository +This allows you to delete a single file. For deleting multiple files with a singleh request see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions). + ``` DELETE /projects/:id/repository/files/:file_path ``` diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md new file mode 100644 index 00000000000..33e4821ccf4 --- /dev/null +++ b/doc/api/resource_label_events.md @@ -0,0 +1,175 @@ +# Resource label events API + +Resource label events keep track about who, when, and which label was added or removed to an issuable. + +## Issues + +### List project issue label events + +Gets a list of all label events for a single issue. + +``` +GET /projects/:id/issues/:issue_iid/resource_label_events +``` + +| Attribute | Type | Required | Description | +| ------------------- | ---------------- | ---------- | ------------ | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `issue_iid` | integer | yes | The IID of an issue | + +```json +[ + { + "id": 142, + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://gitlab.example.com/root" + }, + "created_at": "2018-08-20T13:38:20.077Z", + "resource_type": "Issue", + "resource_id": 253, + "label": { + "id": 73, + "name": "a1", + "color": "#34495E", + "description": "" + }, + "action": "add" + }, + { + "id": 143, + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://gitlab.example.com/root" + }, + "created_at": "2018-08-20T13:38:20.077Z", + "resource_type": "Issue", + "resource_id": 253, + "label": { + "id": 74, + "name": "p1", + "color": "#0033CC", + "description": "" + }, + "action": "remove" + } +] +``` + +```bash +curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/resource_label_events +``` + +### Get single issue label event + +Returns a single label event for a specific project issue + +``` +GET /projects/:id/issues/:issue_iid/resource_label_events/:resource_label_event_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `issue_iid` | integer | yes | The IID of an issue | +| `resource_label_event_id` | integer | yes | The ID of a label event | + +```bash +curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/resource_label_events/1 +``` + +## Merge requests + +### List project merge request label events + +Gets a list of all label events for a single merge request. + +``` +GET /projects/:id/merge_requests/:merge_request_iid/resource_label_events +``` + +| Attribute | Type | Required | Description | +| ------------------- | ---------------- | ---------- | ------------ | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `merge_request_iid` | integer | yes | The IID of a merge request | + +```json +[ + { + "id": 119, + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://gitlab.example.com/root" + }, + "created_at": "2018-08-20T06:17:28.394Z", + "resource_type": "MergeRequest", + "resource_id": 28, + "label": { + "id": 74, + "name": "p1", + "color": "#0033CC", + "description": "" + }, + "action": "add" + }, + { + "id": 120, + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://gitlab.example.com/root" + }, + "created_at": "2018-08-20T06:17:28.394Z", + "resource_type": "MergeRequest", + "resource_id": 28, + "label": { + "id": 41, + "name": "project", + "color": "#D1D100", + "description": "" + }, + "action": "add" + } +] +``` + +```bash +curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/resource_label_events +``` + +### Get single merge request label event + +Returns a single label event for a specific project merge request + +``` +GET /projects/:id/merge_requests/:merge_request_iid/resource_label_events/:resource_label_event_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| ------------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `merge_request_iid` | integer | yes | The IID of a merge request | +| `resource_label_event_id` | integer | yes | The ID of a label event | + +```bash +curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/resource_label_events/120 +``` diff --git a/doc/api/runners.md b/doc/api/runners.md index ac814bbf19a..0bcbd0aebf0 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -11,11 +11,15 @@ Get a list of specific runners available to the user. ``` GET /runners GET /runners?scope=active +GET /runners?type=project_type +GET /runners?status=active ``` | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `scope` | string | no | The scope of specific runners to show, one of: `active`, `paused`, `online`; showing all runners if none provided | +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided | +| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | +| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | ``` curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners" @@ -56,11 +60,15 @@ is restricted to users with `admin` privileges. ``` GET /runners/all GET /runners/all?scope=online +GET /runners/all?type=project_type +GET /runners/all?status=active ``` | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `scope` | string | no | The scope of runners to show, one of: `specific`, `shared`, `active`, `paused`, `online`; showing all runners if none provided | +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of runners to show, one of: `specific`, `shared`, `active`, `paused`, `online`, `offline`; showing all runners if none provided | +| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | +| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | ``` curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/all" @@ -286,6 +294,7 @@ Example response: "created_at": "2017-11-16T18:38:46.000Z", "bio": null, "location": null, + "public_email": "", "skype": "", "linkedin": "", "twitter": "", @@ -336,11 +345,17 @@ usage is enabled in the project's settings. ``` GET /projects/:id/runners +GET /projects/:id/runners?scope=active +GET /projects/:id/runners?type=project_type +GET /projects/:id/runners?status=active ``` -| Attribute | Type | Required | Description | -|-----------|---------|----------|---------------------| +| 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 | +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided | +| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | +| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | ``` curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners" diff --git a/doc/api/services.md b/doc/api/services.md index 8c59b232b6d..741ea83070f 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -544,10 +544,10 @@ GET /projects/:id/services/jira Set JIRA service for a project. ->**Notes:** -- Starting with GitLab 8.14, `api_url`, `issues_url`, `new_issue_url` and - `project_url` are replaced by `project_key`, `url`. If you are using an - older version, [follow this documentation][old-jira-api]. +> **Notes:** +> - Starting with GitLab 8.14, `api_url`, `issues_url`, `new_issue_url` and +> `project_url` are replaced by `project_key`, `url`. If you are using an +> older version, [follow this documentation][old-jira-api]. ``` PUT /projects/:id/services/jira diff --git a/doc/api/settings.md b/doc/api/settings.md index b480d62e16a..1c41b3345ad 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -1,12 +1,14 @@ # Application settings API -These API calls allow you to read and modify GitLab instance application -settings as appear in `/admin/application_settings`. You have to be an +These API calls allow you to read and modify GitLab instance +[application settings](#list-of-settings-that-can-be-accessed-via-api-calls) +as appear in `/admin/application_settings`. You have to be an administrator in order to perform this action. ## Get current application settings -List the current application settings of the GitLab instance. +List the current [application settings](#list-of-settings-that-can-be-accessed-via-api-calls) +of the GitLab instance. ``` GET /application/settings @@ -63,108 +65,13 @@ Example response: ## Change application settings +Use an API call to modify GitLab instance +[application settings](#list-of-settings-that-can-be-accessed-via-api-calls). + ``` PUT /application/settings ``` -| Attribute | Type | Required | Description | -| --------- | ---- | :------: | ----------- | -| `admin_notification_email` | string | no | Abuse reports will be sent to this address if it is set. Abuse reports are always available in the admin area. | -| `after_sign_out_path` | string | no | Where to redirect users after logout | -| `after_sign_up_text` | string | no | Text shown to the user after signing up | -| `akismet_api_key` | string | no | API key for akismet spam protection | -| `akismet_enabled` | boolean | no | Enable or disable akismet spam protection | -| `circuitbreaker_access_retries` | integer | no | The number of attempts GitLab will make to access a storage. | -| `circuitbreaker_check_interval` | integer | no | Number of seconds in between storage checks. | -| `circuitbreaker_failure_count_threshold` | integer | no | The number of failures of after which GitLab will completely prevent access to the storage. | -| `circuitbreaker_failure_reset_time` | integer | no | Time in seconds GitLab will keep storage failure information. When no failures occur during this time, the failure information is reset. | -| `circuitbreaker_storage_timeout` | integer | no | Seconds to wait for a storage access attempt | -| `clientside_sentry_dsn` | string | no | Required if `clientside_sentry_dsn` is enabled | -| `clientside_sentry_enabled` | boolean | no | Enable Sentry error reporting for the client side | -| `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_projects_limit` | integer | no | Project limit per user. Default is `100000` | -| `default_snippet_visibility` | string | no | What visibility level new snippets receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | -| `disabled_oauth_sign_in_sources` | Array of strings | no | Disabled OAuth sign-in sources | -| `domain_blacklist_enabled` | boolean | no | Enable/disable the `domain_blacklist` | -| `domain_blacklist` | array of strings | yes (if `domain_blacklist_enabled` is `true`) | People trying to sign-up with emails from this domain will not be allowed to do so. | -| `domain_whitelist` | array of strings | no | Force people to use only corporate emails for sign-up. Default is null, meaning there is no restriction. | -| `dsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded DSA key. Default is `0` (no restriction). `-1` disables DSA keys. | -| `ecdsa_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ECDSA key. Default is `0` (no restriction). `-1` disables ECDSA keys. | -| `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. | -| `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. | -| `gravatar_enabled` | boolean | no | Enable Gravatar | -| `help_page_hide_commercial_content` | boolean | no | Hide marketing-related entries from help | -| `help_page_support_url` | string | no | Alternate support URL for help page | -| `home_page_url` | string | no | Redirect to this URL when not logged in | -| `housekeeping_bitmaps_enabled` | boolean | no | Enable Git pack file bitmap creation | -| `housekeeping_enabled` | boolean | no | Enable or disable git housekeeping | -| `housekeeping_full_repack_period` | integer | no | Number of Git pushes after which an incremental 'git repack' is run. | -| `housekeeping_gc_period` | integer | no | Number of Git pushes after which 'git gc' is run. | -| `housekeeping_incremental_repack_period` | integer | no | Number of Git pushes after which an incremental 'git repack' is run. | -| `html_emails_enabled` | boolean | no | Enable HTML emails | -| `import_sources` | Array of strings | no | Sources to allow project import from, possible values: "github bitbucket gitlab google_code fogbugz git gitlab_project manifest | -| `koding_enabled` | boolean | no | Enable Koding integration. Default is `false`. | -| `koding_url` | string | yes (if `koding_enabled` is `true`) | The Koding instance URL for integration. | -| `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 | -| `metrics_enabled` | boolean | no | Enable influxDB metrics | -| `metrics_host` | string | yes (if `metrics_enabled` is `true`) | InfluxDB host | -| `metrics_method_call_threshold` | integer | yes (if `metrics_enabled` is `true`) | A method call is only tracked when it takes longer than the given amount of milliseconds | -| `metrics_packet_size` | integer | yes (if `metrics_enabled` is `true`) | The amount of datapoints to send in a single UDP packet. | -| `metrics_pool_size` | integer | yes (if `metrics_enabled` is `true`) | The amount of InfluxDB connections to keep open | -| `metrics_port` | integer | no | The UDP port to use for connecting to InfluxDB | -| `metrics_sample_interval` | integer | yes (if `metrics_enabled` is `true`) | The sampling interval in seconds. | -| `metrics_timeout` | integer | yes (if `metrics_enabled` is `true`) | The amount of seconds after which InfluxDB will time out. | -| `password_authentication_enabled_for_web` | boolean | no | Enable authentication for the web interface via a GitLab account password. Default is `true`. | -| `password_authentication_enabled_for_git` | boolean | no | Enable authentication for Git over HTTP(S) via a GitLab account password. Default is `true`. | -| `performance_bar_allowed_group_path` | string | no | Path of the group that is allowed to toggle the performance bar | -| `performance_bar_allowed_group_id` | string | no | Deprecated: Use `performance_bar_allowed_group_path` instead. Path of the group that is allowed to toggle the performance bar | -| `performance_bar_enabled` | boolean | no | Deprecated: Pass `performance_bar_allowed_group_path: nil` instead. Allow enabling the performance bar | -| `plantuml_enabled` | boolean | no | Enable PlantUML integration. Default is `false`. | -| `plantuml_url` | string | yes (if `plantuml_enabled` is `true`) | The PlantUML instance URL for integration. | -| `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 | -| `recaptcha_enabled` | boolean | no | Enable recaptcha | -| `recaptcha_private_key` | string | yes (if `recaptcha_enabled` is true) | Private key for recaptcha | -| `recaptcha_site_key` | string | yes (if `recaptcha_enabled` is true) | Site key for recaptcha | -| `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_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. | -| `require_two_factor_authentication` | boolean | no | Require all users to setup Two-factor authentication | -| `restricted_visibility_levels` | array of strings | no | Selected levels cannot be used by non-admin users for groups, projects or snippets. Can take `private`, `internal` and `public` as a parameter. Default is null which means there is no restriction. | -| `rsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded RSA key. Default is `0` (no restriction). `-1` disables RSA keys. | -| `send_user_confirmation_email` | boolean | no | Send confirmation email on sign-up | -| `sentry_dsn` | string | yes (if `sentry_enabled` is true) | Sentry Data Source Name | -| `sentry_enabled` | boolean | no | Sentry is an error reporting and logging tool which is currently not shipped with GitLab, get it here: https://getsentry.com | -| `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes | -| `shared_runners_enabled` | true | no | Enable shared runners for new projects | -| `shared_runners_text` | string | no | Shared runners text | -| `sidekiq_throttling_enabled` | boolean | no | Enable Sidekiq Job Throttling | -| `sidekiq_throttling_factor` | decimal | yes (if `sidekiq_throttling_enabled` is true) | The factor by which the queues should be throttled. A value between 0.0 and 1.0, exclusive. | -| `sidekiq_throttling_queues` | array of strings | yes (if `sidekiq_throttling_enabled` is true) | Choose which queues you wish to throttle | -| `sign_in_text` | string | no | Text on login page | -| `signup_enabled` | boolean | no | Enable registration. Default is `true`. | -| `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to 0 for unlimited time. | -| `two_factor_grace_period` | integer | no | Amount of time (in hours) that users are allowed to skip forced configuration of two-factor authentication | -| `unique_ips_limit_enabled` | boolean | no | Limit sign in from multiple ips | -| `unique_ips_limit_per_user` | integer | yes (if `unique_ips_limit_enabled` is true) | Maximum number of ips per user | -| `unique_ips_limit_time_window` | integer | yes (if `unique_ips_limit_enabled` is true) | 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 by default be external | -| `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider | -| `version_check_enabled` | boolean | no | Let GitLab inform you when an update is available. | -| `enforce_terms` | boolean | no | Enforce application ToS to all users | -| `terms` | text | yes (if `enforce_terms` is true) | Markdown content for the ToS | -| `instance_statistics_visibility_private` | boolean | no | When set to `true` Instance statistics will only be available to admins | -| `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 | - ```bash curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/application/settings?signup_enabled=false&default_project_visibility=internal ``` @@ -175,7 +82,7 @@ Example response: { "id": 1, "default_projects_limit": 100000, - "signup_enabled": true, + "signup_enabled": false, "password_authentication_enabled_for_web": true, "gravatar_enabled": true, "sign_in_text": "", @@ -213,3 +120,125 @@ Example response: "user_show_add_ssh_key_message": true } ``` + +## List of settings that can be accessed via API calls + +In general, all settings are optional. Certain settings though, if enabled, will +require other settings to be set in order to function properly. These requirements +are listed in the descriptions of the relevant settings. + +| Attribute | Type | Required | Description | +| --------- | ---- | :------: | ----------- | +| `admin_notification_email` | string | no | Abuse reports will be sent to this address if it is set. Abuse reports are always available in the admin area. | +| `after_sign_out_path` | string | no | Where to redirect users after logout. | +| `after_sign_up_text` | string | no | Text shown to the user after signing up | +| `akismet_api_key` | string | required by: `akismet_enabled` | API key for akismet spam protection. | +| `akismet_enabled` | boolean | no | (**If enabled, requires:** `akismet_api_key`) Enable or disable akismet spam protection. | +| `allow_local_requests_from_hooks_and_services` | boolean | no | Allow requests to the local network from hooks and services. | +| `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. | +| `circuitbreaker_access_retries` | integer | no | The number of attempts GitLab will make to access a storage. | +| `circuitbreaker_check_interval` | integer | no | Number of seconds in between storage checks. | +| `circuitbreaker_failure_count_threshold` | integer | no | The number of failures after which GitLab will completely prevent access to the storage. | +| `circuitbreaker_failure_reset_time` | integer | no | Time in seconds GitLab will keep storage failure information. When no failures occur during this time, the failure information is reset. | +| `circuitbreaker_storage_timeout` | integer | no | Seconds to wait for a storage access attempt. | +| `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. | +| `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_projects_limit` | integer | no | Project limit per user. Default is `100000`. | +| `default_snippet_visibility` | string | no | What visibility level new snippets receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | +| `disabled_oauth_sign_in_sources` | array of strings | no | Disabled OAuth sign-in sources. | +| `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. | +| `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. | +| `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. | +| `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. | +| `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. | +| `help_page_support_url` | string | no | Alternate support URL for help page. | +| `help_page_text` | string | no | Custom text displayed on the help page. | +| `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_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. | +| `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`. | +| `koding_enabled` | boolean | no | (If enabled, requires: `koding_url`) Enable Koding integration. Default is `false`. | +| `koding_url` | string | required by: `koding_enabled` | The Koding instance URL for integration. | +| `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 | +| `metrics_enabled` | boolean | no | (**If enabled, requires:** `metrics_host`, `metrics_method_call_threshold`, `metrics_packet_size`, `metrics_pool_size`, `metrics_port`, `metrics_sample_interval` and `metrics_timeout`) Enable influxDB metrics. | +| `metrics_host` | string | required by: `metrics_enabled` | InfluxDB host. | +| `metrics_method_call_threshold` | integer | required by: `metrics_enabled` | A method call is only tracked when it takes longer than the given amount of milliseconds. | +| `metrics_packet_size` | integer | required by: `metrics_enabled` | The amount of datapoints to send in a single UDP packet. | +| `metrics_pool_size` | integer | required by: `metrics_enabled` | The amount of InfluxDB connections to keep open. | +| `metrics_port` | integer | required by: `metrics_enabled` | The UDP port to use for connecting to InfluxDB. | +| `metrics_sample_interval` | integer | required by: `metrics_enabled` | The sampling interval in seconds. | +| `metrics_timeout` | integer | required by: `metrics_enabled` | The amount of seconds after which InfluxDB will time out. | +| `mirror_available` | boolean | no | Allow mirrors to be set up for projects. If disabled, only admins will be able to set up mirrors in projects. | +| `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`. | +| `performance_bar_allowed_group_id` | string | no | (Deprecated: Use `performance_bar_allowed_group_path` instead) Path of the group that is allowed to toggle the performance bar. | +| `performance_bar_allowed_group_path` | string | no | Path of the group that is allowed to toggle the performance bar. | +| `performance_bar_enabled` | boolean | no | (Deprecated: Pass `performance_bar_allowed_group_path: nil` instead) Allow enabling the performance bar. | +| `plantuml_enabled` | boolean | no | (**If enabled, requires:** `plantuml_url`) Enable PlantUML integration. Default is `false`. | +| `plantuml_url` | string | required by: `plantuml_enabled` | The PlantUML instance URL for integration. | +| `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. | +| `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. | +| `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_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. | +| `require_two_factor_authentication` | boolean | no | (**If enabled, requires:** `two_factor_grace_period`) Require all users to set up Two-factor authentication. | +| `restricted_visibility_levels` | array of strings | no | Selected levels cannot be used by non-admin users for groups, projects or snippets. Can take `private`, `internal` and `public` as a parameter. Default is `null` which means there is no restriction. | +| `rsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded RSA key. Default is `0` (no restriction). `-1` disables RSA keys. | +| `send_user_confirmation_email` | boolean | no | Send confirmation email on sign-up. | +| `sentry_dsn` | string | required by: `sentry_enabled` | Sentry Data Source Name. | +| `sentry_enabled` | boolean | no | (**If enabled, requires:** `sentry_dsn`) Sentry is an error reporting and logging tool which is currently not shipped with GitLab, available at https://getsentry.com. | +| `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes | +| `shared_runners_enabled` | boolean | no | (**If enabled, requires:** `shared_runners_text`) Enable shared runners for new projects. | +| `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. | +| `signup_enabled` | boolean | no | Enable registration. Default is `true`. | +| `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). | +| `throttle_authenticated_api_period_in_seconds` | integer | required by: `throttle_authenticated_api_enabled` | Rate limit period in seconds. | +| `throttle_authenticated_api_requests_per_period` | integer | required by: `throttle_authenticated_api_enabled` | Max requests per period per user. | +| `throttle_authenticated_web_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_web_period_in_seconds` and `throttle_authenticated_web_requests_per_period`) Enable authenticated web request rate limit. Helps reduce request volume (e.g. from crawlers or abusive bots). | +| `throttle_authenticated_web_period_in_seconds` | integer | required by: `throttle_authenticated_web_enabled` | Rate limit period in seconds. | +| `throttle_authenticated_web_requests_per_period` | integer | required by: `throttle_authenticated_web_enabled` | Max requests per period per user. | +| `throttle_unauthenticated_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_period_in_seconds` and `throttle_unauthenticated_requests_per_period`) Enable unauthenticated request rate limit. Helps reduce request volume (e.g. from crawlers or abusive bots). | +| `throttle_unauthenticated_period_in_seconds` | integer | required by: `throttle_unauthenticated_enabled` | Rate limit period in seconds. | +| `throttle_unauthenticated_requests_per_period` | integer | required by: `throttle_unauthenticated_enabled` | Max requests per period per IP. | +| `two_factor_grace_period` | integer | required by: `require_two_factor_authentication` | Amount of time (in hours) that users are allowed to skip forced configuration of two-factor authentication. | +| `unique_ips_limit_enabled` | boolean | no | (**If enabled, requires:** `unique_ips_limit_per_user` and `unique_ips_limit_time_window`) Limit sign in from multiple ips. | +| `unique_ips_limit_per_user` | integer | required by: `unique_ips_limit_enabled` | Maximum number of ips per user. | +| `unique_ips_limit_time_window` | integer | required by: `unique_ips_limit_enabled` | How many seconds an IP will be counted towards the limit. | +| `usage_ping_enabled` | boolean | no | Every week GitLab will report license usage back to GitLab, Inc. | +| `user_default_external` | boolean | no | Newly registered users will be external by default. | +| `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. | diff --git a/doc/api/tags.md b/doc/api/tags.md index 4af096c3c0c..f2a3f9f28d2 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -174,10 +174,21 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `tag_name` (required) - The name of a tag + +Request body: + - `description` (required) - Release notes with markdown support ```json { + "description": "Amazing release. Wow" +} +``` + +Response: + +```json +{ "tag_name": "1.0.0", "description": "Amazing release. Wow" } @@ -195,10 +206,21 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `tag_name` (required) - The name of a tag + +Request body: + - `description` (required) - Release notes with markdown support ```json { + "description": "Amazing release. Wow" +} +``` + +Response: + +```json +{ "tag_name": "1.0.0", "description": "Amazing release. Wow" } diff --git a/doc/api/templates/dockerfiles.md b/doc/api/templates/dockerfiles.md new file mode 100644 index 00000000000..a08b8d33693 --- /dev/null +++ b/doc/api/templates/dockerfiles.md @@ -0,0 +1,113 @@ +# Dockerfiles API + +## List Dockerfile templates + +Get all Dockerfile templates. + +``` +GET /templates/dockerfiles +``` + +```bash +curl https://gitlab.example.com/api/v4/templates/dockerfiles +``` + +Example response: + +```json +[ + { + "key": "Binary", + "name": "Binary" + }, + { + "key": "Binary-alpine", + "name": "Binary-alpine" + }, + { + "key": "Binary-scratch", + "name": "Binary-scratch" + }, + { + "key": "Golang", + "name": "Golang" + }, + { + "key": "Golang-alpine", + "name": "Golang-alpine" + }, + { + "key": "Golang-scratch", + "name": "Golang-scratch" + }, + { + "key": "HTTPd", + "name": "HTTPd" + }, + { + "key": "Node", + "name": "Node" + }, + { + "key": "Node-alpine", + "name": "Node-alpine" + }, + { + "key": "OpenJDK", + "name": "OpenJDK" + }, + { + "key": "OpenJDK-alpine", + "name": "OpenJDK-alpine" + }, + { + "key": "PHP", + "name": "PHP" + }, + { + "key": "Python", + "name": "Python" + }, + { + "key": "Python-alpine", + "name": "Python-alpine" + }, + { + "key": "Python2", + "name": "Python2" + }, + { + "key": "Ruby", + "name": "Ruby" + }, + { + "key": "Ruby-alpine", + "name": "Ruby-alpine" + } +] +``` + +## Single Dockerfile template + +Get a single Dockerfile template. + +``` +GET /templates/dockerfiles/:key +``` + +| Attribute | Type | Required | Description | +| ---------- | ------ | -------- | ----------- | +| `key` | string | yes | The key of the Dockerfile template | + +```bash +curl https://gitlab.example.com/api/v4/templates/dockerfiles/Binary +``` + +Example response: + +```json +{ + "name": "Binary", + "content": "# This file is a template, and might need editing before it works on your project.\n# This Dockerfile installs a compiled binary into a bare system.\n# You must either commit your compiled binary into source control (not recommended)\n# or build the binary first as part of a CI/CD pipeline.\n\nFROM buildpack-deps:jessie\n\nWORKDIR /usr/local/bin\n\n# Change `app` to whatever your binary is called\nAdd app .\nCMD [\"./app\"]\n" +} +``` diff --git a/doc/api/templates/gitignores.md b/doc/api/templates/gitignores.md index d3f5c88ca90..3804855129c 100644 --- a/doc/api/templates/gitignores.md +++ b/doc/api/templates/gitignores.md @@ -17,538 +17,84 @@ Example response: ```json [ { - "name": "AppEngine" - }, - { - "name": "Laravel" - }, - { - "name": "Elisp" - }, - { - "name": "SketchUp" + "key": "Actionscript", + "name": "Actionscript" }, { + "key": "Ada", "name": "Ada" }, { - "name": "Ruby" - }, - { - "name": "Kohana" - }, - { - "name": "Nanoc" - }, - { - "name": "Erlang" - }, - { - "name": "OCaml" - }, - { - "name": "Lithium" - }, - { - "name": "Fortran" - }, - { - "name": "Scala" - }, - { - "name": "Node" - }, - { - "name": "Fancy" - }, - { - "name": "Perl" - }, - { - "name": "Zephir" - }, - { - "name": "WordPress" - }, - { - "name": "Symfony" - }, - { - "name": "FuelPHP" - }, - { - "name": "DM" - }, - { - "name": "Sdcc" - }, - { - "name": "Rust" - }, - { - "name": "C" - }, - { - "name": "Umbraco" - }, - { - "name": "Actionscript" + "key": "Agda", + "name": "Agda" }, { + "key": "Android", "name": "Android" }, { - "name": "Grails" - }, - { - "name": "Composer" - }, - { - "name": "ExpressionEngine" - }, - { - "name": "Gcov" - }, - { - "name": "Qt" + "key": "AppEngine", + "name": "AppEngine" }, { - "name": "Phalcon" + "key": "AppceleratorTitanium", + "name": "AppceleratorTitanium" }, { + "key": "ArchLinuxPackages", "name": "ArchLinuxPackages" }, { - "name": "TeX" - }, - { - "name": "SCons" - }, - { - "name": "Lilypond" - }, - { - "name": "CommonLisp" - }, - { - "name": "Rails" - }, - { - "name": "Mercury" - }, - { - "name": "Magento" - }, - { - "name": "ChefCookbook" - }, - { - "name": "GitBook" - }, - { - "name": "C++" - }, - { - "name": "Eagle" - }, - { - "name": "Go" - }, - { - "name": "OpenCart" - }, - { - "name": "Scheme" - }, - { - "name": "Typo3" - }, - { - "name": "SeamGen" - }, - { - "name": "Swift" - }, - { - "name": "Elm" - }, - { - "name": "Unity" - }, - { - "name": "Agda" - }, - { - "name": "CUDA" - }, - { - "name": "VVVV" - }, - { - "name": "Finale" - }, - { - "name": "LemonStand" - }, - { - "name": "Textpattern" - }, - { - "name": "Julia" - }, - { - "name": "Packer" - }, - { - "name": "Scrivener" - }, - { - "name": "Dart" - }, - { - "name": "Plone" - }, - { - "name": "Jekyll" - }, - { - "name": "Xojo" - }, - { - "name": "LabVIEW" - }, - { + "key": "Autotools", "name": "Autotools" }, { - "name": "KiCad" - }, - { - "name": "Prestashop" - }, - { - "name": "ROS" - }, - { - "name": "Smalltalk" - }, - { - "name": "GWT" - }, - { - "name": "OracleForms" - }, - { - "name": "SugarCRM" - }, - { - "name": "Nim" - }, - { - "name": "SymphonyCMS" + "key": "C", + "name": "C" }, { - "name": "Maven" + "key": "C++", + "name": "C++" }, { + "key": "CFWheels", "name": "CFWheels" }, { - "name": "Python" - }, - { - "name": "ZendFramework" - }, - { - "name": "CakePHP" - }, - { - "name": "Concrete5" - }, - { - "name": "PlayFramework" - }, - { - "name": "Terraform" - }, - { - "name": "Elixir" - }, - { + "key": "CMake", "name": "CMake" }, { - "name": "Joomla" - }, - { - "name": "Coq" - }, - { - "name": "Delphi" - }, - { - "name": "Haskell" - }, - { - "name": "Yii" - }, - { - "name": "Java" - }, - { - "name": "UnrealEngine" - }, - { - "name": "AppceleratorTitanium" - }, - { - "name": "CraftCMS" - }, - { - "name": "ForceDotCom" - }, - { - "name": "ExtJs" - }, - { - "name": "MetaProgrammingSystem" - }, - { - "name": "D" - }, - { - "name": "Objective-C" - }, - { - "name": "RhodesRhomobile" - }, - { - "name": "R" - }, - { - "name": "EPiServer" - }, - { - "name": "Yeoman" - }, - { - "name": "VisualStudio" - }, - { - "name": "Processing" - }, - { - "name": "Leiningen" - }, - { - "name": "Stella" - }, - { - "name": "Opa" - }, - { - "name": "Drupal" - }, - { - "name": "TurboGears2" - }, - { - "name": "Idris" - }, - { - "name": "Jboss" - }, - { - "name": "CodeIgniter" - }, - { - "name": "Qooxdoo" - }, - { - "name": "Waf" + "key": "CUDA", + "name": "CUDA" }, { - "name": "Sass" + "key": "CakePHP", + "name": "CakePHP" }, { - "name": "Lua" + "key": "ChefCookbook", + "name": "ChefCookbook" }, { + "key": "Clojure", "name": "Clojure" }, { - "name": "IGORPro" - }, - { - "name": "Gradle" - }, - { - "name": "Archives" - }, - { - "name": "SynopsysVCS" - }, - { - "name": "Ninja" - }, - { - "name": "Tags" - }, - { - "name": "OSX" - }, - { - "name": "Dreamweaver" - }, - { - "name": "CodeKit" - }, - { - "name": "NotepadPP" - }, - { - "name": "VisualStudioCode" - }, - { - "name": "Mercurial" - }, - { - "name": "BricxCC" - }, - { - "name": "DartEditor" - }, - { - "name": "Eclipse" - }, - { - "name": "Cloud9" - }, - { - "name": "TortoiseGit" - }, - { - "name": "NetBeans" - }, - { - "name": "GPG" - }, - { - "name": "Espresso" - }, - { - "name": "Redcar" - }, - { - "name": "Xcode" - }, - { - "name": "Matlab" - }, - { - "name": "LyX" - }, - { - "name": "SlickEdit" - }, - { - "name": "Dropbox" - }, - { - "name": "CVS" - }, - { - "name": "Calabash" - }, - { - "name": "JDeveloper" - }, - { - "name": "Vagrant" - }, - { - "name": "IPythonNotebook" - }, - { - "name": "TextMate" - }, - { - "name": "Ensime" - }, - { - "name": "WebMethods" - }, - { - "name": "VirtualEnv" - }, - { - "name": "Emacs" - }, - { - "name": "Momentics" - }, - { - "name": "JetBrains" - }, - { - "name": "SublimeText" - }, - { - "name": "Kate" - }, - { - "name": "ModelSim" - }, - { - "name": "Redis" - }, - { - "name": "KDevelop4" - }, - { - "name": "Bazaar" - }, - { - "name": "Linux" - }, - { - "name": "Windows" - }, - { - "name": "XilinxISE" - }, - { - "name": "Lazarus" - }, - { - "name": "EiffelStudio" - }, - { - "name": "Anjuta" - }, - { - "name": "Vim" - }, - { - "name": "Otto" - }, - { - "name": "MicrosoftOffice" - }, - { - "name": "LibreOffice" - }, - { - "name": "SBT" + "key": "CodeIgniter", + "name": "CodeIgniter" }, { - "name": "MonoDevelop" + "key": "CommonLisp", + "name": "CommonLisp" }, { - "name": "SVN" + "key": "Composer", + "name": "Composer" }, { - "name": "FlexBuilder" + "key": "Concrete5", + "name": "Concrete5" } ] ``` diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md index bdb128fc336..cecfc8cd9b9 100644 --- a/doc/api/templates/gitlab_ci_ymls.md +++ b/doc/api/templates/gitlab_ci_ymls.md @@ -17,79 +17,84 @@ Example response: ```json [ { - "name": "C++" - }, - { - "name": "Docker" - }, - { - "name": "Elixir" - }, - { - "name": "LaTeX" - }, - { - "name": "Grails" - }, - { - "name": "Rust" + "key": "Android", + "name": "Android" }, { - "name": "Nodejs" + "key": "Auto-DevOps", + "name": "Auto-DevOps" }, { - "name": "Ruby" + "key": "Bash", + "name": "Bash" }, { - "name": "Scala" + "key": "C++", + "name": "C++" }, { - "name": "Maven" + "key": "Chef", + "name": "Chef" }, { - "name": "Harp" + "key": "Clojure", + "name": "Clojure" }, { - "name": "Pelican" + "key": "Crystal", + "name": "Crystal" }, { - "name": "Hyde" + "key": "Django", + "name": "Django" }, { - "name": "Nanoc" + "key": "Docker", + "name": "Docker" }, { - "name": "Octopress" + "key": "Elixir", + "name": "Elixir" }, { - "name": "JBake" + "key": "Go", + "name": "Go" }, { - "name": "HTML" + "key": "Gradle", + "name": "Gradle" }, { - "name": "Hugo" + "key": "Grails", + "name": "Grails" }, { - "name": "Metalsmith" + "key": "Julia", + "name": "Julia" }, { - "name": "Hexo" + "key": "LaTeX", + "name": "LaTeX" }, { - "name": "Lektor" + "key": "Laravel", + "name": "Laravel" }, { - "name": "Doxygen" + "key": "Maven", + "name": "Maven" }, { - "name": "Brunch" + "key": "Mono", + "name": "Mono" }, { - "name": "Jekyll" + "key": "Nodejs", + "name": "Nodejs" }, { - "name": "Middleman" + "key": "OpenShift", + "name": "OpenShift" } ] ``` diff --git a/doc/api/users.md b/doc/api/users.md index a8858468cab..07f03f9c827 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -199,6 +199,7 @@ Parameters: "created_at": "2012-05-23T08:00:58Z", "bio": null, "location": null, + "public_email": "john@example.com", "skype": "", "linkedin": "", "twitter": "", @@ -230,6 +231,7 @@ Parameters: "is_admin": false, "bio": null, "location": null, + "public_email": "john@example.com", "skype": "", "linkedin": "", "twitter": "", @@ -263,7 +265,7 @@ GET /users/:id?with_custom_attributes=true ## User creation -Creates a new user. Note only administrators can create new users. Either `password` or `reset_password` should be specified (`reset_password` takes priority). +Creates a new user. Note only administrators can create new users. Either `password` or `reset_password` should be specified (`reset_password` takes priority). If `reset_password` is `false`, then `password` is required. ``` POST /users @@ -286,6 +288,7 @@ Parameters: - `provider` (optional) - External provider name - `bio` (optional) - User's biography - `location` (optional) - User's location +- `public_email` (optional) - The public email of the user - `admin` (optional) - User is admin - true or false (default) - `can_create_group` (optional) - User can create groups - true or false - `skip_confirmation` (optional) - Skip confirmation - true or false (default) @@ -303,26 +306,27 @@ PUT /users/:id Parameters: -- `email` - Email -- `username` - Username -- `name` - Name -- `password` - Password -- `skype` - Skype ID -- `linkedin` - LinkedIn -- `twitter` - Twitter account -- `website_url` - Website URL -- `organization` - Organization name -- `projects_limit` - Limit projects each user can create -- `extern_uid` - External UID -- `provider` - External provider name -- `bio` - User's biography -- `location` (optional) - User's location -- `admin` (optional) - User is admin - true or false (default) -- `can_create_group` (optional) - User can create groups - true or false +- `email` - Email +- `username` - Username +- `name` - Name +- `password` - Password +- `skype` - Skype ID +- `linkedin` - LinkedIn +- `twitter` - Twitter account +- `website_url` - Website URL +- `organization` - Organization name +- `projects_limit` - Limit projects each user can create +- `extern_uid` - External UID +- `provider` - External provider name +- `bio` - User's biography +- `location` (optional) - User's location +- `public_email` (optional) - The public email of the user +- `admin` (optional) - User is admin - true or false (default) +- `can_create_group` (optional) - User can create groups - true or false - `skip_reconfirmation` (optional) - Skip reconfirmation - true or false (default) -- `external` (optional) - Flags the user as external - true or false(default) -- `avatar` (optional) - Image file for user's avatar -- `private_profile` (optional) - User's profile is private - true or false +- `external` (optional) - Flags the user as external - true or false(default) +- `avatar` (optional) - Image file for user's avatar +- `private_profile` (optional) - User's profile is private - true or false On password update, user will be forced to change it upon next login. Note, at the moment this method does only return a `404` error, @@ -367,6 +371,7 @@ GET /user "created_at": "2012-05-23T08:00:58Z", "bio": null, "location": null, + "public_email": "john@example.com", "skype": "", "linkedin": "", "twitter": "", @@ -415,6 +420,7 @@ GET /user "is_admin": false, "bio": null, "location": null, + "public_email": "john@example.com", "skype": "", "linkedin": "", "twitter": "", @@ -504,7 +510,7 @@ PUT /user/status When both parameters `emoji` and `message` are empty, the status will be cleared. ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "emoji=coffee" --data "emoji=I crave coffee" https://gitlab.example.com/api/v4/user/status +curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "emoji=coffee" --data "message=I crave coffee" https://gitlab.example.com/api/v4/user/status ``` Example responses @@ -552,7 +558,7 @@ Parameters: ## List SSH keys for user -Get a list of a specified user's SSH keys. Available only for admin +Get a list of a specified user's SSH keys. ``` GET /users/:id/keys @@ -972,6 +978,7 @@ Parameters: - `id` (required) - id of specified user - `email` (required) - email address +- `skip_confirmation` (optional) - Skip confirmation and assume e-mail is verified - true or false (default) ## Delete email for current user diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index 98eae66469f..5752fb7c078 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.md @@ -76,8 +76,8 @@ Below are the changes made between V3 and V4. - Simplify project payload exposed on Environment endpoints [!9675](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9675) - API uses merge request `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the merge requests, award emoji, todos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9530) - API uses issue `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the issues, award emoji, todos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9530) -- Change initial page from `0` to `1` on `GET /projects/:id/repository/commits` (like on the rest of the API) [!9679] (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679) -- Return correct `Link` header data for `GET /projects/:id/repository/commits` [!9679] (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679) +- Change initial page from `0` to `1` on `GET /projects/:id/repository/commits` (like on the rest of the API) [!9679](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679) +- Return correct `Link` header data for `GET /projects/:id/repository/commits` [!9679](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679) - Update endpoints for repository files [!9637](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9637) - Moved `GET /projects/:id/repository/files?file_path=:file_path` to `GET /projects/:id/repository/files/:file_path` (`:file_path` should be URL-encoded) - `GET /projects/:id/repository/blobs/:sha` now returns JSON attributes for the blob identified by `:sha`, instead of finding the commit identified by `:sha` and returning the raw content of the blob in that commit identified by the required `?filepath=:filepath` diff --git a/doc/api/wikis.md b/doc/api/wikis.md index 15ce5f96b60..fb0ec773da5 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -97,12 +97,12 @@ curl --data "format=rdoc&title=Hello&content=Hello world" --header "PRIVATE-TOKE Example response: ```json -{ +{ "content" : "Hello world", "format" : "markdown", "slug" : "Hello", "title" : "Hello" -} +} ``` ## Edit an existing wiki page @@ -154,6 +154,44 @@ DELETE /projects/:id/wikis/:slug curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/wikis/foo" ``` -On success the HTTP status code is `204` and no JSON response is expected. +On success the HTTP status code is `204` and no JSON response is expected. [ce-13372]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13372 + +## Upload an attachment to the wiki repository + +Uploads a file to the attachment folder inside the wiki's repository. The + attachment folder is the `uploads` folder. + +``` +POST /projects/:id/wikis/attachments +``` + +| Attribute | Type | Required | Description | +| ------------- | ------- | -------- | ---------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `file` | string | yes | The attachment to be uploaded | +| `branch` | string | no | The name of the branch. Defaults to the wiki repository default branch | + +To upload a file from your filesystem, use the `--form` argument. This causes +cURL to post data using the header `Content-Type: multipart/form-data`. +The `file=` parameter must point to a file on your filesystem and be preceded +by `@`. For example: + +```bash +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "file=@dk.png" https://gitlab.example.com/api/v4/projects/1/wikis/attachments +``` + +Example response: + +```json +{ + "file_name" : "dk.png", + "file_path" : "uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png", + "branch" : "master", + "link" : { + "url" : "uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png", + "markdown" : "" + } +} +``` diff --git a/doc/ci/README.md b/doc/ci/README.md index d782d64e971..dba1f38abe2 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -132,5 +132,3 @@ your whole GitLab instance as well as in each project. - [New CI job permissions model](../user/project/new_ci_build_permissions_model.md) Read about what changed in GitLab 8.12 and how that affects your jobs. There's a new way to access your Git submodules and LFS objects in jobs. - -[gitlab-ci-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml diff --git a/doc/ci/autodeploy/quick_start_guide.md b/doc/ci/autodeploy/quick_start_guide.md index cc6c9ec0e0a..3836216e951 100644 --- a/doc/ci/autodeploy/quick_start_guide.md +++ b/doc/ci/autodeploy/quick_start_guide.md @@ -11,7 +11,7 @@ We made a minimal [Ruby application](https://gitlab.com/gitlab-examples/minimal- Let’s start by forking our sample application. Go to [the project page](https://gitlab.com/gitlab-examples/minimal-ruby-app) and press the `Fork` button. Soon you should have a project under your namespace with the necessary files. -## Setup your own cluster on Google Kubernetes Engine +## Set up your own cluster on Google Kubernetes Engine If you do not already have a Google Cloud account, create one at https://console.cloud.google.com. @@ -71,7 +71,7 @@ Use this IP address to configure your DNS. This part heavily depends on your pre Use `nslookup minimal-ruby-app-staging.<yourdomain>` to confirm that domain is assigned to the cluster IP. -## Setup Auto Deploy +## Set up Auto Deploy Visit the home page of your GitLab.com project and press "Set up Auto Deploy" button. diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index c159198d16b..f479dc74d1f 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -14,6 +14,65 @@ starting from GitLab 9.0. Make sure you read the [`cache` reference](../yaml/README.md#cache) to learn how it is defined in `.gitlab-ci.yml`. +## Cache vs artifacts + +NOTE: **Note:** +Be careful if you use cache and artifacts to store the same path in your jobs +as **caches are restored before artifacts** and the content would be overwritten. + +Don't mix the caching with passing artifacts between stages. Caching is not +designed to pass artifacts between stages. Cache is for runtime dependencies +needed to compile the project: + +- `cache`: **Use for temporary storage for project dependencies.** Not useful + for keeping intermediate build results, like `jar` or `apk` files. + Cache was designed to be used to speed up invocations of subsequent runs of a + given job, by keeping things like dependencies (e.g., npm packages, Go vendor + packages, etc.) so they don't have to be re-fetched from the public internet. + While the cache can be abused to pass intermediate build results between stages, + there may be cases where artifacts are a better fit. +- `artifacts`: **Use for stage results that will be passed between stages.** + Artifacts were designed to upload some compiled/generated bits of the build, + and they can be fetched by any number of concurrent Runners. They are + guaranteed to be available and are there to pass data between jobs. They are + also exposed to be downloaded from the UI. **Artifacts can only exist in + directories relative to the build directory** and specifying paths which don't + comply to this rule trigger an unintuitive and illogical error message (an + enhancement is discussed at + https://gitlab.com/gitlab-org/gitlab-ce/issues/15530). Artifacts need to be + uploaded to the GitLab instance (not only the GitLab runner) before the next + stage job(s) can start, so you need to evaluate carefully whether your + bandwidth allows you to profit from parallelization with stages and shared + artifacts before investing time in changes to the setup. + +It's sometimes confusing because the name artifact sounds like something that +is only useful outside of the job, like for downloading a final image. But +artifacts are also available in between stages within a pipeline. So if you +build your application by downloading all the required modules, you might want +to declare them as artifacts so that each subsequent stage can depend on them +being there. There are some optimizations like declaring an +[expiry time](../yaml/README.md#artifacts-expire_in) so you don't keep artifacts +around too long, and using [dependencies](../yaml/README.md#dependencies) to +control exactly where artifacts are passed around. + +In summary: + +- Caches are disabled if not defined globally or per job (using `cache:`). +- Caches are available for all jobs in your `.gitlab-ci.yml` if enabled globally. +- Caches can be used by subsequent pipelines of that very same job (a script in + a stage) in which the cache was created (if not defined globally). +- Caches are stored where the Runner is installed **and** uploaded to S3 if + [distributed cache is enabled](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching). +- Caches defined per job are only used, either: + - For the next pipeline of that job. + - If that same cache is also defined in a subsequent job of the same pipeline. +- Artifacts are disabled if not defined per job (using `artifacts:`). +- Artifacts can only be enabled per job, not globally. +- Artifacts are created during a pipeline and can be used by the subsequent + jobs of that currently active pipeline. +- Artifacts are always uploaded to GitLab (known as coordinator). +- Artifacts can have an expiration value for controlling disk usage (30 days by default). + ## Good caching practices We have the cache from the perspective of the developers (who consume a cache @@ -39,13 +98,13 @@ or pipelines in a guaranteed manner. From the perspective of the Runner, in order for cache to work effectively, one of the following must be true: -- Use a single Runner for all your jobs -- Use multiple Runners (in autoscale mode or not) that use +- Use a single Runner for all your jobs. +- Use multiple Runners (in autoscale mode or not) that use. [distributed caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching), - where the cache is stored in S3 buckets (like shared Runners on GitLab.com) + where the cache is stored in S3 buckets (like shared Runners on GitLab.com). - Use multiple Runners (not in autoscale mode) of the same architecture that share a common network-mounted directory (using NFS or something similar) - where the cache will be stored + where the cache will be stored. TIP: **Tip:** Read about the [availability of the cache](#availability-of-the-cache) @@ -87,7 +146,7 @@ you can use the same key for all of them: ```yaml cache: - key: one-key-to-rull-them-all + key: one-key-to-rule-them-all ``` To share the same cache between branches, but separate them by job: @@ -119,8 +178,8 @@ runs of jobs for things like dependencies and commonly used libraries so they don't have to be re-fetched from the public internet. NOTE: **Note:** -For more examples, check the [GitLab CI Yml](https://gitlab.com/gitlab-org/gitlab-ci-yml) -project. +For more examples, check out our [GitLab CI/CD +templates](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates). ### Caching Nodejs dependencies @@ -131,7 +190,7 @@ Nodejs modules are installed in `node_modules/` and are cached per-branch: ```yaml # -# https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Nodejs.gitlab-ci.yml +# https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates/Nodejs.gitlab-ci.yml # image: node:latest @@ -158,7 +217,7 @@ are cached per-branch: ```yaml # -# https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/PHP.gitlab-ci.yml +# https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates/PHP.gitlab-ci.yml # image: php:7.2 @@ -187,7 +246,7 @@ pip's cache is defined under `.cache/pip/` and both are cached per-branch: ```yaml # -# https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Python.gitlab-ci.yml +# https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates/Python.gitlab-ci.yml # image: python:latest @@ -227,7 +286,7 @@ jobs inherit it. Gems are installed in `vendor/ruby/` and are cached per-branch: ```yaml # -# https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Ruby.gitlab-ci.yml +# https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates/Ruby.gitlab-ci.yml # image: ruby:2.5 @@ -309,19 +368,19 @@ job B: Here's what happens behind the scenes: -1. Pipeline starts -1. `job A` runs -1. `before_script` is executed -1. `script` is executed -1. `after_script` is executed +1. Pipeline starts. +1. `job A` runs. +1. `before_script` is executed. +1. `script` is executed. +1. `after_script` is executed. 1. `cache` runs and the `vendor/` directory is zipped into `cache.zip`. This file is then saved in the directory based on the [Runner's setting](#where-the-caches-are-stored) and the `cache: key`. -1. `job B` runs -1. The cache is extracted (if found) -1. `before_script` is executed -1. `script` is executed -1. Pipeline finishes +1. `job B` runs. +1. The cache is extracted (if found). +1. `before_script` is executed. +1. `script` is executed. +1. Pipeline finishes. By using a single Runner on a single machine, you'll not have the issue where `job B` might execute on a Runner different from `job A`, thus guaranteeing the @@ -393,13 +452,13 @@ job B: - vendor/ ``` -1. `job A` runs -1. `public/` is cached as cache.zip -1. `job B` runs -1. The previous cache, if any, is unzipped -1. `vendor/` is cached as cache.zip and overwrites the previous one +1. `job A` runs. +1. `public/` is cached as cache.zip. +1. `job B` runs. +1. The previous cache, if any, is unzipped. +1. `vendor/` is cached as cache.zip and overwrites the previous one. 1. The next time `job A` runs it will use the cache of `job B` which is different - and thus will be ineffective + and thus will be ineffective. To fix that, use different `keys` for each job. @@ -456,63 +515,14 @@ next run of the pipeline, the cache will be stored in a different location. If you want to avoid editing `.gitlab-ci.yml`, you can easily clear the cache via GitLab's UI: -1. Navigate to your project's **CI/CD > Pipelines** page -1. Click on the **Clear Runner caches** button to clean up the cache +1. Navigate to your project's **CI/CD > Pipelines** page. +1. Click on the **Clear Runner caches** button to clean up the cache.  -1. On the next push, your CI/CD job will use a new cache +1. On the next push, your CI/CD job will use a new cache. Behind the scenes, this works by increasing a counter in the database, and the value of that counter is used to create the key for the cache by appending an integer to it: `-1`, `-2`, etc. After a push, a new key is generated and the old cache is not valid anymore. - -## Cache vs artifacts - -NOTE: **Note:** -Be careful if you use cache and artifacts to store the same path in your jobs -as **caches are restored before artifacts** and the content would be overwritten. - -Don't mix the caching with passing artifacts between stages. Caching is not -designed to pass artifacts between stages. Cache is for runtime dependencies -needed to compile the project: - -- `cache` - **Use for temporary storage for project dependencies.** Not useful - for keeping intermediate build results, like `jar` or `apk` files. - Cache was designed to be used to speed up invocations of subsequent runs of a - given job, by keeping things like dependencies (e.g., npm packages, Go vendor - packages, etc.) so they don't have to be re-fetched from the public internet. - While the cache can be abused to pass intermediate build results between stages, - there may be cases where artifacts are a better fit. -- `artifacts` - **Use for stage results that will be passed between stages.** - Artifacts were designed to upload some compiled/generated bits of the build, - and they can be fetched by any number of concurrent Runners. They are - guaranteed to be available and are there to pass data between jobs. They are - also exposed to be downloaded from the UI. - -It's sometimes confusing because the name artifact sounds like something that -is only useful outside of the job, like for downloading a final image. But -artifacts are also available in between stages within a pipeline. So if you -build your application by downloading all the required modules, you might want -to declare them as artifacts so that each subsequent stage can depend on them -being there. There are some optimizations like declaring an -[expiry time](../yaml/README.md#artifacts-expire_in) so you don't keep artifacts -around too long, and using [dependencies](../yaml/README.md#dependencies) to -control exactly where artifacts are passed around. - -So, to sum up: -- Caches are disabled if not defined globally or per job (using `cache:`) -- Caches are available for all jobs in your `.gitlab-ci.yml` if enabled globally -- Caches can be used by subsequent pipelines of that very same job (a script in - a stage) in which the cache was created (if not defined globally). -- Caches are stored where the Runner is installed **and** uploaded to S3 if - [distributed cache is enabled](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) -- Caches defined per job are only used either a) for the next pipeline of that job, - or b) if that same cache is also defined in a subsequent job of the same pipeline -- Artifacts are disabled if not defined per job (using `artifacts:`) -- Artifacts can only be enabled per job, not globally -- Artifacts are created during a pipeline and can be used by the subsequent - jobs of that currently active pipeline -- Artifacts are always uploaded to GitLab (known as coordinator) -- Artifacts can have an expiration value for controlling disk usage (30 days by default) diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 63338ff632c..0b64c8caba7 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -151,16 +151,16 @@ In order to do that, follow the steps: DOCKER_DRIVER: overlay2 services: - - docker:dind + - docker:dind before_script: - - docker info + - docker info build: stage: build script: - - docker build -t my-docker-image . - - docker run my-docker-image /script/to/run/tests + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests ``` Docker-in-Docker works well, and is the recommended configuration, but it is @@ -246,13 +246,13 @@ In order to do that, follow the steps: image: docker:stable before_script: - - docker info + - docker info build: stage: build script: - - docker build -t my-docker-image . - - docker run my-docker-image /script/to/run/tests + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests ``` While the above method avoids using Docker in privileged mode, you should be @@ -314,8 +314,8 @@ build: stage: build script: - docker pull $CONTAINER_IMAGE:latest || true - - docker build --cache-from $CONTAINER_IMAGE:latest --tag $CONTAINER_IMAGE:$CI_BUILD_REF --tag $CONTAINER_IMAGE:latest . - - docker push $CONTAINER_IMAGE:$CI_BUILD_REF + - docker build --cache-from $CONTAINER_IMAGE:latest --tag $CONTAINER_IMAGE:$CI_COMMIT_SHA --tag $CONTAINER_IMAGE:latest . + - docker push $CONTAINER_IMAGE:$CI_COMMIT_SHA - docker push $CONTAINER_IMAGE:latest ``` @@ -381,17 +381,18 @@ environment = ["DOCKER_DRIVER=overlay2"] If you're running multiple Runners you will have to modify all configuration files. > **Notes:** -- More information about the Runner configuration is available in the [Runner documentation](https://docs.gitlab.com/runner/configuration/). -- For more information about using OverlayFS with Docker, you can read - [Use the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/). +> +> - More information about the Runner configuration is available in the [Runner documentation](https://docs.gitlab.com/runner/configuration/). +> - For more information about using OverlayFS with Docker, you can read +> [Use the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/). ## Using the GitLab Container Registry > **Notes:** -- This feature requires GitLab 8.8 and GitLab Runner 1.2. -- Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need - to pass a [personal access token][pat] instead of your password in order to - login to GitLab's Container Registry. +> - This feature requires GitLab 8.8 and GitLab Runner 1.2. +> - Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need +> to pass a [personal access token][pat] instead of your password in order to +> login to GitLab's Container Registry. Once you've built a Docker image, you can push it up to the built-in [GitLab Container Registry](../../user/project/container_registry.md). For example, @@ -402,7 +403,7 @@ could look like: build: image: docker:stable services: - - docker:dind + - docker:dind variables: DOCKER_HOST: tcp://docker:2375 DOCKER_DRIVER: overlay2 @@ -455,13 +456,13 @@ an application-specific deploy script: ```yaml image: docker:stable services: -- docker:dind + - docker:dind stages: -- build -- test -- release -- deploy + - build + - test + - release + - deploy variables: DOCKER_HOST: tcp://docker:2375 diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 71f1d69cdf4..9abedcc6acb 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -452,13 +452,14 @@ 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. -- If the repository is private you need to authenticate your GitLab Runner in the - registry. Learn more about how [GitLab Runner works in this case][runner-priv-reg]. +> +> - 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. +> - If the repository is private you need to authenticate your GitLab Runner in the +> registry. Learn more about how [GitLab Runner works in this case][runner-priv-reg]. As an example, let's assume that you want to use the `registry.example.com/private/image:latest` image which is private and requires you to login into a private container registry. @@ -475,57 +476,57 @@ To configure access for `registry.example.com`, follow these steps: 1. Find what the value of `DOCKER_AUTH_CONFIG` should be. There are two ways to accomplish this: - - **First way -** Do a `docker login` on your local machine: + - **First way -** Do a `docker login` on your local machine: - ```bash - docker login registry.example.com --username my_username --password my_password - ``` + ```bash + docker login registry.example.com --username my_username --password my_password + ``` - Then copy the content of `~/.docker/config.json`. - - **Second way -** In some setups, it's possible that Docker client will use + Then copy the content of `~/.docker/config.json`. + - **Second way -** In some setups, it's possible that Docker client will use the available system keystore to store the result of `docker login`. In that case, it's impossible to read `~/.docker/config.json`, so you will need to prepare the required base64-encoded version of `${username}:${password}` manually. Open a terminal and execute the following command: - ```bash - echo -n "my_username:my_password" | base64 + ```bash + echo -n "my_username:my_password" | base64 - # Example output to copy - bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= - ``` + # Example output to copy + bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= + ``` 1. Create a [variable] `DOCKER_AUTH_CONFIG` with the content of the Docker configuration file as the value: - ```json - { - "auths": { - "registry.example.com": { - "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" - } - } - } - ``` + ```json + { + "auths": { + "registry.example.com": { + "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" + } + } + } + ``` 1. Optionally,if you followed the first way of finding the `DOCKER_AUTH_CONFIG` value, do a `docker logout` on your computer if you don't need access to the registry from it: - ```bash - docker logout registry.example.com - ``` + ```bash + docker logout registry.example.com + ``` 1. You can now use any private image from `registry.example.com` defined in `image` and/or `services` in your `.gitlab-ci.yml` file: - ```yaml - image: my.registry.tld:5000/namespace/image:tag - ``` + ```yaml + image: my.registry.tld:5000/namespace/image:tag + ``` - In the example above, GitLab Runner will look at `my.registry.tld:5000` for the - image `namespace/image:tag`. + In the example above, GitLab Runner will look at `my.registry.tld:5000` for the + image `namespace/image:tag`. You can add configuration for as many registries as you want, adding more registries to the `"auths"` hash as described above. diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 8ea2e0a81dc..4d740c32fd6 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -87,18 +87,18 @@ will later see, is exposed in various places within GitLab. Each time a job that has an environment specified and succeeds, a deployment is recorded, remembering the Git SHA and environment name. ->**Note:** -Starting with GitLab 8.15, the environment name is exposed to the Runner in -two forms: `$CI_ENVIRONMENT_NAME`, and `$CI_ENVIRONMENT_SLUG`. The first is -the name given in `.gitlab-ci.yml` (with any variables expanded), while the -second is a "cleaned-up" version of the name, suitable for use in URLs, DNS, -etc. - ->**Note:** -Starting with GitLab 9.3, the environment URL is exposed to the Runner via -`$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if -the URL was not defined there, the external URL from the environment would be -used. +> **Note:** +> Starting with GitLab 8.15, the environment name is exposed to the Runner in +> two forms: `$CI_ENVIRONMENT_NAME`, and `$CI_ENVIRONMENT_SLUG`. The first is +> the name given in `.gitlab-ci.yml` (with any variables expanded), while the +> second is a "cleaned-up" version of the name, suitable for use in URLs, DNS, +> etc. +> +> **Note:** +> Starting with GitLab 9.3, the environment URL is exposed to the Runner via +> `$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if +> the URL was not defined there, the external URL from the environment would be +> used. To sum up, with the above `.gitlab-ci.yml` we have achieved that: @@ -134,14 +134,15 @@ There's a bunch of information there, specifically you can see: - A button that re-deploys the latest deployment, meaning it runs the job defined by the environment name for that specific commit ->**Notes:** -- While you can create environments manually in the web interface, we recommend - that you define your environments in `.gitlab-ci.yml` first. They will - be automatically created for you after the first deploy. -- The environments page can only be viewed by Reporters and above. For more - information on the permissions, see the [permissions documentation][permissions]. -- Only deploys that happen after your `.gitlab-ci.yml` is properly configured - will show up in the "Environment" and "Last deployment" lists. +> **Notes:** +> +> - While you can create environments manually in the web interface, we recommend +> that you define your environments in `.gitlab-ci.yml` first. They will +> be automatically created for you after the first deploy. +> - The environments page can only be viewed by Reporters and above. For more +> information on the permissions, see the [permissions documentation][permissions]. +> - Only deploys that happen after your `.gitlab-ci.yml` is properly configured +> will show up in the "Environment" and "Last deployment" lists. The information shown in the Environments page is limited to the latest deployments, but as you may have guessed an environment can have multiple @@ -369,7 +370,7 @@ review_app: url: https://$CI_COMMIT_REF_SLUG.example.com ``` -It is assumed that the user has already setup NGINX and GitLab Runner in the +It is assumed that the user has already set up NGINX and GitLab Runner in the server this job will run on. >**Note:** @@ -563,13 +564,13 @@ exist, you should see something like: ## Monitoring environments ->**Notes:** +> **Notes:** > -- For the monitoring dashboard to appear, you need to: - - Have enabled the [Prometheus integration][prom] - - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/metrics.md) -- With GitLab 9.2, all deployments to an environment are shown directly on the - monitoring dashboard +> - For the monitoring dashboard to appear, you need to: +> - Have enabled the [Prometheus integration][prom] +> - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/metrics.md) +> - With GitLab 9.2, all deployments to an environment are shown directly on the +> monitoring dashboard If you have enabled [Prometheus for monitoring system and response metrics](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html), you can monitor the performance behavior of your app running in each environment. diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md index 8eb96ae10b2..fdf09d332a5 100644 --- a/doc/ci/examples/README.md +++ b/doc/ci/examples/README.md @@ -4,8 +4,8 @@ comments: false # GitLab CI/CD Examples -A collection of `.gitlab-ci.yml` template files is maintained at the [GitLab CI/CD YAML project][gitlab-ci-templates]. When you create a new file via the UI, -GitLab will give you the option to choose one of the templates existent on this project. +A collection of [`.gitlab-ci.yml` template files][gitlab-ci-templates] is maintained in GitLab. When you create a new file via the UI, +GitLab will give you the option to choose one of these templates. If your favorite programming language or framework are missing we would love your help by sending a merge request with a new `.gitlab-ci.yml` to this project. @@ -87,4 +87,4 @@ language users and GitLab by sending a merge request with a guide for that langu You may want to apply for the [GitLab Community Writers Program](https://about.gitlab.com/community-writers/) to get paid for writing complete articles for GitLab. -[gitlab-ci-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml +[gitlab-ci-templates]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates diff --git a/doc/ci/examples/browser_performance.md b/doc/ci/examples/browser_performance.md index 0dab07a7f80..d36e97ebfd3 100644 --- a/doc/ci/examples/browser_performance.md +++ b/doc/ci/examples/browser_performance.md @@ -110,4 +110,4 @@ performance: - sitespeed-results/ ``` -A complete example can be found in our [Auto DevOps CI YML](https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Auto-DevOps.gitlab-ci.yml). +A complete example can be found in our [Auto DevOps CI YML](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml). diff --git a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md index c226b5bfb71..b75ed87bc91 100644 --- a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md @@ -520,7 +520,7 @@ a lot of breathing room in quickly getting changes to players. Here are some ideas to further investigate that can speed up or improve your pipeline: - [Yarn](https://yarnpkg.com) instead of npm -- Setup a custom [Docker](../../../ci/docker/using_docker_images.md#define-image-and-services-from-gitlab-ci-yml) image that can preload dependencies and tools (like AWS CLI) +- Set up a custom [Docker](../../../ci/docker/using_docker_images.md#define-image-and-services-from-gitlab-ci-yml) image that can preload dependencies and tools (like AWS CLI) - Forward a [custom domain](http://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html) to your game's S3 static website - Combine jobs if you find it unnecessary for a small project - Avoid the queues and set up your own [custom GitLab CI/CD runner](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/) diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index 39c65399332..ab429e0ded3 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -13,7 +13,7 @@ date: 2017-08-31 GitLab features our applications with Continuous Integration, and it is possible to easily deploy the new code changes to the production server whenever we want. -In this tutorial, we'll show you how to initialize a [Laravel](http://laravel.com/) application and setup our [Envoy](https://laravel.com/docs/envoy) tasks, then we'll jump into see how to test and deploy it with [GitLab CI/CD](../README.md) via [Continuous Delivery](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/). +In this tutorial, we'll show you how to initialize a [Laravel](http://laravel.com/) application and set up our [Envoy](https://laravel.com/docs/envoy) tasks, then we'll jump into see how to test and deploy it with [GitLab CI/CD](../README.md) via [Continuous Delivery](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/). We assume you have a basic experience with Laravel, Linux servers, and you know how to use GitLab. @@ -23,7 +23,7 @@ It has a great community with a [fantastic documentation](https://laravel.com/do Aside from the usual routing, controllers, requests, responses, views, and (blade) templates, out of the box Laravel provides plenty of additional services such as cache, events, localization, authentication and many others. We will use [Envoy](https://laravel.com/docs/master/envoy) as an SSH task runner based on PHP. -It uses a clean, minimal [Blade syntax](https://laravel.com/docs/blade) to setup tasks that can run on remote servers, such as, cloning your project from the repository, installing the Composer dependencies, and running [Artisan commands](https://laravel.com/docs/artisan). +It uses a clean, minimal [Blade syntax](https://laravel.com/docs/blade) to set up tasks that can run on remote servers, such as, cloning your project from the repository, installing the Composer dependencies, and running [Artisan commands](https://laravel.com/docs/artisan). ## Initialize our Laravel app on GitLab @@ -372,7 +372,7 @@ At the end, our `Envoy.blade.php` file will look like this: One more thing we should do before any deployment is to manually copy our application `storage` folder to the `/var/www/app` directory on the server for the first time. You might want to create another Envoy task to do that for you. -We also create the `.env` file in the same path to setup our production environment variables for Laravel. +We also create the `.env` file in the same path to set up our production environment variables for Laravel. These are persistent data and will be shared to every new release. Now, we would need to deploy our app by running `envoy run deploy`, but it won't be necessary since GitLab can handle that for us with CI's [environments](../../environments.md), which will be described [later](#setting-up-gitlab-ci-cd) in this tutorial. @@ -587,7 +587,7 @@ unit_test: script: # Install app dependencies - composer install - # Setup .env + # Set up .env - cp .env.example .env # Generate an environment key - php artisan key:generate diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index a2ba29a4ee2..df4805ea7ac 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -199,7 +199,7 @@ pecl install <extension> ``` It's not advised to add this to `.gitlab-ci.yml`. You should execute this -command once, only to setup the build environment. +command once, only to set up the build environment. ## Extend your tests diff --git a/doc/ci/examples/test-scala-application.md b/doc/ci/examples/test-scala-application.md index 09d83c33f95..b3961ec91f3 100644 --- a/doc/ci/examples/test-scala-application.md +++ b/doc/ci/examples/test-scala-application.md @@ -1,6 +1,6 @@ # Test and deploy to Heroku a Scala application -This example demonstrates the integration of Gitlab CI with Scala +This example demonstrates the integration of GitLab CI with Scala applications using SBT. Checkout the example [project](https://gitlab.com/gitlab-examples/scala-sbt) and [build status](https://gitlab.com/gitlab-examples/scala-sbt/builds). diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md index a2de0408797..b2c73caae2e 100644 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md @@ -85,7 +85,7 @@ When asked, answer `Y` to fetch and install dependencies. If everything went fine, you'll get an output like this: - + Now, our project is located inside the directory with the same name we pass to `mix` command, for example, `~/GitLab/hello_gitlab_ci`. @@ -145,7 +145,7 @@ Now, we have our app running locally. We can preview it directly on our browser. not work, open [`127.0.0.1:4000`](http://127.0.0.1:4000) instead and later, configure your OS to point `localhost` to `127.0.0.1`. - + Great, now we have a local Phoenix Server running our app. diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index 286f3dee665..37078230b34 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -1,15 +1,16 @@ # Using Git submodules with GitLab CI > **Notes:** -- GitLab 8.12 introduced a new [CI job permissions model][newperms] and you - are encouraged to upgrade your GitLab instance if you haven't done already. - If you are **not** using GitLab 8.12 or higher, you would need to work your way - around submodules in order to access the sources of e.g., `gitlab.com/group/project` - with the use of [SSH keys](ssh_keys/README.md). -- With GitLab 8.12 onward, your permissions are used to evaluate what a CI job - can access. More information about how this system works can be found in the - [Jobs permissions model](../user/permissions.md#job-permissions). -- The HTTP(S) Git protocol [must be enabled][gitpro] in your GitLab instance. +> +> - GitLab 8.12 introduced a new [CI job permissions model][newperms] and you +> are encouraged to upgrade your GitLab instance if you haven't done already. +> If you are **not** using GitLab 8.12 or higher, you would need to work your way +> around submodules in order to access the sources of e.g., `gitlab.com/group/project` +> with the use of [SSH keys](ssh_keys/README.md). +> - With GitLab 8.12 onward, your permissions are used to evaluate what a CI job +> can access. More information about how this system works can be found in the +> [Jobs permissions model](../user/permissions.md#job-permissions). +> - The HTTP(S) Git protocol [must be enabled][gitpro] in your GitLab instance. ## Configuring the `.gitmodules` file diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 507aceb27fa..df83f30fbb7 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -1,13 +1,9 @@ # Getting started with interactive web terminals -> Introduced in GitLab 11.3. - -CAUTION: **Warning:** -Interactive web terminals are in beta, so they might not work properly and -lack features. For more information [follow issue #25990](https://gitlab.com/gitlab-org/gitlab-ce/issues/25990). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/50144) in GitLab 11.3. Interactive web terminals give the user access to a terminal in GitLab for -running one-of commands for their CI pipeline. +running one-off commands for their CI pipeline. NOTE: **Note:** This is not available for the shared Runners on GitLab.com. @@ -21,7 +17,7 @@ Two things need to be configured for the interactive web terminal to work: - The Runner needs to have [`[session_server]` configured properly][session-server] -- Web terminals need to be +- If you are using a reverse proxy with your GitLab instance, web terminals need to be [enabled](../../administration/integration/terminal.md#enabling-and-disabling-terminal-support) ## Debugging a running job diff --git a/doc/ci/junit_test_reports.md b/doc/ci/junit_test_reports.md index 5ae8ecaafa6..3fd54647abb 100644 --- a/doc/ci/junit_test_reports.md +++ b/doc/ci/junit_test_reports.md @@ -100,3 +100,71 @@ golang: reports: junit: report.xml ``` + +### Java examples + +There are a few tools that can produce JUnit reports in Java. + +#### Gradle + +In the following example, `gradle` is used to generate the test reports. +If there are multiple test tasks defined, `gradle` will generate multiple +directories under `build/test-results/`. In that case, you can leverage regex +matching by defining the following path: `build/test-results/test/TEST-*.xml`: + +```yaml +java: + stage: test + script: + - gradle test + artifacts: + reports: + junit: build/test-results/test/TEST-*.xml +``` + +#### Maven + +For parsing [Surefire](https://maven.apache.org/surefire/maven-surefire-plugin/) +and [Failsafe](https://maven.apache.org/surefire/maven-failsafe-plugin/) test +reports, use the following job in `.gitlab-ci.yml`: + +```yaml +java: + stage: test + script: + - mvn verify + artifacts: + reports: + junit: + - target/surefire-reports/TEST-*.xml + - target/failsafe-reports/TEST-*.xml +``` + +### C/C++ example + +There are a few tools that can produce JUnit reports in C/C++. + +#### GoogleTest + +In the following example, `gtest` is used to generate the test reports. +If there are multiple gtest executables created for different architectures (`x86`, `x64` or `arm`), +you will be required to run each test providing a unique filename. The results +will then be aggregated together. + +```yaml +cpp: + stage: test + script: + - gtest.exe --gtest_output="xml:report.xml" + artifacts: + reports: + junit: report.xml +``` + +## Limitations + +Currently, the following tools might not work because their XML formats are unsupported in GitLab. + +|Case|Tool|Issue| +|---|---|---| +|`<testcase>` does not have `classname` attribute|ESlint, sass-lint|https://gitlab.com/gitlab-org/gitlab-ce/issues/50964| diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index 4e964af97f5..ea47d676edb 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -9,7 +9,7 @@ you may need to enable pipeline triggering in your project's ## Pipelines -A pipeline is a group of [jobs][] that get executed in [stages][](batches). +A pipeline is a group of [jobs] that get executed in [stages]. All of the jobs in a stage are executed in parallel (if there are enough concurrent [Runners]), and if they all succeed, the pipeline moves on to the next stage. If one of the jobs fails, the next stage is not (usually) @@ -29,17 +29,17 @@ There are three types of pipelines that often use the single shorthand of "pipel  -1. **CI Pipeline**: Build and test stages defined in `.gitlab-ci.yml` -2. **Deploy Pipeline**: Deploy stage(s) defined in `.gitlab-ci.yml` The flow of deploying code to servers through various stages: e.g. development to staging to production -3. **Project Pipeline**: Cross-project CI dependencies [triggered via API][triggers], particularly for micro-services, but also for complicated build dependencies: e.g. api -> front-end, ce/ee -> omnibus. +1. **CI Pipeline**: Build and test stages defined in `.gitlab-ci.yml`. +1. **Deploy Pipeline**: Deploy stage(s) defined in `.gitlab-ci.yml` The flow of deploying code to servers through various stages: e.g. development to staging to production. +1. **Project Pipeline**: Cross-project CI dependencies [triggered via API][triggers], particularly for micro-services, but also for complicated build dependencies: e.g. api -> front-end, ce/ee -> omnibus. ## Development workflows Pipelines accommodate several development workflows: -1. **Branch Flow** (e.g. different branch for dev, qa, staging, production) -2. **Trunk-based Flow** (e.g. feature branches and single master branch, possibly with tags for releases) -3. **Fork-based Flow** (e.g. merge requests come from forks) +1. **Branch Flow** (e.g. different branch for dev, qa, staging, production). +1. **Trunk-based Flow** (e.g. feature branches and single master branch, possibly with tags for releases). +1. **Fork-based Flow** (e.g. merge requests come from forks). Example continuous delivery flow: @@ -57,6 +57,16 @@ Pipelines are defined in `.gitlab-ci.yml` by specifying [jobs] that run in See the reference [documentation for jobs](yaml/README.md#jobs). +## Manually executing pipelines + +Pipelines can be manually executed, with predefined or manually-specified [variables](variables/README.md). + +To execute a pipeline manually: + +1. Navigate to your project's **CI/CD > Pipelines**. +1. Click on the **Run Pipeline** button. +1. Select the branch to run the pipeline for and enter any environment variables required for the pipeline run. + ## Seeing pipeline status You can find the current and historical pipeline runs under your project's @@ -112,9 +122,9 @@ Then, there is the pipeline mini graph which takes less space and can give you a quick glance if all jobs pass or something failed. The pipeline mini graph can be found when you visit: -- the pipelines index page -- a single commit page -- a merge request page +- The pipelines index page. +- A single commit page. +- A merge request page. That way, you can see all related jobs for a single commit and the net result of each stage of your pipeline. This allows you to quickly see what failed and @@ -142,9 +152,9 @@ jobs. Click to expand them. The basic requirements is that there are two numbers separated with one of the following (you can even use them interchangeably): -- a space -- a slash (`/`) -- a colon (`:`) +- A space (` `) +- A slash (`/`) +- A colon (`:`) >**Note:** More specifically, [it uses][regexp] this regular expression: `\d+[\s:\/\\]+\d+\s*`. @@ -252,11 +262,12 @@ A strict security model is enforced when pipelines are executed on The following actions are allowed on protected branches only if the user is [allowed to merge or push](../user/project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings) on that specific branch: -- run **manual pipelines** (using Web UI or Pipelines API) -- run **scheduled pipelines** -- run pipelines using **triggers** -- trigger **manual actions** on existing pipelines -- **retry/cancel** existing jobs (using Web UI or Pipelines API) + +- Run **manual pipelines** (using [Web UI](#manually-executing-pipelines) or Pipelines API). +- Run **scheduled pipelines**. +- Run pipelines using **triggers**. +- Trigger **manual actions** on existing pipelines. +- **Retry/cancel** existing jobs (using Web UI or Pipelines API). **Variables** marked as **protected** are accessible only to jobs that run on protected branches, avoiding untrusted users to get unintended access to diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 47e658f610e..636117536a2 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -7,7 +7,7 @@ projects. GitLab offers a [continuous integration][ci] service. If you [add a `.gitlab-ci.yml` file][yaml] to the root directory of your repository, and configure your GitLab project to use a [Runner], then each commit or -push, triggers your CI [pipeline]. +push triggers your CI [pipeline]. The `.gitlab-ci.yml` file tells the GitLab runner what to do. By default it runs a pipeline with three [stages]: `build`, `test`, and `deploy`. You don't need to diff --git a/doc/ci/review_apps/img/continuous-delivery-review-apps.svg b/doc/ci/review_apps/img/continuous-delivery-review-apps.svg new file mode 100644 index 00000000000..90ac763a01e --- /dev/null +++ b/doc/ci/review_apps/img/continuous-delivery-review-apps.svg @@ -0,0 +1,48 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg width="1170px" height="638px" viewBox="0 0 1170 638" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> + <!-- Generator: Sketch 41 (35326) - http://www.bohemiancoding.com/sketch --> + <title>review-apps-CD-outlined</title> + <desc>Created with Sketch.</desc> + <defs></defs> + <g id="Page-2" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd"> + <g id="review-apps-CD-outlined"> + <g id="Group-4-Copy" transform="translate(22.000000, 43.000000)"> + <polygon id="Line-Copy-25" fill="#E0513E" points="163.545966 259 858.690432 259 858.690432 255 163.545966 255"></polygon> + <path d="M870.470919,266.702602 C875.287562,266.702602 879.19137,262.80085 879.19137,257.988848 C879.19137,253.176845 875.287562,249.275093 870.470919,249.275093 C865.654276,249.275093 861.750469,253.176845 861.750469,257.988848 C861.750469,262.80085 865.654276,266.702602 870.470919,266.702602 Z M870.470919,270.702602 C863.445609,270.702602 857.750469,265.01046 857.750469,257.988848 C857.750469,250.967235 863.445609,245.275093 870.470919,245.275093 C877.49623,245.275093 883.19137,250.967235 883.19137,257.988848 C883.19137,265.01046 877.49623,270.702602 870.470919,270.702602 Z" id="Oval-Copy-20" fill="#E04733"></path> + <path d="M991.315197,145.921933 C996.13184,145.921933 1000.03565,142.020181 1000.03565,137.208178 C1000.03565,132.396176 996.13184,128.494424 991.315197,128.494424 C986.498554,128.494424 982.594747,132.396176 982.594747,137.208178 C982.594747,142.020181 986.498554,145.921933 991.315197,145.921933 Z M991.315197,149.921933 C984.289886,149.921933 978.594747,144.229791 978.594747,137.208178 C978.594747,130.186566 984.289886,124.494424 991.315197,124.494424 C998.340508,124.494424 1004.03565,130.186566 1004.03565,137.208178 C1004.03565,144.229791 998.340508,149.921933 991.315197,149.921933 Z" id="Oval-Copy-22" fill="#E04733"></path> + <g id="Group-7" transform="translate(0.000000, 236.799257)" fill="#E04733"> + <path d="M151.765478,29.9033457 C156.582121,29.9033457 160.485929,26.0015933 160.485929,21.1895911 C160.485929,16.3775889 156.582121,12.4758364 151.765478,12.4758364 C146.948835,12.4758364 143.045028,16.3775889 143.045028,21.1895911 C143.045028,26.0015933 146.948835,29.9033457 151.765478,29.9033457 Z M151.765478,33.9033457 C144.740168,33.9033457 139.045028,28.2112039 139.045028,21.1895911 C139.045028,14.1679783 144.740168,8.47583643 151.765478,8.47583643 C158.790789,8.47583643 164.485929,14.1679783 164.485929,21.1895911 C164.485929,28.2112039 158.790789,33.9033457 151.765478,33.9033457 Z" id="Oval-Copy-10"></path> + <path d="M0.187705647,10.1392011 L3.30410548,10.1392011 L7.34270526,21.3328005 L8.86910518,25.5940003 L8.99630517,25.5940003 L10.4591051,21.3328005 L14.4659049,10.1392011 L17.5823047,10.1392011 L17.5823047,31 L15.0701048,31 L15.0701048,19.5202006 C15.0701048,18.587396 15.1072045,17.5592063 15.1814048,16.4356008 C15.2556052,15.3119952 15.3351044,14.2838056 15.4199048,13.351001 L15.2927048,13.351001 L13.6073049,17.9938007 L9.60050514,28.9012001 L8.10590522,28.9012001 L4.06730544,17.9938007 L2.41370553,13.351001 L2.28650553,13.351001 C2.35010585,14.2838056 2.4243051,15.3119952 2.50910552,16.4356008 C2.59390594,17.5592063 2.63630552,18.587396 2.63630552,19.5202006 L2.63630552,31 L0.187705647,31 L0.187705647,10.1392011 Z M32.1785039,22.5094005 L31.192704,19.3294006 C30.8111021,18.1633949 30.4507057,17.0027065 30.111504,15.8473008 C29.7723024,14.6918951 29.4331058,13.510007 29.0939041,12.301601 L28.9667041,12.301601 C28.6487025,13.510007 28.3201058,14.6918951 27.9809041,15.8473008 C27.6417025,17.0027065 27.2813061,18.1633949 26.8997042,19.3294006 L25.9139043,22.5094005 L32.1785039,22.5094005 Z M32.8463039,24.6400003 L25.2461043,24.6400003 L23.2427044,31 L20.5397045,31 L27.5993042,10.1392011 L30.588504,10.1392011 L37.6481036,31 L34.8179038,31 L32.8463039,24.6400003 Z M40.6691035,26.4526002 C41.4111071,27.2370041 42.2855983,27.8676978 43.2926033,28.3447001 C44.2996083,28.8217025 45.3436978,29.0602001 46.4249032,29.0602001 C47.80291,29.0602001 48.8734992,28.7475032 49.636703,28.1221002 C50.3999068,27.4966971 50.7815029,26.6752053 50.7815029,25.6576003 C50.7815029,25.1275977 50.6914038,24.6771022 50.5112029,24.3061004 C50.331002,23.9350985 50.0872045,23.6171017 49.779803,23.3521004 C49.4724014,23.0870991 49.1067051,22.8486015 48.682703,22.6366005 C48.2587009,22.4245994 47.8029055,22.2020016 47.3153031,21.9688005 L44.3261033,20.6650006 C43.8385009,20.4529995 43.3403059,20.1986021 42.8315033,19.9018006 C42.3227008,19.6049991 41.8669054,19.2446028 41.4641034,18.8206007 C41.0613014,18.3965986 40.7327047,17.8931036 40.4783035,17.3101007 C40.2239022,16.7270979 40.0967035,16.0540046 40.0967035,15.2908008 C40.0967035,14.506397 40.2610018,13.7750043 40.5896035,13.096601 C40.9182051,12.4181976 41.3740005,11.8299035 41.9570034,11.3317011 C42.5400063,10.8334986 43.2289993,10.4466025 44.0240033,10.1710011 C44.8190072,9.89539976 45.6934984,9.75760115 46.6475031,9.75760115 C47.8983093,9.75760115 49.0536977,9.99609875 50.113703,10.4731011 C51.1737082,10.9501035 52.0746991,11.5701972 52.8167028,12.333401 L51.3857029,14.0506009 C50.7496997,13.4357979 50.0448068,12.9535027 49.271003,12.603701 C48.4971992,12.2538993 47.622708,12.079001 46.6475031,12.079001 C45.4814974,12.079001 44.5434068,12.3492983 43.8332033,12.889901 C43.1229998,13.4305037 42.7679033,14.1777961 42.7679033,15.1318009 C42.7679033,15.6406034 42.8686023,16.0698991 43.0700033,16.4197008 C43.2714043,16.7695025 43.5417016,17.0768994 43.8809033,17.3419007 C44.220105,17.606902 44.5911012,17.8400997 44.9939032,18.0415007 C45.3967052,18.2429017 45.8101011,18.4283998 46.2341032,18.5980007 L49.191503,19.8700006 C49.7851059,20.1244019 50.3469003,20.4158989 50.8769029,20.7445006 C51.4069055,21.0731022 51.8627009,21.4546983 52.2443028,21.8893005 C52.6259047,22.3239026 52.9280017,22.8326975 53.1506028,23.4157004 C53.3732039,23.9987033 53.4845028,24.6717965 53.4845028,25.4350003 C53.4845028,26.2618044 53.3202044,27.0355966 52.9916028,27.7564002 C52.6630012,28.4772037 52.1913059,29.1078974 51.5765029,29.6485001 C50.9616998,30.1891027 50.2197073,30.6130985 49.350503,30.9205 C48.4812987,31.2279015 47.4955086,31.3816 46.3931032,31.3816 C44.9302959,31.3816 43.5735096,31.1060028 42.3227034,30.5548 C41.0718972,30.0035973 39.9907081,29.2510049 39.0791035,28.2970001 L40.6691035,26.4526002 Z M61.9115023,12.365201 L55.6151027,12.365201 L55.6151027,10.1392011 L70.8791018,10.1392011 L70.8791018,12.365201 L64.5827022,12.365201 L64.5827022,31 L61.9115023,31 L61.9115023,12.365201 Z M74.6315016,10.1392011 L86.651901,10.1392011 L86.651901,12.365201 L77.2709015,12.365201 L77.2709015,18.9160007 L85.1891011,18.9160007 L85.1891011,21.1738005 L77.2709015,21.1738005 L77.2709015,28.7422001 L86.969901,28.7422001 L86.969901,31 L74.6315016,31 L74.6315016,10.1392011 Z M94.0295006,20.0290006 L97.5275004,20.0290006 C99.1599085,20.0290006 100.410696,19.6951039 101.2799,19.0273006 C102.149104,18.3594973 102.5837,17.3472075 102.5837,15.9904008 C102.5837,14.612394 102.149104,13.6478037 101.2799,13.096601 C100.410696,12.5453982 99.1599085,12.269801 97.5275004,12.269801 L94.0295006,12.269801 L94.0295006,20.0290006 Z M102.8381,31 L97.8137004,22.1914005 L94.0295006,22.1914005 L94.0295006,31 L91.3901007,31 L91.3901007,10.1392011 L97.9091004,10.1392011 C98.9691056,10.1392011 99.9495958,10.2399001 100.8506,10.4413011 C101.751605,10.6427021 102.525397,10.9765987 103.172,11.4430011 C103.818603,11.9094034 104.322098,12.5135973 104.6825,13.255601 C105.042902,13.9976046 105.2231,14.9091955 105.2231,15.9904008 C105.2231,17.6228089 104.799104,18.9265958 103.9511,19.9018006 C103.103096,20.8770054 101.968907,21.5447987 100.5485,21.9052005 L105.8273,31 L102.8381,31 Z" id="MASTER"></path> + </g> + <path d="M829.454852,142.471188 C830.196855,143.255591 831.071347,143.886285 832.078351,144.363288 C833.085356,144.84029 834.129446,145.078787 835.210651,145.078787 C836.588658,145.078787 837.659247,144.766091 838.422451,144.140688 C839.185655,143.515284 839.567251,142.693793 839.567251,141.676188 C839.567251,141.146185 839.477152,140.69569 839.296951,140.324688 C839.11675,139.953686 838.872953,139.635689 838.565551,139.370688 C838.25815,139.105686 837.892453,138.867189 837.468451,138.655188 C837.044449,138.443187 836.588654,138.220589 836.101051,137.987388 L833.111851,136.683588 C832.624249,136.471587 832.126054,136.217189 831.617252,135.920388 C831.108449,135.623586 830.652654,135.26319 830.249852,134.839188 C829.84705,134.415186 829.518453,133.911691 829.264052,133.328688 C829.00965,132.745685 828.882452,132.072592 828.882452,131.309388 C828.882452,130.524984 829.04675,129.793592 829.375352,129.115188 C829.703953,128.436785 830.159749,127.848491 830.742752,127.350288 C831.325754,126.852086 832.014748,126.46519 832.809751,126.189588 C833.604755,125.913987 834.479247,125.776189 835.433251,125.776189 C836.684057,125.776189 837.839446,126.014686 838.899451,126.491688 C839.959456,126.968691 840.860447,127.588785 841.602451,128.351988 L840.171451,130.069188 C839.535448,129.454385 838.830555,128.97209 838.056751,128.622288 C837.282947,128.272487 836.408456,128.097588 835.433251,128.097588 C834.267246,128.097588 833.329155,128.367886 832.618951,128.908488 C831.908748,129.449091 831.553652,130.196383 831.553652,131.150388 C831.553652,131.659191 831.654351,132.088486 831.855752,132.438288 C832.057152,132.78809 832.32745,133.095487 832.666651,133.360488 C833.005853,133.625489 833.376849,133.858687 833.779651,134.060088 C834.182453,134.261489 834.595849,134.446987 835.019851,134.616588 L837.977251,135.888588 C838.570854,136.142989 839.132648,136.434486 839.662651,136.763088 C840.192654,137.09169 840.648449,137.473286 841.030051,137.907888 C841.411653,138.34249 841.71375,138.851285 841.936351,139.434288 C842.158952,140.017291 842.270251,140.690384 842.270251,141.453588 C842.270251,142.280392 842.105953,143.054184 841.777351,143.774988 C841.448749,144.495791 840.977054,145.126485 840.362251,145.667087 C839.747448,146.20769 839.005455,146.631686 838.136251,146.939087 C837.267047,147.246489 836.281257,147.400187 835.178851,147.400187 C833.716044,147.400187 832.359258,147.12459 831.108452,146.573387 C829.857645,146.022185 828.776456,145.269592 827.864852,144.315588 L829.454852,142.471188 Z M850.69725,128.383788 L844.400851,128.383788 L844.400851,126.157788 L859.66485,126.157788 L859.66485,128.383788 L853.36845,128.383788 L853.36845,147.018587 L850.69725,147.018587 L850.69725,128.383788 Z M872.289449,138.527988 L871.303649,135.347988 C870.922047,134.181982 870.561651,133.021294 870.222449,131.865888 C869.883248,130.710482 869.544051,129.528594 869.204849,128.320188 L869.077649,128.320188 C868.759648,129.528594 868.431051,130.710482 868.09185,131.865888 C867.752648,133.021294 867.392251,134.181982 867.01065,135.347988 L866.02485,138.527988 L872.289449,138.527988 Z M872.957249,140.658588 L865.35705,140.658588 L863.35365,147.018587 L860.65065,147.018587 L867.71025,126.157788 L870.699449,126.157788 L877.759049,147.018587 L874.928849,147.018587 L872.957249,140.658588 Z M879.508049,136.588188 C879.508049,134.91338 879.746547,133.408195 880.223549,132.072588 C880.700551,130.736982 881.368345,129.602793 882.226949,128.669988 C883.085553,127.737184 884.097843,127.021691 885.263849,126.523488 C886.429854,126.025286 887.712441,125.776189 889.111648,125.776189 C890.553256,125.776189 891.756343,126.046486 892.720948,126.587088 C893.685553,127.127691 894.475245,127.715985 895.090048,128.351988 L893.595448,130.037388 C893.065446,129.486186 892.455952,129.02509 891.766948,128.654088 C891.077945,128.283087 890.203454,128.097588 889.143448,128.097588 C888.083443,128.097588 887.129453,128.293686 886.281449,128.685888 C885.433444,129.07809 884.712652,129.639885 884.119049,130.371288 C883.525446,131.102692 883.06435,131.987783 882.735749,133.026588 C882.407147,134.065393 882.242849,135.231382 882.242849,136.524588 C882.242849,137.838994 882.396547,139.020883 882.703949,140.070288 C883.01135,141.119693 883.456546,142.015384 884.039549,142.757388 C884.622552,143.499391 885.343344,144.071786 886.201949,144.474587 C887.060553,144.877389 888.051643,145.078787 889.175248,145.078787 C889.917252,145.078787 890.622145,144.967489 891.289948,144.744887 C891.957752,144.522286 892.503646,144.220189 892.927648,143.838588 L892.927648,138.400788 L888.507448,138.400788 L888.507448,136.206588 L895.344448,136.206588 L895.344448,144.983387 C894.666045,145.682991 893.770354,146.260685 892.657348,146.716487 C891.544343,147.17229 890.288255,147.400187 888.889048,147.400187 C887.511042,147.400187 886.249654,147.15639 885.104849,146.668787 C883.960043,146.181185 882.974253,145.476292 882.147449,144.554087 C881.320645,143.631883 880.674051,142.497694 880.207649,141.151488 C879.741247,139.805281 879.508049,138.284196 879.508049,136.588188 Z M900.337048,126.157788 L902.976448,126.157788 L902.976448,147.018587 L900.337048,147.018587 L900.337048,126.157788 Z M908.700447,126.157788 L911.435247,126.157788 L918.971847,139.259388 L921.229647,143.584188 L921.356847,143.584188 C921.293246,142.524182 921.224347,141.427093 921.150147,140.292888 C921.075946,139.158682 921.038847,138.040393 921.038847,136.937988 L921.038847,126.157788 L923.551047,126.157788 L923.551047,147.018587 L920.816247,147.018587 L913.247847,133.885188 L910.990047,129.592188 L910.862847,129.592188 C910.947648,130.652194 911.027147,131.728083 911.101347,132.819888 C911.175548,133.911694 911.212647,135.008782 911.212647,136.111188 L911.212647,147.018587 L908.700447,147.018587 L908.700447,126.157788 Z M928.066646,136.588188 C928.066646,134.91338 928.305144,133.408195 928.782146,132.072588 C929.259149,130.736982 929.926942,129.602793 930.785546,128.669988 C931.64415,127.737184 932.65644,127.021691 933.822446,126.523488 C934.988452,126.025286 936.271039,125.776189 937.670246,125.776189 C939.111853,125.776189 940.314941,126.046486 941.279546,126.587088 C942.24415,127.127691 943.033842,127.715985 943.648645,128.351988 L942.154046,130.037388 C941.624043,129.486186 941.014549,129.02509 940.325546,128.654088 C939.636542,128.283087 938.762051,128.097588 937.702046,128.097588 C936.642041,128.097588 935.68805,128.293686 934.840046,128.685888 C933.992042,129.07809 933.271249,129.639885 932.677646,130.371288 C932.084043,131.102692 931.622948,131.987783 931.294346,133.026588 C930.965745,134.065393 930.801446,135.231382 930.801446,136.524588 C930.801446,137.838994 930.955145,139.020883 931.262546,140.070288 C931.569948,141.119693 932.015143,142.015384 932.598146,142.757388 C933.181149,143.499391 933.901942,144.071786 934.760546,144.474587 C935.61915,144.877389 936.61024,145.078787 937.733846,145.078787 C938.475849,145.078787 939.180742,144.967489 939.848546,144.744887 C940.516349,144.522286 941.062243,144.220189 941.486246,143.838588 L941.486246,138.400788 L937.066046,138.400788 L937.066046,136.206588 L943.903045,136.206588 L943.903045,144.983387 C943.224642,145.682991 942.328951,146.260685 941.215946,146.716487 C940.10294,147.17229 938.846853,147.400187 937.447646,147.400187 C936.069639,147.400187 934.808252,147.15639 933.663446,146.668787 C932.51864,146.181185 931.53285,145.476292 930.706046,144.554087 C929.879242,143.631883 929.232649,142.497694 928.766246,141.151488 C928.299844,139.805281 928.066646,138.284196 928.066646,136.588188 Z" id="STAGING" fill="#E04733"></path> + <path d="M888.668416,1.13920113 L895.060216,1.13920113 C896.205021,1.13920113 897.254411,1.24520006 898.208415,1.45720111 C899.16242,1.66920216 899.973312,2.01369869 900.641115,2.49070105 C901.308919,2.96770341 901.828313,3.59839707 902.199315,4.38280095 C902.570317,5.16720483 902.755815,6.13179513 902.755815,7.27660079 C902.755815,8.37900625 902.570317,9.33299666 902.199315,10.1386006 C901.828313,10.9442046 901.303619,11.6119979 900.625215,12.1420005 C899.946812,12.6720032 899.13592,13.0694992 898.192515,13.3345005 C897.249111,13.5995018 896.205021,13.7320004 895.060216,13.7320004 L891.307816,13.7320004 L891.307816,22 L888.668416,22 L888.668416,1.13920113 Z M894.742216,11.5696006 C896.565425,11.5696006 897.916911,11.225104 898.796715,10.5361006 C899.67652,9.84709721 900.116415,8.76060813 900.116415,7.27660079 C900.116415,5.77139335 899.67122,4.72730385 898.780815,4.14430096 C897.890411,3.56129808 896.544224,3.26980101 894.742216,3.26980101 L891.307816,3.26980101 L891.307816,11.5696006 L894.742216,11.5696006 Z M909.624615,11.0290006 L913.122615,11.0290006 C914.755023,11.0290006 916.00581,10.6951039 916.875014,10.0273006 C917.744219,9.35949734 918.178814,8.34720752 918.178814,6.99040081 C918.178814,5.61239399 917.744219,4.64780369 916.875014,4.09660097 C916.00581,3.54539824 914.755023,3.26980101 913.122615,3.26980101 L909.624615,3.26980101 L909.624615,11.0290006 Z M918.433214,22 L913.408815,13.1914005 L909.624615,13.1914005 L909.624615,22 L906.985215,22 L906.985215,1.13920113 L913.504215,1.13920113 C914.56422,1.13920113 915.54471,1.23990011 916.445714,1.44130111 C917.346719,1.64270211 918.120511,1.97659875 918.767114,2.44300106 C919.413717,2.90940336 919.917212,3.51359729 920.277614,4.25560096 C920.638016,4.99760463 920.818214,5.90919546 920.818214,6.99040081 C920.818214,8.62280888 920.394218,9.92659578 919.546214,10.9018006 C918.69821,11.8770054 917.564021,12.5447987 916.143614,12.9052005 L921.422414,22 L918.433214,22 Z M933.156613,22.3816 C931.842207,22.3816 930.639119,22.1272025 929.547314,21.6184 C928.455508,21.1095975 927.517418,20.3835048 926.733014,19.4401001 C925.94861,18.4966955 925.339116,17.351907 924.904514,16.0057003 C924.469912,14.6594937 924.252614,13.1490089 924.252614,11.4742006 C924.252614,9.79939228 924.469912,8.29950736 924.904514,6.97450081 C925.339116,5.64949426 925.94861,4.52590555 926.733014,3.60370099 C927.517418,2.68149643 928.455508,1.97660352 929.547314,1.48900111 C930.639119,1.0013987 931.842207,0.757601147 933.156613,0.757601147 C934.47102,0.757601147 935.674108,1.00669864 936.765913,1.50490111 C937.857719,2.00310357 938.801109,2.71329643 939.596113,3.63550099 C940.391117,4.55770555 941.005911,5.68129426 941.440513,7.00630081 C941.875115,8.33130736 942.092413,9.82059239 942.092413,11.4742006 C942.092413,13.1490089 941.875115,14.6594937 941.440513,16.0057003 C941.005911,17.351907 940.391117,18.4966955 939.596113,19.4401001 C938.801109,20.3835048 937.857719,21.1095975 936.765913,21.6184 C935.674108,22.1272025 934.47102,22.3816 933.156613,22.3816 Z M933.156613,20.0602001 C934.089418,20.0602001 934.93211,19.8588021 935.684713,19.4560001 C936.437317,19.0531981 937.083911,18.475504 937.624513,17.7229002 C938.165116,16.9702965 938.583812,16.0693056 938.880613,15.0199004 C939.177415,13.9704952 939.325813,12.7886071 939.325813,11.4742006 C939.325813,10.1809942 939.177415,9.01500589 938.880613,7.97620076 C938.583812,6.93739562 938.165116,6.05760446 937.624513,5.3368009 C937.083911,4.61599733 936.437317,4.05950293 935.684713,3.66730099 C934.93211,3.27509905 934.089418,3.07900102 933.156613,3.07900102 C932.223809,3.07900102 931.381117,3.27509905 930.628514,3.66730099 C929.87591,4.05950293 929.229316,4.61599733 928.688714,5.3368009 C928.148111,6.05760446 927.729415,6.93739562 927.432614,7.97620076 C927.135812,9.01500589 926.987414,10.1809942 926.987414,11.4742006 C926.987414,12.7886071 927.135812,13.9704952 927.432614,15.0199004 C927.729415,16.0693056 928.148111,16.9702965 928.688714,17.7229002 C929.229316,18.475504 929.87591,19.0531981 930.628514,19.4560001 C931.381117,19.8588021 932.223809,20.0602001 933.156613,20.0602001 Z M946.576213,1.13920113 L951.791412,1.13920113 C955.013828,1.13920113 957.462404,2.02959217 959.137212,3.81040098 C960.81202,5.59120979 961.649412,8.14578411 961.649412,11.4742006 C961.649412,13.1278087 961.437414,14.6064939 961.013412,15.9103003 C960.58941,17.2141068 959.964016,18.3164957 959.137212,19.2175002 C958.310408,20.1185046 957.292818,20.8074977 956.084412,21.2845 C954.876006,21.7615024 953.48742,22 951.918612,22 L946.576213,22 L946.576213,1.13920113 Z M951.600612,19.8376001 C954.038625,19.8376001 955.867106,19.1062075 957.086112,17.6434002 C958.305118,16.180593 958.914612,14.1242137 958.914612,11.4742006 C958.914612,8.82418746 958.305118,6.79960782 957.086112,5.4004009 C955.867106,4.00119398 954.038625,3.30160101 951.600612,3.30160101 L949.215613,3.30160101 L949.215613,19.8376001 L951.600612,19.8376001 Z M966.037812,1.13920113 L968.677212,1.13920113 L968.677212,13.4458005 C968.677212,14.6966066 968.80441,15.7459961 969.058812,16.5940003 C969.313213,17.4420045 969.657709,18.1203977 970.092311,18.6292002 C970.526914,19.1380027 971.041008,19.503699 971.634611,19.7263001 C972.228214,19.9489012 972.864208,20.0602001 973.542611,20.0602001 C974.242215,20.0602001 974.888808,19.9489012 975.482411,19.7263001 C976.076014,19.503699 976.595409,19.1380027 977.040611,18.6292002 C977.485813,18.1203977 977.83561,17.4420045 978.090011,16.5940003 C978.344412,15.7459961 978.471611,14.6966066 978.471611,13.4458005 L978.471611,1.13920113 L981.015611,1.13920113 L981.015611,13.3822005 C981.015611,15.0570087 980.824813,16.4667946 980.443211,17.6116002 C980.061609,18.7564059 979.536914,19.6838966 978.869111,20.3941001 C978.201308,21.1043036 977.411616,21.6130985 976.500011,21.9205 C975.588407,22.2279015 974.602617,22.3816 973.542611,22.3816 C972.482606,22.3816 971.491516,22.2279015 970.569311,21.9205 C969.647107,21.6130985 968.852115,21.1043036 968.184312,20.3941001 C967.516508,19.6838966 966.991814,18.7564059 966.610212,17.6116002 C966.22861,16.4667946 966.037812,15.0570087 966.037812,13.3822005 L966.037812,1.13920113 Z M985.435811,11.5696006 C985.435811,9.89479228 985.669008,8.38960741 986.135411,7.05400081 C986.601813,5.7183942 987.248406,4.5842056 988.07521,3.65140099 C988.902015,2.71859638 989.882505,2.00310357 991.01671,1.50490111 C992.150916,1.00669864 993.385804,0.757601147 994.72141,0.757601147 C995.993416,0.757601147 997.106405,1.01729854 998.06041,1.5367011 C999.014415,2.05610367 999.798807,2.65499765 1000.41361,3.33340101 L998.91901,5.01880092 C998.367807,4.42519798 997.758313,3.95350272 997.09051,3.60370099 C996.422707,3.25389926 995.643615,3.07900102 994.75321,3.07900102 C993.756805,3.07900102 992.855814,3.27509905 992.05021,3.66730099 C991.244606,4.05950293 990.555613,4.62129728 989.98321,5.3527009 C989.410808,6.08410452 988.965612,6.96919562 988.64761,8.00800076 C988.329609,9.04680589 988.17061,10.2127942 988.17061,11.5060006 C988.17061,12.8204071 988.324309,14.0022952 988.63171,15.0517004 C988.939112,16.1011056 989.368408,16.9967966 989.91961,17.7388002 C990.470813,18.4808039 991.143906,19.0531981 991.93891,19.4560001 C992.733914,19.8588021 993.629605,20.0602001 994.62601,20.0602001 C995.643615,20.0602001 996.528706,19.8588021 997.28131,19.4560001 C998.033914,19.0531981 998.749407,18.4808039 999.42781,17.7388002 L1000.92241,19.3606001 C1000.09561,20.3146049 999.162815,21.0565974 998.12401,21.5866 C997.085205,22.1166026 995.898017,22.3816 994.56241,22.3816 C993.248004,22.3816 992.034316,22.1378024 990.92131,21.6502 C989.808305,21.1625976 988.843715,20.4577047 988.02751,19.5355001 C987.211306,18.6132956 986.575313,17.479107 986.119511,16.1329003 C985.663708,14.7866937 985.435811,13.265609 985.435811,11.5696006 Z M1009.12681,3.36520101 L1002.83041,3.36520101 L1002.83041,1.13920113 L1018.09441,1.13920113 L1018.09441,3.36520101 L1011.79801,3.36520101 L1011.79801,22 L1009.12681,22 L1009.12681,3.36520101 Z M1021.84681,1.13920113 L1024.48621,1.13920113 L1024.48621,22 L1021.84681,22 L1021.84681,1.13920113 Z M1037.90581,22.3816 C1036.5914,22.3816 1035.38831,22.1272025 1034.29651,21.6184 C1033.2047,21.1095975 1032.26661,20.3835048 1031.48221,19.4401001 C1030.6978,18.4966955 1030.08831,17.351907 1029.65371,16.0057003 C1029.21911,14.6594937 1029.00181,13.1490089 1029.00181,11.4742006 C1029.00181,9.79939228 1029.21911,8.29950736 1029.65371,6.97450081 C1030.08831,5.64949426 1030.6978,4.52590555 1031.48221,3.60370099 C1032.26661,2.68149643 1033.2047,1.97660352 1034.29651,1.48900111 C1035.38831,1.0013987 1036.5914,0.757601147 1037.90581,0.757601147 C1039.22021,0.757601147 1040.4233,1.00669864 1041.51511,1.50490111 C1042.60691,2.00310357 1043.5503,2.71329643 1044.34531,3.63550099 C1045.14031,4.55770555 1045.75511,5.68129426 1046.18971,7.00630081 C1046.62431,8.33130736 1046.84161,9.82059239 1046.84161,11.4742006 C1046.84161,13.1490089 1046.62431,14.6594937 1046.18971,16.0057003 C1045.75511,17.351907 1045.14031,18.4966955 1044.34531,19.4401001 C1043.5503,20.3835048 1042.60691,21.1095975 1041.51511,21.6184 C1040.4233,22.1272025 1039.22021,22.3816 1037.90581,22.3816 Z M1037.90581,20.0602001 C1038.83861,20.0602001 1039.6813,19.8588021 1040.43391,19.4560001 C1041.18651,19.0531981 1041.8331,18.475504 1042.37371,17.7229002 C1042.91431,16.9702965 1043.33301,16.0693056 1043.62981,15.0199004 C1043.92661,13.9704952 1044.07501,12.7886071 1044.07501,11.4742006 C1044.07501,10.1809942 1043.92661,9.01500589 1043.62981,7.97620076 C1043.33301,6.93739562 1042.91431,6.05760446 1042.37371,5.3368009 C1041.8331,4.61599733 1041.18651,4.05950293 1040.43391,3.66730099 C1039.6813,3.27509905 1038.83861,3.07900102 1037.90581,3.07900102 C1036.973,3.07900102 1036.13031,3.27509905 1035.37771,3.66730099 C1034.6251,4.05950293 1033.97851,4.61599733 1033.43791,5.3368009 C1032.89731,6.05760446 1032.47861,6.93739562 1032.18181,7.97620076 C1031.88501,9.01500589 1031.73661,10.1809942 1031.73661,11.4742006 C1031.73661,12.7886071 1031.88501,13.9704952 1032.18181,15.0199004 C1032.47861,16.0693056 1032.89731,16.9702965 1033.43791,17.7229002 C1033.97851,18.475504 1034.6251,19.0531981 1035.37771,19.4560001 C1036.13031,19.8588021 1036.973,20.0602001 1037.90581,20.0602001 Z M1051.32541,1.13920113 L1054.06021,1.13920113 L1061.59681,14.2408004 L1063.85461,18.5656002 L1063.98181,18.5656002 C1063.91821,17.5055949 1063.84931,16.408506 1063.77511,15.2743004 C1063.70091,14.1400948 1063.66381,13.021806 1063.66381,11.9194005 L1063.66381,1.13920113 L1066.17601,1.13920113 L1066.17601,22 L1063.44121,22 L1055.87281,8.86660071 L1053.61501,4.57360094 L1053.48781,4.57360094 C1053.57261,5.63360618 1053.65211,6.70949537 1053.72631,7.80130077 C1053.80051,8.89310617 1053.83761,9.99019514 1053.83761,11.0926006 L1053.83761,22 L1051.32541,22 L1051.32541,1.13920113 Z" id="PRODUCTION-Copy-2" fill="#E04733"></path> + <polygon id="Line-Copy-17" fill="#E0513E" points="282.270169 382 498.277674 382 498.277674 378 282.270169 378"></polygon> + <path d="M277.201592,391.484016 L283.029685,397.309042 L285.857368,394.47987 L280.029274,388.654844 L277.201592,391.484016 Z M286.198357,400.476046 L292.02645,406.301071 L294.854133,403.4719 L289.026039,397.646874 L286.198357,400.476046 Z M295.195122,409.468075 L301.023216,415.293101 L303.850898,412.463929 L298.022805,406.638904 L295.195122,409.468075 Z M304.191888,418.460105 L310.019981,424.285131 L312.847663,421.455959 L307.01957,415.630933 L304.191888,418.460105 Z M313.188653,427.452135 L319.016746,433.27716 L321.844429,430.447989 L316.016335,424.622963 L313.188653,427.452135 Z M322.185418,436.444164 L328.013511,442.26919 L330.841194,439.440018 L325.0131,433.614993 L322.185418,436.444164 Z M331.182183,445.436194 L337.010277,451.26122 L339.837959,448.432048 L334.009866,442.607022 L331.182183,445.436194 Z M340.178949,454.428224 L346.007042,460.253249 L348.834724,457.424078 L343.006631,451.599052 L340.178949,454.428224 Z M349.175714,463.420253 L355.003807,469.245279 L357.83149,466.416107 L352.003396,460.591082 L349.175714,463.420253 Z M358.172479,472.412283 L364.000572,478.237309 L366.828255,475.408137 L361.000162,469.583111 L358.172479,472.412283 Z M367.169244,481.404313 L372.997338,487.229338 L375.82502,484.400167 L369.996927,478.575141 L367.169244,481.404313 Z M376.16601,490.396342 L381.994103,496.221368 L384.821785,493.392196 L378.993692,487.567171 L376.16601,490.396342 Z" id="Line-Copy-18" fill="#E0513E"></path> + <path d="M516.770072,391.484016 L522.598165,397.309042 L525.425848,394.47987 L519.597754,388.654844 L516.770072,391.484016 Z M525.766837,400.476046 L531.594931,406.301071 L534.422613,403.4719 L528.59452,397.646874 L525.766837,400.476046 Z M534.763603,409.468075 L540.591696,415.293101 L543.419378,412.463929 L537.591285,406.638904 L534.763603,409.468075 Z M543.760368,418.460105 L549.588461,424.285131 L552.416144,421.455959 L546.58805,415.630933 L543.760368,418.460105 Z M552.757133,427.452135 L558.585226,433.27716 L561.412909,430.447989 L555.584816,424.622963 L552.757133,427.452135 Z M561.753898,436.444164 L567.581992,442.26919 L570.409674,439.440018 L564.581581,433.614993 L561.753898,436.444164 Z M570.750664,445.436194 L576.578757,451.26122 L579.406439,448.432048 L573.578346,442.607022 L570.750664,445.436194 Z M579.747429,454.428224 L585.575522,460.253249 L588.403205,457.424078 L582.575111,451.599052 L579.747429,454.428224 Z M588.744194,463.420253 L594.572288,469.245279 L597.39997,466.416107 L591.571877,460.591082 L588.744194,463.420253 Z M597.740959,472.412283 L603.569053,478.237309 L606.396735,475.408137 L600.568642,469.583111 L597.740959,472.412283 Z M606.737725,481.404313 L612.565818,487.229338 L615.3935,484.400167 L609.565407,478.575141 L606.737725,481.404313 Z M615.73449,490.396342 L621.562583,496.221368 L624.390266,493.392196 L618.562172,487.567171 L615.73449,490.396342 Z" id="Line-Copy-22" fill="#E0513E"></path> + <path d="M756.338552,391.484016 L762.166646,397.309042 L764.994328,394.47987 L759.166235,388.654844 L756.338552,391.484016 Z M765.335318,400.476046 L771.163411,406.301071 L773.991093,403.4719 L768.163,397.646874 L765.335318,400.476046 Z M774.332083,409.468075 L780.160176,415.293101 L782.987859,412.463929 L777.159765,406.638904 L774.332083,409.468075 Z M783.328848,418.460105 L789.156941,424.285131 L791.984624,421.455959 L786.156531,415.630933 L783.328848,418.460105 Z M792.325613,427.452135 L798.153707,433.27716 L800.981389,430.447989 L795.153296,424.622963 L792.325613,427.452135 Z M801.322379,436.444164 L807.150472,442.26919 L809.978154,439.440018 L804.150061,433.614993 L801.322379,436.444164 Z M810.319144,445.436194 L816.147237,451.26122 L818.97492,448.432048 L813.146826,442.607022 L810.319144,445.436194 Z M819.315909,454.428224 L825.144003,460.253249 L827.971685,457.424078 L822.143592,451.599052 L819.315909,454.428224 Z M828.312674,463.420253 L834.140768,469.245279 L836.96845,466.416107 L831.140357,460.591082 L828.312674,463.420253 Z M837.30944,472.412283 L843.137533,478.237309 L845.965216,475.408137 L840.137122,469.583111 L837.30944,472.412283 Z M846.306205,481.404313 L852.134298,487.229338 L854.961981,484.400167 L849.133887,478.575141 L846.306205,481.404313 Z M855.30297,490.396342 L861.131064,496.221368 L863.958746,493.392196 L858.130653,487.567171 L855.30297,490.396342 Z" id="Line-Copy-23" fill="#E0513E"></path> + <path d="M880.010512,252.341438 L885.838606,246.516413 L883.010923,243.687241 L877.18283,249.512267 L880.010512,252.341438 Z M889.007278,243.349409 L894.835371,237.524383 L892.007689,234.695211 L886.179595,240.520237 L889.007278,243.349409 Z M898.004043,234.357379 L903.832136,228.532353 L901.004454,225.703182 L895.176361,231.528207 L898.004043,234.357379 Z M907.000808,225.365349 L912.828902,219.540324 L910.001219,216.711152 L904.173126,222.536178 L907.000808,225.365349 Z M915.997573,216.37332 L921.825667,210.548294 L918.997984,207.719122 L913.169891,213.544148 L915.997573,216.37332 Z M924.994339,207.38129 L930.822432,201.556264 L927.99475,198.727093 L922.166656,204.552118 L924.994339,207.38129 Z M933.991104,198.38926 L939.819197,192.564235 L936.991515,189.735063 L931.163422,195.560089 L933.991104,198.38926 Z M942.987869,189.397231 L948.815963,183.572205 L945.98828,180.743033 L940.160187,186.568059 L942.987869,189.397231 Z M951.984635,180.405201 L957.812728,174.580175 L954.985045,171.751004 L949.156952,177.576029 L951.984635,180.405201 Z M960.9814,171.413171 L966.809493,165.588146 L963.981811,162.758974 L958.153717,168.584 L960.9814,171.413171 Z M969.978165,162.421142 L975.806258,156.596116 L972.978576,153.766944 L967.150483,159.59197 L969.978165,162.421142 Z M978.97493,153.429112 L984.803024,147.604086 L981.975341,144.774915 L976.147248,150.59994 L978.97493,153.429112 Z" id="Line-Copy-27" fill="#E0513E"></path> + <path d="M1114.27955,23.0223048 C1119.09619,23.0223048 1123,19.1205524 1123,14.3085502 C1123,9.49654797 1119.09619,5.59479554 1114.27955,5.59479554 C1109.46291,5.59479554 1105.5591,9.49654797 1105.5591,14.3085502 C1105.5591,19.1205524 1109.46291,23.0223048 1114.27955,23.0223048 Z M1114.27955,27.0223048 C1107.25424,27.0223048 1101.5591,21.330163 1101.5591,14.3085502 C1101.5591,7.28693738 1107.25424,1.59479554 1114.27955,1.59479554 C1121.30486,1.59479554 1127,7.28693738 1127,14.3085502 C1127,21.330163 1121.30486,27.0223048 1114.27955,27.0223048 Z" id="Oval-Copy-24" fill="#E04733"></path> + <polygon id="Line" fill="#E04733" points="758.424239 374.304508 864.800215 266.404117 861.951738 263.595883 755.575761 371.496274"></polygon> + <polygon id="Line-Copy" fill="#E04733" points="1000.57718 131.539201 1109.53226 24.6788494 1106.73141 21.8231038 997.776337 128.683455"></polygon> + <path d="M510.058161,389.60223 C514.874804,389.60223 518.778612,385.700478 518.778612,380.888476 C518.778612,376.076474 514.874804,372.174721 510.058161,372.174721 C505.241518,372.174721 501.337711,376.076474 501.337711,380.888476 C501.337711,385.700478 505.241518,389.60223 510.058161,389.60223 Z M510.058161,393.60223 C503.032851,393.60223 497.337711,387.910089 497.337711,380.888476 C497.337711,373.866863 503.032851,368.174721 510.058161,368.174721 C517.083472,368.174721 522.778612,373.866863 522.778612,380.888476 C522.778612,387.910089 517.083472,393.60223 510.058161,393.60223 Z" id="Oval-Copy-15" fill="#E04733"></path> + <polygon id="Line-Copy-19" fill="#E0513E" points="521.838649 382 737.846154 382 737.846154 378 521.838649 378"></polygon> + <path d="M749.626642,389.60223 C754.443285,389.60223 758.347092,385.700478 758.347092,380.888476 C758.347092,376.076474 754.443285,372.174721 749.626642,372.174721 C744.809999,372.174721 740.906191,376.076474 740.906191,380.888476 C740.906191,385.700478 744.809999,389.60223 749.626642,389.60223 Z M749.626642,393.60223 C742.601331,393.60223 736.906191,387.910089 736.906191,380.888476 C736.906191,373.866863 742.601331,368.174721 749.626642,368.174721 C756.651952,368.174721 762.347092,373.866863 762.347092,380.888476 C762.347092,387.910089 756.651952,393.60223 749.626642,393.60223 Z" id="Oval-Copy-16" fill="#E04733"></path> + <path d="M270.489681,389.60223 C275.306324,389.60223 279.210131,385.700478 279.210131,380.888476 C279.210131,376.076474 275.306324,372.174721 270.489681,372.174721 C265.673038,372.174721 261.769231,376.076474 261.769231,380.888476 C261.769231,385.700478 265.673038,389.60223 270.489681,389.60223 Z M270.489681,393.60223 C263.46437,393.60223 257.769231,387.910089 257.769231,380.888476 C257.769231,373.866863 263.46437,368.174721 270.489681,368.174721 C277.514992,368.174721 283.210131,373.866863 283.210131,380.888476 C283.210131,387.910089 277.514992,393.60223 270.489681,393.60223 Z" id="Oval-Copy-14" fill="#E04733"></path> + <path d="M630.902439,510.3829 C635.719082,510.3829 639.622889,506.481147 639.622889,501.669145 C639.622889,496.857143 635.719082,492.95539 630.902439,492.95539 C626.085796,492.95539 622.181989,496.857143 622.181989,501.669145 C622.181989,506.481147 626.085796,510.3829 630.902439,510.3829 Z M630.902439,514.3829 C623.877128,514.3829 618.181989,508.690758 618.181989,501.669145 C618.181989,494.647532 623.877128,488.95539 630.902439,488.95539 C637.92775,488.95539 643.622889,494.647532 643.622889,501.669145 C643.622889,508.690758 637.92775,514.3829 630.902439,514.3829 Z" id="Oval-Copy-19" fill="#E04733"></path> + <path d="M870.470919,510.3829 C875.287562,510.3829 879.19137,506.481147 879.19137,501.669145 C879.19137,496.857143 875.287562,492.95539 870.470919,492.95539 C865.654276,492.95539 861.750469,496.857143 861.750469,501.669145 C861.750469,506.481147 865.654276,510.3829 870.470919,510.3829 Z M870.470919,514.3829 C863.445609,514.3829 857.750469,508.690758 857.750469,501.669145 C857.750469,494.647532 863.445609,488.95539 870.470919,488.95539 C877.49623,488.95539 883.19137,494.647532 883.19137,501.669145 C883.19137,508.690758 877.49623,514.3829 870.470919,514.3829 Z" id="Oval-Copy-18" fill="#E04733"></path> + <path d="M391.333959,510.3829 C396.150602,510.3829 400.054409,506.481147 400.054409,501.669145 C400.054409,496.857143 396.150602,492.95539 391.333959,492.95539 C386.517316,492.95539 382.613508,496.857143 382.613508,501.669145 C382.613508,506.481147 386.517316,510.3829 391.333959,510.3829 Z M391.333959,514.3829 C384.308648,514.3829 378.613508,508.690758 378.613508,501.669145 C378.613508,494.647532 384.308648,488.95539 391.333959,488.95539 C398.359269,488.95539 404.054409,494.647532 404.054409,501.669145 C404.054409,508.690758 398.359269,514.3829 391.333959,514.3829 Z" id="Oval-Copy-17" fill="#E04733"></path> + <path d="M28.833894,372.064086 L22.5374943,372.064086 L22.5374943,369.838086 L37.8014935,369.838086 L37.8014935,372.064086 L31.5050938,372.064086 L31.5050938,390.698885 L28.833894,390.698885 L28.833894,372.064086 Z M49.2494929,391.080485 C47.9350864,391.080485 46.7319985,390.826087 45.6401931,390.317285 C44.5483877,389.808482 43.6102971,389.08239 42.8258932,388.138985 C42.0414893,387.19558 41.4319955,386.050792 40.9973933,384.704585 C40.5627912,383.358378 40.3454934,381.847894 40.3454934,380.173085 C40.3454934,378.498277 40.5627912,376.998392 40.9973933,375.673386 C41.4319955,374.348379 42.0414893,373.22479 42.8258932,372.302586 C43.6102971,371.380381 44.5483877,370.675488 45.6401931,370.187886 C46.7319985,369.700283 47.9350864,369.456486 49.2494929,369.456486 C50.5638994,369.456486 51.7669873,369.705583 52.8587927,370.203786 C53.9505981,370.701988 54.8939886,371.412181 55.6889925,372.334386 C56.4839965,373.25659 57.0987903,374.380179 57.5333924,375.705186 C57.9679946,377.030192 58.1852924,378.519477 58.1852924,380.173085 C58.1852924,381.847894 57.9679946,383.358378 57.5333924,384.704585 C57.0987903,386.050792 56.4839965,387.19558 55.6889925,388.138985 C54.8939886,389.08239 53.9505981,389.808482 52.8587927,390.317285 C51.7669873,390.826087 50.5638994,391.080485 49.2494929,391.080485 Z M49.2494929,388.759085 C50.1822975,388.759085 51.024989,388.557687 51.7775927,388.154885 C52.5301965,387.752083 53.17679,387.174389 53.7173926,386.421785 C54.2579953,385.669181 54.6766911,384.76819 54.9734926,383.718785 C55.270294,382.66938 55.4186925,381.487492 55.4186925,380.173085 C55.4186925,378.879879 55.270294,377.713891 54.9734926,376.675086 C54.6766911,375.63628 54.2579953,374.756489 53.7173926,374.035686 C53.17679,373.314882 52.5301965,372.758388 51.7775927,372.366186 C51.024989,371.973984 50.1822975,371.777886 49.2494929,371.777886 C48.3166883,371.777886 47.4739967,371.973984 46.721393,372.366186 C45.9687893,372.758388 45.3221958,373.314882 44.7815931,374.035686 C44.2409904,374.756489 43.8222947,375.63628 43.5254932,376.675086 C43.2286917,377.713891 43.0802932,378.879879 43.0802932,380.173085 C43.0802932,381.487492 43.2286917,382.66938 43.5254932,383.718785 C43.8222947,384.76819 44.2409904,385.669181 44.7815931,386.421785 C45.3221958,387.174389 45.9687893,387.752083 46.721393,388.154885 C47.4739967,388.557687 48.3166883,388.759085 49.2494929,388.759085 Z M62.6690922,369.838086 L69.0608918,369.838086 C70.2056975,369.838086 71.2550869,369.944085 72.2090916,370.156086 C73.1630964,370.368087 73.9739882,370.712583 74.6417915,371.189586 C75.3095948,371.666588 75.8289896,372.297282 76.1999914,373.081686 C76.5709933,373.86609 76.7564914,374.83068 76.7564914,375.975486 C76.7564914,377.077891 76.5709933,378.031881 76.1999914,378.837485 C75.8289896,379.643089 75.3042949,380.310883 74.6258915,380.840885 C73.9474882,381.370888 73.1365963,381.768384 72.1931916,382.033385 C71.249787,382.298387 70.2056975,382.430885 69.0608918,382.430885 L65.308492,382.430885 L65.308492,390.698885 L62.6690922,390.698885 L62.6690922,369.838086 Z M68.7428918,380.268485 C70.5661008,380.268485 71.9175873,379.923989 72.7973916,379.234985 C73.677196,378.545982 74.1170915,377.459493 74.1170915,375.975486 C74.1170915,374.470278 73.671896,373.426189 72.7814916,372.843186 C71.8910872,372.260183 70.5449007,371.968686 68.7428918,371.968686 L65.308492,371.968686 L65.308492,380.268485 L68.7428918,380.268485 Z M80.9858912,369.838086 L83.625291,369.838086 L83.625291,390.698885 L80.9858912,390.698885 L80.9858912,369.838086 Z M88.1408908,380.268485 C88.1408908,378.593677 88.3740884,377.088492 88.8404907,375.752886 C89.306893,374.417279 89.9534865,373.28309 90.7802906,372.350286 C91.6070947,371.417481 92.5875849,370.701988 93.7217905,370.203786 C94.8559961,369.705583 96.0908837,369.456486 97.4264903,369.456486 C98.6984966,369.456486 99.8114854,369.716183 100.76549,370.235586 C101.719495,370.754988 102.503887,371.353882 103.11869,372.032286 L101.62409,373.717686 C101.072887,373.124083 100.463393,372.652387 99.7955901,372.302586 C99.1277868,371.952784 98.3486947,371.777886 97.4582903,371.777886 C96.4618853,371.777886 95.5608944,371.973984 94.7552904,372.366186 C93.9496864,372.758388 93.2606934,373.320182 92.6882905,374.051586 C92.1158877,374.782989 91.6706922,375.66808 91.3526906,376.706886 C91.034689,377.745691 90.8756906,378.911679 90.8756906,380.204885 C90.8756906,381.519292 91.0293891,382.70118 91.3367906,383.750585 C91.6441921,384.79999 92.0734878,385.695681 92.6246905,386.437685 C93.1758933,387.179689 93.8489865,387.752083 94.6439904,388.154885 C95.4389944,388.557687 96.3346854,388.759085 97.3310903,388.759085 C98.3486953,388.759085 99.2337864,388.557687 99.9863901,388.154885 C100.738994,387.752083 101.454487,387.179689 102.13289,386.437685 L103.62749,388.059485 C102.800686,389.01349 101.867895,389.755482 100.82909,390.285485 C99.790285,390.815487 98.6030969,391.080485 97.2674903,391.080485 C95.9530838,391.080485 94.739396,390.836687 93.6263905,390.349085 C92.513385,389.861482 91.5487947,389.156589 90.7325906,388.234385 C89.9163866,387.31218 89.280393,386.177992 88.8245907,384.831785 C88.3687885,383.485578 88.1408908,381.964494 88.1408908,380.268485 Z M113.930689,369.838086 L120.131689,369.838086 C121.191694,369.838086 122.161585,369.933485 123.041389,370.124286 C123.921193,370.315087 124.673786,370.611884 125.299189,371.014686 C125.924592,371.417488 126.412187,371.942183 126.761989,372.588786 C127.11179,373.235389 127.286689,374.014481 127.286689,374.926086 C127.286689,375.964891 126.989892,376.902981 126.396289,377.740385 C125.802686,378.57779 124.891095,379.155484 123.661489,379.473485 L123.661489,379.600685 C125.187896,379.833887 126.375084,380.363881 127.223089,381.190685 C128.071093,382.017489 128.495089,383.151678 128.495089,384.593285 C128.495089,385.61089 128.304291,386.501281 127.922689,387.264485 C127.541087,388.027689 127.000492,388.663682 126.300889,389.172485 C125.601285,389.681287 124.763894,390.062884 123.788689,390.317285 C122.813484,390.571686 121.742895,390.698885 120.576889,390.698885 L113.930689,390.698885 L113.930689,369.838086 Z M119.654689,378.742085 C121.456698,378.742085 122.744585,378.434688 123.518389,377.819885 C124.292193,377.205082 124.679089,376.314691 124.679089,375.148686 C124.679089,374.00388 124.270993,373.182388 123.454789,372.684186 C122.638585,372.185983 121.414297,371.936886 119.781889,371.936886 L116.570089,371.936886 L116.570089,378.742085 L119.654689,378.742085 Z M120.195289,388.600085 C121.997298,388.600085 123.396484,388.266188 124.392889,387.598385 C125.389294,386.930582 125.887489,385.886492 125.887489,384.466085 C125.887489,383.172879 125.399894,382.224188 124.424689,381.619985 C123.449484,381.015782 122.039698,380.713685 120.195289,380.713685 L116.570089,380.713685 L116.570089,388.600085 L120.195289,388.600085 Z M135.268488,379.727885 L138.766488,379.727885 C140.398896,379.727885 141.649684,379.393989 142.518888,378.726185 C143.388092,378.058382 143.822688,377.046092 143.822688,375.689286 C143.822688,374.311279 143.388092,373.346688 142.518888,372.795486 C141.649684,372.244283 140.398896,371.968686 138.766488,371.968686 L135.268488,371.968686 L135.268488,379.727885 Z M144.077088,390.698885 L139.052688,381.890285 L135.268488,381.890285 L135.268488,390.698885 L132.629088,390.698885 L132.629088,369.838086 L139.148088,369.838086 C140.208093,369.838086 141.188583,369.938785 142.089588,370.140186 C142.990592,370.341587 143.764385,370.675484 144.410988,371.141886 C145.057591,371.608288 145.561086,372.212482 145.921488,372.954486 C146.281889,373.696489 146.462088,374.60808 146.462088,375.689286 C146.462088,377.321694 146.038092,378.625481 145.190088,379.600685 C144.342084,380.57589 143.207895,381.243683 141.787488,381.604085 L147.066288,390.698885 L144.077088,390.698885 Z M159.977087,382.208285 L158.991287,379.028285 C158.609685,377.86228 158.249289,376.701591 157.910087,375.546186 C157.570885,374.39078 157.231689,373.208892 156.892487,372.000486 L156.765287,372.000486 C156.447286,373.208892 156.118689,374.39078 155.779487,375.546186 C155.440285,376.701591 155.079889,377.86228 154.698287,379.028285 L153.712487,382.208285 L159.977087,382.208285 Z M160.644887,384.338885 L153.044687,384.338885 L151.041287,390.698885 L148.338288,390.698885 L155.397887,369.838086 L158.387087,369.838086 L165.446687,390.698885 L162.616487,390.698885 L160.644887,384.338885 Z M168.404086,369.838086 L171.138886,369.838086 L178.675486,382.939685 L180.933286,387.264485 L181.060486,387.264485 C180.996885,386.20448 180.927986,385.107391 180.853786,383.973185 C180.779585,382.83898 180.742486,381.720691 180.742486,380.618285 L180.742486,369.838086 L183.254686,369.838086 L183.254686,390.698885 L180.519886,390.698885 L172.951486,377.565485 L170.693686,373.272486 L170.566486,373.272486 C170.651287,374.332491 170.730786,375.40838 170.804986,376.500186 C170.879187,377.591991 170.916286,378.68908 170.916286,379.791485 L170.916286,390.698885 L168.404086,390.698885 L168.404086,369.838086 Z M187.770285,380.268485 C187.770285,378.593677 188.003483,377.088492 188.469885,375.752886 C188.936288,374.417279 189.582881,373.28309 190.409685,372.350286 C191.236489,371.417481 192.216979,370.701988 193.351185,370.203786 C194.485391,369.705583 195.720278,369.456486 197.055885,369.456486 C198.327891,369.456486 199.44088,369.716183 200.394885,370.235586 C201.348889,370.754988 202.133282,371.353882 202.748085,372.032286 L201.253485,373.717686 C200.702282,373.124083 200.092788,372.652387 199.424985,372.302586 C198.757181,371.952784 197.978089,371.777886 197.087685,371.777886 C196.09128,371.777886 195.190289,371.973984 194.384685,372.366186 C193.579081,372.758388 192.890088,373.320182 192.317685,374.051586 C191.745282,374.782989 191.300087,375.66808 190.982085,376.706886 C190.664084,377.745691 190.505085,378.911679 190.505085,380.204885 C190.505085,381.519292 190.658784,382.70118 190.966185,383.750585 C191.273587,384.79999 191.702882,385.695681 192.254085,386.437685 C192.805288,387.179689 193.478381,387.752083 194.273385,388.154885 C195.068389,388.557687 195.96408,388.759085 196.960485,388.759085 C197.97809,388.759085 198.863181,388.557687 199.615785,388.154885 C200.368388,387.752083 201.083881,387.179689 201.762285,386.437685 L203.256885,388.059485 C202.43008,389.01349 201.49729,389.755482 200.458485,390.285485 C199.41968,390.815487 198.232492,391.080485 196.896885,391.080485 C195.582478,391.080485 194.368791,390.836687 193.255785,390.349085 C192.14278,389.861482 191.178189,389.156589 190.361985,388.234385 C189.545781,387.31218 188.909788,386.177992 188.453985,384.831785 C187.998183,383.485578 187.770285,381.964494 187.770285,380.268485 Z M207.136484,369.838086 L209.775884,369.838086 L209.775884,378.583085 L219.474884,378.583085 L219.474884,369.838086 L222.146084,369.838086 L222.146084,390.698885 L219.474884,390.698885 L219.474884,380.872685 L209.775884,380.872685 L209.775884,390.698885 L207.136484,390.698885 L207.136484,369.838086 Z" id="TOPIC-BRANCH" fill="#E04733"></path> + <path d="M687.15753,304.150354 L690.273929,304.150354 L694.312529,315.343953 L695.838929,319.605153 L695.966129,319.605153 L697.428929,315.343953 L701.435729,304.150354 L704.552129,304.150354 L704.552129,325.011152 L702.039929,325.011152 L702.039929,313.531353 C702.039929,312.598548 702.077028,311.570359 702.151229,310.446753 C702.225429,309.323148 702.304928,308.294958 702.389729,307.362153 L702.262529,307.362153 L700.577129,312.004953 L696.570329,322.912353 L695.075729,322.912353 L691.037129,312.004953 L689.383529,307.362153 L689.256329,307.362153 C689.31993,308.294958 689.394129,309.323148 689.478929,310.446753 C689.56373,311.570359 689.606129,312.598548 689.606129,313.531353 L689.606129,325.011152 L687.15753,325.011152 L687.15753,304.150354 Z M710.276128,304.150354 L722.296528,304.150354 L722.296528,306.376353 L712.915528,306.376353 L712.915528,312.927153 L720.833728,312.927153 L720.833728,315.184953 L712.915528,315.184953 L712.915528,322.753353 L722.614528,322.753353 L722.614528,325.011152 L710.276128,325.011152 L710.276128,304.150354 Z M729.674127,314.040153 L733.172127,314.040153 C734.804535,314.040153 736.055323,313.706256 736.924527,313.038453 C737.793731,312.37065 738.228327,311.35836 738.228327,310.001553 C738.228327,308.623546 737.793731,307.658956 736.924527,307.107753 C736.055323,306.556551 734.804535,306.280953 733.172127,306.280953 L729.674127,306.280953 L729.674127,314.040153 Z M738.482727,325.011152 L733.458327,316.202553 L729.674127,316.202553 L729.674127,325.011152 L727.034727,325.011152 L727.034727,304.150354 L733.553727,304.150354 C734.613732,304.150354 735.594222,304.251053 736.495227,304.452454 C737.396231,304.653855 738.170024,304.987751 738.816627,305.454153 C739.46323,305.920556 739.966725,306.52475 740.327127,307.266753 C740.687528,308.008757 740.867727,308.920348 740.867727,310.001553 C740.867727,311.633961 740.443731,312.937748 739.595727,313.912953 C738.747723,314.888158 737.613534,315.555951 736.193127,315.916353 L741.471927,325.011152 L738.482727,325.011152 Z M744.302126,314.580753 C744.302126,312.905945 744.540624,311.40076 745.017626,310.065153 C745.494629,308.729547 746.162422,307.595358 747.021026,306.662553 C747.879631,305.729749 748.89192,305.014256 750.057926,304.516054 C751.223932,304.017851 752.506519,303.768754 753.905726,303.768754 C755.347333,303.768754 756.550421,304.039051 757.515026,304.579654 C758.479631,305.120256 759.269323,305.70855 759.884126,306.344553 L758.389526,308.029953 C757.859523,307.478751 757.250029,307.017655 756.561026,306.646653 C755.872022,306.275652 754.997531,306.090153 753.937526,306.090153 C752.877521,306.090153 751.92353,306.286251 751.075526,306.678453 C750.227522,307.070655 749.506729,307.63245 748.913126,308.363853 C748.319523,309.095257 747.858428,309.980348 747.529826,311.019153 C747.201225,312.057958 747.036926,313.223947 747.036926,314.517153 C747.036926,315.831559 747.190625,317.013448 747.498026,318.062853 C747.805428,319.112258 748.250623,320.007949 748.833626,320.749953 C749.416629,321.491956 750.137422,322.064351 750.996026,322.467153 C751.85463,322.869955 752.84572,323.071353 753.969326,323.071353 C754.71133,323.071353 755.416223,322.960054 756.084026,322.737453 C756.751829,322.514851 757.297724,322.212754 757.721726,321.831153 L757.721726,316.393353 L753.301526,316.393353 L753.301526,314.199153 L760.138526,314.199153 L760.138526,322.975953 C759.460122,323.675556 758.564431,324.25325 757.451426,324.709052 C756.33842,325.164855 755.082333,325.392752 753.683126,325.392752 C752.305119,325.392752 751.043732,325.148955 749.898926,324.661352 C748.754121,324.17375 747.76833,323.468857 746.941526,322.546653 C746.114722,321.624448 745.468129,320.490259 745.001726,319.144053 C744.535324,317.797846 744.302126,316.276761 744.302126,314.580753 Z M765.131125,304.150354 L777.151525,304.150354 L777.151525,306.376353 L767.770525,306.376353 L767.770525,312.927153 L775.688725,312.927153 L775.688725,315.184953 L767.770525,315.184953 L767.770525,322.753353 L777.469525,322.753353 L777.469525,325.011152 L765.131125,325.011152 L765.131125,304.150354 Z" id="MERGE" fill="#E04733"></path> + <path d="M189.429182,500.508554 L192.927182,500.508554 C194.55959,500.508554 195.810377,500.174658 196.679581,499.506855 C197.548786,498.839051 197.983381,497.826761 197.983381,496.469955 C197.983381,495.091948 197.548786,494.127358 196.679581,493.576155 C195.810377,493.024952 194.55959,492.749355 192.927182,492.749355 L189.429182,492.749355 L189.429182,500.508554 Z M198.237781,511.479554 L193.213382,502.670954 L189.429182,502.670954 L189.429182,511.479554 L186.789782,511.479554 L186.789782,490.618755 L193.308782,490.618755 C194.368787,490.618755 195.349277,490.719454 196.250281,490.920855 C197.151286,491.122256 197.925078,491.456153 198.571681,491.922555 C199.218284,492.388957 199.721779,492.993151 200.082181,493.735155 C200.442583,494.477159 200.622781,495.388749 200.622781,496.469955 C200.622781,498.102363 200.198785,499.40615 199.350781,500.381355 C198.502777,501.356559 197.368588,502.024353 195.948181,502.384754 L201.226981,511.479554 L198.237781,511.479554 Z M205.265581,490.618755 L217.28598,490.618755 L217.28598,492.844755 L207.904981,492.844755 L207.904981,499.395555 L215.82318,499.395555 L215.82318,501.653354 L207.904981,501.653354 L207.904981,509.221754 L217.60398,509.221754 L217.60398,511.479554 L205.265581,511.479554 L205.265581,490.618755 Z M219.16218,490.618755 L221.99238,490.618755 L225.33138,501.875954 C225.712982,503.126761 226.046878,504.282149 226.33308,505.342154 C226.619281,506.402159 226.963778,507.546948 227.36658,508.776554 L227.49378,508.776554 C227.875382,507.546948 228.214578,506.402159 228.51138,505.342154 C228.808181,504.282149 229.136778,503.126761 229.49718,501.875954 L232.836179,490.618755 L235.539179,490.618755 L228.92478,511.479554 L225.84018,511.479554 L219.16218,490.618755 Z M238.401179,490.618755 L241.040579,490.618755 L241.040579,511.479554 L238.401179,511.479554 L238.401179,490.618755 Z M246.764579,490.618755 L258.784978,490.618755 L258.784978,492.844755 L249.403978,492.844755 L249.403978,499.395555 L257.322178,499.395555 L257.322178,501.653354 L249.403978,501.653354 L249.403978,509.221754 L259.102978,509.221754 L259.102978,511.479554 L246.764579,511.479554 L246.764579,490.618755 Z M261.392578,490.618755 L264.127378,490.618755 L266.321578,501.971354 C266.512379,503.11616 266.713776,504.239749 266.925778,505.342154 C267.137779,506.44456 267.339177,507.568148 267.529977,508.712954 L267.657177,508.712954 C267.890379,507.568148 268.134176,506.43926 268.388577,505.326254 C268.642979,504.213249 268.886776,503.09496 269.119977,501.971354 L272.013777,490.618755 L274.430577,490.618755 L277.324377,501.971354 C277.578778,503.07376 277.833176,504.186749 278.087577,505.310354 C278.341978,506.43396 278.596376,507.568148 278.850777,508.712954 L278.977977,508.712954 C279.168778,507.568148 279.359576,506.43926 279.550377,505.326254 C279.741178,504.213249 279.942576,503.09496 280.154577,501.971354 L282.348777,490.618755 L284.892777,490.618755 L280.567977,511.479554 L277.387977,511.479554 L274.239777,498.918555 C274.048976,498.112951 273.874078,497.323259 273.715077,496.549455 C273.556076,495.775651 273.391778,494.985959 273.222177,494.180355 L273.094977,494.180355 C272.925376,494.985959 272.750478,495.775651 272.570277,496.549455 C272.390076,497.323259 272.215178,498.112951 272.045577,498.918555 L268.960977,511.479554 L265.812778,511.479554 L261.392578,490.618755 Z M303.813776,502.988954 L302.827976,499.808955 C302.446374,498.642949 302.085977,497.48226 301.746776,496.326855 C301.407574,495.171449 301.068377,493.989561 300.729176,492.781155 L300.601976,492.781155 C300.283974,493.989561 299.955377,495.171449 299.616176,496.326855 C299.276974,497.48226 298.916578,498.642949 298.534976,499.808955 L297.549176,502.988954 L303.813776,502.988954 Z M304.481576,505.119554 L296.881376,505.119554 L294.877976,511.479554 L292.174976,511.479554 L299.234576,490.618755 L302.223776,490.618755 L309.283375,511.479554 L306.453175,511.479554 L304.481576,505.119554 Z M312.240775,490.618755 L318.632575,490.618755 C319.77738,490.618755 320.82677,490.724754 321.780775,490.936755 C322.734779,491.148756 323.545671,491.493253 324.213474,491.970255 C324.881278,492.447257 325.400673,493.077951 325.771674,493.862355 C326.142676,494.646759 326.328174,495.611349 326.328174,496.756155 C326.328174,497.85856 326.142676,498.812551 325.771674,499.618155 C325.400673,500.423759 324.875978,501.091552 324.197574,501.621554 C323.519171,502.151557 322.708279,502.549053 321.764875,502.814054 C320.82147,503.079056 319.77738,503.211554 318.632575,503.211554 L314.880175,503.211554 L314.880175,511.479554 L312.240775,511.479554 L312.240775,490.618755 Z M318.314575,501.049154 C320.137784,501.049154 321.48927,500.704658 322.369075,500.015655 C323.248879,499.326651 323.688774,498.240162 323.688774,496.756155 C323.688774,495.250947 323.243579,494.206858 322.353175,493.623855 C321.46277,493.040852 320.116584,492.749355 318.314575,492.749355 L314.880175,492.749355 L314.880175,501.049154 L318.314575,501.049154 Z M330.557574,490.618755 L336.949374,490.618755 C338.094179,490.618755 339.143569,490.724754 340.097574,490.936755 C341.051578,491.148756 341.86247,491.493253 342.530273,491.970255 C343.198077,492.447257 343.717472,493.077951 344.088473,493.862355 C344.459475,494.646759 344.644973,495.611349 344.644973,496.756155 C344.644973,497.85856 344.459475,498.812551 344.088473,499.618155 C343.717472,500.423759 343.192777,501.091552 342.514373,501.621554 C341.83597,502.151557 341.025078,502.549053 340.081674,502.814054 C339.138269,503.079056 338.094179,503.211554 336.949374,503.211554 L333.196974,503.211554 L333.196974,511.479554 L330.557574,511.479554 L330.557574,490.618755 Z M336.631374,501.049154 C338.454583,501.049154 339.806069,500.704658 340.685874,500.015655 C341.565678,499.326651 342.005573,498.240162 342.005573,496.756155 C342.005573,495.250947 341.560378,494.206858 340.669974,493.623855 C339.779569,493.040852 338.433383,492.749355 336.631374,492.749355 L333.196974,492.749355 L333.196974,501.049154 L336.631374,501.049154 Z" id="REVIEW-APP" fill="#E04733"></path> + <path d="M281.839315,443.148434 C281.839315,441.89441 281.395681,440.823773 280.5084,439.936492 C279.621119,439.049211 278.550482,438.605577 277.296458,438.605577 C276.042434,438.605577 274.971797,439.049211 274.084516,439.936492 C273.197235,440.823773 272.753601,441.89441 272.753601,443.148434 C272.753601,444.402458 273.197235,445.473095 274.084516,446.360376 C274.971797,447.247657 276.042434,447.691291 277.296458,447.691291 C278.550482,447.691291 279.621119,447.247657 280.5084,446.360376 C281.395681,445.473095 281.839315,444.402458 281.839315,443.148434 Z M295.467886,452.234148 C295.467886,451.618966 295.243111,451.086605 294.793555,450.63705 C294.343999,450.187494 293.811639,449.962719 293.196457,449.962719 C292.581275,449.962719 292.048915,450.187494 291.599359,450.63705 C291.149803,451.086605 290.925029,451.618966 290.925029,452.234148 C290.925029,452.86116 291.146846,453.396478 291.590486,453.840119 C292.034127,454.283759 292.569445,454.505576 293.196457,454.505576 C293.823469,454.505576 294.358787,454.283759 294.802428,453.840119 C295.246069,453.396478 295.467886,452.86116 295.467886,452.234148 Z M295.467886,434.06272 C295.467886,433.447539 295.243111,432.915178 294.793555,432.465622 C294.343999,432.016066 293.811639,431.791292 293.196457,431.791292 C292.581275,431.791292 292.048915,432.016066 291.599359,432.465622 C291.149803,432.915178 290.925029,433.447539 290.925029,434.06272 C290.925029,434.689732 291.146846,435.22505 291.590486,435.668691 C292.034127,436.112332 292.569445,436.334149 293.196457,436.334149 C293.823469,436.334149 294.358787,436.112332 294.802428,435.668691 C295.246069,435.22505 295.467886,434.689732 295.467886,434.06272 Z M288.6536,441.53359 L288.6536,444.816514 C288.6536,444.934818 288.612194,445.050163 288.529381,445.162552 C288.446569,445.274941 288.351927,445.33705 288.245453,445.34888 L285.494895,445.774773 C285.36476,446.188838 285.175477,446.638387 284.927038,447.123434 C285.329272,447.691294 285.861633,448.371532 286.524136,449.16417 C286.606949,449.282474 286.648355,449.400777 286.648355,449.519081 C286.648355,449.661046 286.606949,449.773433 286.524136,449.856246 C286.252036,450.211159 285.764039,450.740562 285.060129,451.444471 C284.35622,452.148381 283.891883,452.500331 283.667105,452.500331 C283.53697,452.500331 283.412753,452.458925 283.294449,452.376112 L281.253712,450.779014 C280.815987,451.003792 280.360523,451.18716 279.887306,451.329125 C279.757171,452.60681 279.621124,453.523654 279.479159,454.079683 C279.396346,454.363613 279.218892,454.505576 278.946793,454.505576 L275.646123,454.505576 C275.515989,454.505576 275.397686,454.461213 275.291212,454.372485 C275.184739,454.283757 275.125588,454.180242 275.113757,454.061938 L274.70561,451.346871 C274.303376,451.228567 273.859742,451.045198 273.374695,450.796759 L271.280722,452.376112 C271.197909,452.458925 271.079606,452.500331 270.925811,452.500331 C270.795676,452.500331 270.671459,452.45301 270.553155,452.358367 C268.849575,450.784921 267.997798,449.838502 267.997798,449.519081 C267.997798,449.412607 268.039204,449.30022 268.122016,449.181916 C268.240321,449.01629 268.48284,448.702789 268.849583,448.241402 C269.216326,447.780016 269.494337,447.419194 269.683624,447.158925 C269.411524,446.638387 269.204495,446.153347 269.06253,445.703791 L266.365209,445.277898 C266.246904,445.266068 266.146347,445.209874 266.063534,445.109316 C265.980722,445.008757 265.939316,444.893412 265.939316,444.763278 L265.939316,441.480354 C265.939316,441.36205 265.980722,441.246705 266.063534,441.134316 C266.146347,441.021927 266.240989,440.959818 266.347463,440.947988 L269.098021,440.522095 C269.228155,440.10803 269.417439,439.658481 269.665878,439.173434 C269.263644,438.605574 268.731283,437.925336 268.06878,437.132698 C267.985967,437.002563 267.944561,436.884261 267.944561,436.777787 C267.944561,436.635822 267.985967,436.51752 268.06878,436.422876 C268.329049,436.067964 268.814089,435.541518 269.523914,434.843524 C270.233739,434.145529 270.701033,433.796537 270.925811,433.796537 C271.055946,433.796537 271.180163,433.837943 271.298467,433.920756 L273.339204,435.517854 C273.741438,435.304907 274.196902,435.115623 274.70561,434.949997 C274.835744,433.672312 274.971792,432.761384 275.113757,432.217185 C275.19657,431.933255 275.374024,431.791292 275.646123,431.791292 L278.946793,431.791292 C279.076927,431.791292 279.19523,431.835655 279.301703,431.924383 C279.408177,432.013111 279.467328,432.116626 279.479159,432.23493 L279.887306,434.949997 C280.28954,435.068301 280.733174,435.25167 281.218221,435.500108 L283.312194,433.920756 C283.406838,433.837943 283.52514,433.796537 283.667105,433.796537 C283.797239,433.796537 283.921457,433.843858 284.039761,433.938501 C285.743341,435.511947 286.595118,436.458366 286.595118,436.777787 C286.595118,436.884261 286.553712,436.996648 286.470899,437.114952 C286.328934,437.304239 286.080499,437.623655 285.725587,438.073211 C285.370674,438.522767 285.104494,438.877674 284.927038,439.137943 C285.199137,439.705803 285.400251,440.190843 285.530386,440.593077 L288.227707,441.001224 C288.346011,441.024885 288.446569,441.086994 288.529381,441.187552 C288.612194,441.288111 288.6536,441.403456 288.6536,441.53359 Z M300.010742,450.99196 L300.010742,453.476335 C300.010742,453.665622 299.12939,453.848991 297.366658,454.026447 C297.224693,454.345868 297.047239,454.653454 296.834292,454.949215 C297.437643,456.286052 297.739314,457.102338 297.739314,457.398098 C297.739314,457.44542 297.715653,457.486826 297.668332,457.522317 C296.225021,458.362277 295.491546,458.78225 295.467886,458.78225 C295.373242,458.78225 295.101147,458.504239 294.651591,457.94821 C294.202035,457.39218 293.894449,456.989952 293.728823,456.741514 C293.492215,456.765174 293.314761,456.777005 293.196457,456.777005 C293.078153,456.777005 292.900699,456.765174 292.664091,456.741514 C292.498465,456.989952 292.190879,457.39218 291.741323,457.94821 C291.291767,458.504239 291.019672,458.78225 290.925029,458.78225 C290.901368,458.78225 290.167893,458.362277 288.724582,457.522317 C288.677261,457.486826 288.6536,457.44542 288.6536,457.398098 C288.6536,457.102338 288.955271,456.286052 289.558622,454.949215 C289.345675,454.653454 289.168221,454.345868 289.026256,454.026447 C287.263524,453.848991 286.382172,453.665622 286.382172,453.476335 L286.382172,450.99196 C286.382172,450.802674 287.263524,450.619305 289.026256,450.441849 C289.180052,450.098767 289.357505,449.791181 289.558622,449.519081 C288.955271,448.182244 288.6536,447.365958 288.6536,447.070197 C288.6536,447.022875 288.677261,446.98147 288.724582,446.945978 C288.771904,446.922318 288.978933,446.804015 289.345676,446.591068 C289.712419,446.37812 290.061411,446.177006 290.392663,445.98772 C290.723914,445.798433 290.901368,445.703791 290.925029,445.703791 C291.019672,445.703791 291.291767,445.978844 291.741323,446.528958 C292.190879,447.079073 292.498465,447.478343 292.664091,447.726782 C292.900699,447.703121 293.078153,447.691291 293.196457,447.691291 C293.314761,447.691291 293.492215,447.703121 293.728823,447.726782 C294.332174,446.886822 294.876365,446.224329 295.361412,445.739282 L295.467886,445.703791 C295.515207,445.703791 296.248682,446.117849 297.668332,446.945978 C297.715653,446.98147 297.739314,447.022875 297.739314,447.070197 C297.739314,447.365958 297.437643,448.182244 296.834292,449.519081 C297.035409,449.791181 297.212862,450.098767 297.366658,450.441849 C299.12939,450.619305 300.010742,450.802674 300.010742,450.99196 Z M300.010742,432.820533 L300.010742,435.304908 C300.010742,435.494194 299.12939,435.677563 297.366658,435.855019 C297.224693,436.17444 297.047239,436.482027 296.834292,436.777787 C297.437643,438.114624 297.739314,438.93091 297.739314,439.226671 C297.739314,439.273992 297.715653,439.315398 297.668332,439.35089 C296.225021,440.190849 295.491546,440.610822 295.467886,440.610822 C295.373242,440.610822 295.101147,440.332812 294.651591,439.776782 C294.202035,439.220753 293.894449,438.818525 293.728823,438.570086 C293.492215,438.593747 293.314761,438.605577 293.196457,438.605577 C293.078153,438.605577 292.900699,438.593747 292.664091,438.570086 C292.498465,438.818525 292.190879,439.220753 291.741323,439.776782 C291.291767,440.332812 291.019672,440.610822 290.925029,440.610822 C290.901368,440.610822 290.167893,440.190849 288.724582,439.35089 C288.677261,439.315398 288.6536,439.273992 288.6536,439.226671 C288.6536,438.93091 288.955271,438.114624 289.558622,436.777787 C289.345675,436.482027 289.168221,436.17444 289.026256,435.855019 C287.263524,435.677563 286.382172,435.494194 286.382172,435.304908 L286.382172,432.820533 C286.382172,432.631246 287.263524,432.447877 289.026256,432.270421 C289.180052,431.927339 289.357505,431.619753 289.558622,431.347653 C288.955271,430.010816 288.6536,429.19453 288.6536,428.89877 C288.6536,428.851448 288.677261,428.810042 288.724582,428.774551 C288.771904,428.75089 288.978933,428.632588 289.345676,428.41964 C289.712419,428.206693 290.061411,428.005579 290.392663,427.816292 C290.723914,427.627005 290.901368,427.532363 290.925029,427.532363 C291.019672,427.532363 291.291767,427.807416 291.741323,428.357531 C292.190879,428.907645 292.498465,429.306916 292.664091,429.555354 C292.900699,429.531694 293.078153,429.519863 293.196457,429.519863 C293.314761,429.519863 293.492215,429.531694 293.728823,429.555354 C294.332174,428.715395 294.876365,428.052901 295.361412,427.567854 L295.467886,427.532363 C295.515207,427.532363 296.248682,427.946422 297.668332,428.774551 C297.715653,428.810042 297.739314,428.851448 297.739314,428.89877 C297.739314,429.19453 297.437643,430.010816 296.834292,431.347653 C297.035409,431.619753 297.212862,431.927339 297.366658,432.270421 C299.12939,432.447877 300.010742,432.631246 300.010742,432.820533 Z" id="" fill="#E04733"></path> + <path d="M518.847717,443.148434 C518.847717,441.89441 518.404083,440.823773 517.516802,439.936492 C516.629521,439.049211 515.558884,438.605577 514.30486,438.605577 C513.050836,438.605577 511.9802,439.049211 511.092919,439.936492 C510.205637,440.823773 509.762003,441.89441 509.762003,443.148434 C509.762003,444.402458 510.205637,445.473095 511.092919,446.360376 C511.9802,447.247657 513.050836,447.691291 514.30486,447.691291 C515.558884,447.691291 516.629521,447.247657 517.516802,446.360376 C518.404083,445.473095 518.847717,444.402458 518.847717,443.148434 Z M532.476288,452.234148 C532.476288,451.618966 532.251513,451.086605 531.801958,450.63705 C531.352402,450.187494 530.820041,449.962719 530.20486,449.962719 C529.589678,449.962719 529.057317,450.187494 528.607761,450.63705 C528.158206,451.086605 527.933431,451.618966 527.933431,452.234148 C527.933431,452.86116 528.155248,453.396478 528.598889,453.840119 C529.042529,454.283759 529.577847,454.505576 530.20486,454.505576 C530.831872,454.505576 531.36719,454.283759 531.81083,453.840119 C532.254471,453.396478 532.476288,452.86116 532.476288,452.234148 Z M532.476288,434.06272 C532.476288,433.447539 532.251513,432.915178 531.801958,432.465622 C531.352402,432.016066 530.820041,431.791292 530.20486,431.791292 C529.589678,431.791292 529.057317,432.016066 528.607761,432.465622 C528.158206,432.915178 527.933431,433.447539 527.933431,434.06272 C527.933431,434.689732 528.155248,435.22505 528.598889,435.668691 C529.042529,436.112332 529.577847,436.334149 530.20486,436.334149 C530.831872,436.334149 531.36719,436.112332 531.81083,435.668691 C532.254471,435.22505 532.476288,434.689732 532.476288,434.06272 Z M525.662003,441.53359 L525.662003,444.816514 C525.662003,444.934818 525.620597,445.050163 525.537784,445.162552 C525.454971,445.274941 525.360329,445.33705 525.253855,445.34888 L522.503297,445.774773 C522.373163,446.188838 522.183879,446.638387 521.93544,447.123434 C522.337674,447.691294 522.870035,448.371532 523.532538,449.16417 C523.615351,449.282474 523.656757,449.400777 523.656757,449.519081 C523.656757,449.661046 523.615351,449.773433 523.532538,449.856246 C523.260439,450.211159 522.772442,450.740562 522.068532,451.444471 C521.364622,452.148381 520.900285,452.500331 520.675507,452.500331 C520.545373,452.500331 520.421155,452.458925 520.302851,452.376112 L518.262115,450.779014 C517.824389,451.003792 517.368925,451.18716 516.895708,451.329125 C516.765574,452.60681 516.629526,453.523654 516.487561,454.079683 C516.404748,454.363613 516.227295,454.505576 515.955195,454.505576 L512.654526,454.505576 C512.524391,454.505576 512.406089,454.461213 512.299615,454.372485 C512.193141,454.283757 512.13399,454.180242 512.12216,454.061938 L511.714012,451.346871 C511.311778,451.228567 510.868144,451.045198 510.383097,450.796759 L508.289124,452.376112 C508.206311,452.458925 508.088009,452.500331 507.934213,452.500331 C507.804079,452.500331 507.679861,452.45301 507.561557,452.358367 C505.857977,450.784921 505.0062,449.838502 505.0062,449.519081 C505.0062,449.412607 505.047606,449.30022 505.130419,449.181916 C505.248723,449.01629 505.491243,448.702789 505.857986,448.241402 C506.224729,447.780016 506.502739,447.419194 506.692026,447.158925 C506.419926,446.638387 506.212897,446.153347 506.070932,445.703791 L503.373611,445.277898 C503.255307,445.266068 503.15475,445.209874 503.071937,445.109316 C502.989124,445.008757 502.947718,444.893412 502.947718,444.763278 L502.947718,441.480354 C502.947718,441.36205 502.989124,441.246705 503.071937,441.134316 C503.15475,441.021927 503.249392,440.959818 503.355865,440.947988 L506.106423,440.522095 C506.236558,440.10803 506.425842,439.658481 506.67428,439.173434 C506.272046,438.605574 505.739686,437.925336 505.077182,437.132698 C504.994369,437.002563 504.952964,436.884261 504.952964,436.777787 C504.952964,436.635822 504.994369,436.51752 505.077182,436.422876 C505.337451,436.067964 505.822491,435.541518 506.532316,434.843524 C507.242141,434.145529 507.709436,433.796537 507.934213,433.796537 C508.064348,433.796537 508.188565,433.837943 508.30687,433.920756 L510.347606,435.517854 C510.74984,435.304907 511.205304,435.115623 511.714012,434.949997 C511.844147,433.672312 511.980195,432.761384 512.12216,432.217185 C512.204973,431.933255 512.382426,431.791292 512.654526,431.791292 L515.955195,431.791292 C516.08533,431.791292 516.203632,431.835655 516.310106,431.924383 C516.41658,432.013111 516.475731,432.116626 516.487561,432.23493 L516.895708,434.949997 C517.297943,435.068301 517.741577,435.25167 518.226624,435.500108 L520.320597,433.920756 C520.41524,433.837943 520.533542,433.796537 520.675507,433.796537 C520.805642,433.796537 520.929859,433.843858 521.048164,433.938501 C522.751743,435.511947 523.603521,436.458366 523.603521,436.777787 C523.603521,436.884261 523.562115,436.996648 523.479302,437.114952 C523.337337,437.304239 523.088902,437.623655 522.733989,438.073211 C522.379077,438.522767 522.112897,438.877674 521.93544,439.137943 C522.20754,439.705803 522.408654,440.190843 522.538789,440.593077 L525.23611,441.001224 C525.354414,441.024885 525.454971,441.086994 525.537784,441.187552 C525.620597,441.288111 525.662003,441.403456 525.662003,441.53359 Z M537.019145,450.99196 L537.019145,453.476335 C537.019145,453.665622 536.137792,453.848991 534.37506,454.026447 C534.233095,454.345868 534.055642,454.653454 533.842694,454.949215 C534.446045,456.286052 534.747716,457.102338 534.747716,457.398098 C534.747716,457.44542 534.724056,457.486826 534.676734,457.522317 C533.233424,458.362277 532.499949,458.78225 532.476288,458.78225 C532.381645,458.78225 532.109549,458.504239 531.659993,457.94821 C531.210438,457.39218 530.902851,456.989952 530.737226,456.741514 C530.500617,456.765174 530.323164,456.777005 530.20486,456.777005 C530.086555,456.777005 529.909102,456.765174 529.672493,456.741514 C529.506868,456.989952 529.199281,457.39218 528.749726,457.94821 C528.30017,458.504239 528.028074,458.78225 527.933431,458.78225 C527.90977,458.78225 527.176295,458.362277 525.732985,457.522317 C525.685663,457.486826 525.662003,457.44542 525.662003,457.398098 C525.662003,457.102338 525.963674,456.286052 526.567025,454.949215 C526.354077,454.653454 526.176624,454.345868 526.034659,454.026447 C524.271927,453.848991 523.390574,453.665622 523.390574,453.476335 L523.390574,450.99196 C523.390574,450.802674 524.271927,450.619305 526.034659,450.441849 C526.188454,450.098767 526.365908,449.791181 526.567025,449.519081 C525.963674,448.182244 525.662003,447.365958 525.662003,447.070197 C525.662003,447.022875 525.685663,446.98147 525.732985,446.945978 C525.780306,446.922318 525.987336,446.804015 526.354078,446.591068 C526.720821,446.37812 527.069813,446.177006 527.401065,445.98772 C527.732317,445.798433 527.90977,445.703791 527.933431,445.703791 C528.028074,445.703791 528.30017,445.978844 528.749726,446.528958 C529.199281,447.079073 529.506868,447.478343 529.672493,447.726782 C529.909102,447.703121 530.086555,447.691291 530.20486,447.691291 C530.323164,447.691291 530.500617,447.703121 530.737226,447.726782 C531.340577,446.886822 531.884768,446.224329 532.369815,445.739282 L532.476288,445.703791 C532.52361,445.703791 533.257084,446.117849 534.676734,446.945978 C534.724056,446.98147 534.747716,447.022875 534.747716,447.070197 C534.747716,447.365958 534.446045,448.182244 533.842694,449.519081 C534.043811,449.791181 534.221265,450.098767 534.37506,450.441849 C536.137792,450.619305 537.019145,450.802674 537.019145,450.99196 Z M537.019145,432.820533 L537.019145,435.304908 C537.019145,435.494194 536.137792,435.677563 534.37506,435.855019 C534.233095,436.17444 534.055642,436.482027 533.842694,436.777787 C534.446045,438.114624 534.747716,438.93091 534.747716,439.226671 C534.747716,439.273992 534.724056,439.315398 534.676734,439.35089 C533.233424,440.190849 532.499949,440.610822 532.476288,440.610822 C532.381645,440.610822 532.109549,440.332812 531.659993,439.776782 C531.210438,439.220753 530.902851,438.818525 530.737226,438.570086 C530.500617,438.593747 530.323164,438.605577 530.20486,438.605577 C530.086555,438.605577 529.909102,438.593747 529.672493,438.570086 C529.506868,438.818525 529.199281,439.220753 528.749726,439.776782 C528.30017,440.332812 528.028074,440.610822 527.933431,440.610822 C527.90977,440.610822 527.176295,440.190849 525.732985,439.35089 C525.685663,439.315398 525.662003,439.273992 525.662003,439.226671 C525.662003,438.93091 525.963674,438.114624 526.567025,436.777787 C526.354077,436.482027 526.176624,436.17444 526.034659,435.855019 C524.271927,435.677563 523.390574,435.494194 523.390574,435.304908 L523.390574,432.820533 C523.390574,432.631246 524.271927,432.447877 526.034659,432.270421 C526.188454,431.927339 526.365908,431.619753 526.567025,431.347653 C525.963674,430.010816 525.662003,429.19453 525.662003,428.89877 C525.662003,428.851448 525.685663,428.810042 525.732985,428.774551 C525.780306,428.75089 525.987336,428.632588 526.354078,428.41964 C526.720821,428.206693 527.069813,428.005579 527.401065,427.816292 C527.732317,427.627005 527.90977,427.532363 527.933431,427.532363 C528.028074,427.532363 528.30017,427.807416 528.749726,428.357531 C529.199281,428.907645 529.506868,429.306916 529.672493,429.555354 C529.909102,429.531694 530.086555,429.519863 530.20486,429.519863 C530.323164,429.519863 530.500617,429.531694 530.737226,429.555354 C531.340577,428.715395 531.884768,428.052901 532.369815,427.567854 L532.476288,427.532363 C532.52361,427.532363 533.257084,427.946422 534.676734,428.774551 C534.724056,428.810042 534.747716,428.851448 534.747716,428.89877 C534.747716,429.19453 534.446045,430.010816 533.842694,431.347653 C534.043811,431.619753 534.221265,431.927339 534.37506,432.270421 C536.137792,432.447877 537.019145,432.631246 537.019145,432.820533 Z" id="-copy" fill="#E04733"></path> + <path d="M859.734507,544.858471 C857.81798,544.917623 856.250474,545.674758 855.031941,547.1299 L852.654039,547.1299 C851.683945,547.1299 850.867659,546.890337 850.205155,546.411205 C849.542652,545.932074 849.211405,545.231132 849.211405,544.30836 C849.211405,540.132223 849.94488,538.044186 851.411852,538.044186 C851.482834,538.044186 851.740142,538.168403 852.183782,538.416842 C852.627423,538.665281 853.204147,538.916673 853.913972,539.171027 C854.623797,539.425381 855.327696,539.552556 856.025691,539.552556 C856.818329,539.552556 857.605039,539.416509 858.385847,539.144409 C858.326695,539.582134 858.297119,539.972532 858.297119,540.315614 C858.297119,541.960042 858.776244,543.474313 859.734507,544.858471 Z M878.739975,556.162377 C878.739975,557.582027 878.308171,558.702942 877.444551,559.525156 C876.580931,560.34737 875.433398,560.75847 874.001917,560.75847 L858.49232,560.75847 C857.06084,560.75847 855.913307,560.34737 855.049686,559.525156 C854.186066,558.702942 853.754262,557.582027 853.754262,556.162377 C853.754262,555.535365 853.774965,554.92315 853.816372,554.325714 C853.857778,553.728278 853.94059,553.08353 854.064809,552.391451 C854.189028,551.699371 854.345779,551.057581 854.535066,550.46606 C854.724352,549.874539 854.978703,549.297815 855.298124,548.73587 C855.617545,548.173926 855.984282,547.694801 856.398347,547.298482 C856.812411,546.902163 857.318154,546.585704 857.91559,546.349096 C858.513026,546.112488 859.172562,545.994185 859.894217,545.994185 C860.012521,545.994185 860.266872,546.12136 860.657275,546.375714 C861.047679,546.630068 861.479483,546.913994 861.952699,547.2275 C862.425916,547.541006 863.058834,547.824932 863.851471,548.079286 C864.644109,548.33364 865.44265,548.460815 866.247119,548.460815 C867.051587,548.460815 867.850128,548.33364 868.642766,548.079286 C869.435404,547.824932 870.068321,547.541006 870.541538,547.2275 C871.014755,546.913994 871.446558,546.630068 871.836962,546.375714 C872.227366,546.12136 872.481716,545.994185 872.60002,545.994185 C873.321675,545.994185 873.981211,546.112488 874.578647,546.349096 C875.176083,546.585704 875.681826,546.902163 876.09589,547.298482 C876.509955,547.694801 876.876692,548.173926 877.196114,548.73587 C877.515535,549.297815 877.769885,549.874539 877.959172,550.46606 C878.148458,551.057581 878.305209,551.699371 878.429428,552.391451 C878.553648,553.08353 878.636459,553.728278 878.677866,554.325714 C878.719272,554.92315 878.739975,555.535365 878.739975,556.162377 Z M860.568548,533.501329 C860.568548,534.755353 860.124914,535.82599 859.237632,536.713271 C858.350351,537.600552 857.279715,538.044186 856.025691,538.044186 C854.771667,538.044186 853.70103,537.600552 852.813749,536.713271 C851.926468,535.82599 851.482834,534.755353 851.482834,533.501329 C851.482834,532.247305 851.926468,531.176668 852.813749,530.289387 C853.70103,529.402106 854.771667,528.958472 856.025691,528.958472 C857.279715,528.958472 858.350351,529.402106 859.237632,530.289387 C860.124914,531.176668 860.568548,532.247305 860.568548,533.501329 Z M873.061404,540.315614 C873.061404,542.19665 872.395953,543.802605 871.065031,545.133527 C869.73411,546.464449 868.128155,547.1299 866.247119,547.1299 C864.366083,547.1299 862.760128,546.464449 861.429206,545.133527 C860.098284,543.802605 859.432833,542.19665 859.432833,540.315614 C859.432833,538.434578 860.098284,536.828623 861.429206,535.497702 C862.760128,534.16678 864.366083,533.501329 866.247119,533.501329 C868.128155,533.501329 869.73411,534.16678 871.065031,535.497702 C872.395953,536.828623 873.061404,538.434578 873.061404,540.315614 Z M883.282832,544.30836 C883.282832,545.231132 882.951585,545.932074 882.289082,546.411205 C881.626579,546.890337 880.810292,547.1299 879.840198,547.1299 L877.462297,547.1299 C876.243764,545.674758 874.676257,544.917623 872.75973,544.858471 C873.717994,543.474313 874.197118,541.960042 874.197118,540.315614 C874.197118,539.972532 874.167543,539.582134 874.108391,539.144409 C874.889198,539.416509 875.675909,539.552556 876.468547,539.552556 C877.166541,539.552556 877.87044,539.425381 878.580265,539.171027 C879.29009,538.916673 879.866814,538.665281 880.310455,538.416842 C880.754096,538.168403 881.011403,538.044186 881.082386,538.044186 C882.549357,538.044186 883.282832,540.132223 883.282832,544.30836 Z M881.011404,533.501329 C881.011404,534.755353 880.56777,535.82599 879.680489,536.713271 C878.793207,537.600552 877.722571,538.044186 876.468547,538.044186 C875.214523,538.044186 874.143886,537.600552 873.256605,536.713271 C872.369324,535.82599 871.92569,534.755353 871.92569,533.501329 C871.92569,532.247305 872.369324,531.176668 873.256605,530.289387 C874.143886,529.402106 875.214523,528.958472 876.468547,528.958472 C877.722571,528.958472 878.793207,529.402106 879.680489,530.289387 C880.56777,531.176668 881.011404,532.247305 881.011404,533.501329 Z M920.88562,539.002445 C920.88562,539.475661 920.719997,539.877889 920.388745,540.209141 L905.127585,555.470301 C904.796334,555.801553 904.394106,555.967176 903.920889,555.967176 C903.447672,555.967176 903.045444,555.801553 902.714193,555.470301 L893.876916,546.633025 C893.545665,546.301773 893.380041,545.899545 893.380041,545.426328 C893.380041,544.953112 893.545665,544.550884 893.876916,544.219632 L896.290309,541.806239 C896.621561,541.474988 897.023789,541.309364 897.497005,541.309364 C897.970222,541.309364 898.37245,541.474988 898.703702,541.806239 L903.920889,547.041172 L915.56196,535.382356 C915.893211,535.051104 916.29544,534.885481 916.768656,534.885481 C917.241873,534.885481 917.644101,535.051104 917.975353,535.382356 L920.388745,537.795748 C920.719997,538.127 920.88562,538.529228 920.88562,539.002445 Z" id="--copy" fill="#E04733"></path> + <path d="M1045.7411,135.899363 C1043.82457,135.958515 1042.25707,136.715651 1041.03854,138.170792 L1038.66063,138.170792 C1037.69054,138.170792 1036.87425,137.931229 1036.21175,137.452098 C1035.54925,136.972966 1035.218,136.272024 1035.218,135.349252 C1035.218,131.173115 1035.95147,129.085078 1037.41845,129.085078 C1037.48943,129.085078 1037.74674,129.209295 1038.19038,129.457734 C1038.63402,129.706173 1039.21074,129.957566 1039.92057,130.211919 C1040.63039,130.466273 1041.33429,130.593448 1042.03229,130.593448 C1042.82492,130.593448 1043.61163,130.457401 1044.39244,130.185301 C1044.33329,130.623027 1044.30371,131.013424 1044.30371,131.356506 C1044.30371,133.000934 1044.78284,134.515205 1045.7411,135.899363 Z M1064.74657,147.203269 C1064.74657,148.622919 1064.31477,149.743834 1063.45115,150.566048 C1062.58753,151.388262 1061.43999,151.799362 1060.00851,151.799362 L1044.49891,151.799362 C1043.06743,151.799362 1041.9199,151.388262 1041.05628,150.566048 C1040.19266,149.743834 1039.76086,148.622919 1039.76086,147.203269 C1039.76086,146.576257 1039.78156,145.964042 1039.82297,145.366606 C1039.86437,144.76917 1039.94718,144.124422 1040.0714,143.432343 C1040.19562,142.740264 1040.35237,142.098473 1040.54166,141.506952 C1040.73095,140.915432 1040.9853,140.338707 1041.30472,139.776763 C1041.62414,139.214818 1041.99088,138.735693 1042.40494,138.339374 C1042.81901,137.943055 1043.32475,137.626597 1043.92218,137.389988 C1044.51962,137.15338 1045.17916,137.035078 1045.90081,137.035078 C1046.01912,137.035078 1046.27347,137.162253 1046.66387,137.416607 C1047.05427,137.67096 1047.48608,137.954886 1047.95929,138.268392 C1048.43251,138.581898 1049.06543,138.865824 1049.85807,139.120178 C1050.6507,139.374532 1051.44924,139.501707 1052.25371,139.501707 C1053.05818,139.501707 1053.85672,139.374532 1054.64936,139.120178 C1055.442,138.865824 1056.07492,138.581898 1056.54813,138.268392 C1057.02135,137.954886 1057.45315,137.67096 1057.84356,137.416607 C1058.23396,137.162253 1058.48831,137.035078 1058.60661,137.035078 C1059.32827,137.035078 1059.98781,137.15338 1060.58524,137.389988 C1061.18268,137.626597 1061.68842,137.943055 1062.10248,138.339374 C1062.51655,138.735693 1062.88329,139.214818 1063.20271,139.776763 C1063.52213,140.338707 1063.77648,140.915432 1063.96577,141.506952 C1064.15505,142.098473 1064.3118,142.740264 1064.43602,143.432343 C1064.56024,144.124422 1064.64305,144.76917 1064.68446,145.366606 C1064.72587,145.964042 1064.74657,146.576257 1064.74657,147.203269 Z M1046.57514,124.542221 C1046.57514,125.796245 1046.13151,126.866882 1045.24423,127.754163 C1044.35695,128.641444 1043.28631,129.085078 1042.03229,129.085078 C1040.77826,129.085078 1039.70762,128.641444 1038.82034,127.754163 C1037.93306,126.866882 1037.48943,125.796245 1037.48943,124.542221 C1037.48943,123.288197 1037.93306,122.21756 1038.82034,121.330279 C1039.70762,120.442998 1040.77826,119.999364 1042.03229,119.999364 C1043.28631,119.999364 1044.35695,120.442998 1045.24423,121.330279 C1046.13151,122.21756 1046.57514,123.288197 1046.57514,124.542221 Z M1059.068,131.356506 C1059.068,133.237543 1058.40255,134.843497 1057.07163,136.174419 C1055.7407,137.505341 1054.13475,138.170792 1052.25371,138.170792 C1050.37268,138.170792 1048.76672,137.505341 1047.4358,136.174419 C1046.10488,134.843497 1045.43943,133.237543 1045.43943,131.356506 C1045.43943,129.47547 1046.10488,127.869516 1047.4358,126.538594 C1048.76672,125.207672 1050.37268,124.542221 1052.25371,124.542221 C1054.13475,124.542221 1055.7407,125.207672 1057.07163,126.538594 C1058.40255,127.869516 1059.068,129.47547 1059.068,131.356506 Z M1069.28943,135.349252 C1069.28943,136.272024 1068.95818,136.972966 1068.29568,137.452098 C1067.63317,137.931229 1066.81689,138.170792 1065.84679,138.170792 L1063.46889,138.170792 C1062.25036,136.715651 1060.68285,135.958515 1058.76632,135.899363 C1059.72459,134.515205 1060.20371,133.000934 1060.20371,131.356506 C1060.20371,131.013424 1060.17414,130.623027 1060.11498,130.185301 C1060.89579,130.457401 1061.6825,130.593448 1062.47514,130.593448 C1063.17314,130.593448 1063.87703,130.466273 1064.58686,130.211919 C1065.29668,129.957566 1065.87341,129.706173 1066.31705,129.457734 C1066.76069,129.209295 1067.018,129.085078 1067.08898,129.085078 C1068.55595,129.085078 1069.28943,131.173115 1069.28943,135.349252 Z M1067.018,124.542221 C1067.018,125.796245 1066.57436,126.866882 1065.68708,127.754163 C1064.7998,128.641444 1063.72917,129.085078 1062.47514,129.085078 C1061.22112,129.085078 1060.15048,128.641444 1059.2632,127.754163 C1058.37592,126.866882 1057.93228,125.796245 1057.93228,124.542221 C1057.93228,123.288197 1058.37592,122.21756 1059.2632,121.330279 C1060.15048,120.442998 1061.22112,119.999364 1062.47514,119.999364 C1063.72917,119.999364 1064.7998,120.442998 1065.68708,121.330279 C1066.57436,122.21756 1067.018,123.288197 1067.018,124.542221 Z M1106.89221,130.043337 C1106.89221,130.516553 1106.72659,130.918782 1106.39534,131.250033 L1091.13418,146.511193 C1090.80293,146.842445 1090.4007,147.008068 1089.92748,147.008068 C1089.45427,147.008068 1089.05204,146.842445 1088.72079,146.511193 L1079.88351,137.673917 C1079.55226,137.342665 1079.38664,136.940437 1079.38664,136.46722 C1079.38664,135.994004 1079.55226,135.591776 1079.88351,135.260524 L1082.2969,132.847131 C1082.62816,132.51588 1083.03038,132.350256 1083.5036,132.350256 C1083.97682,132.350256 1084.37904,132.51588 1084.7103,132.847131 L1089.92748,138.082064 L1101.56855,126.423248 C1101.89981,126.091996 1102.30203,125.926373 1102.77525,125.926373 C1103.24847,125.926373 1103.6507,126.091996 1103.98195,126.423248 L1106.39534,128.83664 C1106.72659,129.167892 1106.89221,129.57012 1106.89221,130.043337 Z" id="--copy-2" fill="#E04733"></path> + <path d="M385.53174,544.858471 C383.615212,544.917623 382.047706,545.674758 380.829173,547.1299 L378.451271,547.1299 C377.481177,547.1299 376.664891,546.890337 376.002387,546.411205 C375.339884,545.932074 375.008638,545.231132 375.008638,544.30836 C375.008638,540.132223 375.742112,538.044186 377.209084,538.044186 C377.280066,538.044186 377.537374,538.168403 377.981015,538.416842 C378.424655,538.665281 379.001379,538.916673 379.711204,539.171027 C380.421029,539.425381 381.124928,539.552556 381.822923,539.552556 C382.615561,539.552556 383.402272,539.416509 384.183079,539.144409 C384.123927,539.582134 384.094351,539.972532 384.094351,540.315614 C384.094351,541.960042 384.573476,543.474313 385.53174,544.858471 Z M404.537207,556.162377 C404.537207,557.582027 404.105404,558.702942 403.241783,559.525156 C402.378163,560.34737 401.23063,560.75847 399.79915,560.75847 L384.289552,560.75847 C382.858072,560.75847 381.710539,560.34737 380.846918,559.525156 C379.983298,558.702942 379.551494,557.582027 379.551494,556.162377 C379.551494,555.535365 379.572197,554.92315 379.613604,554.325714 C379.65501,553.728278 379.737822,553.08353 379.862041,552.391451 C379.986261,551.699371 380.143011,551.057581 380.332298,550.46606 C380.521585,549.874539 380.775935,549.297815 381.095356,548.73587 C381.414777,548.173926 381.781515,547.694801 382.195579,547.298482 C382.609644,546.902163 383.115386,546.585704 383.712822,546.349096 C384.310258,546.112488 384.969794,545.994185 385.691449,545.994185 C385.809754,545.994185 386.064104,546.12136 386.454507,546.375714 C386.844911,546.630068 387.276715,546.913994 387.749932,547.2275 C388.223148,547.541006 388.856066,547.824932 389.648704,548.079286 C390.441342,548.33364 391.239883,548.460815 392.044351,548.460815 C392.848819,548.460815 393.64736,548.33364 394.439998,548.079286 C395.232636,547.824932 395.865554,547.541006 396.33877,547.2275 C396.811987,546.913994 397.243791,546.630068 397.634194,546.375714 C398.024598,546.12136 398.278948,545.994185 398.397252,545.994185 C399.118908,545.994185 399.778443,546.112488 400.375879,546.349096 C400.973315,546.585704 401.479058,546.902163 401.893123,547.298482 C402.307187,547.694801 402.673925,548.173926 402.993346,548.73587 C403.312767,549.297815 403.567117,549.874539 403.756404,550.46606 C403.945691,551.057581 404.102441,551.699371 404.226661,552.391451 C404.35088,553.08353 404.433692,553.728278 404.475098,554.325714 C404.516504,554.92315 404.537207,555.535365 404.537207,556.162377 Z M386.36578,533.501329 C386.36578,534.755353 385.922146,535.82599 385.034865,536.713271 C384.147584,537.600552 383.076947,538.044186 381.822923,538.044186 C380.568899,538.044186 379.498262,537.600552 378.610981,536.713271 C377.7237,535.82599 377.280066,534.755353 377.280066,533.501329 C377.280066,532.247305 377.7237,531.176668 378.610981,530.289387 C379.498262,529.402106 380.568899,528.958472 381.822923,528.958472 C383.076947,528.958472 384.147584,529.402106 385.034865,530.289387 C385.922146,531.176668 386.36578,532.247305 386.36578,533.501329 Z M398.858636,540.315614 C398.858636,542.19665 398.193185,543.802605 396.862264,545.133527 C395.531342,546.464449 393.925387,547.1299 392.044351,547.1299 C390.163315,547.1299 388.55736,546.464449 387.226438,545.133527 C385.895516,543.802605 385.230066,542.19665 385.230066,540.315614 C385.230066,538.434578 385.895516,536.828623 387.226438,535.497702 C388.55736,534.16678 390.163315,533.501329 392.044351,533.501329 C393.925387,533.501329 395.531342,534.16678 396.862264,535.497702 C398.193185,536.828623 398.858636,538.434578 398.858636,540.315614 Z M409.080064,544.30836 C409.080064,545.231132 408.748818,545.932074 408.086314,546.411205 C407.423811,546.890337 406.607525,547.1299 405.637431,547.1299 L403.259529,547.1299 C402.040996,545.674758 400.47349,544.917623 398.556962,544.858471 C399.515226,543.474313 399.99435,541.960042 399.99435,540.315614 C399.99435,539.972532 399.964775,539.582134 399.905623,539.144409 C400.68643,539.416509 401.473141,539.552556 402.265779,539.552556 C402.963773,539.552556 403.667673,539.425381 404.377498,539.171027 C405.087323,538.916673 405.664047,538.665281 406.107687,538.416842 C406.551328,538.168403 406.808635,538.044186 406.879618,538.044186 C408.34659,538.044186 409.080064,540.132223 409.080064,544.30836 Z M406.808636,533.501329 C406.808636,534.755353 406.365002,535.82599 405.477721,536.713271 C404.59044,537.600552 403.519803,538.044186 402.265779,538.044186 C401.011755,538.044186 399.941118,537.600552 399.053837,536.713271 C398.166556,535.82599 397.722922,534.755353 397.722922,533.501329 C397.722922,532.247305 398.166556,531.176668 399.053837,530.289387 C399.941118,529.402106 401.011755,528.958472 402.265779,528.958472 C403.519803,528.958472 404.59044,529.402106 405.477721,530.289387 C406.365002,531.176668 406.808636,532.247305 406.808636,533.501329 Z M440.063768,552.418069 C440.063768,552.891286 439.898145,553.293514 439.566893,553.624765 L437.1535,556.038158 C436.822249,556.36941 436.420021,556.535033 435.946804,556.535033 C435.473587,556.535033 435.071359,556.36941 434.740108,556.038158 L429.52292,550.820971 L424.305733,556.038158 C423.974481,556.36941 423.572253,556.535033 423.099037,556.535033 C422.62582,556.535033 422.223592,556.36941 421.89234,556.038158 L419.478948,553.624765 C419.147696,553.293514 418.982073,552.891286 418.982073,552.418069 C418.982073,551.944852 419.147696,551.542624 419.478948,551.211373 L424.696135,545.994185 L419.478948,540.776998 C419.147696,540.445747 418.982073,540.043518 418.982073,539.570302 C418.982073,539.097085 419.147696,538.694857 419.478948,538.363605 L421.89234,535.950213 C422.223592,535.618961 422.62582,535.453338 423.099037,535.453338 C423.572253,535.453338 423.974481,535.618961 424.305733,535.950213 L429.52292,541.1674 L434.740108,535.950213 C435.071359,535.618961 435.473587,535.453338 435.946804,535.453338 C436.420021,535.453338 436.822249,535.618961 437.1535,535.950213 L439.566893,538.363605 C439.898145,538.694857 440.063768,539.097085 440.063768,539.570302 C440.063768,540.043518 439.898145,540.445747 439.566893,540.776998 L434.349706,545.994185 L439.566893,551.211373 C439.898145,551.542624 440.063768,551.944852 440.063768,552.418069 Z" id="-" fill="#E04733"></path> + <path d="M622.540142,544.858471 C620.623615,544.917623 619.056108,545.674758 617.837575,547.1299 L615.459674,547.1299 C614.48958,547.1299 613.673293,546.890337 613.01079,546.411205 C612.348287,545.932074 612.01704,545.231132 612.01704,544.30836 C612.01704,540.132223 612.750515,538.044186 614.217486,538.044186 C614.288469,538.044186 614.545777,538.168403 614.989417,538.416842 C615.433058,538.665281 616.009782,538.916673 616.719607,539.171027 C617.429432,539.425381 618.133331,539.552556 618.831325,539.552556 C619.623963,539.552556 620.410674,539.416509 621.191481,539.144409 C621.132329,539.582134 621.102754,539.972532 621.102754,540.315614 C621.102754,541.960042 621.581878,543.474313 622.540142,544.858471 Z M641.54561,556.162377 C641.54561,557.582027 641.113806,558.702942 640.250186,559.525156 C639.386565,560.34737 638.239032,560.75847 636.807552,560.75847 L621.297955,560.75847 C619.866474,560.75847 618.718941,560.34737 617.855321,559.525156 C616.991701,558.702942 616.559897,557.582027 616.559897,556.162377 C616.559897,555.535365 616.5806,554.92315 616.622006,554.325714 C616.663413,553.728278 616.746224,553.08353 616.870444,552.391451 C616.994663,551.699371 617.151414,551.057581 617.3407,550.46606 C617.529987,549.874539 617.784337,549.297815 618.103758,548.73587 C618.42318,548.173926 618.789917,547.694801 619.203982,547.298482 C619.618046,546.902163 620.123789,546.585704 620.721225,546.349096 C621.318661,546.112488 621.978197,545.994185 622.699852,545.994185 C622.818156,545.994185 623.072506,546.12136 623.46291,546.375714 C623.853314,546.630068 624.285117,546.913994 624.758334,547.2275 C625.231551,547.541006 625.864468,547.824932 626.657106,548.079286 C627.449744,548.33364 628.248285,548.460815 629.052753,548.460815 C629.857222,548.460815 630.655763,548.33364 631.448401,548.079286 C632.241038,547.824932 632.873956,547.541006 633.347173,547.2275 C633.820389,546.913994 634.252193,546.630068 634.642597,546.375714 C635.033001,546.12136 635.287351,545.994185 635.405655,545.994185 C636.12731,545.994185 636.786846,546.112488 637.384282,546.349096 C637.981718,546.585704 638.487461,546.902163 638.901525,547.298482 C639.31559,547.694801 639.682327,548.173926 640.001748,548.73587 C640.32117,549.297815 640.57552,549.874539 640.764806,550.46606 C640.954093,551.057581 641.110844,551.699371 641.235063,552.391451 C641.359282,553.08353 641.442094,553.728278 641.4835,554.325714 C641.524907,554.92315 641.54561,555.535365 641.54561,556.162377 Z M623.374182,533.501329 C623.374182,534.755353 622.930548,535.82599 622.043267,536.713271 C621.155986,537.600552 620.085349,538.044186 618.831325,538.044186 C617.577301,538.044186 616.506665,537.600552 615.619384,536.713271 C614.732102,535.82599 614.288468,534.755353 614.288468,533.501329 C614.288468,532.247305 614.732102,531.176668 615.619384,530.289387 C616.506665,529.402106 617.577301,528.958472 618.831325,528.958472 C620.085349,528.958472 621.155986,529.402106 622.043267,530.289387 C622.930548,531.176668 623.374182,532.247305 623.374182,533.501329 Z M635.867039,540.315614 C635.867039,542.19665 635.201588,543.802605 633.870666,545.133527 C632.539744,546.464449 630.933789,547.1299 629.052753,547.1299 C627.171717,547.1299 625.565762,546.464449 624.234841,545.133527 C622.903919,543.802605 622.238468,542.19665 622.238468,540.315614 C622.238468,538.434578 622.903919,536.828623 624.234841,535.497702 C625.565762,534.16678 627.171717,533.501329 629.052753,533.501329 C630.933789,533.501329 632.539744,534.16678 633.870666,535.497702 C635.201588,536.828623 635.867039,538.434578 635.867039,540.315614 Z M646.088467,544.30836 C646.088467,545.231132 645.75722,545.932074 645.094717,546.411205 C644.432214,546.890337 643.615927,547.1299 642.645833,547.1299 L640.267931,547.1299 C639.049399,545.674758 637.481892,544.917623 635.565365,544.858471 C636.523628,543.474313 637.002753,541.960042 637.002753,540.315614 C637.002753,539.972532 636.973177,539.582134 636.914025,539.144409 C637.694833,539.416509 638.481544,539.552556 639.274181,539.552556 C639.972176,539.552556 640.676075,539.425381 641.3859,539.171027 C642.095725,538.916673 642.672449,538.665281 643.11609,538.416842 C643.55973,538.168403 643.817038,538.044186 643.88802,538.044186 C645.354992,538.044186 646.088467,540.132223 646.088467,544.30836 Z M643.817038,533.501329 C643.817038,534.755353 643.373404,535.82599 642.486123,536.713271 C641.598842,537.600552 640.528205,538.044186 639.274181,538.044186 C638.020157,538.044186 636.949521,537.600552 636.06224,536.713271 C635.174958,535.82599 634.731325,534.755353 634.731325,533.501329 C634.731325,532.247305 635.174958,531.176668 636.06224,530.289387 C636.949521,529.402106 638.020157,528.958472 639.274181,528.958472 C640.528205,528.958472 641.598842,529.402106 642.486123,530.289387 C643.373404,531.176668 643.817038,532.247305 643.817038,533.501329 Z M677.07217,552.418069 C677.07217,552.891286 676.906547,553.293514 676.575295,553.624765 L674.161903,556.038158 C673.830651,556.36941 673.428423,556.535033 672.955206,556.535033 C672.48199,556.535033 672.079762,556.36941 671.74851,556.038158 L666.531323,550.820971 L661.314136,556.038158 C660.982884,556.36941 660.580656,556.535033 660.107439,556.535033 C659.634223,556.535033 659.231994,556.36941 658.900743,556.038158 L656.48735,553.624765 C656.156098,553.293514 655.990475,552.891286 655.990475,552.418069 C655.990475,551.944852 656.156098,551.542624 656.48735,551.211373 L661.704537,545.994185 L656.48735,540.776998 C656.156098,540.445747 655.990475,540.043518 655.990475,539.570302 C655.990475,539.097085 656.156098,538.694857 656.48735,538.363605 L658.900743,535.950213 C659.231994,535.618961 659.634223,535.453338 660.107439,535.453338 C660.580656,535.453338 660.982884,535.618961 661.314136,535.950213 L666.531323,541.1674 L671.74851,535.950213 C672.079762,535.618961 672.48199,535.453338 672.955206,535.453338 C673.428423,535.453338 673.830651,535.618961 674.161903,535.950213 L676.575295,538.363605 C676.906547,538.694857 677.07217,539.097085 677.07217,539.570302 C677.07217,540.043518 676.906547,540.445747 676.575295,540.776998 L671.358108,545.994185 L676.575295,551.211373 C676.906547,551.542624 677.07217,551.944852 677.07217,552.418069 Z" id="--copy" fill="#E04733"></path> + <path d="M756.856155,443.148434 C756.856155,441.89441 756.412521,440.823773 755.52524,439.936492 C754.637959,439.049211 753.567322,438.605577 752.313298,438.605577 C751.059274,438.605577 749.988638,439.049211 749.101357,439.936492 C748.214075,440.823773 747.770441,441.89441 747.770441,443.148434 C747.770441,444.402458 748.214075,445.473095 749.101357,446.360376 C749.988638,447.247657 751.059274,447.691291 752.313298,447.691291 C753.567322,447.691291 754.637959,447.247657 755.52524,446.360376 C756.412521,445.473095 756.856155,444.402458 756.856155,443.148434 Z M770.484726,452.234148 C770.484726,451.618966 770.259951,451.086605 769.810396,450.63705 C769.36084,450.187494 768.828479,449.962719 768.213297,449.962719 C767.598116,449.962719 767.065755,450.187494 766.616199,450.63705 C766.166644,451.086605 765.941869,451.618966 765.941869,452.234148 C765.941869,452.86116 766.163686,453.396478 766.607327,453.840119 C767.050967,454.283759 767.586285,454.505576 768.213297,454.505576 C768.840309,454.505576 769.375628,454.283759 769.819268,453.840119 C770.262909,453.396478 770.484726,452.86116 770.484726,452.234148 Z M770.484726,434.06272 C770.484726,433.447539 770.259951,432.915178 769.810396,432.465622 C769.36084,432.016066 768.828479,431.791292 768.213297,431.791292 C767.598116,431.791292 767.065755,432.016066 766.616199,432.465622 C766.166644,432.915178 765.941869,433.447539 765.941869,434.06272 C765.941869,434.689732 766.163686,435.22505 766.607327,435.668691 C767.050967,436.112332 767.586285,436.334149 768.213297,436.334149 C768.840309,436.334149 769.375628,436.112332 769.819268,435.668691 C770.262909,435.22505 770.484726,434.689732 770.484726,434.06272 Z M763.670441,441.53359 L763.670441,444.816514 C763.670441,444.934818 763.629035,445.050163 763.546222,445.162552 C763.463409,445.274941 763.368767,445.33705 763.262293,445.34888 L760.511735,445.774773 C760.381601,446.188838 760.192317,446.638387 759.943878,447.123434 C760.346112,447.691294 760.878473,448.371532 761.540976,449.16417 C761.623789,449.282474 761.665195,449.400777 761.665195,449.519081 C761.665195,449.661046 761.623789,449.773433 761.540976,449.856246 C761.268877,450.211159 760.780879,450.740562 760.07697,451.444471 C759.37306,452.148381 758.908723,452.500331 758.683945,452.500331 C758.553811,452.500331 758.429593,452.458925 758.311289,452.376112 L756.270553,450.779014 C755.832827,451.003792 755.377363,451.18716 754.904146,451.329125 C754.774012,452.60681 754.637964,453.523654 754.495999,454.079683 C754.413186,454.363613 754.235733,454.505576 753.963633,454.505576 L750.662964,454.505576 C750.532829,454.505576 750.414527,454.461213 750.308053,454.372485 C750.201579,454.283757 750.142428,454.180242 750.130598,454.061938 L749.72245,451.346871 C749.320216,451.228567 748.876582,451.045198 748.391535,450.796759 L746.297562,452.376112 C746.214749,452.458925 746.096447,452.500331 745.942651,452.500331 C745.812517,452.500331 745.688299,452.45301 745.569995,452.358367 C743.866415,450.784921 743.014638,449.838502 743.014638,449.519081 C743.014638,449.412607 743.056044,449.30022 743.138857,449.181916 C743.257161,449.01629 743.499681,448.702789 743.866424,448.241402 C744.233167,447.780016 744.511177,447.419194 744.700464,447.158925 C744.428364,446.638387 744.221335,446.153347 744.07937,445.703791 L741.382049,445.277898 C741.263745,445.266068 741.163188,445.209874 741.080375,445.109316 C740.997562,445.008757 740.956156,444.893412 740.956156,444.763278 L740.956156,441.480354 C740.956156,441.36205 740.997562,441.246705 741.080375,441.134316 C741.163188,441.021927 741.25783,440.959818 741.364303,440.947988 L744.114861,440.522095 C744.244996,440.10803 744.43428,439.658481 744.682718,439.173434 C744.280484,438.605574 743.748124,437.925336 743.08562,437.132698 C743.002807,437.002563 742.961401,436.884261 742.961401,436.777787 C742.961401,436.635822 743.002807,436.51752 743.08562,436.422876 C743.345889,436.067964 743.830929,435.541518 744.540754,434.843524 C745.250579,434.145529 745.717873,433.796537 745.942651,433.796537 C746.072786,433.796537 746.197003,433.837943 746.315308,433.920756 L748.356044,435.517854 C748.758278,435.304907 749.213742,435.115623 749.72245,434.949997 C749.852585,433.672312 749.988633,432.761384 750.130598,432.217185 C750.21341,431.933255 750.390864,431.791292 750.662964,431.791292 L753.963633,431.791292 C754.093768,431.791292 754.21207,431.835655 754.318544,431.924383 C754.425017,432.013111 754.484169,432.116626 754.495999,432.23493 L754.904146,434.949997 C755.306381,435.068301 755.750014,435.25167 756.235061,435.500108 L758.329035,433.920756 C758.423678,433.837943 758.54198,433.796537 758.683945,433.796537 C758.81408,433.796537 758.938297,433.843858 759.056602,433.938501 C760.760181,435.511947 761.611959,436.458366 761.611959,436.777787 C761.611959,436.884261 761.570553,436.996648 761.48774,437.114952 C761.345775,437.304239 761.09734,437.623655 760.742427,438.073211 C760.387515,438.522767 760.121334,438.877674 759.943878,439.137943 C760.215978,439.705803 760.417092,440.190843 760.547226,440.593077 L763.244548,441.001224 C763.362852,441.024885 763.463409,441.086994 763.546222,441.187552 C763.629035,441.288111 763.670441,441.403456 763.670441,441.53359 Z M775.027583,450.99196 L775.027583,453.476335 C775.027583,453.665622 774.14623,453.848991 772.383498,454.026447 C772.241533,454.345868 772.06408,454.653454 771.851132,454.949215 C772.454483,456.286052 772.756154,457.102338 772.756154,457.398098 C772.756154,457.44542 772.732494,457.486826 772.685172,457.522317 C771.241861,458.362277 770.508387,458.78225 770.484726,458.78225 C770.390083,458.78225 770.117987,458.504239 769.668431,457.94821 C769.218876,457.39218 768.911289,456.989952 768.745663,456.741514 C768.509055,456.765174 768.331602,456.777005 768.213297,456.777005 C768.094993,456.777005 767.91754,456.765174 767.680931,456.741514 C767.515306,456.989952 767.207719,457.39218 766.758164,457.94821 C766.308608,458.504239 766.036512,458.78225 765.941869,458.78225 C765.918208,458.78225 765.184733,458.362277 763.741423,457.522317 C763.694101,457.486826 763.670441,457.44542 763.670441,457.398098 C763.670441,457.102338 763.972112,456.286052 764.575463,454.949215 C764.362515,454.653454 764.185062,454.345868 764.043097,454.026447 C762.280365,453.848991 761.399012,453.665622 761.399012,453.476335 L761.399012,450.99196 C761.399012,450.802674 762.280365,450.619305 764.043097,450.441849 C764.196892,450.098767 764.374346,449.791181 764.575463,449.519081 C763.972112,448.182244 763.670441,447.365958 763.670441,447.070197 C763.670441,447.022875 763.694101,446.98147 763.741423,446.945978 C763.788744,446.922318 763.995774,446.804015 764.362516,446.591068 C764.729259,446.37812 765.078251,446.177006 765.409503,445.98772 C765.740755,445.798433 765.918208,445.703791 765.941869,445.703791 C766.036512,445.703791 766.308608,445.978844 766.758164,446.528958 C767.207719,447.079073 767.515306,447.478343 767.680931,447.726782 C767.91754,447.703121 768.094993,447.691291 768.213297,447.691291 C768.331602,447.691291 768.509055,447.703121 768.745663,447.726782 C769.349015,446.886822 769.893206,446.224329 770.378253,445.739282 L770.484726,445.703791 C770.532048,445.703791 771.265522,446.117849 772.685172,446.945978 C772.732494,446.98147 772.756154,447.022875 772.756154,447.070197 C772.756154,447.365958 772.454483,448.182244 771.851132,449.519081 C772.052249,449.791181 772.229703,450.098767 772.383498,450.441849 C774.14623,450.619305 775.027583,450.802674 775.027583,450.99196 Z M775.027583,432.820533 L775.027583,435.304908 C775.027583,435.494194 774.14623,435.677563 772.383498,435.855019 C772.241533,436.17444 772.06408,436.482027 771.851132,436.777787 C772.454483,438.114624 772.756154,438.93091 772.756154,439.226671 C772.756154,439.273992 772.732494,439.315398 772.685172,439.35089 C771.241861,440.190849 770.508387,440.610822 770.484726,440.610822 C770.390083,440.610822 770.117987,440.332812 769.668431,439.776782 C769.218876,439.220753 768.911289,438.818525 768.745663,438.570086 C768.509055,438.593747 768.331602,438.605577 768.213297,438.605577 C768.094993,438.605577 767.91754,438.593747 767.680931,438.570086 C767.515306,438.818525 767.207719,439.220753 766.758164,439.776782 C766.308608,440.332812 766.036512,440.610822 765.941869,440.610822 C765.918208,440.610822 765.184733,440.190849 763.741423,439.35089 C763.694101,439.315398 763.670441,439.273992 763.670441,439.226671 C763.670441,438.93091 763.972112,438.114624 764.575463,436.777787 C764.362515,436.482027 764.185062,436.17444 764.043097,435.855019 C762.280365,435.677563 761.399012,435.494194 761.399012,435.304908 L761.399012,432.820533 C761.399012,432.631246 762.280365,432.447877 764.043097,432.270421 C764.196892,431.927339 764.374346,431.619753 764.575463,431.347653 C763.972112,430.010816 763.670441,429.19453 763.670441,428.89877 C763.670441,428.851448 763.694101,428.810042 763.741423,428.774551 C763.788744,428.75089 763.995774,428.632588 764.362516,428.41964 C764.729259,428.206693 765.078251,428.005579 765.409503,427.816292 C765.740755,427.627005 765.918208,427.532363 765.941869,427.532363 C766.036512,427.532363 766.308608,427.807416 766.758164,428.357531 C767.207719,428.907645 767.515306,429.306916 767.680931,429.555354 C767.91754,429.531694 768.094993,429.519863 768.213297,429.519863 C768.331602,429.519863 768.509055,429.531694 768.745663,429.555354 C769.349015,428.715395 769.893206,428.052901 770.378253,427.567854 L770.484726,427.532363 C770.532048,427.532363 771.265522,427.946422 772.685172,428.774551 C772.732494,428.810042 772.756154,428.851448 772.756154,428.89877 C772.756154,429.19453 772.454483,430.010816 771.851132,431.347653 C772.052249,431.619753 772.229703,431.927339 772.383498,432.270421 C774.14623,432.447877 775.027583,432.631246 775.027583,432.820533 Z" id="-copy-2" fill="#E04733"></path> + <path d="M885.860729,188.873341 C885.860729,187.619317 885.417095,186.54868 884.529814,185.661399 C883.642532,184.774118 882.571896,184.330484 881.317872,184.330484 C880.063848,184.330484 878.993211,184.774118 878.10593,185.661399 C877.218649,186.54868 876.775015,187.619317 876.775015,188.873341 C876.775015,190.127365 877.218649,191.198002 878.10593,192.085283 C878.993211,192.972564 880.063848,193.416198 881.317872,193.416198 C882.571896,193.416198 883.642532,192.972564 884.529814,192.085283 C885.417095,191.198002 885.860729,190.127365 885.860729,188.873341 Z M899.489299,197.959055 C899.489299,197.343873 899.264525,196.811512 898.814969,196.361957 C898.365413,195.912401 897.833053,195.687626 897.217871,195.687626 C896.602689,195.687626 896.070329,195.912401 895.620773,196.361957 C895.171217,196.811512 894.946442,197.343873 894.946442,197.959055 C894.946442,198.586067 895.168259,199.121385 895.6119,199.565026 C896.055541,200.008666 896.590859,200.230483 897.217871,200.230483 C897.844883,200.230483 898.380201,200.008666 898.823842,199.565026 C899.267482,199.121385 899.489299,198.586067 899.489299,197.959055 Z M899.489299,179.787627 C899.489299,179.172446 899.264525,178.640085 898.814969,178.190529 C898.365413,177.740973 897.833053,177.516199 897.217871,177.516199 C896.602689,177.516199 896.070329,177.740973 895.620773,178.190529 C895.171217,178.640085 894.946442,179.172446 894.946442,179.787627 C894.946442,180.414639 895.168259,180.949958 895.6119,181.393598 C896.055541,181.837239 896.590859,182.059056 897.217871,182.059056 C897.844883,182.059056 898.380201,181.837239 898.823842,181.393598 C899.267482,180.949958 899.489299,180.414639 899.489299,179.787627 Z M892.675014,187.258497 L892.675014,190.541421 C892.675014,190.659725 892.633608,190.77507 892.550795,190.887459 C892.467982,190.999848 892.37334,191.061957 892.266867,191.073787 L889.516309,191.49968 C889.386174,191.913745 889.19689,192.363294 888.948452,192.848341 C889.350686,193.416201 889.883047,194.096439 890.54555,194.889077 C890.628363,195.007381 890.669769,195.125684 890.669769,195.243988 C890.669769,195.385953 890.628363,195.49834 890.54555,195.581153 C890.27345,195.936066 889.785453,196.465469 889.081543,197.169379 C888.377634,197.873288 887.913297,198.225238 887.688519,198.225238 C887.558384,198.225238 887.434167,198.183832 887.315863,198.101019 L885.275126,196.503921 C884.837401,196.728699 884.381937,196.912068 883.90872,197.054033 C883.778585,198.331717 883.642538,199.248561 883.500573,199.80459 C883.41776,200.08852 883.240306,200.230483 882.968207,200.230483 L879.667537,200.230483 C879.537403,200.230483 879.4191,200.18612 879.312626,200.097392 C879.206153,200.008664 879.147001,199.905149 879.135171,199.786845 L878.727024,197.071778 C878.32479,196.953474 877.881156,196.770105 877.396109,196.521667 L875.302136,198.101019 C875.219323,198.183832 875.10102,198.225238 874.947225,198.225238 C874.81709,198.225238 874.692873,198.177917 874.574569,198.083274 C872.870989,196.509828 872.019212,195.563409 872.019212,195.243988 C872.019212,195.137514 872.060617,195.025127 872.14343,194.906823 C872.261734,194.741197 872.504254,194.427696 872.870997,193.96631 C873.23774,193.504923 873.515751,193.144101 873.705037,192.883832 C873.432938,192.363294 873.225909,191.878254 873.083944,191.428698 L870.386622,191.002805 C870.268318,190.990975 870.167761,190.934781 870.084948,190.834223 C870.002135,190.733664 869.96073,190.618319 869.96073,190.488185 L869.96073,187.205261 C869.96073,187.086957 870.002135,186.971612 870.084948,186.859223 C870.167761,186.746834 870.262403,186.684725 870.368877,186.672895 L873.119435,186.247002 C873.249569,185.832937 873.438853,185.383388 873.687292,184.898341 C873.285058,184.330481 872.752697,183.650243 872.090194,182.857605 C872.007381,182.72747 871.965975,182.609168 871.965975,182.502694 C871.965975,182.360729 872.007381,182.242427 872.090194,182.147783 C872.350463,181.792871 872.835503,181.266425 873.545328,180.568431 C874.255153,179.870436 874.722447,179.521444 874.947225,179.521444 C875.077359,179.521444 875.201577,179.56285 875.319881,179.645663 L877.360618,181.242761 C877.762852,181.029814 878.218316,180.84053 878.727024,180.674904 C878.857158,179.397219 878.993206,178.486291 879.135171,177.942092 C879.217984,177.658162 879.395438,177.516199 879.667537,177.516199 L882.968207,177.516199 C883.098341,177.516199 883.216643,177.560562 883.323117,177.64929 C883.429591,177.738018 883.488742,177.841533 883.500573,177.959837 L883.90872,180.674904 C884.310954,180.793208 884.754588,180.976577 885.239635,181.225016 L887.333608,179.645663 C887.428251,179.56285 887.546554,179.521444 887.688519,179.521444 C887.818653,179.521444 887.942871,179.568765 888.061175,179.663408 C889.764755,181.236854 890.616532,182.183273 890.616532,182.502694 C890.616532,182.609168 890.575126,182.721555 890.492313,182.839859 C890.350348,183.029146 890.101913,183.348562 889.747001,183.798118 C889.392088,184.247674 889.125908,184.602581 888.948452,184.86285 C889.220551,185.43071 889.421665,185.91575 889.5518,186.317984 L892.249121,186.726131 C892.367425,186.749792 892.467982,186.811901 892.550795,186.912459 C892.633608,187.013018 892.675014,187.128363 892.675014,187.258497 Z M904.032156,196.716867 L904.032156,199.201242 C904.032156,199.390529 903.150804,199.573898 901.388072,199.751354 C901.246107,200.070775 901.068653,200.378361 900.855706,200.674122 C901.459057,202.010959 901.760728,202.827245 901.760728,203.123005 C901.760728,203.170327 901.737067,203.211733 901.689746,203.247224 C900.246435,204.087184 899.51296,204.507157 899.489299,204.507157 C899.394656,204.507157 899.122561,204.229147 898.673005,203.673117 C898.223449,203.117087 897.915863,202.714859 897.750237,202.466421 C897.513629,202.490081 897.336175,202.501912 897.217871,202.501912 C897.099567,202.501912 896.922113,202.490081 896.685505,202.466421 C896.519879,202.714859 896.212293,203.117087 895.762737,203.673117 C895.313181,204.229147 895.041086,204.507157 894.946442,204.507157 C894.922782,204.507157 894.189307,204.087184 892.745996,203.247224 C892.698675,203.211733 892.675014,203.170327 892.675014,203.123005 C892.675014,202.827245 892.976685,202.010959 893.580036,200.674122 C893.367089,200.378361 893.189635,200.070775 893.04767,199.751354 C891.284938,199.573898 890.403586,199.390529 890.403586,199.201242 L890.403586,196.716867 C890.403586,196.527581 891.284938,196.344212 893.04767,196.166756 C893.201466,195.823674 893.378919,195.516088 893.580036,195.243988 C892.976685,193.907151 892.675014,193.090865 892.675014,192.795104 C892.675014,192.747783 892.698675,192.706377 892.745996,192.670885 C892.793318,192.647225 893.000347,192.528922 893.36709,192.315975 C893.733833,192.103027 894.082825,191.901913 894.414076,191.712627 C894.745328,191.52334 894.922782,191.428698 894.946442,191.428698 C895.041086,191.428698 895.313181,191.703751 895.762737,192.253865 C896.212293,192.80398 896.519879,193.20325 896.685505,193.451689 C896.922113,193.428028 897.099567,193.416198 897.217871,193.416198 C897.336175,193.416198 897.513629,193.428028 897.750237,193.451689 C898.353588,192.611729 898.897779,191.949236 899.382826,191.464189 L899.489299,191.428698 C899.536621,191.428698 900.270096,191.842756 901.689746,192.670885 C901.737067,192.706377 901.760728,192.747783 901.760728,192.795104 C901.760728,193.090865 901.459057,193.907151 900.855706,195.243988 C901.056823,195.516088 901.234276,195.823674 901.388072,196.166756 C903.150804,196.344212 904.032156,196.527581 904.032156,196.716867 Z M904.032156,178.54544 L904.032156,181.029815 C904.032156,181.219101 903.150804,181.40247 901.388072,181.579926 C901.246107,181.899347 901.068653,182.206934 900.855706,182.502694 C901.459057,183.839531 901.760728,184.655817 901.760728,184.951578 C901.760728,184.9989 901.737067,185.040305 901.689746,185.075797 C900.246435,185.915756 899.51296,186.33573 899.489299,186.33573 C899.394656,186.33573 899.122561,186.057719 898.673005,185.501689 C898.223449,184.94566 897.915863,184.543432 897.750237,184.294993 C897.513629,184.318654 897.336175,184.330484 897.217871,184.330484 C897.099567,184.330484 896.922113,184.318654 896.685505,184.294993 C896.519879,184.543432 896.212293,184.94566 895.762737,185.501689 C895.313181,186.057719 895.041086,186.33573 894.946442,186.33573 C894.922782,186.33573 894.189307,185.915756 892.745996,185.075797 C892.698675,185.040305 892.675014,184.9989 892.675014,184.951578 C892.675014,184.655817 892.976685,183.839531 893.580036,182.502694 C893.367089,182.206934 893.189635,181.899347 893.04767,181.579926 C891.284938,181.40247 890.403586,181.219101 890.403586,181.029815 L890.403586,178.54544 C890.403586,178.356153 891.284938,178.172784 893.04767,177.995328 C893.201466,177.652246 893.378919,177.34466 893.580036,177.07256 C892.976685,175.735723 892.675014,174.919437 892.675014,174.623677 C892.675014,174.576355 892.698675,174.534949 892.745996,174.499458 C892.793318,174.475797 893.000347,174.357495 893.36709,174.144547 C893.733833,173.9316 894.082825,173.730486 894.414076,173.541199 C894.745328,173.351912 894.922782,173.25727 894.946442,173.25727 C895.041086,173.25727 895.313181,173.532323 895.762737,174.082438 C896.212293,174.632552 896.519879,175.031823 896.685505,175.280261 C896.922113,175.256601 897.099567,175.24477 897.217871,175.24477 C897.336175,175.24477 897.513629,175.256601 897.750237,175.280261 C898.353588,174.440302 898.897779,173.777809 899.382826,173.292762 L899.489299,173.25727 C899.536621,173.25727 900.270096,173.671329 901.689746,174.499458 C901.737067,174.534949 901.760728,174.576355 901.760728,174.623677 C901.760728,174.919437 901.459057,175.735723 900.855706,177.07256 C901.056823,177.34466 901.234276,177.652246 901.388072,177.995328 C903.150804,178.172784 904.032156,178.356153 904.032156,178.54544 Z" id="-copy-3" fill="#E04733"></path> + </g> + </g> + </g> +</svg>
\ No newline at end of file diff --git a/doc/ci/review_apps/img/review_apps_preview_in_mr.png b/doc/ci/review_apps/img/review_apps_preview_in_mr.png Binary files differindex 7d0923f198f..3e6506a6a3a 100644 --- a/doc/ci/review_apps/img/review_apps_preview_in_mr.png +++ b/doc/ci/review_apps/img/review_apps_preview_in_mr.png diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 28c484ddbe6..64be011008e 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -1,96 +1,94 @@ -# Getting started with Review Apps +# Review Apps -> -- [Introduced][ce-21971] in GitLab 8.12. Further additions were made in GitLab - 8.13 and 8.14. -- Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by - [Fourchette]. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/21971) in GitLab 8.12. Further additions were made in GitLab 8.13 and 8.14. +> - Inspired by [Heroku's Review Apps](https://devcenter.heroku.com/articles/github-integration-review-apps), which itself was inspired by [Fourchette](https://github.com/rainforestapp/fourchette). -The basis of Review Apps is the [dynamic environments] which allow you to create -a new environment (dynamically) for each one of your branches. +For a video introduction to Review Apps, see [8.14 Webcast: Review Apps & Time Tracking Beta (EE) - GitLab Release](https://www.youtube.com/watch?v=CteZol_7pxo). -A Review App can then be visible as a link when you visit the [merge request] -relevant to the branch. That way, you are able to see live all changes introduced -by the merge request changes. Reviewing anything, from performance to interface -changes, becomes much easier with a live environment and as such, Review Apps -can make a huge impact on your development flow. +## Overview -They mostly make sense to be used with web applications, but you can use them -any way you'd like. +Review Apps are a collaboration tool that takes the hard work out of providing an environment to showcase product changes. -## Overview +Review Apps: + +- Provide an automatic live preview of changes made in a feature branch by spinning up a dynamic environment for your merge requests. +- Allow designers and product manages to see your changes without needing to check out your branch and run your changes in a sandbox environment. +- Are fully integrated with the [GitLab DevOps LifeCycle](../../README.md#complete-devops-with-gitlab). +- Allow you to deploy your changes wherever you want. + + + +Reviewing anything, from performance to interface changes, becomes much easier with a live environment and so Review Apps can make a large impact on your development flow. -Simply put, a Review App is a mapping of a branch with an environment as there -is a 1:1 relation between them. +## What are Review Apps? -Here's an example of what it looks like when viewing a merge request with a -dynamically set environment. +A Review App is a mapping of a branch with an [environment](../environments.md). The following is an example of a merge request with an environment set dynamically.  -In the image above you can see that the `add-new-line` branch was successfully -built and deployed under a dynamic environment and can be previewed with an -also dynamically URL. +In this example, you can see a branch was: + +- Successfully built. +- Deployed under a dynamic environment that can be reached by clicking on the **View app** button. + +## How do Review Apps work? + +The basis of Review Apps in GitLab is [dynamic environments](../environments.md#dynamic-environments), which allow you to dynamically create a new environment for each branch. + +Access to the Review App is made available as a link on the [merge request](../../user/project/merge_requests.md) relevant to the branch. Review Apps enable you to review all changes proposed by the merge request in live environment. -The details of the Review Apps implementation depend widely on your real -technology stack and on your deployment process. The simplest case is to -deploy a simple static HTML website, but it will not be that straightforward -when your app is using a database for example. To make a branch be deployed -on a temporary instance and booting up this instance with all required software -and services automatically on the fly is not a trivial task. However, it is -doable, especially if you use Docker, or at least a configuration management -tool like Chef, Puppet, Ansible or Salt. +## Use cases -## Prerequisites +Some supported use cases include the: -To get a better understanding of Review Apps, you must first learn how -environments and deployments work. The following docs will help you grasp that -knowledge: +- Simple case of deploying a simple static HTML website. +- More complicated case of an application that uses a database. Deploying a branch on a temporary instance and booting up this instance with all required software and services automatically on the fly is not a trivial task. However, it is possible, especially if you use Docker or a configuration management tool like Chef, Puppet, Ansible, or Salt. -1. First, learn about [environments][] and their role in the development workflow. -1. Then make a small stop to learn about [CI variables][variables] and how they - can be used in your CI jobs. -1. Next, explore the [`environment` syntax][yaml-env] as defined in `.gitlab-ci.yml`. - This will be your primary reference when you are finally comfortable with - how environments work. -1. Additionally, find out about [manual actions][] and how you can use them to - deploy to critical environments like production with the push of a button. -1. And as a last step, follow the [example tutorials](#examples) which will - guide you step by step to set up the infrastructure and make use of - Review Apps. +Review Apps usually make sense with web applications, but you can use them any way you'd like. -## Configuration +## Implementing Review Apps -The configuration of Review apps depends on your technology stack and your -infrastructure. Read the [dynamic environments] documentation to understand -how to define and create them. +Implementing Review Apps depends on your: -## Creating and destroying Review Apps +- Technology stack. +- Deployment process. -The creation and destruction of a Review App is defined in `.gitlab-ci.yml` -at a job level under the `environment` keyword. +### Prerequisite Knowledge -Check the [environments] documentation how to do so. +To get a better understanding of Review Apps, review documentation on how environments and deployments work. Before you implement your own Review Apps: -## A simple workflow +1. Learn about [environments](../environments.md) and their role in the development workflow. +1. Learn about [CI variables](../variables/README.md) and how they can be used in your CI jobs. +1. Explore the [`environment` syntax](../yaml/README.md#environment) as defined in `.gitlab-ci.yml`. This will become a primary reference. +1. Additionally, find out about [manual actions](../environments.md#manual-actions) and how you can use them to deploy to critical environments like production with the push of a button. +1. Follow the [example tutorials](#examples). These will guide you through setting up infrastructure and using Review Apps. -The process of adding Review Apps in your workflow would look like: +### Configuring dynamic environments + +Configuring Review Apps dynamic environments depends on your technology stack and infrastructure. + +For more information, see [dynamic environments](../environments.md#dynamic-environments) documentation to understand how to define and create them. + +### Creating and destroying Review Apps + +Creating and destroying Review Apps is defined in `.gitlab-ci.yml` at a job level under the `environment` keyword. + +For more information, see [Introduction to environments and deployments](../environments.md). + +### Adding Review Apps to your workflow + +The process of adding Review Apps in your workflow is as follows: 1. Set up the infrastructure to host and deploy the Review Apps. -1. [Install][install-runner] and [configure][conf-runner] a Runner that does - the deployment. -1. Set up a job in `.gitlab-ci.yml` that uses the predefined - [predefined CI environment variable][variables] `${CI_COMMIT_REF_NAME}` to - create dynamic environments and restrict it to run only on branches. -1. Optionally set a job that [manually stops][manual-env] the Review Apps. +1. [Install](https://docs.gitlab.com/runner/install/) and [configure](https://docs.gitlab.com/runner/commands/) a Runner to do deployment. +1. Set up a job in `.gitlab-ci.yml` that uses the predefined [predefined CI environment variable](../variables/README.md) `${CI_COMMIT_REF_NAME}` to create dynamic environments and restrict it to run only on branches. +1. Optionally, set a job that [manually stops](../environments.md#stopping-an-environment) the Review Apps. -From there on, you would follow the branched Git flow: +After adding Review Apps to your workflow, you follow the branched Git flow. That is: -1. Push a branch and let the Runner deploy the Review App based on the `script` - definition of the dynamic environment job. -1. Wait for the Runner to build and/or deploy your web app. -1. Click on the link that's present in the MR related to the branch and see the - changes live. +1. Push a branch and let the Runner deploy the Review App based on the `script` definition of the dynamic environment job. +1. Wait for the Runner to build and deploy your web application. +1. Click on the link that provided in the merge request related to the branch to see the changes live. ## Limitations @@ -98,27 +96,9 @@ Check the [environments limitations](../environments.md#limitations). ## Examples -A list of examples used with Review Apps can be found below: - -- [Use with NGINX][app-nginx] - Use NGINX and the shell executor of GitLab Runner - to deploy a simple HTML website. - -And below is a soon to be added examples list: - -- Use with Amazon S3 -- Use on Heroku with dpl -- Use with OpenShift/kubernetes - -[app-nginx]: https://gitlab.com/gitlab-examples/review-apps-nginx -[ce-21971]: https://gitlab.com/gitlab-org/gitlab-ce/issues/21971 -[dynamic environments]: ../environments.md#dynamic-environments -[environments]: ../environments.md -[fourchette]: https://github.com/rainforestapp/fourchette -[heroku-apps]: https://devcenter.heroku.com/articles/github-integration-review-apps -[manual actions]: ../environments.md#manual-actions -[merge request]: ../../user/project/merge_requests.md -[variables]: ../variables/README.md -[yaml-env]: ../yaml/README.md#environment -[install-runner]: https://docs.gitlab.com/runner/install/ -[conf-runner]: https://docs.gitlab.com/runner/commands/ -[manual-env]: ../environments.md#stopping-an-environment +The following are example projects that use Review Apps with: + +- [NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx). +- [OpenShift](https://gitlab.com/gitlab-examples/review-apps-openshift). + +See also the video [Demo: Cloud Native Development with GitLab](https://www.youtube.com/watch?v=jfIyQEwrocw), which includes a Review Apps example. diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 8f1ff190804..83e0fa34ad6 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -29,7 +29,7 @@ are: - **Specific Runners** are useful for jobs that have special requirements or for projects with a specific demand. If a job has certain requirements, you can set up the specific Runner with this in mind, while not having to do this for all - Runners. For example, if you want to deploy a certain project, you can setup + Runners. For example, if you want to deploy a certain project, you can set up a specific Runner to have the right credentials for this. The [usage of tags](#using-tags) may be useful in this case. Specific Runners process jobs using a [FIFO] queue. - **Group Runners** are useful when you have multiple projects under one group @@ -144,9 +144,8 @@ 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 @@ -223,7 +222,7 @@ should keep in mind. ### Using tags -You must setup a Runner to be able to run all the different types of jobs +You must set up a Runner to be able to run all the different types of jobs that it may encounter on the projects it's shared over. This would be problematic for large amounts of projects, if it wasn't for tags. @@ -299,7 +298,7 @@ and using more secure [Runner Executors](https://docs.gitlab.com/runner/executor ### Forks Whenever a project is forked, it copies the settings of the jobs that relate -to it. This means that if you have shared Runners setup for a project and +to it. This means that if you have shared Runners set up for a project and someone forks that project, the shared Runners will also serve jobs of this project. diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index 4cb05509e7b..0c3b0bf6990 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -46,7 +46,7 @@ to access it. This is where an SSH key pair comes in handy. 1. You will first need to create an SSH key pair. For more information, follow the instructions to [generate an SSH key](../../ssh/README.md#generating-a-new-ssh-key-pair). - **Do not** add a passphrase to the SSH key, or the `before_script` will\ + **Do not** add a passphrase to the SSH key, or the `before_script` will prompt for it. 1. Create a new [variable](../variables/README.md#variables). @@ -175,7 +175,7 @@ Now that the `SSH_KNOWN_HOSTS` variable is created, in addition to the [content of `.gitlab-ci.yml`](#ssh-keys-when-using-the-docker-executor) above, here's what more you need to add: - ```yaml +```yaml before_script: ## ## Assuming you created the SSH_KNOWN_HOSTS variable, uncomment the diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index c213b096a14..cf92d90ba30 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -1,9 +1,10 @@ # Triggering pipelines through the API > **Notes**: -- [Introduced][ci-229] in GitLab CE 7.14. -- GitLab 8.12 has a completely redesigned job permissions system. Read all - about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#job-triggers). +> +> - [Introduced][ci-229] in GitLab CE 7.14. +> - GitLab 8.12 has a completely redesigned job permissions system. Read all +> about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#job-triggers). Triggers can be used to force a pipeline rerun of a specific `ref` (branch or tag) with an API call. @@ -49,11 +50,12 @@ The action is irreversible. ## Triggering a pipeline > **Notes**: -- Valid refs are only the branches and tags. If you pass a commit SHA as a ref, - it will not trigger a job. -- If your project is public, passing the token in plain text is probably not the - wisest idea, so you might want to use a - [variable](../variables/README.md#variables) for that purpose. +> +> - Valid refs are only the branches and tags. If you pass a commit SHA as a ref, +> it will not trigger a job. +> - If your project is public, passing the token in plain text is probably not the +> wisest idea, so you might want to use a +> [variable](../variables/README.md#variables) for that purpose. To trigger a job you need to send a `POST` request to GitLab's API endpoint: @@ -122,11 +124,12 @@ Now, whenever a new tag is pushed on project A, the job will run and the ## Triggering a pipeline from a webhook > **Notes**: -- Introduced in GitLab 8.14. -- `ref` should be passed as part of the URL in order to take precedence over - `ref` from the webhook body that designates the branch ref that fired the - trigger in the source repository. -- `ref` should be URL-encoded if it contains slashes. +> +> - Introduced in GitLab 8.14. +> - `ref` should be passed as part of the URL in order to take precedence over +> `ref` from the webhook body that designates the branch ref that fired the +> trigger in the source repository. +> - `ref` should be URL-encoded if it contains slashes. To trigger a job from a webhook of another project you need to add the following webhook URL for Push and Tag events (change the project ID, ref and token): diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 115e6e390c9..93e7ca7bd89 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -34,7 +34,7 @@ Some of the predefined environment variables are available only if a minimum version of [GitLab Runner][runner] is used. Consult the table below to find the version of Runner required. ->**Note:** +NOTE: **Note:** Starting with GitLab 9.0, we have deprecated some variables. Read the [9.0 Renaming](#9-0-renaming) section to find out their replacements. **You are strongly advised to use the new variables as we will remove the old ones in @@ -94,6 +94,9 @@ future GitLab releases.** | **CI_SERVER_NAME** | all | all | The name of CI server that is used to coordinate jobs | | **CI_SERVER_REVISION** | all | all | GitLab revision that is used to schedule jobs | | **CI_SERVER_VERSION** | all | all | GitLab version that is used to schedule jobs | +| **CI_SERVER_VERSION_MAJOR** | 11.4 | all | GitLab version major component | +| **CI_SERVER_VERSION_MINOR** | 11.4 | all | GitLab version minor component | +| **CI_SERVER_VERSION_PATCH** | 11.4 | all | GitLab version patch component | | **CI_SHARED_ENVIRONMENT** | all | 10.1 | Marks that the job is executed in a shared environment (something that is persisted across CI invocations like `shell` or `ssh` executor). If the environment is shared, it is set to true, otherwise it is not defined at all. | | **GET_SOURCES_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to fetch sources running a job | | **GITLAB_CI** | all | all | Mark that job is executed in GitLab CI environment | @@ -109,7 +112,7 @@ To follow conventions of naming across GitLab, and to further move away from the `build` term and toward `job` CI variables have been renamed for the 9.0 release. ->**Note:** +NOTE: **Note:** Starting with GitLab 9.0, we have deprecated the `$CI_BUILD_*` variables. **You are strongly advised to use the new variables as we will remove the old ones in future GitLab releases.** @@ -131,7 +134,7 @@ future GitLab releases.** ## `.gitlab-ci.yml` defined variables ->**Note:** +NOTE **Note:** This feature requires GitLab Runner 0.5.0 or higher and GitLab CI 7.14 or higher. GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in the @@ -215,9 +218,15 @@ Protected variables can be added by going to your project's Once you set them, they will be available for all subsequent pipelines. +### Manually-specified variables + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/44059) in GitLab 10.8. + +Variables can be specified for a single pipeline run when a [manual pipeline](../pipelines.md#manually-executing-pipelines) is created. + ## Deployment variables ->**Note:** +NOTE: **Note:** This feature requires GitLab CI 8.15 or higher. [Project services](../../user/project/integrations/project_services.md) that are @@ -317,6 +326,12 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach ++ CI_SERVER_NAME='GitLab CI' ++ export CI_SERVER_VERSION= ++ CI_SERVER_VERSION= +++ export CI_SERVER_VERSION_MAJOR= +++ CI_SERVER_VERSION_MAJOR= +++ export CI_SERVER_VERSION_MINOR= +++ CI_SERVER_VERSION_MINOR= +++ export CI_SERVER_VERSION_PATCH= +++ CI_SERVER_VERSION_PATCH= ++ export CI_SERVER_REVISION= ++ CI_SERVER_REVISION= ++ export GITLAB_CI=true @@ -462,6 +477,9 @@ export CI_SERVER="yes" export CI_SERVER_NAME="GitLab" export CI_SERVER_REVISION="70606bf" export CI_SERVER_VERSION="8.9.0" +export CI_SERVER_VERSION_MAJOR="8" +export CI_SERVER_VERSION_MINOR="9" +export CI_SERVER_VERSION_PATCH="0" export GITLAB_USER_ID="42" export GITLAB_USER_EMAIL="user@example.com" export CI_REGISTRY_USER="gitlab-ci-token" @@ -567,4 +585,4 @@ Below you can find supported syntax reference: [builds-policies]: ../yaml/README.md#only-and-except-complex [gitlab-deploy-token]: ../../user/project/deploy_tokens/index.md#gitlab-deploy-token [registry]: ../../user/project/container_registry.md -[dependent-repositories]: ../../user/project/new_ci_build_permissions_model.md#dependent-repositories
\ No newline at end of file +[dependent-repositories]: ../../user/project/new_ci_build_permissions_model.md#dependent-repositories diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index b2b4a26bdda..4e8ce10c9cb 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -8,17 +8,17 @@ This document describes where and how the different types of variables can be us ## Variables usage -There are basically two places where you can use any defined variables: +There are two places defined variables can be used. On the: -1. On GitLab's side there's `.gitlab-ci.yml` -1. On the Runner's side there's `config.toml` +1. GitLab side, in `.gitlab-ci.yml`. +1. The runner side, in `config.toml`. ### `.gitlab-ci.yml` file | Definition | Can be expanded? | Expansion place | Description | |--------------------------------------|-------------------|-----------------|--------------| -| `environment:url` | yes | GitLab | The variable expansion is made by GitLab's [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism).<ul><li>**Supported:** all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules)</li><li>**Not suported:** variables defined in Runner's `config.toml` and variables created in job's `script`</li></ul> | -| `environment:name` | yes | GitLab | Similar to `environment:url`, but the variables expansion **doesn't support**: <ul><li>variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`)</li><li>any other variables related to environment (currently only `CI_ENVIRONMENT_URL`)</li><li>[persisted variables](#persisted-variables)</li></ul> | +| `environment:url` | yes | GitLab | The variable expansion is made by GitLab's [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism).<ul><li>Supported: all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules)</li><li>Not suported: variables defined in Runner's `config.toml` and variables created in job's `script`</li></ul> | +| `environment:name` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support: <ul><li>variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`)</li><li>any other variables related to environment (currently only `CI_ENVIRONMENT_URL`)</li><li>[persisted variables](#persisted-variables)</li></ul> | | `variables` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | | `image` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | | `services:[]` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | @@ -26,7 +26,7 @@ There are basically two places where you can use any defined variables: | `cache:key` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | | `artifacts:name` | yes | Runner | The variable expansion is made by GitLab Runner's shell environment | | `script`, `before_script`, `after_script` | yes | Script execution shell | The variable expansion is made by the [execution shell environment](#execution-shell-environment) | -| `only:variables:[]`, `except:variables:[]` | no | n/a | The variable must be in the form of `$variable`.<br/>**Not supported:**<ul><li>variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`)</li><li>any other variables related to environment (currently only `CI_ENVIRONMENT_URL`)</li><li>[persisted variables](#persisted-variables)</li></ul> | +| `only:variables:[]`, `except:variables:[]` | no | n/a | The variable must be in the form of `$variable`.<br/>Not supported:<ul><li>variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`)</li><li>any other variables related to environment (currently only `CI_ENVIRONMENT_URL`)</li><li>[persisted variables](#persisted-variables)</li></ul> | ### `config.toml` file @@ -55,9 +55,9 @@ since the expansion is done in GitLab before any Runner will get the job. ### GitLab Runner internal variable expansion mechanism -- **Supported:** project/group variables, `.gitlab-ci.yml` variables, `config.toml` variables, and - variables from triggers and pipeline schedules -- **Not supported:** variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`) +- Supported: project/group variables, `.gitlab-ci.yml` variables, `config.toml` variables, and + variables from triggers, pipeline schedules, and manual pipelines. +- Not supported: variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`). The Runner uses Go's `os.Expand()` method for variable expansion. It means that it will handle only variables defined as `$variable` and `${variable}`. What's also important, is that @@ -73,18 +73,17 @@ by bash/sh (leaving empty strings or some values depending whether the variables defined or not), but will not work with Windows' cmd/PowerShell, since these shells are using a different variables syntax. -**Supported:** +Supported: - The `script` may use all available variables that are default for the shell (e.g., `$PATH` which should be present in all bash/sh shells) and all variables defined by GitLab CI/CD (project/group variables, `.gitlab-ci.yml` variables, `config.toml` variables, and variables from triggers and pipeline schedules). - The `script` may also use all variables defined in the lines before. So, for example, if you define a variable `export MY_VARIABLE="test"`: - - - in `before_script`, it will work in the following lines of `before_script` and - all lines of the related `script` - - in `script`, it will work in the following lines of `script` - - in `after_script`, it will work in following lines of `after_script` + - In `before_script`, it will work in the following lines of `before_script` and + all lines of the related `script`. + - In `script`, it will work in the following lines of `script`. + - In `after_script`, it will work in following lines of `after_script`. ## Persisted variables @@ -107,7 +106,9 @@ The following variables are known as "persisted": They are: -- **supported** for all definitions as [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "Runner" -- **not supported:** - - by the definitions [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "GitLab" - - in the `only` and `except` [variables expressions](README.md#variables-expressions) +- Supported for definitions where the ["Expansion place"](#gitlab-ci-yml-file) is: + - Runner. + - Script execution shell. +- Not supported: + - For definitions where the ["Expansion place"](#gitlab-ci-yml-file) is GitLab. + - In the `only` and `except` [variables expressions](README.md#variables-expressions). diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index abba748db8b..15dde36cca8 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -56,6 +56,7 @@ A job is defined by a list of parameters that define the job behavior. | Keyword | Required | Description | |---------------|----------|-------------| | script | yes | Defines a shell script which is executed by Runner | +| extends | no | Defines a configuration entry that this job is going to inherit from | | image | no | Use docker image, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) | | services | no | Use docker services, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) | | stage | no | Defines a job stage (default: `test`) | @@ -75,6 +76,81 @@ A job is defined by a list of parameters that define the job behavior. | coverage | no | Define code coverage settings for a given job | | retry | no | Define how many times a job can be auto-retried in case of a failure | +### `extends` + +> Introduced in GitLab 11.3. + +`extends` defines an entry name that a job that uses `extends` is going to +inherit from. + +It is an alternative to using [YAML anchors](#anchors) and is a little +more flexible and readable: + +```yaml +.tests: + script: rake test + stage: test + only: + refs: + - branches + +rspec: + extends: .tests + script: rake rspec + only: + variables: + - $RSPEC +``` + +In the example above, the `rspec` job is going to inherit from the `.tests` +template job. GitLab will perform a reverse deep merge, which means that it will +merge the `rspec` contents into `.tests` recursively, and this is going to result in +the following `rspec` job: + +```yaml +rspec: + script: rake rspec + stage: test + only: + refs: + - branches + variables: + - $RSPEC +``` + +`.tests` in this example is a [hidden key](#hidden-keys-jobs), but it's +possible to inherit from regular jobs as well. + +`extends` supports multi-level inheritance, however it is not recommended to +use more than three levels. The maximum nesting level that is supported is 10. +The following example has two levels of inheritance: + +```yaml +.tests: + only: + - pushes + +.rspec: + extends: .tests + script: rake rspec + +rspec 1: + variables: + RSPEC_SUITE: '1' + extends: .rspec + +rspec 2: + variables: + RSPEC_SUITE: '2' + extends: .rspec + +spinach: + extends: .tests + script: rake spinach +``` + +`extends` works across configuration files combined with [`include`](#include). + ### `pages` `pages` is a special job that is used to upload static content to GitLab that @@ -112,7 +188,7 @@ used for time of the job. The configuration of this feature is covered in ## `before_script` and `after_script` -> Introduced in GitLab 8.7 and requires Gitlab Runner v1.2 +> Introduced in GitLab 8.7 and requires GitLab Runner v1.2 `before_script` is used to define the command that should be run before all jobs, including deploy jobs, but after the restoration of [artifacts](#artifacts). @@ -309,8 +385,10 @@ except master. ## `only` and `except` (complex) > `refs` and `kubernetes` policies introduced in GitLab 10.0 - +> > `variables` policy introduced in 10.7 +> +> `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/19232) in 11.4 CAUTION: **Warning:** This an _alpha_ feature, and it it subject to change at any time without @@ -322,10 +400,15 @@ policy configuration. GitLab now supports both, simple and complex strategies, so it is possible to use an array and a hash configuration scheme. -Three keys are now available: `refs`, `kubernetes` and `variables`. +Four keys are now available: `refs`, `kubernetes` and `variables` and `changes`. + +### `refs` and `kubernetes` + Refs strategy equals to simplified only/except configuration, whereas kubernetes strategy accepts only `active` keyword. +### `variables` + `variables` keyword is used to define variables expressions. In other words you can use predefined variables / project / group or environment-scoped variables to define an expression GitLab is going to @@ -369,6 +452,46 @@ end-to-end: Learn more about variables expressions on [a separate page][variables-expressions]. +### `changes` + +Using `changes` keyword with `only` or `except` makes it possible to define if +a job should be created based on files modified by a git push event. + +For example: + +```yaml +docker build: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + only: + changes: + - Dockerfile + - docker/scripts/* +``` + +In the scenario above, if you are pushing multiple commits to GitLab to an +existing branch, GitLab creates and triggers `docker build` job, provided that +one of the commits contains changes to either: + +- The `Dockerfile` file. +- Any of the files inside `docker/scripts/` directory. + +CAUTION: **Warning:** +There are some caveats when using this feature with new branches and tags. See +the section below. + +#### Using `changes` with new branches and tags + +If you are pushing a **new** branch or a **new** tag to GitLab, the policy +always evaluates to true and GitLab will create a job. This feature is not +connected with merge requests yet, and because GitLab is creating pipelines +before an user can create a merge request we don't know a target branch at +this point. + +Without a target branch, it is not possible to know what the common ancestor is, +thus we always create a job in that case. This feature works best for stable +branches like `master` because in that case GitLab uses the previous commit +that is present in a branch to compare against the latest SHA that was pushed. + ## `tags` `tags` is used to select specific Runners from the list of all Runners that are @@ -390,10 +513,33 @@ job: The specification above, will make sure that `job` is built by a Runner that has both `ruby` AND `postgres` tags defined. +Tags are also a great way to run different jobs on different platforms, for +example, given an OS X Runner with tag `osx` and Windows Runner with tag +`windows`, the following jobs run on respective platforms: + +```yaml +windows job: + stage: + - build + tags: + - windows + script: + - echo Hello, %USERNAME%! + +osx job: + stage: + - build + tags: + - osx + script: + - echo "Hello, $USER!" +``` + ## `allow_failure` `allow_failure` is used when you want to allow a job to fail without impacting the rest of the CI suite. Failed jobs don't contribute to the commit status. +The default value is `false`. When enabled and the job fails, the pipeline will be successful/green for all intents and purposes, but a "CI build passed with warnings" message will be @@ -487,9 +633,10 @@ The above script will: ### `when:manual` > **Notes:** -- Introduced in GitLab 8.10. -- Blocking manual actions were introduced in GitLab 9.0. -- Protected actions were introduced in GitLab 9.2. +> +> - Introduced in GitLab 8.10. +> - Blocking manual actions were introduced in GitLab 9.0. +> - Protected actions were introduced in GitLab 9.2. Manual actions are a special type of job that are not executed automatically, they need to be explicitly started by a user. An example usage of manual actions @@ -520,11 +667,11 @@ have ability to merge to this branch. ## `environment` +> **Notes:** > -**Notes:** -- Introduced in GitLab 8.9. -- You can read more about environments and find more examples in the - [documentation about environments][environment]. +> - Introduced in GitLab 8.9. +> - You can read more about environments and find more examples in the +> [documentation about environments][environment]. `environment` is used to define that a job deploys to a specific environment. If `environment` is specified and no environment under that name exists, a new @@ -545,15 +692,15 @@ deployment to the `production` environment. ### `environment:name` +> **Notes:** > -**Notes:** -- Introduced in GitLab 8.11. -- Before GitLab 8.11, the name of an environment could be defined as a string like - `environment: production`. The recommended way now is to define it under the - `name` keyword. -- The `name` parameter can use any of the defined CI variables, - including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). - You however cannot use variables defined under `script`. +> - Introduced in GitLab 8.11. +> - Before GitLab 8.11, the name of an environment could be defined as a string like +> `environment: production`. The recommended way now is to define it under the +> `name` keyword. +> - The `name` parameter can use any of the defined CI variables, +> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). +> You however cannot use variables defined under `script`. The `environment` name can contain: @@ -584,14 +731,14 @@ deploy to production: ### `environment:url` +> **Notes:** > -**Notes:** -- Introduced in GitLab 8.11. -- Before GitLab 8.11, the URL could be added only in GitLab's UI. The - recommended way now is to define it in `.gitlab-ci.yml`. -- The `url` parameter can use any of the defined CI variables, - including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). - You however cannot use variables defined under `script`. +> - Introduced in GitLab 8.11. +> - Before GitLab 8.11, the URL could be added only in GitLab's UI. The +> recommended way now is to define it in `.gitlab-ci.yml`. +> - The `url` parameter can use any of the defined CI variables, +> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). +> You however cannot use variables defined under `script`. This is an optional value that when set, it exposes buttons in various places in GitLab which when clicked take you to the defined URL. @@ -611,12 +758,12 @@ deploy to production: ### `environment:on_stop` +> **Notes:** > -**Notes:** -- [Introduced][ce-6669] in GitLab 8.13. -- Starting with GitLab 8.14, when you have an environment that has a stop action - defined, GitLab will automatically trigger a stop action when the associated - branch is deleted. +> - [Introduced][ce-6669] in GitLab 8.13. +> - Starting with GitLab 8.14, when you have an environment that has a stop action +> defined, GitLab will automatically trigger a stop action when the associated +> branch is deleted. Closing (stoping) environments can be achieved with the `on_stop` keyword defined under `environment`. It declares a different job that runs in order to close @@ -667,13 +814,13 @@ The `stop_review_app` job is **required** to have the following keywords defined ### Dynamic environments +> **Notes:** > -**Notes:** -- [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6. -- The `$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15. -- The `name` and `url` parameters can use any of the defined CI variables, - including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). - You however cannot use variables defined under `script`. +> - [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6. +> - The `$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15. +> - The `name` and `url` parameters can use any of the defined CI variables, +> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). +> You however cannot use variables defined under `script`. For example: @@ -703,13 +850,13 @@ as Review Apps. You can see a simple example using Review Apps at ## `cache` +> **Notes:** > -**Notes:** -- Introduced in GitLab Runner v0.7.0. -- `cache` can be set globally and per-job. -- From GitLab 9.0, caching is enabled and shared between pipelines and jobs - by default. -- From GitLab 9.2, caches are restored before [artifacts](#artifacts). +> - Introduced in GitLab Runner v0.7.0. +> - `cache` can be set globally and per-job. +> - From GitLab 9.0, caching is enabled and shared between pipelines and jobs +> by default. +> - From GitLab 9.2, caches are restored before [artifacts](#artifacts). TIP: **Learn more:** Read how caching works and find out some good practices in the @@ -871,13 +1018,13 @@ skip the download step. ## `artifacts` +> **Notes:** > -**Notes:** -- Introduced in GitLab Runner v0.7.0 for non-Windows platforms. -- Windows support was added in GitLab Runner v.1.0.0. -- From GitLab 9.2, caches are restored before artifacts. -- Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). -- Job artifacts are only collected for successful jobs by default. +> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms. +> - Windows support was added in GitLab Runner v.1.0.0. +> - From GitLab 9.2, caches are restored before artifacts. +> - Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). +> - Job artifacts are only collected for successful jobs by default. `artifacts` is used to specify a list of files and directories which should be attached to the job after success. @@ -1132,13 +1279,16 @@ rspec: ``` The collected JUnit reports will be uploaded to GitLab as an artifact and will -be automatically [shown in merge requests](../junit_test_reports.md). +be automatically shown in merge requests. + +For more examples, see [JUnit test reports](../junit_test_reports.md). NOTE: **Note:** In case the JUnit tool you use exports to multiple XML files, you can specify -multiple test report paths within a single job -(`junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml]`) and they will be automatically -concatenated into a single file. +multiple test report paths within a single job and they will be automatically +concatenated into a single file. Use a filename pattern (`junit: rspec-*.xml`), +an array of filenames (`junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml]`), or a +combination thereof (`junit: [rspec.xml, test-results/TEST-*.xml]`). ## `dependencies` @@ -1255,6 +1405,187 @@ test: retry: 2 ``` +## `include` + +> Introduced in [GitLab Edition Premium][ee] 10.5. +> Available for Starter, Premium and Ultimate [versions][gitlab-versions] since 10.6. +> Behaviour expanded in GitLab 10.8 to allow more flexible overriding. +> Available for Libre since [11.4](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21603) + +Using the `include` keyword, you can allow the inclusion of external YAML files. + +In the following example, the content of `.before-script-template.yml` will be +automatically fetched and evaluated along with the content of `.gitlab-ci.yml`: + +```yaml +# Content of https://gitlab.com/awesome-project/raw/master/.before-script-template.yml + +before_script: + - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs + - gem install bundler --no-ri --no-rdoc + - bundle install --jobs $(nproc) "${FLAGS[@]}" +``` + +```yaml +# Content of .gitlab-ci.yml + +include: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml' + +rspec: + script: + - bundle exec rspec +``` + +You can define it either as a single string, or, in case you want to include +more than one files, an array of different values . The following examples +are both valid cases: + +```yaml +# Single string + +include: '/templates/.after-script-template.yml' +``` + +```yaml +# Array + +include: + - 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml' + - '/templates/.after-script-template.yml' +``` + +--- + +`include` supports two types of files: + +- **local** to the same repository, referenced by using full paths in the same + repository, with `/` being the root directory. For example: + + ```yaml + # Within the repository + include: '/templates/.gitlab-ci-template.yml' + ``` + + NOTE: **Note:** + You can only use files that are currently tracked by Git on the same branch + your configuration file is. In other words, when using a **local file**, make + sure that both `.gitlab-ci.yml` and the local file are on the same branch. + + NOTE: **Note:** + We don't support the inclusion of local files through Git submodules paths. + +- **remote** in a different location, accessed using HTTP/HTTPS, referenced + using the full URL. For example: + + ```yaml + include: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml' + ``` + + NOTE: **Note:** + The remote file must be publicly accessible through a simple GET request, as we don't support authentication schemas in the remote URL. + +--- + + +Since GitLab 10.8 we are now recursively merging the files defined in `include` +with those in `.gitlab-ci.yml`. Files defined by `include` are always +evaluated first and recursively merged with the content of `.gitlab-ci.yml`, no +matter the position of the `include` keyword. You can take advantage of +recursive merging to customize and override details in included CI +configurations with local definitions. + +The following example shows specific YAML-defined variables and details of the +`production` job from an include file being customized in `.gitlab-ci.yml`. + +```yaml +# Content of https://company.com/autodevops-template.yml + +variables: + POSTGRES_USER: user + POSTGRES_PASSWORD: testing_password + POSTGRES_DB: $CI_ENVIRONMENT_SLUG + +production: + stage: production + script: + - install_dependencies + - deploy + environment: + name: production + url: https://$CI_PROJECT_PATH_SLUG.$AUTO_DEVOPS_DOMAIN + only: + - master +``` + +```yaml +# Content of .gitlab-ci.yml + +include: 'https://company.com/autodevops-template.yml' + +image: alpine:latest + +variables: + POSTGRES_USER: root + POSTGRES_PASSWORD: secure_password + +stages: + - build + - test + - production + +production: + environment: + url: https://domain.com +``` + +In this case, the variables `POSTGRES_USER` and `POSTGRES_PASSWORD` along +with the environment url of the `production` job defined in +`autodevops-template.yml` have been overridden by new values defined in +`.gitlab-ci.yml`. + +NOTE: **Note:** +Recursive includes are not supported meaning your external files +should not use the `include` keyword, as it will be ignored. + +Recursive merging lets you extend and override dictionary mappings, but +you cannot add or modify items to an included array. For example, to add +an additional item to the production job script, you must repeat the +existing script items. + +```yaml +# Content of https://company.com/autodevops-template.yml + +production: + stage: production + script: + - install_dependencies + - deploy +``` + +```yaml +# Content of .gitlab-ci.yml + +include: 'https://company.com/autodevops-template.yml' + +stages: + - production + +production: + script: + - install_depedencies + - deploy + - notify_owner +``` + +In this case, if `install_dependencies` and `deploy` were not repeated in +`.gitlab-ci.yml`, they would not be part of the script for the `production` +job in the combined CI configuration. + +NOTE: **Note:** +We currently do not support using YAML aliases across different YAML files +sourced by `include`. You must only refer to aliases in the same file. Instead +of using YAML anchors you can use [`extends` keyword](#extends). + ## `variables` > Introduced in GitLab Runner v0.5.0. @@ -1359,7 +1690,9 @@ There are three possible values: `none`, `normal`, and `recursive`: ``` - `recursive` means that all submodules (including submodules of submodules) - will be included. It is equivalent to: + will be included. This feature needs Git v1.8.1 and later. When using a + GitLab Runner with an executor not based on Docker, make sure the Git version + meets that requirement. It is equivalent to: ``` git submodule sync --recursive diff --git a/doc/development/README.md b/doc/development/README.md index 20f8fa1d368..43d3865da0e 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -7,7 +7,7 @@ description: 'Learn how to contribute to GitLab.' ## Get started! -- Setup GitLab's development environment with [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/README.md) +- 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](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md) - [Architecture](architecture.md) of GitLab - [Rake tasks](rake_tasks.md) for development @@ -47,14 +47,20 @@ description: 'Learn how to contribute to GitLab.' - [How to dump production data to staging](db_dump.md) - [Working with the GitHub importer](github_importer.md) - [Working with Merge Request diffs](diffs.md) +- [Permissions](permissions.md) +- [Prometheus metrics](prometheus_metrics.md) +- [Guidelines for reusing abstractions](reusing_abstractions.md) ## Performance guides -- [Instrumentation](instrumentation.md) -- [Performance guidelines](performance.md) +- [Instrumentation](instrumentation.md) for Ruby code running in production + environments +- [Performance guidelines](performance.md) for writing code, benchmarks, and + certain patterns to avoid - [Merge request performance guidelines](merge_request_performance_guidelines.md) for ensuring merge requests do not negatively impact GitLab performance -- [Profiling](profiling.md) for profiling a URL +- [Profiling](profiling.md) a URL, measuring performance using Sherlock, or + tracking down N+1 queries using Bullet ## Database guides @@ -88,6 +94,7 @@ description: 'Learn how to contribute to GitLab.' - [Verifying database capabilities](verifying_database_capabilities.md) - [Database Debugging and Troubleshooting](database_debugging.md) - [Query Count Limits](query_count_limits.md) +- [Database helper modules](database_helpers.md) ## Testing guides diff --git a/doc/development/automatic_ce_ee_merge.md b/doc/development/automatic_ce_ee_merge.md index 8d41503f874..9dd78806a12 100644 --- a/doc/development/automatic_ce_ee_merge.md +++ b/doc/development/automatic_ce_ee_merge.md @@ -9,16 +9,16 @@ This merge is done automatically in a ## What to do if you are pinged in a `CE Upstream` merge request to resolve a conflict? 1. Please resolve the conflict as soon as possible or ask someone else to do it - - It's ok to resolve more conflicts than the one that you are asked to resolve. - In that case, it's a good habit to ask for a double-check on your resolution - by someone who is familiar with the code you touched. + - It's ok to resolve more conflicts than the one that you are asked to resolve. + In that case, it's a good habit to ask for a double-check on your resolution + by someone who is familiar with the code you touched. 1. Once you have resolved your conflicts, push to the branch (no force-push) 1. Assign the merge request to the next person that has to resolve a conflict 1. If all conflicts are resolved after your resolution is pushed, keep the merge - request assigned to you: **you are now responsible for the merge request to be - green** + request assigned to you: **you are now responsible for the merge request to be + green** 1. If you need any help, you can ping the current [release managers], or ask in - the `#ce-to-ee` Slack channel + the `#ce-to-ee` Slack channel A few notes about the automatic CE->EE merge job: @@ -63,7 +63,7 @@ EE version of your CE merge request. For each commit (except on `master`), the `ee_compat_check` CI job tries to detect if the current branch's changes will conflict during the CE->EE merge. -The job reports what files are conflicting and how to setup a merge request +The job reports what files are conflicting and how to set up a merge request against EE. #### How the job works @@ -127,19 +127,19 @@ Now, every time you create an MR for CE and EE: 1. Open two terminal windows, one in CE, and another one in EE 1. In the CE terminal: - 1. Create the CE branch, e.g., `branch-example` - 1. Make your changes and push a commit (commit A) - 1. Create the CE merge request in GitLab + 1. Create the CE branch, e.g., `branch-example` + 1. Make your changes and push a commit (commit A) + 1. Create the CE merge request in GitLab 1. In the EE terminal: - 1. Create the EE-equivalent branch ending with `-ee`, e.g., - `git checkout -b branch-example-ee` - 1. Fetch the CE branch: `git fetch ce branch-example` - 1. Cherry-pick the commit A: `git cherry-pick commit-A-SHA` - 1. If Git prompts you to fix the conflicts, do a `git status` - to check which files contain conflicts, fix them, save the files - 1. Add the changes with `git add .` but **DO NOT commit** them - 1. Continue cherry-picking: `git cherry-pick --continue` - 1. Push to EE: `git push origin branch-example-ee` + 1. Create the EE-equivalent branch ending with `-ee`, e.g., + `git checkout -b branch-example-ee` + 1. Fetch the CE branch: `git fetch ce branch-example` + 1. Cherry-pick the commit A: `git cherry-pick commit-A-SHA` + 1. If Git prompts you to fix the conflicts, do a `git status` + to check which files contain conflicts, fix them, save the files + 1. Add the changes with `git add .` but **DO NOT commit** them + 1. Continue cherry-picking: `git cherry-pick --continue` + 1. Push to EE: `git push origin branch-example-ee` 1. Create the EE-equivalent MR and link to the CE MR from the description "Ports [CE-MR-LINK] to EE" 1. Once all the jobs are passing in both CE and EE, you've addressed the diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index f0d5af9fcb5..bb9a296ef12 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -10,10 +10,10 @@ migrations automatically reschedule themselves for a later point in time. ## When To Use Background Migrations ->**Note:** -When adding background migrations _you must_ make sure they are announced in the -monthly release post along with an estimate of how long it will take to complete -the migrations. +> **Note:** +> When adding background migrations _you must_ make sure they are announced in the +> monthly release post along with an estimate of how long it will take to complete +> the migrations. In the vast majority of cases you will want to use a regular Rails migration instead. Background migrations should _only_ be used when migrating _data_ in @@ -127,23 +127,23 @@ big JSON blob) to column `bar` (containing a string). The process for this would roughly be as follows: 1. Release A: - 1. Create a migration class that perform the migration for a row with a given ID. - 1. Deploy the code for this release, this should include some code that will - schedule jobs for newly created data (e.g. using an `after_create` hook). - 1. Schedule jobs for all existing rows in a post-deployment migration. It's - possible some newly created rows may be scheduled twice so your migration - should take care of this. + 1. Create a migration class that perform the migration for a row with a given ID. + 1. Deploy the code for this release, this should include some code that will + schedule jobs for newly created data (e.g. using an `after_create` hook). + 1. Schedule jobs for all existing rows in a post-deployment migration. It's + possible some newly created rows may be scheduled twice so your migration + should take care of this. 1. Release B: - 1. Deploy code so that the application starts using the new column and stops - scheduling jobs for newly created data. - 1. In a post-deployment migration you'll need to ensure no jobs remain. - 1. Use `Gitlab::BackgroundMigration.steal` to process any remaining - jobs in Sidekiq. - 1. Reschedule the migration to be run directly (i.e. not through Sidekiq) - on any rows that weren't migrated by Sidekiq. This can happen if, for - instance, Sidekiq received a SIGKILL, or if a particular batch failed - enough times to be marked as dead. - 1. Remove the old column. + 1. Deploy code so that the application starts using the new column and stops + scheduling jobs for newly created data. + 1. In a post-deployment migration you'll need to ensure no jobs remain. + 1. Use `Gitlab::BackgroundMigration.steal` to process any remaining + jobs in Sidekiq. + 1. Reschedule the migration to be run directly (i.e. not through Sidekiq) + on any rows that weren't migrated by Sidekiq. This can happen if, for + instance, Sidekiq received a SIGKILL, or if a particular batch failed + enough times to be marked as dead. + 1. Remove the old column. This may also require a bump to the [import/export version][import-export], if importing a project from a prior version of GitLab requires the data to be in diff --git a/doc/development/changelog.md b/doc/development/changelog.md index 9e0c81b3d60..f06d40d1dbb 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -110,7 +110,8 @@ At this point the script would ask you to select the category of the change (map 4. New deprecation 5. Feature removal 6. Security fix -7. Other +7. Performance improvement +8. Other ``` The entry filename is based on the name of the current Git branch. If you run diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 23c80799235..edf0b6f46df 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -5,30 +5,31 @@ There are a few rules to get your merge request accepted: 1. Your merge request should only be **merged by a [maintainer][team]**. - 1. If your merge request includes only backend changes [^1], it must be - **approved by a [backend maintainer][projects]**. - 1. If your merge request includes only frontend changes [^1], it must be - **approved by a [frontend maintainer][projects]**. - 1. If your merge request includes UX changes [^1], it must - be **approved by a [UX team member][team]**. - 1. If your merge request includes adding a new JavaScript library [^1], it must be - **approved by a [frontend lead][team]**. - 1. If your merge request includes adding a new UI/UX paradigm [^1], it must be - **approved by a [UX lead][team]**. - 1. If your merge request includes frontend and backend changes [^1], it must - be **approved by a [frontend and a backend maintainer][projects]**. - 1. If your merge request includes UX and frontend changes [^1], it must - be **approved by a [UX team member and a frontend maintainer][team]**. - 1. If your merge request includes UX, frontend and backend changes [^1], it must - be **approved by a [UX team member, a frontend and a backend maintainer][team]**. - 1. If your merge request includes a new dependency or a filesystem change, it must - be *approved by a [Distribution team member][team]*. See how to work with the [Distribution team for more details.](https://about.gitlab.com/handbook/engineering/dev-backend/distribution/) + 1. If your merge request includes only backend changes [^1], it must be + **approved by a [backend maintainer][projects]**. + 1. If your merge request includes only frontend changes [^1], it must be + **approved by a [frontend maintainer][projects]**. + 1. If your merge request includes UX changes [^1], it must + be **approved by a [UX team member][team]**. + 1. If your merge request includes adding a new JavaScript library [^1], it must be + **approved by a [frontend lead][team]**. + 1. If your merge request includes adding a new UI/UX paradigm [^1], it must be + **approved by a [UX lead][team]**. + 1. If your merge request includes frontend and backend changes [^1], it must + be **approved by a [frontend and a backend maintainer][projects]**. + 1. If your merge request includes UX and frontend changes [^1], it must + be **approved by a [UX team member and a frontend maintainer][team]**. + 1. If your merge request includes UX, frontend and backend changes [^1], it must + be **approved by a [UX team member, a frontend and a backend maintainer][team]**. + 1. If your merge request includes a new dependency or a filesystem change, it must + be *approved by a [Distribution team member][team]*. See how to work with the [Distribution team for more details.](https://about.gitlab.com/handbook/engineering/dev-backend/distribution/) 1. To lower the amount of merge requests maintainers need to review, you can - ask or assign any [reviewers][projects] for a first review. - 1. If you need some guidance (e.g. it's your first merge request), feel free - to ask one of the [Merge request coaches][team]. - 1. The reviewer will assign the merge request to a maintainer once the - reviewer is satisfied with the state of the merge request. + ask or assign any [reviewers][projects] for a first review. + 1. If you need some guidance (e.g. it's your first merge request), feel free + to ask one of the [Merge request coaches][team]. + 1. It is recommended that you assign a maintainer that is from a different team than your own. + This ensures that all code across GitLab is consistent and can be easily understood by all contributors. + 1. Keep in mind that maintainers are also going to perform a final code review. The ideal scenario is that the reviewer has already addressed any concerns the maintainer would have found, and the maintainer only has to perform the @@ -160,41 +161,41 @@ Enterprise Edition instance. This has some implications: 1. **Query changes** should be tested to ensure that they don't result in worse performance at the scale of GitLab.com: - 1. Generating large quantities of data locally can help. - 2. Asking for query plans from GitLab.com is the most reliable way to validate - these. + 1. Generating large quantities of data locally can help. + 2. Asking for query plans from GitLab.com is the most reliable way to validate + these. 2. **Database migrations** must be: - 1. Reversible. - 2. Performant at the scale of GitLab.com - ask a maintainer to test the - migration on the staging environment if you aren't sure. - 3. Categorised correctly: - - Regular migrations run before the new code is running on the instance. - - [Post-deployment migrations](post_deployment_migrations.md) run _after_ - the new code is deployed, when the instance is configured to do that. - - [Background migrations](background_migrations.md) run in Sidekiq, and - should only be done for migrations that would take an extreme amount of - time at GitLab.com scale. + 1. Reversible. + 2. Performant at the scale of GitLab.com - ask a maintainer to test the + migration on the staging environment if you aren't sure. + 3. Categorised correctly: + - Regular migrations run before the new code is running on the instance. + - [Post-deployment migrations](post_deployment_migrations.md) run _after_ + the new code is deployed, when the instance is configured to do that. + - [Background migrations](background_migrations.md) run in Sidekiq, and + should only be done for migrations that would take an extreme amount of + time at GitLab.com scale. 3. **Sidekiq workers** [cannot change in a backwards-incompatible way](sidekiq_style_guide.md#removing-or-renaming-queues): - 1. Sidekiq queues are not drained before a deploy happens, so there will be - workers in the queue from the previous version of GitLab. - 2. If you need to change a method signature, try to do so across two releases, - and accept both the old and new arguments in the first of those. - 3. Similarly, if you need to remove a worker, stop it from being scheduled in - one release, then remove it in the next. This will allow existing jobs to - execute. - 4. Don't forget, not every instance will upgrade to every intermediate version - (some people may go from X.1.0 to X.10.0, or even try bigger upgrades!), so - try to be liberal in accepting the old format if it is cheap to do so. + 1. Sidekiq queues are not drained before a deploy happens, so there will be + workers in the queue from the previous version of GitLab. + 2. If you need to change a method signature, try to do so across two releases, + and accept both the old and new arguments in the first of those. + 3. Similarly, if you need to remove a worker, stop it from being scheduled in + one release, then remove it in the next. This will allow existing jobs to + execute. + 4. Don't forget, not every instance will upgrade to every intermediate version + (some people may go from X.1.0 to X.10.0, or even try bigger upgrades!), so + try to be liberal in accepting the old format if it is cheap to do so. 4. **Cached values** may persist across releases. If you are changing the type a cached value returns (say, from a string or nil to an array), change the cache key at the same time. 5. **Settings** should be added as a [last resort](https://about.gitlab.com/handbook/product/#convention-over-configuration). If you're adding a new setting in `gitlab.yml`: - 1. Try to avoid that, and add to `ApplicationSetting` instead. - 2. Ensure that it is also - [added to Omnibus](https://docs.gitlab.com/omnibus/settings/gitlab.yml.html#adding-a-new-setting-to-gitlab-yml). + 1. Try to avoid that, and add to `ApplicationSetting` instead. + 2. Ensure that it is also + [added to Omnibus](https://docs.gitlab.com/omnibus/settings/gitlab.yml.html#adding-a-new-setting-to-gitlab-yml). 6. **Filesystem access** can be slow, so try to avoid [shared files](shared_files.md) when an alternative solution is available. diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md new file mode 100644 index 00000000000..c508969f7f4 --- /dev/null +++ b/doc/development/contributing/community_roles.md @@ -0,0 +1,12 @@ +### Community members & roles + +GitLab community members and their privileges/responsibilities. + +| Roles | Responsibilities | Requirements | +|-------|------------------|--------------| +| Maintainer | Accepts merge requests on several GitLab projects | Added to the [team page](https://about.gitlab.com/team/). An expert on code reviews and knows the product/code base | +| Reviewer | Performs code reviews on MRs | Added to the [team page](https://about.gitlab.com/team/) | +| Developer |Has access to GitLab internal infrastructure & issues (e.g. HR-related) | GitLab employee or a Core Team member (with an NDA) | +| Contributor | Can make contributions to all GitLab public projects | Have a GitLab.com account | + +[List of current reviewers/maintainers](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce)
\ No newline at end of file diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index 57ae318e821..be7891061f9 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -1,13 +1,4 @@ -<!-- START doctoc generated TOC please keep comment here to allow auto update --> -<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - -- [Implement design & UI elements](#implement-design--ui-elements) -- [Style guides](#style-guides) - -<!-- END doctoc generated TOC please keep comment here to allow auto update --> - -## Implement design & UI elements +# Implement design & UI elements For guidance on UX implementation at GitLab, please refer to our [Design System](https://design.gitlab.com/). @@ -25,34 +16,36 @@ There is a special type label called ~"product discovery". It represents a disco The initial issue should be about the problem we are solving. If a separate [product discovery issue](#product-discovery-issues) is needed for additional research and design work, it will be created by a PM or UX person. Assign the ~UX, ~"product discovery" and ~"Deliverable" labels, add a milestone and use a title that makes it clear that the scheduled issue is product discovery (e.g. `Product discovery for XYZ`). -When the ~"product discovery" issue has been completed, the UXer removes the ~UX -label, adds the ~"UX ready" label and closes the issue. This indicates the -UX work for the issue is complete. The UXer will also copy any designs to related -issues for implementation in an upcoming milestone. +In order to complete a product discovery issue in a release, you must complete the following: + +1. UXer removes the ~UX label, adds the ~"UX ready" label. +1. Modify the issue description in the product discovery issue to contain the final design. If it makes sense, the original information indicating the need for the design can be moved to a lower "Original Information" section. +1. Copy the design to the description of the delivery issue for which the product discovery issue was created. Do not simply refer to the product discovery issue as a separate source of truth. +1. In some cases, a product discovery issue also identifies future enhancements that will not go into the issue that originated the product discovery issue. For these items, create new issues containing the designs to ensure they are not lost. Put the issues in the backlog if they are agreed upon as good ideas. Otherwise leave them for triage. ## Style guides -1. [Ruby](https://github.com/bbatsov/ruby-style-guide). - Important sections include [Source Code Layout][rss-source] and - [Naming][rss-naming]. Use: - - multi-line method chaining style **Option A**: dot `.` on the second line - - string literal quoting style **Option A**: single quoted by default -1. [Rails](https://github.com/bbatsov/rails-style-guide) -1. [Newlines styleguide][newlines-styleguide] -1. [Testing][testing] -1. [JavaScript styleguide][js-styleguide] -1. [SCSS styleguide][scss-styleguide] -1. [Shell commands](../shell_commands.md) created by GitLab - contributors to enhance security -1. [Database Migrations](../migration_style_guide.md) -1. [Markdown](http://www.cirosantilli.com/markdown-styleguide) -1. [Documentation styleguide](https://docs.gitlab.com/ee/development/documentation/styleguide.html) -1. Interface text should be written subjectively instead of objectively. It - should be the GitLab core team addressing a person. It should be written in - present time and never use past tense (has been/was). For example instead - of _prohibited this user from being saved due to the following errors:_ the - text should be _sorry, we could not create your account because:_ -1. Code should be written in [US English][us-english] +1. [Ruby](https://github.com/bbatsov/ruby-style-guide). + Important sections include [Source Code Layout][rss-source] and + [Naming][rss-naming]. Use: + - multi-line method chaining style **Option A**: dot `.` on the second line + - string literal quoting style **Option A**: single quoted by default +1. [Rails](https://github.com/bbatsov/rails-style-guide) +1. [Newlines styleguide][newlines-styleguide] +1. [Testing][testing] +1. [JavaScript styleguide][js-styleguide] +1. [SCSS styleguide][scss-styleguide] +1. [Shell commands](../shell_commands.md) created by GitLab + contributors to enhance security +1. [Database Migrations](../migration_style_guide.md) +1. [Markdown](http://www.cirosantilli.com/markdown-styleguide) +1. [Documentation styleguide](https://docs.gitlab.com/ee/development/documentation/styleguide.html) +1. Interface text should be written subjectively instead of objectively. It + should be the GitLab core team addressing a person. It should be written in + present time and never use past tense (has been/was). For example instead + of _prohibited this user from being saved due to the following errors:_ the + text should be _sorry, we could not create your account because:_ +1. Code should be written in [US English][us-english] This is also the style used by linting tools such as [RuboCop](https://github.com/bbatsov/rubocop), diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 64f5a2c8022..f4486ae3549 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -1,41 +1,4 @@ -<!-- START doctoc generated TOC please keep comment here to allow auto update --> -<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - -- [Contribute to GitLab](#contribute-to-gitlab) -- [Security vulnerability disclosure](#security-vulnerability-disclosure) -- [Code of conduct](#code-of-conduct) -- [Closing policy for issues and merge requests](#closing-policy-for-issues-and-merge-requests) -- [Helping others](#helping-others) -- [I want to contribute!](#i-want-to-contribute) -- [Contribution Flow](#contribution-flow) -- [Workflow labels](#workflow-labels) - - [Type labels](#type-labels) - - [Subject labels](#subject-labels) - - [Team labels](#team-labels) - - [Milestone labels](#milestone-labels) - - [Bug Priority labels](#bug-priority-labels) - - [Bug Severity labels](#bug-severity-labels) - - [Severity impact guidance](#severity-impact-guidance) - - [Label for community contributors](#label-for-community-contributors) -- [Implement design & UI elements](#implement-design--ui-elements) -- [Issue tracker](#issue-tracker) - - [Issue triaging](#issue-triaging) - - [Feature proposals](#feature-proposals) - - [Issue tracker guidelines](#issue-tracker-guidelines) - - [Issue weight](#issue-weight) - - [Regression issues](#regression-issues) - - [Technical and UX debt](#technical-and-ux-debt) - - [Stewardship](#stewardship) -- [Merge requests](#merge-requests) - - [Merge request guidelines](#merge-request-guidelines) - - [Contribution acceptance criteria](#contribution-acceptance-criteria) -- [Definition of done](#definition-of-done) -- [Style guides](#style-guides) - -<!-- END doctoc generated TOC please keep comment here to allow auto update --> - -## Contribute to GitLab +# Contribute to GitLab For a first-time step-by-step guide to the contribution process, see ["Contributing to GitLab"](https://about.gitlab.com/contributing/). diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 6a334e9b17d..2f06677bfec 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -1,27 +1,4 @@ -<!-- START doctoc generated TOC please keep comment here to allow auto update --> -<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - -- [Workflow labels](#workflow-labels) - - [Type labels](#type-labels) - - [Subject labels](#subject-labels) - - [Team labels](#team-labels) - - [Release Scoping labels](#release-scoping-labels) - - [Priority labels](#priority-labels) - - [Severity labels](#severity-labels) - - [Severity impact guidance](#severity-impact-guidance) - - [Label for community contributors](#label-for-community-contributors) - - [Issue triaging](#issue-triaging) - - [Feature proposals](#feature-proposals) - - [Issue tracker guidelines](#issue-tracker-guidelines) - - [Issue weight](#issue-weight) - - [Regression issues](#regression-issues) - - [Technical and UX debt](#technical-and-ux-debt) - - [Stewardship](#stewardship) - -<!-- END doctoc generated TOC please keep comment here to allow auto update --> - -## Workflow labels +# Workflow labels To allow for asynchronous issue handling, we use [milestones][milestones-page] and [labels][labels-page]. Leads and product managers handle most of the @@ -45,7 +22,7 @@ labels, you can _always_ add the team and type, and often also the subject. [milestones-page]: https://gitlab.com/gitlab-org/gitlab-ce/milestones [labels-page]: https://gitlab.com/gitlab-org/gitlab-ce/labels -### Type labels +## Type labels Type labels are very important. They define what kind of issue this is. Every issue should have one or more. @@ -61,7 +38,7 @@ already reserved for subject labels). The descriptions on the [labels page][labels-page] explain what falls under each type label. -### Subject labels +## Subject labels Subject labels are labels that define what area or feature of GitLab this issue hits. They are not always necessary, but very convenient. @@ -75,7 +52,7 @@ issue is labeled with a subject label corresponding to your expertise. Subject labels are always all-lowercase. -### Team labels +## Team labels Team labels specify what team is responsible for this issue. Assigning a team label makes sure issues get the attention of the appropriate @@ -83,7 +60,7 @@ people. The current team labels are: -- ~Configuration +- ~Configure - ~"CI/CD" - ~Create - ~Distribution @@ -107,7 +84,7 @@ indicate if an issue needs backend work, frontend work, or both. Team labels are always capitalized so that they show up as the first label for any issue. -### 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: @@ -138,7 +115,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) | | ~P4 | Low Priority | Anything outside the next 3 releases (approx beyond one quarter) | -### Severity labels +## Severity labels Severity labels help us clearly communicate the impact of a ~bug on users. @@ -149,7 +126,7 @@ Severity labels help us clearly communicate the impact of a ~bug on users. | ~S3 | Major Severity | Broken Feature, workaround acceptable | Can create merge requests only from the Merge Requests page, not through the Issue. | | ~S4 | Low Severity | Functionality inconvenience or cosmetic issue | Label colors are incorrect / not being displayed. | -#### Severity impact guidance +### Severity impact guidance Severity levels can be applied further depending on the facet of the impact; e.g. Affected customers, GitLab.com availability, performance and etc. The below is a guideline. @@ -160,7 +137,7 @@ Severity levels can be applied further depending on the facet of the impact; e.g | ~S3 | A few users or a single paid customer affected | Limited impact on important portions of GitLab.com | Degradation is likely to occur in the near future | | ~S4 | No paid users/customer affected, or expected to in the near future | Minor impact on on GitLab.com | Degradation _may_ occur but it's not likely | -### 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 @@ -200,7 +177,7 @@ 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) as soon as possible. The product manager will then pull in appropriate GitLab team members to further discuss scope, design, and technical considerations. This will -ensure that that your contribution is aligned with the GitLab product and minimize +ensure that your contribution is aligned with the GitLab product and minimize any rework and delay in getting it merged into master. GitLab team members who apply the ~"Accepting Merge Requests" label to an issue @@ -210,8 +187,7 @@ any potential community contributor to @-mention per above. [up-for-grabs]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=Accepting+Merge+Requests&scope=all&sort=weight_asc&state=opened [firt-timers]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name%5B%5D=Accepting+Merge+Requests&scope=all&sort=upvotes_desc&state=opened&weight=1 - -### Issue triaging +## 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 @@ -224,7 +200,7 @@ on those issues. Please select someone with relevant experience from the the commit history for the affected files to find someone. We also use [GitLab Triage] to automate some triaging policies. This is -currently setup as a [scheduled pipeline] running on [quality/triage-ops] +currently set up as a [scheduled pipeline] running on [quality/triage-ops] project. [described in our handbook]: https://about.gitlab.com/handbook/engineering/issue-triage/ @@ -233,7 +209,7 @@ project. [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 -### Feature proposals +## Feature proposals To create a feature proposal for CE, open an issue on the [issue tracker of CE][ce-tracker]. @@ -250,7 +226,7 @@ code snippet right after your description in a new line: `~"feature proposal"`. Please keep feature proposals as small and simple as possible, complex ones might be edited to make them small and simple. -Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/Feature Proposal.md) provided on the issue tracker. +Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/Feature%20proposal.md) provided on the issue tracker. For changes in the interface, it is helpful to include a mockup. Issues that add to, or change, the interface should be given the ~"UX" label. This will allow the UX team to provide input and guidance. You may @@ -259,7 +235,7 @@ need to ask one of the [core team] members to add the label, if you do not have If you want to create something yourself, consider opening an issue first to discuss whether it is interesting to include this in GitLab. -### Issue tracker guidelines +## 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 @@ -271,7 +247,7 @@ 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 Issue weight allows us to get an idea of the amount of work required to solve one or multiple issues. This makes it possible to schedule work more accurately. @@ -293,7 +269,7 @@ is probably 1, adding a new Git Hook maybe 4 or 5, big features 7-9. issues or chunks. You can simply not set the weight of a parent issue and set weights to children issues. -### Regression issues +## Regression issues Every monthly release has a corresponding issue on the CE issue tracker to keep track of functionality broken by that release and any fixes that need to be @@ -313,7 +289,7 @@ addressed. [8.3 Regressions]: https://gitlab.com/gitlab-org/gitlab-ce/issues/4127 [update the notes]: https://gitlab.com/gitlab-org/release-tools/blob/master/doc/pro-tips.md#update-the-regression-issue -### Technical and UX debt +## 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]. @@ -337,7 +313,7 @@ for a release by the appropriate person. Make sure to mention the merge request that the ~"technical debt" issue or ~"UX debt" issue is associated with in the description of the issue. -### Stewardship +## Stewardship For issues related to the open source stewardship of GitLab, there is the ~"stewardship" label. diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 9b1da4e7bc1..a286e74908c 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -1,15 +1,4 @@ -<!-- START doctoc generated TOC please keep comment here to allow auto update --> -<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - -- [Merge requests](#merge-requests) - - [Merge request guidelines](#merge-request-guidelines) - - [Contribution acceptance criteria](#contribution-acceptance-criteria) -- [Definition of done](#definition-of-done) - -<!-- END doctoc generated TOC please keep comment here to allow auto update --> - -## Merge requests +# Merge requests We welcome merge requests with fixes and improvements to GitLab code, tests, and/or documentation. The issues that are specifically suitable for @@ -36,7 +25,7 @@ some potentially easy issues. To start with GitLab development download the [GitLab Development Kit][gdk] and see the [Development section](../README.md) for some guidelines. -### Merge request guidelines +## Merge request guidelines If you can, please submit a merge request with the fix or improvements including tests. If you don't know how to fix the issue but can write a test @@ -55,30 +44,30 @@ request is as follows: organized commits by [squashing them][git-squash] 1. Push the commit(s) to your fork 1. Submit a merge request (MR) to the `master` branch - 1. Your merge request needs at least 1 approval but feel free to require more. - For instance if you're touching backend and frontend code, it's a good idea - to require 2 approvals: 1 from a backend maintainer and 1 from a frontend - maintainer - 1. You don't have to select any approvers, but you can if you really want - specific people to approve your merge request + 1. Your merge request needs at least 1 approval but feel free to require more. + For instance if you're touching backend and frontend code, it's a good idea + to require 2 approvals: 1 from a backend maintainer and 1 from a frontend + maintainer + 1. You don't have to select any approvers, but you can if you really want + specific people to approve your merge request 1. The MR title should describe the change you want to make 1. The MR description should give a motive for your change and the method you used to achieve it. - 1. If you are contributing code, fill in the template already provided in the - "Description" field. - 1. If you are contributing documentation, choose `Documentation` from the - "Choose a template" menu and fill in the template. - 1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or - `Closes #XXX` syntax to auto-close the issue(s) once the merge request will - be merged. + 1. If you are contributing code, fill in the template already provided in the + "Description" field. + 1. If you are contributing documentation, choose `Documentation` from the + "Choose a template" menu and fill in the template. + 1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or + `Closes #XXX` syntax to auto-close the issue(s) once the merge request will + be merged. 1. If you're allowed to, set a relevant milestone and labels 1. If the MR changes the UI it should include *Before* and *After* screenshots 1. If the MR changes CSS classes please include the list of affected pages, `grep css-class ./app -R` 1. Be prepared to answer questions and incorporate feedback even if requests for this arrive weeks or months after your MR submission - 1. If a discussion has been addressed, select the "Resolve discussion" button - beneath it to mark it resolved. + 1. If a discussion has been addressed, select the "Resolve discussion" button + beneath it to mark it resolved. 1. If your MR touches code that executes shell commands, reads or opens files or handles paths to files on disk, make sure it adheres to the [shell command guidelines](../shell_commands.md) @@ -114,7 +103,7 @@ Please ensure that your merge request meets the contribution acceptance criteria When having your code reviewed and when reviewing merge requests please take the [code review guidelines](../code_review.md) into account. -### Contribution acceptance criteria +## Contribution acceptance criteria 1. The change is as small as possible 1. Include proper tests and make all tests pass (unless it contains a test @@ -138,7 +127,7 @@ When having your code reviewed and when reviewing merge requests please take the making and testing future changes 1. Changes do not adversely degrade performance. - Avoid repeated polling of endpoints that require a significant amount of overhead - - Check for N+1 queries via the SQL log or [`QueryRecorder`](https://docs.gitlab.com/ce/development/mer ge_request_performance_guidelines.html) + - Check for N+1 queries via the SQL log or [`QueryRecorder`](https://docs.gitlab.com/ce/development/merge_request_performance_guidelines.html) - Avoid repeated access of filesystem 1. If you need polling to support real-time features, please use [polling with ETag caching][polling-etag]. diff --git a/doc/development/database_debugging.md b/doc/development/database_debugging.md index 9c31265e417..b2c804b2ff0 100644 --- a/doc/development/database_debugging.md +++ b/doc/development/database_debugging.md @@ -33,7 +33,7 @@ If your test DB is giving you problems, it is safe to nuke it because it doesn't - `bundle exec rake db:migrate RAILS_ENV=development`: Execute any pending migrations that you may have picked up from a MR - `bundle exec rake db:migrate:status RAILS_ENV=development`: Check if all migrations are `up` or `down` - `bundle exec rake db:migrate:down VERSION=20170926203418 RAILS_ENV=development`: Tear down a migration - - `bundle exec rake db:migrate:up VERSION=20170926203418 RAILS_ENV=development`: Setup a migration + - `bundle exec rake db:migrate:up VERSION=20170926203418 RAILS_ENV=development`: Set up a migration - `bundle exec rake db:migrate:redo VERSION=20170926203418 RAILS_ENV=development`: Re-run a specific migration diff --git a/doc/development/database_helpers.md b/doc/development/database_helpers.md new file mode 100644 index 00000000000..21e4e725de6 --- /dev/null +++ b/doc/development/database_helpers.md @@ -0,0 +1,63 @@ +# Database helpers + +There are a number of useful helper modules defined in `/lib/gitlab/database/`. + +## Subquery + +In some cases it is not possible to perform an operation on a query. +For example: + +```ruby +Geo::EventLog.where('id < 100').limit(10).delete_all +``` + +Will give this error: + +> ActiveRecord::ActiveRecordError: delete_all doesn't support limit + +One solution would be to wrap it in another `where`: + +```ruby +Geo::EventLog.where(id: Geo::EventLog.where('id < 100').limit(10)).delete_all +``` + +This works with PostgreSQL, but with MySQL it gives this error: + +> ActiveRecord::StatementInvalid: Mysql2::Error: This version of MySQL +> doesn't yet support 'LIMIT & IN/ALL/ANY/SOME subquery' + +Also, that query doesn't have very good performance. Using a +`INNER JOIN` with itself is better. + +So instead of this query: + +```sql +SELECT geo_event_log.* +FROM geo_event_log +WHERE geo_event_log.id IN + (SELECT geo_event_log.id + FROM geo_event_log + WHERE (id < 100) + LIMIT 10) +``` + +It's better to write: + +```sql +SELECT geo_event_log.* +FROM geo_event_log +INNER JOIN + (SELECT geo_event_log.* + FROM geo_event_log + WHERE (id < 100) + LIMIT 10) t2 ON geo_event_log.id = t2.id +``` + +And this is where `Gitlab::Database::Subquery.self_join` can help +you. So you can rewrite the above statement as: + +```ruby +Gitlab::Database::Subquery.self_join(Geo::EventLog.where('id < 100').limit(10)).delete_all +``` + +And this also works with MySQL, so you don't need to worry about that. diff --git a/doc/development/diffs.md b/doc/development/diffs.md index d06339480b1..4adae5dabe2 100644 --- a/doc/development/diffs.md +++ b/doc/development/diffs.md @@ -2,35 +2,33 @@ Currently we rely on different sources to present diffs, these include: -- Rugged gem - Gitaly service - Database (through `merge_request_diff_files`) - Redis (cached highlighted diffs) -We're constantly moving Rugged calls to Gitaly and the progress can be followed through [Gitaly repo](https://gitlab.com/gitlab-org/gitaly). - ## Architecture overview ### Merge request diffs When refreshing a Merge Request (pushing to a source branch, force-pushing to target branch, or if the target branch now contains any commits from the MR) we fetch the comparison information using `Gitlab::Git::Compare`, which fetches `base` and `head` data using Gitaly and diff between them through -`Gitlab::Git::Diff.between` (which uses _Gitaly_ if it's enabled, otherwise _Rugged_). +`Gitlab::Git::Diff.between`. The diffs fetching process _limits_ single file diff sizes and the overall size of the whole diff through a series of constant values. Raw diff files are -then persisted on `merge_request_diff_files` table. +then persisted on `merge_request_diff_files` table. -Even though diffs higher than 10kb are collapsed (`Gitlab::Git::Diff::COLLAPSE_LIMIT`), we still keep them on Postgres. However, diff files over _safety limits_ -(see the [Diff limits section](#diff-limits)) are _not_ persisted. +Even though diffs larger than 10% of the value of `ApplicationSettings#diff_max_patch_bytes` are collapsed, +we still keep them on Postgres. However, diff files larger than defined _safety limits_ +(see the [Diff limits section](#diff-limits)) are _not_ persisted in the database. In order to present diffs information on the Merge Request diffs page, we: 1. Fetch all diff files from database `merge_request_diff_files` 2. Fetch the _old_ and _new_ file blobs in batch to: - 1. Highlight old and new file content - 2. Know which viewer it should use for each file (text, image, deleted, etc) - 3. Know if the file content changed - 4. Know if it was stored externally - 5. Know if it had storage errors + 1. Highlight old and new file content + 2. Know which viewer it should use for each file (text, image, deleted, etc) + 3. Know if the file content changed + 4. Know if it was stored externally + 5. Know if it had storage errors 3. If the diff file is cacheable (text-based), it's cached on Redis using `Gitlab::Diff::FileCollection::MergeRequestDiff` @@ -63,55 +61,59 @@ File diffs will be collapsed (but be expandable) if 100 files have already been ```ruby -Gitlab::Git::DiffCollection.collection_limits[:safe_max_lines] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 +Gitlab::Git::DiffCollection.collection_limits[:safe_max_lines] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 ``` File diffs will be collapsed (but be expandable) if 5000 lines have already been rendered. ```ruby -Gitlab::Git::DiffCollection.collection_limits[:safe_max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] * 5.kilobytes = 500.kilobytes +Gitlab::Git::DiffCollection.collection_limits[:safe_max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] * 5.kilobytes = 500.kilobytes ``` File diffs will be collapsed (but be expandable) if 500 kilobytes have already been rendered. ```ruby -Gitlab::Git::DiffCollection.collection_limits[:max_files] = Commit::DIFF_HARD_LIMIT_FILES = 1000 +Gitlab::Git::DiffCollection.collection_limits[:max_files] = Commit::DIFF_HARD_LIMIT_FILES = 1000 ``` No more files will be rendered at all if 1000 files have already been rendered. ```ruby -Gitlab::Git::DiffCollection.collection_limits[:max_lines] = Commit::DIFF_HARD_LIMIT_LINES = 50000 +Gitlab::Git::DiffCollection.collection_limits[:max_lines] = Commit::DIFF_HARD_LIMIT_LINES = 50000 ``` No more files will be rendered at all if 50,000 lines have already been rendered. ```ruby -Gitlab::Git::DiffCollection.collection_limits[:max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:max_files] * 5.kilobytes = 5000.kilobytes +Gitlab::Git::DiffCollection.collection_limits[:max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:max_files] * 5.kilobytes = 5000.kilobytes ``` No more files will be rendered at all if 5 megabytes have already been rendered. +*Note:* All collection limit parameters are currently sent and applied on Gitaly. That is, once the limit is surpassed, +Gitaly will only return the safe amount of data to be persisted on `merge_request_diff_files`. ### Individual diff file limits Limits that act onto each diff file of a collection. Files number, lines number and files size are considered. -```ruby -Gitlab::Git::Diff::COLLAPSE_LIMIT = 10.kilobytes -``` +#### Expandable patches (collapsed) -File diff will be collapsed (but be expandable) if it is larger than 10 kilobytes. +Diff patches are collapsed when surpassing 10% of the value set in `ApplicationSettings#diff_max_patch_bytes`. +That is, it's equivalent to 10kb if the maximum allowed value is 100kb. +The diff will still be persisted and expandable if the patch size doesn't +surpass `ApplicationSettings#diff_max_patch_bytes`. -```ruby -Gitlab::Git::Diff::SIZE_LIMIT = 100.kilobytes -``` +*Note:* Although this nomenclature (Collapsing) is also used on Gitaly, this limit is only used on GitLab (hardcoded - not sent to Gitaly). +Gitaly will only return `Diff.Collapsed` (RPC) when surpassing collection limits. -File diff will not be rendered if it's larger than 100 kilobytes. +#### Not expandable patches (too large) +The patch not be rendered if it's larger than `ApplicationSettings#diff_max_patch_bytes`. +Users will see a `This source diff could not be displayed because it is too large` message. ```ruby Commit::DIFF_SAFE_LINES = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 @@ -119,10 +121,12 @@ Commit::DIFF_SAFE_LINES = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines File diff will be suppressed (technically different from collapsed, but behaves the same, and is expandable) if it has more than 5000 lines. +*Note:* This limit is currently hardcoded and only applied on GitLab. + ## Viewers Diff Viewers, which can be found on `models/diff_viewer/*` are classes used to map metadata about each type of Diff File. It has information -whether it's a binary, which partial should be used to render it or which File extensions this class accounts for. +whether it's a binary, which partial should be used to render it or which File extensions this class accounts for. `DiffViewer::Base` validates _blobs_ (old and new versions) content, extension and file type in order to check if it can be rendered. diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index f46c171d9f1..2db78e4a365 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -43,13 +43,13 @@ how to structure GitLab docs. Currently GitLab docs use Redcarpet as [markdown](../../user/markdown.md) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future. -All the docs follow the [documentation style guidelines](styleguide.md). +All the docs follow the [documentation style guidelines](styleguide.md). See [Linting](#linting) for help to follow the guidelines. ## Documentation directory structure The documentation is structured based on the GitLab UI structure itself, separated by [`user`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/user), -[`administrator`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`contributor`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development). +[`administrator`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`contributor`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development). In order to have a [solid site structure](https://searchengineland.com/seo-benefits-developing-solid-site-structure-277456) for our documentation, all docs should be linked. Every new document should be cross-linked to its related documentation, and linked from its topic-related index, when existent. @@ -223,6 +223,108 @@ redirect_from: 'https://docs.gitlab.com/my-old-location/README.html' Note: it is necessary to include the file name in the `redirect_from` URL, even if it's `index.html` or `README.html`. +## Linting + +To help adhere to the [documentation style guidelines](styleguide.md), and to improve the content + added to documentation, consider locally installing and running documentation linters. This will + help you catch common issues before raising merge requests for review of documentation. + +The following are some suggested linters you can install locally and sample configuration: + +- `proselint` +- `markdownlint` + +NOTE: **Note:** +This list does not limit what other linters you can add to your local documentation writing + toolchain. + +### `proselint` + +`proselint` checks for common problems with English prose. It provides a + [plethora of checks](http://proselint.com/checks/) that are helpful for technical writing. + +`proselint` can be used [on the command line](http://proselint.com/utility/), either on a single + Markdown file or on all Markdown files in a project. For example, to run `proselint` on all + documentation in the [`gitlab-ce` project](https://gitlab.com/gitlab-org/gitlab-ce), run the + following commands from within the `gitlab-ce` project: + +```sh +cd doc +proselint **/*.md +``` + +`proselint` can also be run from within editors using plugins. For example, the following plugins + are available: + +- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-proselint) +- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=PatrykPeszko.vscode-proselint) +- [Others](https://github.com/amperser/proselint#plugins-for-other-software) + +#### Sample `proselint` configuration + +All of the checks are good to use. However, excluding the `typography.symbols` checks might reduce + noise. The following sample `proselint` configuration disables the `typography.symbols` checks: + +```json +{ + "checks": { + "typography.symbols": false + } +} +``` + +A file with `proselint` configuration must be placed in a + [valid location](https://github.com/amperser/proselint#checks). For example, `~/.config/proselint/config`. + +### `markdownlint` + +`markdownlint` checks that certain rules ([example](https://github.com/DavidAnson/markdownlint/blob/master/README.md#rules--aliases)) + are followed for Markdown syntax. Our [style guidelines](styleguide.md) elaborate on which choices + must be made when selecting Markdown syntax for GitLab documentation and this tool helps + catch deviations from those guidelines. + +`markdownlint` can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--), + either on a single Markdown file or on all Markdown files in a project. For example, to run + `markdownlint` on all documentation in the [`gitlab-ce` project](https://gitlab.com/gitlab-org/gitlab-ce), + run the following commands from within the `gitlab-ce` project: + +```sh +cd doc +markdownlint **/*.md +``` + +`markdownlint` can also be run from within editors using plugins. For example, the following plugins + are available: + +- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) +- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) +- [Others](https://github.com/DavidAnson/markdownlint#related) + +#### Sample `markdownlint` configuration + +The following sample `markdownlint` configuration modifies the available default rules to: + +- Adhere to the [style guidelines](styleguide.md). +- Apply conventions found in the GitLab documentation. + +```json +{ + "default": true, + "header-style": { "style": "atx" }, + "ul-style": { "style": "dash" }, + "line-length": false, + "no-trailing-punctuation": false, + "ol-prefix": { "style": "one" }, + "blanks-around-fences": false, + "hr-style": { "style": "---" }, + "fenced-code-language": false +} +``` + +For [`markdownlint`](https://gitahub.com/DavidAnson/markdownlint/), this configuration must be + placed in a [valid location](https://github.com/igorshubovych/markdownlint-cli#configuration). For + example, `~/.markdownlintrc`. + ## Testing We treat documentation as code, thus have implemented some testing. @@ -257,6 +359,15 @@ choices: If your branch name matches any of the above, it will run only the docs tests. If it doesn't, the whole test suite will run (including docs). +## Danger bot + +GitLab uses [danger bot](https://github.com/danger/danger) for some elements in +code review. For docs changes in merge requests, the following actions are taken: + +1. Whenever a change under `/doc` is made, the bot leaves a comment for the + author to mention `@gl-docsteam`, so that the docs can be properly + reviewed. + ## Merge requests for GitLab documentation Before getting started, make sure you read the introductory section @@ -269,7 +380,6 @@ for GitLab Team members. - Label the MR `Documentation` - Assign the correct milestone (see note below) - NOTE: **Note:** If the release version you want to add the documentation to has already been frozen or released, use the label `Pick into X.Y` to get it merged into @@ -402,6 +512,22 @@ The following GitLab features are used among others: Every GitLab instance includes the documentation, which is available from `/help` (`http://my-instance.com/help`), e.g., <https://gitlab.com/help>. +The documentation available online on docs.gitlab.com is continuously +deployed every hour from the `master` branch of CE, EE, Omnibus, and Runner. Therefore, +once a merge request gets merged, it will be available online on the same day, +but they will be shipped (and available on `/help`) within the milestone assigned +to the MR. + +For instance, let's say your merge request has a milestone set to 11.3, which +will be released on 2018-09-22. If it gets merged on 2018-09-15, it will be +available online on 2018-09-15, but, as the feature freeze date has passed, if +the MR does not have a "pick into 11.3" label, the milestone has to be changed +to 11.4 and it will be shipped with all GitLab packages only on 2018-10-22, +with GitLab 11.4. Meaning, it will only be available under `/help` from GitLab +11.4 onwards, but available on docs.gitlab.com on the same day it was merged. + +### Linking to `/help` + When you're building a new feature, you may need to link the documentation from GitLab, the application. This is normally done in files inside the `app/views/` directory with the help of the `help_page_path` helper method. diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 6c60a517b6d..c43f91278de 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -10,13 +10,15 @@ GitLab documentation. Check the Check the GitLab handbook for the [writing styles guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines). +For help adhering to the guidelines, see [Linting](index.md#linting). + ## Files - [Directory structure](index.md#location-and-naming-documents): place the docs -in the correct location -- [Documentation files](index.md#documentation-files): name the files accordingly +in the correct location. +- [Documentation files](index.md#documentation-files): name the files accordingly. - [Markdown](../../user/markdown.md): use the GitLab Flavored Markdown in the -documentation +documentation. NOTE: **Note:** **Do not** use capital letters, spaces, or special chars in file names, @@ -30,17 +32,17 @@ a test that will fail if it spots a new `README.md` file. - Split up long lines (wrap text), this makes it much easier to review and edit. Only double line breaks are shown as a full line break in [GitLab markdown][gfm]. - 80-100 characters is a good line length + 80-100 characters is a good line length. - Make sure that the documentation is added in the correct [directory](index.md#documentation-directory-structure) and that - there's a link to it somewhere useful -- Do not duplicate information -- Be brief and clear -- Unless there's a logical reason not to, add documents in alphabetical order -- Write in US English -- Use [single spaces][] instead of double spaces + there's a link to it somewhere useful. +- Do not duplicate information. +- Be brief and clear. +- Unless there's a logical reason not to, add documents in alphabetical order. +- Write in US English. +- Use [single spaces][] instead of double spaces. - Jump a line between different markups (e.g., after every paragraph, header, list, etc) -- Capitalize "G" and "L" in GitLab +- Capitalize "G" and "L" in GitLab. - Use sentence case for titles, headings, labels, menu items, and buttons. - Use title case when referring to [features](https://about.gitlab.com/features/) or [products](https://about.gitlab.com/pricing/) (e.g., GitLab Runner, Geo, @@ -50,10 +52,9 @@ some features are also objects (e.g. "Merge Requests" and "merge requests"). ## Formatting -- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`) -- Use undescore (`_`) for text in italics (`_italic_`) -- Jump a line between different markups, for example: - +- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`). +- Use undescore (`_`) for text in italics (`_italic_`). +- Put an empty line between different markups. For example: ```md ## Header @@ -69,9 +70,16 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl ### Ordered and unordered lists -- Use dashes (`-`) for unordered lists instead of asterisks (`*`) -- Use the number one (`1`) for ordered lists -- For punctuation in bullet lists, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/) +- Use dashes (`-`) for unordered lists instead of asterisks (`*`). +- Use the number one (`1`) for ordered lists. +- Separate list items from explanatory text with a colon (`:`). For example: + ```md + The list is as follows: + + - First item: This explains the first item. + - Second item: This explains the second item. + ``` +- For further guidance on punctuation in bullet lists, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/). ## Headings @@ -82,7 +90,7 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl - Avoid putting numbers in headings. Numbers shift, hence documentation anchor links shift too, which eventually leads to dead links. If you think it is compelling to add numbers in headings, make sure to at least discuss it with - someone in the Merge Request + someone in the Merge Request. - [Avoid using symbols and special chars](https://gitlab.com/gitlab-com/gitlab-docs/issues/84) in headers. Whenever possible, they should be plain and short text. - Avoid adding things that show ephemeral statuses. For example, if a feature is @@ -92,8 +100,8 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl of the following GitLab members for a review: `@axil` or `@marcia`. This is to ensure that no document with wrong heading is going live without an audit, thus preventing dead links and redirection issues when - corrected -- Leave exactly one new line after a heading + corrected. +- Leave exactly one new line after a heading. ## Links @@ -120,11 +128,11 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl To indicate the steps of navigation through the UI: -- Use the exact word as shown in the UI, including any capital letters as-is +- Use the exact word as shown in the UI, including any capital letters as-is. - Use bold text for navigation items and the char `>` as separator -(e.g., `Navigate to your project's **Settings > CI/CD**` ) +(e.g., `Navigate to your project's **Settings > CI/CD**` ). - If there are any expandable menus, make sure to mention that the user -needs to expand the tab to find the settings you're referring to +needs to expand the tab to find the settings you're referring to. ## Images @@ -149,12 +157,12 @@ Inside the document: `` - Always use a proper description for what the image is about. That way, when a browser fails to show the image, this text will be used as an alternative - description + description. - If there are consecutive images with little text between them, always add three dashes (`---`) between the image and the text to create a horizontal - line for better clarity + line for better clarity. - If a heading is placed right after an image, always add three dashes (`---`) - between the image and the heading + between the image and the heading. ## Alert boxes @@ -245,7 +253,7 @@ below. (in that order) that introduced it. The above quote would be then transformed to: ```md - > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/1242) in GitLab 8.3. + > [Introduced](<link-to-issue>) in GitLab 8.3. ``` - If the feature is only available in GitLab Enterprise Edition, don't forget to mention @@ -253,27 +261,39 @@ below. the feature is available in: ```md - > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/1242) - in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. + > [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. ``` +#### Early versions of EE + +If the feature was created before GitLab 9.2 (before [different EE tiers were introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1851)): + +- Declare it as "Introduced in GitLab Enterprise Edition X.Y". +- Note which tier the feature is available in. + +For example: + +```md +> [Introduced](<link-to-issue>) in GitLab Enterprise Edition 9.0. Available in [GitLab Premium](https://about.gitlab.com/pricing/). +``` + ### Product badges When a feature is available in EE-only tiers, add the corresponding tier according to the feature availability: -- For GitLab Starter and GitLab.com Bronze: `**[STARTER]**` -- For GitLab Premium and GitLab.com Silver: `**[PREMIUM]**` -- For GitLab Ultimate and GitLab.com Gold: `**[ULTIMATE]**` -- For GitLab Core and GitLab.com Free: `**[CORE]**` +- For GitLab Starter and GitLab.com Bronze: `**[STARTER]**`. +- For GitLab Premium and GitLab.com Silver: `**[PREMIUM]**`. +- For GitLab Ultimate and GitLab.com Gold: `**[ULTIMATE]**`. +- For GitLab Core and GitLab.com Free: `**[CORE]**`. To exclude GitLab.com tiers (when the feature is not available in GitLab.com), add the keyword "only": -- For GitLab Starter: `**[STARTER ONLY]**` -- For GitLab Premium: `**[PREMIUM ONLY]**` -- For GitLab Ultimate: `**[ULTIMATE ONLY]**` -- For GitLab Core: `**[CORE ONLY]**` +- For GitLab Starter: `**[STARTER ONLY]**`. +- For GitLab Premium: `**[PREMIUM ONLY]**`. +- For GitLab Ultimate: `**[ULTIMATE ONLY]**`. +- For GitLab Core: `**[CORE ONLY]**`. The tier should be ideally added to headers, so that the full badge will be displayed. But it can be also mentioned from paragraphs, list items, and table cells. For these cases, @@ -297,10 +317,10 @@ avoid duplication, link to the special document that can be found in [`doc/administration/restart_gitlab.md`][doc-restart]. Usually the text will read like: - ``` - Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md) - for the changes to take effect. - ``` +``` +Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md) +for the changes to take effect. +``` If the document you are editing resides in a place other than the GitLab CE/EE `doc/` directory, instead of the relative link, use the full path: @@ -328,8 +348,8 @@ prefer to document it in the CE docs to avoid duplication. Configuration settings include: -- settings that touch configuration files in `config/` -- NGINX settings and settings in `lib/support/` in general +- Settings that touch configuration files in `config/`. +- NGINX settings and settings in `lib/support/` in general. When there is a list of steps to perform, usually that entails editing the configuration file and reconfiguring/restarting GitLab. In such case, follow diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 339ec80f889..52bc059a925 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -31,7 +31,7 @@ only and does not directly affect the way that any regular user or administrator would interact with GitLab. NOTE: **Note:** -When refactoring documentation in needed, it should be submitted it in its own MR. +When refactoring documentation, it should be submitted in its own MR. **Do not** join new features' MRs with refactoring existing docs, as they might have different priorities. diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 1cd873b6fe3..f9e6efa2c30 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -166,47 +166,53 @@ There are a few gotchas with it: to make it call the other method we want to extend, like a [template method pattern](https://en.wikipedia.org/wiki/Template_method_pattern). For example, given this base: - ``` ruby - class Base - def execute - return unless enabled? - # ... - # ... - end - end - ``` - Instead of just overriding `Base#execute`, we should update it and extract - the behaviour into another method: - ``` ruby - class Base - def execute - return unless enabled? - - do_something + ```ruby + class Base + def execute + return unless enabled? + + # ... + # ... + end end + ``` - private + Instead of just overriding `Base#execute`, we should update it and extract + the behaviour into another method: - def do_something - # ... - # ... + ```ruby + class Base + def execute + return unless enabled? + + do_something + end + + private + + def do_something + # ... + # ... + end end - end - ``` - Then we're free to override that `do_something` without worrying about the - guards: - ``` ruby - module EE::Base - extend ::Gitlab::Utils::Override - - override :do_something - def do_something - # Follow the above pattern to call super and extend it + ``` + + Then we're free to override that `do_something` without worrying about the + guards: + + ```ruby + module EE::Base + extend ::Gitlab::Utils::Override + + override :do_something + def do_something + # Follow the above pattern to call super and extend it + end end - end - ``` - This would require updating CE first, or make sure this is back ported to CE. + ``` + + This would require updating CE first, or make sure this is back ported to CE. When prepending, place them in the `ee/` specific sub-directory, and wrap class or module in `module EE` to avoid naming conflicts. @@ -469,7 +475,7 @@ Put the EE module files following For EE API routes, we put them in a `prepended` block: -``` ruby +```ruby module EE module API module MergeRequests @@ -503,7 +509,7 @@ interface first here. For example, suppose we have a few more optional params for EE, given this CE API code: -``` ruby +```ruby module API class MergeRequests < Grape::API # EE::API::MergeRequests would override the following helpers @@ -525,7 +531,7 @@ end And then we could override it in EE module: -``` ruby +```ruby module EE module API module MergeRequests @@ -552,7 +558,7 @@ To make it easy for an EE module to override the CE helpers, we need to define those helpers we want to extend first. Try to do that immediately after the class definition to make it easy and clear: -``` ruby +```ruby module API class JobArtifacts < Grape::API # EE::API::JobArtifacts would override the following helpers @@ -569,7 +575,7 @@ end And then we can follow regular object-oriented practices to override it: -``` ruby +```ruby module EE module API module JobArtifacts @@ -596,7 +602,7 @@ therefore can't be simply overridden. We need to extract them into a standalone method, or introduce some "hooks" where we could inject behavior in the CE route. Something like this: -``` ruby +```ruby module API class MergeRequests < Grape::API helpers do @@ -623,7 +629,7 @@ end Note that `update_merge_request_ee` doesn't do anything in CE, but then we could override it in EE: -``` ruby +```ruby module EE module API module MergeRequests @@ -662,7 +668,7 @@ For example, in one place we need to pass an extra argument to `at_least_one_of` so that the API could consider an EE-only argument as the least argument. This is not quite beautiful but it's working: -``` ruby +```ruby module API class MergeRequests < Grape::API def self.update_params_at_least_one_of @@ -683,7 +689,7 @@ end And then we could easily extend that argument in the EE class method: -``` ruby +```ruby module EE module API module MergeRequests diff --git a/doc/development/fe_guide/components.md b/doc/development/fe_guide/components.md index 66a8abe42f7..ee0c2d534ff 100644 --- a/doc/development/fe_guide/components.md +++ b/doc/development/fe_guide/components.md @@ -42,7 +42,7 @@ See also the [corresponding UX guide](../ux_guide/components.md#dropdowns). See also the [corresponding UX guide](../ux_guide/components.md#modals). -We have a reusable Vue component for modals: [vue_shared/components/gl-modal.vue](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/vue_shared/components/gl-modal.vue) +We have a reusable Vue component for modals: [vue_shared/components/gl_modal.vue](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/vue_shared/components/gl_modal.vue) Here is an example of how to use it: diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index da836a0e82e..ef0eed786d2 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -74,7 +74,7 @@ bundle and included on the page. > `content_for :page_specific_javascripts` within haml files, along with > manually generated webpack bundles. However under this new system you should > not ever need to manually add an entry point to the `webpack.config.js` file. - +> > **Tip:** > If you are unsure what controller and action corresponds to a given page, you > can find this out by inspecting `document.body.dataset.page` within your @@ -109,7 +109,6 @@ bundle and included on the page. `my_widget.js` is only imported within `pages/widget/show/index.js`, you should place the module at `pages/widget/show/my_widget.js` and import it with a relative path (e.g. `import initMyWidget from './my_widget';`). - - If a class or module is _used by multiple routes_, place it within a shared directory at the closest common parent directory for the entry points that import it. For example, if `my_widget.js` is imported within diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index 284b4b53334..656ddd868cd 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -17,74 +17,81 @@ at the top, but legacy files are a special case. Any time you develop a new fea refactor an existing one, you should abide by the eslint rules. 1. **Never Ever EVER** disable eslint globally for a file - ```javascript - // bad - /* eslint-disable */ - - // better - /* eslint-disable some-rule, some-other-rule */ - // best - // nothing :) - ``` + ```javascript + // bad + /* eslint-disable */ + + // better + /* eslint-disable some-rule, some-other-rule */ + + // 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 */ - - import Foo from 'foo'; - - new Foo(); - // better - import Foo from 'foo'; + ```javascript + // bad + /* eslint-disable no-new */ + + import Foo from 'foo'; + + new 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: - 1. [no-new][eslint-new] - 1. [class-methods-use-this][eslint-this] + 1. [no-new][eslint-new] + 1. [class-methods-use-this][eslint-this] 1. When they are needed _always_ place ESlint directive comment blocks on the first line of a script, 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'; - - // good - /* eslint-disable no-new */ - /* global Foo */ - import Bar from './bar'; - ``` + ```javascript + // bad + /* global Foo */ + /* eslint-disable no-new */ + import Bar from './bar'; + + // good + /* eslint-disable no-new */ + /* global Foo */ + + import Bar from './bar'; + ``` 1. **Never** disable the `no-undef` rule. Declare globals with `/* global Foo */` instead. 1. When declaring multiple globals, always use one `/* global [name] */` line per variable. - ```javascript - // bad - /* globals Flash, Cookies, jQuery */ - // good - /* global Flash */ - /* global Cookies */ - /* global jQuery */ - ``` + ```javascript + // bad + /* globals Flash, Cookies, 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) {} - // good - fn(options) {} - ``` + ```javascript + // bad + fn(p1, p2, p3, p4) {} + + // good + fn(options) {} + ``` #### Modules, Imports, and Exports + 1. Use ES module syntax to import modules ```javascript // bad @@ -178,109 +185,116 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod ``` #### Data Mutation and Pure functions + 1. Strive to write many small pure functions, and minimize where mutations occur. - ```javascript + + ```javascript // bad const values = {foo: 1}; - + function impureFunction(items) { const bar = 1; - + items.foo = items.a * bar + 2; - + return items.a; } - + const c = impureFunction(values); - + // good var values = {foo: 1}; - + function pureFunction (foo) { var bar = 1; - + foo = foo * bar + 2; - + return foo; } - + var c = pureFunction(values.foo); - ``` + ``` 1. Avoid constructors with side-effects. -Although we aim for code without side-effects we need some side-effects for our code to run. - -If the class won't do anything if we only instantiate it, it's ok to add side effects into the constructor (_Note:_ The following is just an example. If the only purpose of the class is to add an event listener and handle the callback a function will be more suitable.) - -```javascript -// Bad -export class Foo { - constructor() { - this.init(); - } - init() { - document.addEventListener('click', this.handleCallback) - }, - handleCallback() { - - } -} - -// Good -export class Foo { - constructor() { - document.addEventListener() - } - handleCallback() { - } -} -``` - -On the other hand, if a class only needs to extend a third party/add event listeners in some specific cases, they should be initialized outside of the constructor. + Although we aim for code without side-effects we need some side-effects for our code to run. -1. Prefer `.map`, `.reduce` or `.filter` over `.forEach` -A forEach will most likely cause side effects, it will be mutating the array being iterated. Prefer using `.map`, -`.reduce` or `.filter` - ```javascript - const users = [ { name: 'Foo' }, { name: 'Bar' } ]; + If the class won't do anything if we only instantiate it, it's ok to add side effects into the constructor (_Note:_ The following is just an example. If the only purpose of the class is to add an event listener and handle the callback a function will be more suitable.) - // bad - users.forEach((user, index) => { - user.id = index; - }); + ```javascript + // Bad + export class Foo { + constructor() { + this.init(); + } + init() { + document.addEventListener('click', this.handleCallback) + }, + handleCallback() { + + } + } + + // Good + export class Foo { + constructor() { + document.addEventListener() + } + handleCallback() { + } + } + ``` - // good - const usersWithId = users.map((user, index) => { - return Object.assign({}, user, { id: index }); - }); - ``` + On the other hand, if a class only needs to extend a third party/add event listeners in some specific cases, they should be initialized outside of the constructor. + +1. Prefer `.map`, `.reduce` or `.filter` over `.forEach` + A forEach will most likely cause side effects, it will be mutating the array being iterated. Prefer using `.map`, + `.reduce` or `.filter` + + ```javascript + const users = [ { name: 'Foo' }, { name: 'Bar' } ]; + + // bad + users.forEach((user, index) => { + user.id = index; + }); + + // good + const usersWithId = users.map((user, index) => { + return Object.assign({}, user, { id: index }); + }); + ``` #### Parse Strings into Numbers -1. `parseInt()` is preferable over `Number()` or `+` - ```javascript - // bad - +'10' // 10 - // good - Number('10') // 10 +1. `parseInt()` is preferable over `Number()` or `+` - // better - parseInt('10', 10); - ``` + ```javascript + // bad + +'10' // 10 + + // good + Number('10') // 10 + + // better + parseInt('10', 10); + ``` #### CSS classes used for JavaScript + 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> - // good - <button class="js-add-user"> - Add User - </button> - ``` + ```html + // bad + <button class="add-user"> + Add User + </button> + + // good + <button class="js-add-user"> + Add User + </button> + ``` ### Vue.js @@ -292,197 +306,211 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. 1. The service has it's own file 1. The store has it's own file 1. Use a function in the bundle file to instantiate the Vue component: - ```javascript - // bad - class { - init() { - new Component({}) - } - } - // good - document.addEventListener('DOMContentLoaded', () => new Vue({ - el: '#element', - components: { - componentName - }, - render: createElement => createElement('component-name'), - })); - ``` + ```javascript + // bad + class { + init() { + new Component({}) + } + } + + // 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 + + ```javascript + // 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. #### Naming 1. **Extensions**: Use `.vue` extension for Vue components. Do not use `.js` as file extension ([#34371]). 1. **Reference Naming**: Use PascalCase for their instances: - ```javascript - // bad - import cardBoard from 'cardBoard.vue' - components: { - cardBoard, - }; - - // good - import CardBoard from 'cardBoard.vue' - - components: { - CardBoard, - }; - ``` + ```javascript + // bad + import cardBoard from 'cardBoard.vue' + + components: { + cardBoard, + }; + + // good + import CardBoard from 'cardBoard.vue' + + 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"> - - // good - <component css-class="btn"> - // bad - <component myProp="prop" /> - - // good - <component my-prop="prop" /> - ``` + ```javascript + // bad + <component class="btn"> + + // good + <component css-class="btn"> + + // bad + <component myProp="prop" /> + + // good + <component my-prop="prop" /> + ``` [#34371]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34371 #### Alignment 1. Follow these alignment styles for the template method: - 1. With more than one attribute, all attributes should be on a new line: - ```javascript - // bad - <component v-if="bar" - param="baz" /> - - <button class="btn">Click me</button> - - // good - <component - v-if="bar" - param="baz" - /> - - <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" - /> - // bad - <component - bar="bar" /> - ``` + 1. With more than one attribute, all attributes should be on a new line: + + ```javascript + // bad + <component v-if="bar" + param="baz" /> + + <button class="btn">Click me</button> + + // good + <component + v-if="bar" + param="baz" + /> + + <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" + /> + + // bad + <component + bar="bar" /> + ``` #### Quotes + 1. Always use double quotes `"` inside templates and single quotes `'` for all other JS. - ```javascript - // bad - template: ` - <button :class='style'>Button</button> - ` - // good - template: ` - <button :class="style">Button</button> - ` - ``` + ```javascript + // bad + template: ` + <button :class='style'>Button</button> + ` + + // good + template: ` + <button :class="style">Button</button> + ` + ``` #### Props -1. Props should be declared as an object - ```javascript - // bad - props: ['foo'] - // good - props: { - foo: { - type: String, - required: false, - default: 'bar' +1. Props should be declared as an object + ```javascript + // 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, - } - } - // good - props: { - foo: { - type: String, - required: false, - default: 'bar' + ```javascript + // bad + props: { + foo: { + type: String, + } } - } - ``` + + // good + props: { + foo: { + type: String, + required: false, + default: 'bar' + } + } + ``` 1. Default key should be provided if the prop is not required. _Note:_ There are some scenarios where we need to check for the existence of the property. On those a default key should not be provided. - ```javascript - // good - props: { - foo: { - type: String, - required: false, - } - } - // good - props: { - foo: { - type: String, - required: false, - default: 'bar' + ```javascript + // good + props: { + foo: { + type: String, + required: false, + } } - } - - // good - props: { - foo: { - type: String, - required: true + + // good + props: { + foo: { + type: String, + required: false, + default: 'bar' + } } - } - ``` + + // good + props: { + foo: { + type: String, + required: true + } + } + ``` #### Data + 1. `data` method should always be a function ```javascript @@ -502,38 +530,41 @@ On those a default key should not be provided. #### Directives 1. Shorthand `@` is preferable over `v-on` - ```javascript - // bad - <component v-on:click="eventHandler"/> - - // good - <component @click="eventHandler"/> - ``` + ```javascript + // bad + <component v-on:click="eventHandler"/> + + // good + <component @click="eventHandler"/> + ``` 1. Shorthand `:` is preferable over `v-bind` - ```javascript - // bad - <component v-bind:class="btn"/> - - // good - <component :class="btn"/> - ``` + ```javascript + // bad + <component v-bind:class="btn"/> + + // good + <component :class="btsn"/> + ``` #### Closing tags + 1. Prefer self closing component tags - ```javascript - // bad - <component></component> - // good - <component /> - ``` + ```javascript + // bad + <component></component> + + // good + <component /> + ``` #### Ordering 1. Tag order in `.vue` file + ``` <script> // ... @@ -550,12 +581,14 @@ On those a default key should not be provided. ``` 1. Properties in a Vue Component: - Check [order of properties in components rule][vue-order]. + Check [order of properties in components rule][vue-order]. #### `:key` + 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" @@ -566,6 +599,7 @@ When using `v-for` you need to provide a *unique* `:key` attribute for each item ``` 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" @@ -575,8 +609,8 @@ When using `v-for` you need to provide a *unique* `:key` attribute for each item </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> @@ -585,64 +619,69 @@ When using `v-for` you need to provide a *unique* `:key` attribute for each item ``` 1. When dealing with nested `v-for` use the same guidelines as above. - ```html - <div - v-for="item in items" - :key="item.id" - > - <span - v-for="element in array" - :key="element.id" - > - <!-- content --> - </span> - </div> - ``` + ```html + <div + v-for="item in items" + :key="item.id" + > + <span + v-for="element in array" + :key="element.id" + > + <!-- content --> + </span> + </div> + ``` Useful links: + 1. [`key`](https://vuejs.org/v2/guide/list.html#key) 1. [Vue Style Guide: Keyed v-for](https://vuejs.org/v2/style-guide/#Keyed-v-for-essential ) + #### Vue and Bootstrap 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> - // good - <span - v-tooltip - title="Some tooltip text"> - Text - </span> - ``` + ```javascript + // bad + <span + class="has-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` 1. Don't change `data-original-title`. - ```javascript - // bad - <span data-original-title="tooltip text">Foo</span> - - // good - <span title="tooltip text">Foo</span> - $('span').tooltip('_fixTitle'); - ``` + ```javascript + // bad + <span data-original-title="tooltip text">Foo</span> + + // good + <span title="tooltip text">Foo</span> + + $('span').tooltip('_fixTitle'); + ``` ### The Javascript/Vue Accord + The goal of this accord is to make sure we are all on the same page. 1. When writing Vue, you may not use jQuery in your application. - 1. If you need to grab data from the DOM, you may query the DOM 1 time while bootstrapping your application to grab data attributes using `dataset`. You can do this without jQuery. - 1. You may use a jQuery dependency in Vue.js following [this example from the docs](https://vuejs.org/v2/examples/select2.html). - 1. If an outside jQuery Event needs to be listen to inside the Vue application, you may use jQuery event listeners. - 1. We will avoid adding new jQuery events when they are not required. Instead of adding new jQuery events take a look at [different methods to do the same task](https://vuejs.org/v2/api/#vm-emit). + 1. If you need to grab data from the DOM, you may query the DOM 1 time while bootstrapping your application to grab data attributes using `dataset`. You can do this without jQuery. + 1. You may use a jQuery dependency in Vue.js following [this example from the docs](https://vuejs.org/v2/examples/select2.html). + 1. If an outside jQuery Event needs to be listen to inside the Vue application, you may use jQuery event listeners. + 1. We will avoid adding new jQuery events when they are not required. Instead of adding new jQuery events take a look at [different methods to do the same task](https://vuejs.org/v2/api/#vm-emit). 1. You may query the `window` object 1 time, while bootstrapping your application for application specific data (e.g. `scrollTo` is ok to access anytime). Do this access during the bootstrapping of your application. 1. You may have a temporary but immediate need to create technical debt by writing code that does not follow our standards, to be refactored later. Maintainers need to be ok with the tech debt in the first place. An issue should be created for that tech debt to evaluate it further and discuss. In the coming months you should fix that tech debt, with it's priority to be determined by maintainers. 1. When creating tech debt you must write the tests for that code before hand and those tests may not be rewritten. e.g. jQuery tests rewritten to Vue tests. @@ -650,6 +689,7 @@ The goal of this accord is to make sure we are all on the same page. 1. Once you have chosen a centralized state management solution you must use it for your entire application. i.e. Don't mix and match your state management solutions. ## SCSS + - [SCSS](style_guide_scss.md) [airbnb-js-style-guide]: https://github.com/airbnb/javascript diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 4089cd37d73..f582f5da323 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -290,23 +290,24 @@ export default { ``` ### Vuex Gotchas -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. - ```javascript - // component.vue - - // bad - created() { - this.$store.commit('mutation'); - } +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: - // good - created() { - this.$store.dispatch('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 + + // bad + created() { + this.$store.commit('mutation'); + } + + // good + created() { + this.$store.dispatch('action'); + } + ``` 1. Use mutation types instead of hardcoding strings. It will be less error prone. 1. The State will be accessible in all components descending from the use where the store is instantiated. @@ -342,7 +343,7 @@ describe('component', () => { name: 'Foo', age: '30', }; - + store = createStore(); // populate the store diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md index 702caacc74f..417298205f5 100644 --- a/doc/development/feature_flags.md +++ b/doc/development/feature_flags.md @@ -58,13 +58,25 @@ Features that are developed and are intended to be merged behind a feature flag should not include a changelog entry. The entry should be added in the merge request removing the feature flags. +In the rare case that you need the feature flag to be on automatically, use +`default_enabled: true` when checking: + +```ruby +Feature.enabled?(:feature_flag, project, default_enabled: true) +``` + +For more information about rolling out changes using feature flags, refer to the +[Rolling out changes using feature flags](rolling_out_changes_using_feature_flags.md) +guide. + ### Specs In the test environment `Feature.enabled?` is stubbed to always respond to `true`, so we make sure behavior under feature flag doesn't go untested in some non-specific contexts. - -If you need to test the feature flag in a different state, you need to stub it with: + +Whenever a feature flag is present, make sure to test _both_ states of the +feature flag. You can stub a feature flag as follows: ```ruby stub_feature_flags(my_feature_flag: false) diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md index fdbd7f1fa37..6e014e8c751 100644 --- a/doc/development/file_storage.md +++ b/doc/development/file_storage.md @@ -45,6 +45,11 @@ In the case of Issues/MR/Notes Markdown attachments, there is a different approa instead of basing the path into a mutable variable `:project_path_with_namespace`, it's possible to use the hash of the project ID instead, if project migrates to the new approach (introduced in 10.2). +> Note: We provide an [all-in-one rake task] to migrate all uploads to object +> storage in one go. If a new Uploader class or model type is introduced, make +> sure you add a rake task invocation corresponding to it to the [category +> list]. + ### Path segments Files are stored at multiple locations and use different path schemes. @@ -137,3 +142,5 @@ end [CarrierWave]: https://github.com/carrierwaveuploader/carrierwave [Hashed Storage]: ../administration/repository_storage_types.md +[all-in-one rake task]: ../administration/raketasks/uploads/migrate.md +[category list]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/tasks/gitlab/uploads/migrate.rake diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 4f9ca1920a5..32beafad307 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -1,15 +1,11 @@ # GitLab Developers Guide to Working with Gitaly [Gitaly](https://gitlab.com/gitlab-org/gitaly) is a high-level Git RPC service used by GitLab CE/EE, -Workhorse and GitLab-Shell. All Rugged operations in GitLab CE/EE are currently being phased out to -be replaced by Gitaly API calls. - -Visit the [Gitaly Migration Board](https://gitlab.com/gitlab-org/gitaly/boards/331341) for current -status of the migration. +Workhorse and GitLab-Shell. ## Developing new Git features -Starting with Gitlab 10.8, all new Git features should be developed in +Starting with GitLab 10.8, all new Git features should be developed in Gitaly. > This is a new process that is not clearly defined yet. If you want @@ -52,57 +48,6 @@ comfortable writing Go code. There is documentation for this approach in [the Gitaly repo](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/ruby_endpoint.md). -## Modifying existing Git features - -If you modify existing Git features in `lib/gitlab/git` you need to make -sure the changes also work in Gitaly. Because we are still in the -migration process there are a number of subtle pitfalls. Features that -have been migrated have dual implementations (Gitaly and local). The -Gitaly implementation may or may not use a vendored (and therefore -possibly outdated) copy of the local implementation in `lib/gitlab/git`. - -To avoid unexpected problems and conflicts, all changes to -`lib/gitlab/git` need to be approved by a member of the Gitaly team. - -For the time being, while the Gitaly migration is still in progress, -there should be no Enterprise Edition-only Git code in -`lib/gitlab/git`. Also no mixins. - -## Feature Flags - -Gitaly makes heavy use of [feature flags](feature_flags.md). - -Each Rugged-to-Gitaly migration goes through a [series of phases](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/MIGRATION_PROCESS.md): - -* **Opt-In**: by default the Rugged implementation is used. - * Production instances can choose to enable the Gitaly endpoint by enabling the feature flag. - * For testing purposes, you may wish to enable all feature flags by default. This can be done by exporting the following - environment variable: `GITALY_FEATURE_DEFAULT_ON=1`. - * On developer instances (ie, when `Rails.env.development?` is true), the Gitaly endpoint - is enabled by default, but can be _disabled_ using feature flags. -* **Opt-Out**: by default, the Gitaly endpoint is used, but the feature can be explicitly disabled using the feature flag. -* **Mandatory**: The migration is complete and cannot be disabled. The old codepath is removed. - -### Enabling and Disabling Feature - -In the Rails console, type: - -```ruby -Feature.enable(:gitaly_feature_name) -Feature.disable(:gitaly_feature_name) -``` - -Where `gitaly_feature_name` is the name of the Gitaly feature. This can be determined by finding the appropriate -`gitaly_migrate` code block, for example: - -```ruby -gitaly_migrate(:tag_names) do -... -end -``` - -Since Gitaly features are always prefixed with `gitaly_`, the name of the feature flag in this case would be `gitaly_tag_names`. - ## Gitaly-Related Test Failures If your test-suite is failing with Gitaly issues, as a first step, try running: diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index d25d856c3a3..84dea7ce9aa 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -101,8 +101,10 @@ end in a prepended module, which is very likely the case in EE. We could see error like this: - 1.1) Failure/Error: allow_any_instance_of(ApplicationSetting).to receive_messages(messages) - Using `any_instance` to stub a method (elasticsearch_indexing) that has been defined on a prepended module (EE::ApplicationSetting) is not supported. + ``` + 1.1) Failure/Error: allow_any_instance_of(ApplicationSetting).to receive_messages(messages) + Using `any_instance` to stub a method (elasticsearch_indexing) that has been defined on a prepended module (EE::ApplicationSetting) is not supported. + ``` ### Alternative: `expect_next_instance_of` diff --git a/doc/development/i18n/index.md b/doc/development/i18n/index.md index 7290a175501..c44690a4c5d 100644 --- a/doc/development/i18n/index.md +++ b/doc/development/i18n/index.md @@ -50,3 +50,5 @@ able to proofread and instructions on becoming a proofreader yourself. ## Release Translations are typically included in the next major or minor release. + +See [Merging translations from Crowdin](merging_translations.md) diff --git a/doc/development/i18n/merging_translations.md b/doc/development/i18n/merging_translations.md new file mode 100644 index 00000000000..d172aa6da21 --- /dev/null +++ b/doc/development/i18n/merging_translations.md @@ -0,0 +1,60 @@ +# Merging translations from Crowdin + +Crowdin automatically syncs the `gitlab.pot` file presenting newly +added translations to the community of translators. + +At the same time, it creates a merge request to merge all newly added +& approved translations. Find the [merge reqeust created by +`gitlab-crowdin-bot`](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&author_username=gitlab-crowdin-bot) +to see new and merged merge requests. They are created in EE and need +to be ported to CE manually. + +## Validation + +By default Crowdin commits translations with `[skip ci]` in the commit +message. This is done to avoid a bunch of pipelines being run. Before +merging translations, make sure to trigger a pipeline to validate +translations, we have static analysis validating things Crowdin +doesn't do. Create a [new pipeline](https://gitlab.com/gitlab-org/gitlab-ee/pipelines/new) for the +`master-i18n` branch. + +If there are validation errors, the easiest solution is to disapprove +the offending string in Crowdin, leaving a comment with what is +required to fix the offense. There is an +[issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/49208) +suggesting to automate this process. Disapproving will exclude the +invalid translation, the merge request will be updated within a few +minutes. + +It might be handy to pause the integration on the Crowdin side for a +little while so translations don't keep coming. This can be done by +clicking `Pause sync` on the [Crowdin integration settings +page](https://translate.gitlab.com/project/gitlab-ee/settings#integration). + +When all failures are resolved, the translations need to be double +checked once more [as discussed in this +issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/37850). + +## Merging translations + +When all translations are found good and pipelines pass the +translations can be merged into the master branch. After that is done, +create a new merge request cherry-picking the translations from EE to +CE. When merging the translations, make sure to check the `Remove +source branch` checkbox, so Crowdin recreates the `master-i18n` from +master after the new translation was merged. + +We are discussing automating this entire process +[here](https://gitlab.com/gitlab-org/gitlab-ce/issues/39309). + +## Recreate the merge request + +Crowdin creates a new merge request as soon as the old one is closed +or merged. But it won't recreate the `master-i18n` branch every +time. To force Crowdin to recreate the branch, close any [open merge +request](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&author_username=gitlab-crowdin-bot) +and delete the +[`master-18n`](https://gitlab.com/gitlab-org/gitlab-ee/branches/all?utf8=%E2%9C%93&search=master-i18n). + +This might be needed when the merge request contains failures that +have been fixed on master. diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index ad5f6b2ecf6..5e13c725e15 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -30,6 +30,7 @@ are very appreciative of the work done by translators and proofreaders! - Korean - Chang-Ho Cha - [GitLab](https://gitlab.com/changho-cha), [Crowdin](https://crowdin.com/profile/zzazang) - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) + - Ji Hun Oh - [GitLab](https://gitlab.com/Baw-Appie), [Crowdin](https://crowdin.com/profile/BawAppie) - Polish - Filip Mech - [GitLab](https://gitlab.com/mehenz), [Crowdin](https://crowdin.com/profile/mehenz) - Portuguese, Brazilian @@ -65,7 +66,6 @@ are very appreciative of the work done by translators and proofreaders! Add your language in alphabetical order, and add yourself to the list including: - - name - link to your GitLab profile - link to your CrowdIn profile diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md index a14c0752366..7761f65d78a 100644 --- a/doc/development/instrumentation.md +++ b/doc/development/instrumentation.md @@ -69,7 +69,7 @@ The easiest way to check if a method has been instrumented is to check its source location. For example: ```ruby -method = Rugged::TagCollection.instance_method(:[]) +method = Banzai::Renderer.method(:render) method.source_location ``` @@ -82,7 +82,7 @@ method (along with its source location), this is easier than running the above Ruby code. In case of the above snippet you'd run the following: ``` -$ Rugged::TagCollection#[] +$ Banzai::Renderer.render ``` This will print out something along the lines of: diff --git a/doc/development/licensing.md b/doc/development/licensing.md index ddaf636a742..0e71cd47481 100644 --- a/doc/development/licensing.md +++ b/doc/development/licensing.md @@ -100,7 +100,7 @@ If a gem uses a license which is not listed above, open an issue and ask. If a l Keep in mind that each license has its own restrictions (typically defined in their body text). Please make sure to comply with those restrictions at all times whenever an external library is used. -Gems which are included only in the "development" or "test" groups by Bundler are exempt from license requirements, as they're not distributed for use in production. +Dependencies which are only used in development or test environment are exempt from license requirements, as they're not distributed for use in production. **NOTE:** This document is **not** legal advice, nor is it comprehensive. It should not be taken as such. diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index 12badbe39b2..ee01c89e0ed 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -168,6 +168,7 @@ user objects for every username we can remove the need for running the same query for every mention of `@alice`. Caching data per transaction can be done using -[RequestStore](https://github.com/steveklabnik/request_store). Caching data in -Redis can be done using [Rails' caching +[RequestStore](https://github.com/steveklabnik/request_store) (use +`Gitlab::SafeRequestStore` to avoid having to remember to check +`RequestStore.active?`). Caching data in Redis can be done using [Rails' caching system](http://guides.rubyonrails.org/caching_with_rails.html). diff --git a/doc/development/module_with_instance_variables.md b/doc/development/module_with_instance_variables.md index 48a1b7f847e..7bdfa04fc57 100644 --- a/doc/development/module_with_instance_variables.md +++ b/doc/development/module_with_instance_variables.md @@ -60,7 +60,7 @@ as long as it's contained in the same module; that is, no other modules or objects are touching them, then it would be an acceptable use. We especially allow the case where a single instance variable is used with -`||=` to setup the value. This would look like: +`||=` to set up the value. This would look like: ``` ruby module M diff --git a/doc/development/new_fe_guide/development/testing.md b/doc/development/new_fe_guide/development/testing.md index 53dfe6774e9..a9223ac6b0f 100644 --- a/doc/development/new_fe_guide/development/testing.md +++ b/doc/development/new_fe_guide/development/testing.md @@ -6,7 +6,7 @@ * **[Ruby unit tests](#ruby-unit-tests-spec-rb)** for models, controllers, helpers, etc. (`/spec/**/*.rb`) * **[Full feature tests](#full-feature-tests-spec-features-rb)** (`/spec/features/**/*.rb`) * **[Karma](#karma-tests-spec-javascripts-js)** (`/spec/javascripts/**/*.js`) -* ~~Spinach~~ — These have been removed from our codebase in May 2018. (`/features/`) +* <s>Spinach</s> — These have been removed from our codebase in May 2018. (`/features/`) ## RSpec: Ruby unit tests `/spec/**/*.rb` diff --git a/doc/development/new_fe_guide/style/javascript.md b/doc/development/new_fe_guide/style/javascript.md index 57efd9353bc..922fd1e4ea4 100644 --- a/doc/development/new_fe_guide/style/javascript.md +++ b/doc/development/new_fe_guide/style/javascript.md @@ -12,158 +12,157 @@ You can run eslint locally by running `yarn eslint` <a name="avoid-foreach"></a><a name="1.1"></a> - [1.1](#avoid-foreach) **Avoid ForEach when mutating data** Use `map`, `reduce` or `filter` instead of `forEach` when mutating data. This will minimize mutations in functions ([which is aligned with Airbnb's style guide][airbnb-minimize-mutations]) -``` -// bad -users.forEach((user, index) => { - user.id = index; -}); - -// good -const usersWithId = users.map((user, index) => { - return Object.assign({}, user, { id: index }); -}); -``` + ``` + // bad + users.forEach((user, index) => { + user.id = index; + }); + + // good + const usersWithId = users.map((user, index) => { + return Object.assign({}, user, { id: index }); + }); + ``` ## Functions <a name="limit-params"></a><a name="2.1"></a> - [2.1](#limit-params) **Limit number of parameters** If your function or method has more than 3 parameters, use an object as a parameter instead. -``` -// bad -function a(p1, p2, p3) { - // ... -}; - -// good -function a(p) { - // ... -}; -``` + ``` + // bad + function a(p1, p2, p3) { + // ... + }; + + // good + function a(p) { + // ... + }; + ``` ## Classes & constructors <a name="avoid-constructor-side-effects"></a><a name="3.1"></a> - [3.1](#avoid-constructor-side-effects) **Avoid side effects in constructors** Avoid making some operations in the `constructor`, such as asynchronous calls, API requests and DOM manipulations. Prefer moving them into separate functions. This will make tests easier to write and code easier to maintain. - ```javascript - // bad - class myClass { - constructor(config) { - this.config = config; - axios.get(this.config.endpoint) + ```javascript + // bad + class myClass { + constructor(config) { + this.config = config; + axios.get(this.config.endpoint) + } } - } - - // good - class myClass { - constructor(config) { - this.config = config; + + // good + class myClass { + constructor(config) { + this.config = config; + } + + makeRequest() { + axios.get(this.config.endpoint) + } } - - makeRequest() { - axios.get(this.config.endpoint) - } - } - const instance = new myClass(); - instance.makeRequest(); - - ``` + const instance = new myClass(); + instance.makeRequest(); + + ``` <a name="avoid-classes-to-handle-dom-events"></a><a name="3.2"></a> - [3.2](#avoid-classes-to-handle-dom-events) **Avoid classes to handle DOM events** If the only purpose of the class is to bind a DOM event and handle the callback, prefer using a function. -``` -// bad -class myClass { - constructor(config) { - this.config = config; - } - - init() { - document.addEventListener('click', () => {}); - } -} - -// good - -const myFunction = () => { - document.addEventListener('click', () => { - // handle callback here - }); -} -``` + ``` + // bad + class myClass { + constructor(config) { + this.config = config; + } + + init() { + document.addEventListener('click', () => {}); + } + } + + // good + + const myFunction = () => { + document.addEventListener('click', () => { + // handle callback here + }); + } + ``` <a name="element-container"></a><a name="3.3"></a> - [3.3](#element-container) **Pass element container to constructor** When your class manipulates the DOM, receive the element container as a parameter. This is more maintainable and performant. -``` -// bad -class a { - constructor() { - document.querySelector('.b'); - } -} - -// good -class a { - constructor(options) { - options.container.querySelector('.b'); - } -} -``` + ``` + // bad + class a { + constructor() { + document.querySelector('.b'); + } + } + + // good + class a { + constructor(options) { + options.container.querySelector('.b'); + } + } + ``` ## Type Casting & Coercion <a name="use-parseint"></a><a name="4.1"></a> - [4.1](#use-parseint) **Use ParseInt** Use `ParseInt` when converting a numeric string into a number. -``` -// bad -Number('10') - - -// good -parseInt('10', 10); -``` + ``` + // bad + Number('10') + + // good + parseInt('10', 10); + ``` ## CSS Selectors <a name="use-js-prefix"></a><a name="5.1"></a> - [5.1](#use-js-prefix) **Use js prefix** If a CSS class is only being used in JavaScript as a reference to the element, prefix the class name with `js-` -``` -// bad -<button class="add-user"></button> - -// good -<button class="js-add-user"></button> -``` + ``` + // bad + <button class="add-user"></button> + + // good + <button class="js-add-user"></button> + ``` ## Modules <a name="use-absolute-paths"></a><a name="6.1"></a> - [6.1](#use-absolute-paths) **Use absolute paths for nearby modules** Use absolute paths if the module you are importing is less than two levels up. -``` -// bad -import GitLabStyleGuide from '~/guides/GitLabStyleGuide'; - -// good -import GitLabStyleGuide from '../GitLabStyleGuide'; -``` + ``` + // bad + import GitLabStyleGuide from '~/guides/GitLabStyleGuide'; + + // good + import GitLabStyleGuide from '../GitLabStyleGuide'; + ``` <a name="use-relative-paths"></a><a name="6.2"></a> - [6.2](#use-relative-paths) **Use relative paths for distant modules** If the module you are importing is two or more levels up, use a relative path instead of an absolute path. -``` -// bad -import GitLabStyleGuide from '../../../guides/GitLabStyleGuide'; - -// good -import GitLabStyleGuide from '~/GitLabStyleGuide'; -``` + ``` + // bad + import GitLabStyleGuide from '../../../guides/GitLabStyleGuide'; + + // good + import GitLabStyleGuide from '~/GitLabStyleGuide'; + ``` <a name="global-namespace"></a><a name="6.3"></a> - [6.3](#global-namespace) **Do not add to global namespace** diff --git a/doc/development/newlines_styleguide.md b/doc/development/newlines_styleguide.md index 32aac2529a4..5f7210020b6 100644 --- a/doc/development/newlines_styleguide.md +++ b/doc/development/newlines_styleguide.md @@ -10,7 +10,7 @@ def method issue = Issue.new issue.save - + render json: issue end ``` @@ -20,7 +20,7 @@ end def method issue = Issue.new issue.save - + render json: issue end ``` diff --git a/doc/development/ordering_table_columns.md b/doc/development/ordering_table_columns.md index 5d00e1f7a0c..e9c6481635b 100644 --- a/doc/development/ordering_table_columns.md +++ b/doc/development/ordering_table_columns.md @@ -1,32 +1,49 @@ -# Ordering Table Columns +# Ordering Table Columns in PostgreSQL Similar to C structures the space of a table is influenced by the order of columns. This is because the size of columns is aligned depending on the type of -the column. Take the following column order for example: +the following column. Let's consider an example: -* id (integer, 4 bytes) -* name (text, variable) -* user_id (integer, 4 bytes) +- `id` (integer, 4 bytes) +- `name` (text, variable) +- `user_id` (integer, 4 bytes) -Integers are aligned to the word size. This means that on a 64 bit platform the -actual size of each column would be: 8 bytes, variable, 8 bytes. This means that -each row will require at least 16 bytes for the two integers, and a variable -amount for the text field. If a table has a few rows this is not an issue, but -once you start storing millions of rows you can save space by using a different -order. For the above example a more ideal column order would be the following: +The first column is a 4-byte integer. The next is text of variable length. The +`text` data type requires 1-word alignment, and on 64-bit platform, 1 word is 8 +bytes. To meet the alignment requirements, four zeros are to be added right +after the first column, so `id` occupies 4 bytes, then 4 bytes of alignment +padding, and only next `name` is being stored. Therefore, in this case, 8 bytes +will be spent for storing a 4-byte integer. -* id (integer, 4 bytes) -* user_id (integer, 4 bytes) -* name (text, variable) +The space between rows is also subject to alignment padding. The `user_id` +column takes only 4 bytes, and on 64-bit platform, 4 zeroes will be added for +alignment padding, to allow storing the next row beginning with the "clear" word. -In this setup the `id` and `user_id` columns can be packed together, which means -we only need 8 bytes to store _both_ of them. This in turn each row will require -8 bytes less of space. +As a result, the actual size of each column would be (ommiting variable length +data and 24-byte tuple header): 8 bytes, variable, 8 bytes. This means that +each row will require at least 16 bytes for the two 4-byte integers. If a table +has a few rows this is not an issue. However, once you start storing millions of +rows you can save space by using a different order. For the above example, the +ideal column order would be the following: + +- `id` (integer, 4 bytes) +- `user_id` (integer, 4 bytes) +- `name` (text, variable) + +or + +- `name` (text, variable) +- `id` (integer, 4 bytes) +- `user_id` (integer, 4 bytes) + +In these examples, the `id` and `user_id` columns are packed together, which +means we only need 8 bytes to store _both_ of them. This in turn means each row +will require 8 bytes less space. For GitLab we require that columns of new tables are ordered based to use the least amount of space. An easy way of doing this is to order them based on the -type size in descending order with variable sizes (string and text columns for -example) at the end. +type size in descending order with variable sizes (`text`, `varchar`, arrays, +`json`, `jsonb`, and so on) at the end. ## Type Sizes @@ -36,7 +53,7 @@ of information we will list the sizes of common types here so it's easier to look them up. Here "word" refers to the word size, which is 4 bytes for a 32 bits platform and 8 bytes for a 64 bits platform. -| Type | Size | Aligned To | +| Type | Size | Alignment needed | |:-----------------|:-------------------------------------|:-----------| | smallint | 2 bytes | 1 word | | integer | 4 bytes | 1 word | @@ -58,7 +75,7 @@ always be at the end of a table. ## Real Example -Let's use the "events" table as an example, which currently has the following +Let's use the `events` table as an example, which currently has the following layout: | Column | Type | Size | @@ -89,8 +106,8 @@ divided into fixed size chunks as follows: | 8 bytes | updated_at | | 8 bytes | action, author_id | -This means that excluding the variable sized data we need at least 48 bytes per -row. +This means that excluding the variable sized data and tuple header, we need at +least 8 * 6 = 48 bytes per row. We can optimise this by using the following column order instead: @@ -120,8 +137,8 @@ This would produce the following chunks: | variable | title | | variable | data | -Here we only need 40 bytes per row excluding the variable sized data. 8 bytes -being saved may not sound like much, but for tables as large as the "events" -table it does begin to matter. For example, when storing 80 000 000 rows this -translates to a space saving of at least 610 MB: all by just changing the order -of a few columns. +Here we only need 40 bytes per row excluding the variable sized data and 24-byte +tuple header. 8 bytes being saved may not sound like much, but for tables as +large as the `events` table it does begin to matter. For example, when storing +80 000 000 rows this translates to a space saving of at least 610 MB, all by +just changing the order of a few columns. diff --git a/doc/development/performance.md b/doc/development/performance.md index 6b4cb6d72d1..c7b10dfd5ce 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -43,7 +43,7 @@ GitLab provides built-in tools to aid the process of improving performance: * [QueryRecoder](query_recorder.md) for preventing `N+1` regressions GitLab employees can use GitLab.com's performance monitoring systems located at -<http://performance.gitlab.net>, this requires you to log in using your +<https://dashboards.gitlab.net>, this requires you to log in using your `@gitlab.com` Email address. Non-GitLab employees are advised to set up their own InfluxDB + Grafana stack. @@ -364,8 +364,7 @@ Depending on the size of the String and how frequently it would be allocated there's no guarantee it will. Strings will be frozen by default in Ruby 3.0. To prepare our code base for -this eventuality, it's a good practice to add the following header to all -Ruby files: +this eventuality, we will be adding the following header to all Ruby files: ```ruby # frozen_string_literal: true @@ -379,6 +378,9 @@ test = +"hello" test += " world" ``` +When adding new Ruby files, please check that you can add the above header, +as omitting it may lead to style check failures. + ## Anti-Patterns This is a collection of [anti-patterns][anti-pattern] that should be avoided diff --git a/doc/development/permissions.md b/doc/development/permissions.md new file mode 100644 index 00000000000..5d409c9461e --- /dev/null +++ b/doc/development/permissions.md @@ -0,0 +1,63 @@ +# GitLab permissions guide + +There are multiple types of permissions across GitLab, and when implementing +anything that deals with permissions, all of them should be considered. + +## Groups and Projects + +### General permissions + +Groups and projects can have the following visibility levels: + +- public (20) - an entity is visible to everyone +- internal (10) - an entity is visible to logged in users +- private (0) - an entity is visible only to the approved members of the entity + +The visibility level of a group can be changed only if all subgroups and +subprojects have the same or lower visibility level. (e.g., a group can be set +to internal only if all subgroups and projects are internal or private). + +Visibility levels can be found in the `Gitlab::VisibilityLevel` module. + +### Feature specific permissions + +Additionally, the following project features can have different visibility levels: + +- Issues +- Repository + - Merge Request + - Pipelines + - Container Registry + - Git Large File Storage +- Wiki +- Snippets + +These features can be set to "Everyone with Access" or "Only Project Members". +They make sense only for public or internal projects because private projects +can be accessed only by project members by default. + +### Members + +Users can be members of multiple groups and projects. The following access +levels are available (defined in the `Gitlab::Access` module): + +- Guest +- Reporter +- Developer +- Maintainer +- Owner + +If a user is the member of both a project and the project parent group, the +higher permission is taken into account for the project. + +If a user is the member of a project, but not the parent group (or groups), they +can still view the groups and their entities (like epics). + +Project membership (where the group membership is already taken into account) +is stored in the `project_authorizations` table. + +### Confidential issues + +Confidential issues can be accessed only by project members who are at least +reporters (they can't be accessed by guests). Additionally they can be accessed +by their authors and assignees. diff --git a/doc/development/prometheus_metrics.md b/doc/development/prometheus_metrics.md new file mode 100644 index 00000000000..b6b6d9665ea --- /dev/null +++ b/doc/development/prometheus_metrics.md @@ -0,0 +1,48 @@ +# Working with Prometheus Metrics + +## Adding to the library + +We strive to support the 2-4 most important metrics for each common system service that supports Prometheus. If you are looking for support for a particular exporter which has not yet been added to the library, additions can be made [to the `common_metrics.yml`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/prometheus/common_metrics.yml) file. + +### Query identifier + +The requirement for adding a new metric is to make each query to have an unique identifier which is used to update the metric later when changed: + +```yaml +- group: Response metrics (NGINX Ingress) + metrics: + - title: "Throughput" + y_label: "Requests / Sec" + queries: + - id: response_metrics_nginx_ingress_throughput_status_code + query_range: 'sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) by (status_code)' + unit: req / sec + label: Status Code +``` + +### Update existing metrics + +After you add or change existing _common_ metric you have to create a new database migration that will query and update all existing metrics. + +NOTE: **Note:** +If a query metric (which is identified by `id:`) is removed it will not be removed from database by default. +You might want to add additional database migration that makes a decision what to do with removed one. +For example: you might be interested in migrating all dependent data to a different metric. + +```ruby +class ImportCommonMetrics < ActiveRecord::Migration + include Gitlab::Database::MigrationHelpers + + require Rails.root.join('db/importers/common_metrics_importer.rb') + + DOWNTIME = false + + def up + Importers::CommonMetricsImporter.new.execute + end + + def down + # no-op + end +end +``` diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index fc51b74da1d..2ad748d4802 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -1,6 +1,6 @@ # Rake tasks for developers -## Setup db with developer seeds +## Set up db with developer seeds Note that if your db user does not have advanced privileges you must create the db manually before running this command. diff --git a/doc/development/reusing_abstractions.md b/doc/development/reusing_abstractions.md new file mode 100644 index 00000000000..83d7d42bd1f --- /dev/null +++ b/doc/development/reusing_abstractions.md @@ -0,0 +1,182 @@ +# Guidelines for reusing abstractions + +As GitLab has grown, different patterns emerged across the codebase. Service +classes, serializers, and presenters are just a few. These patterns made it easy +to reuse code, but at the same time make it easy to accidentally reuse the wrong +abstraction in a particular place. + +## Why these guidelines are necessary + +Code reuse is good, but sometimes this can lead to shoehorning the wrong +abstraction into a particular use case. This in turn can have a negative impact +on maintainability, the ability to easily debug problems, or even performance. + +An example would be to use `ProjectsFinder` in `IssuesFinder` to limit issues to +those belonging to a set of projects. While initially this may seem like a good +idea, both classes provide a very high level interface with very little control. +This means that `IssuesFinder` may not be able to produce a better optimised +database query, as a large portion of the query is controlled by the internals +of `ProjectsFinder`. + +To work around this problem, you would use the same code used by +`ProjectsFinder`, instead of using `ProjectsFinder` itself directly. This allows +you to compose your behaviour better, giving you more control over the behaviour +of the code. + +To illustrate, consider the following code from `IssuableFinder#projects`: + +```ruby +return @projects = project if project? + +projects = + if current_user && params[:authorized_only].presence && !current_user_related? + current_user.authorized_projects + elsif group + finder_options = { include_subgroups: params[:include_subgroups], only_owned: true } + GroupProjectsFinder.new(group: group, current_user: current_user, options: finder_options).execute + else + ProjectsFinder.new(current_user: current_user).execute + end + +@projects = projects.with_feature_available_for_user(klass, current_user).reorder(nil) +``` + +Here we determine what projects to scope our data to, using three different +approaches. When a group is specified, we use `GroupProjectsFinder` to retrieve +all the projects of that group. On the surface this seems harmless: it is easy +to use, and we only need two lines of code. + +In reality, things can get hairy very quickly. For example, the query produced +by `GroupProjectsFinder` may start out simple. Over time more and more +functionality is added to this (high level) interface. Instead of _only_ +affecting the cases where this is necessary, it may also start affecting +`IssuableFinder` in a negative way. For example, the query produced by +`GroupProjectsFinder` may include unnecessary conditions. Since we're using a +finder here, we can't easily opt-out of that behaviour. We could add options to +do so, but then we'd need as many options as we have features. Every option adds +two code paths, which means that for four features we have to cover 8 different +code paths. + +A much more reliable (and pleasant) way of dealing with this, is to simply use +the underlying bits that make up `GroupProjectsFinder` directly. This means we +may need a little bit more code in `IssuableFinder`, but it also gives us much +more control and certainty. This means we might end up with something like this: + +```ruby +return @projects = project if project? + +projects = + if current_user && params[:authorized_only].presence && !current_user_related? + current_user.authorized_projects + elsif group + current_user + .owned_groups(subgroups: params[:include_subgroups]) + .projects + .any_additional_method_calls + .that_might_be_necessary + else + current_user + .projects_visible_to_user + .any_additional_method_calls + .that_might_be_necessary + end + +@projects = projects.with_feature_available_for_user(klass, current_user).reorder(nil) +``` + +This is just a sketch, but it shows the general idea: we would use whatever the +`GroupProjectsFinder` and `ProjectsFinder` finders use under the hoods. + +## End goal + +The guidelines in this document are meant to foster _better_ code reuse, by +clearly defining what can be reused where, and what to do when you can not reuse +something. Clearly separating abstractions makes it harder to use the wrong one, +makes it easier to debug the code, and (hopefully) results in fewer performance +problems. + +## Abstractions + +Now let's take a look at the various abstraction levels available, and what they +can (or cannot) reuse. For this we can use the following table, which defines +the various abstractions and what they can (not) reuse: + +| Abstraction | Service classes | Finders | Presenters | Serializers | Model instance method | Model class methods | Active Record | Worker +|:-----------------------|:-----------------|:---------|:------------|:--------------|:------------------------|:----------------------|:----------------|:-------- +| Controller | Yes | Yes | Yes | Yes | Yes | No | No | No +| Service class | Yes | Yes | No | No | Yes | No | No | Yes +| Finder | No | No | No | No | Yes | Yes | No | No +| Presenter | No | Yes | No | No | Yes | Yes | No | No +| Serializer | No | Yes | No | No | Yes | Yes | No | No +| Model class method | No | No | No | No | Yes | Yes | Yes | No +| Model instance method | No | Yes | No | No | Yes | Yes | Yes | Yes +| Worker | Yes | Yes | No | No | Yes | No | No | Yes + +### Controllers + +Everything in `app/controllers`. + +Controllers should not do much work on their own, instead they simply pass input +to other classes and present the results. + +### Grape endpoint + +Everything in `lib/api`. + +### Service classes + +Everything that resides in `app/services`. + +### Finders + +Everything in `app/finders`, typically used for retrieving data from a database. + +Finders can not reuse other finders in an attempt to better control the SQL +queries they produce. + +### Presenters + +Everything in `app/presenters`, used for exposing complex data to a Rails view, +without having to create many instance variables. + +### Serializers + +Everything in `app/serializers`, used for presenting the response to a request, +typically in JSON. + +### Model class methods + +These are class methods defined by _GitLab itself_, including the following +methods provided by Active Record: + +* `find` +* `find_by_id` +* `delete_all` +* `destroy` +* `destroy_all` + +Any other methods such as `find_by(some_column: X)` are not included, and +instead fall under the "Active Record" abstraction. + +### Model instance methods + +Instance methods defined on Active Record models by _GitLab itself_. Methods +provided by Active Record are not included, except for the following methods: + +* `save` +* `update` +* `destroy` +* `delete` + +### Active Record + +The API provided by Active Record itself, such as the `where` method, `save`, +`delete_all`, etc. + +### Worker + +Everything in `app/workers`. + +The scheduling of Sidekiq jobs using `SomeWorker.perform_async`, `perform_in`, +etc. Directly invoking a worker using `SomeWorker.new.perform` should be avoided +at all times in application code, though this is fine to use in tests. diff --git a/doc/development/rolling_out_changes_using_feature_flags.md b/doc/development/rolling_out_changes_using_feature_flags.md new file mode 100644 index 00000000000..905aa26a40b --- /dev/null +++ b/doc/development/rolling_out_changes_using_feature_flags.md @@ -0,0 +1,153 @@ +# Rolling out changes using feature flags + +[Feature flags](feature_flags.md) can be used to gradually roll out changes, be +it a new feature, or a performance improvement. By using feature flags, we can +comfortably measure the impact of our changes, while still being able to easily +disable those changes, without having to revert an entire release. + +## When to use feature flags + +Starting with GitLab 11.4, developers are required to use feature flags for +non-trivial changes. Such changes include: + +* New features (e.g. a new merge request widget, epics, etc). +* Complex performance improvements that may require additional testing in + production, such as rewriting complex queries. +* Invasive changes to the user interface, such as a new navigation bar or the + removal of a sidebar. +* Adding support for importing projects from a third-party service. + +In all cases, those working on the changes can best decide if a feature flag is +necessary. For example, changing the color of a button doesn't need a feature +flag, while changing the navigation bar definitely needs one. In case you are +uncertain if a feature flag is necessary, simply ask about this in the merge +request, and those reviewing the changes will likely provide you with an answer. + +When using a feature flag for UI elements, make sure to _also_ use a feature +flag for the underlying backend code, if there is any. This ensures there is +absolutely no way to use the feature until it is enabled. + +## The cost of feature flags + +When reading the above, one might be tempted to think this procedure is going to +add a lot of work. Fortunately, this is not the case, and we'll show why. For +this example we'll specify the cost of the work to do as a number, ranging from +0 to infinity. The greater the number, the more expensive the work is. The cost +does _not_ translate to time, it's just a way of measuring complexity of one +change relative to another. + +Let's say we are building a new feature, and we have determined that the cost of +this is 10. We have also determined that the cost of adding a feature flag check +in a variety of places is 1. If we do not use feature flags, and our feature +works as intended, our total cost is 10. This however is the best case scenario. +Optimising for the best case scenario is guaranteed to lead to trouble, whereas +optimising for the worst case scenario is almost always better. + +To illustrate this, let's say our feature causes an outage, and there's no +immediate way to resolve it. This means we'd have to take the following steps to +resolve the outage: + +1. Revert the release. +1. Perform any cleanups that might be necessary, depending on the changes that + were made. +1. Revert the commit, ensuring the "master" branch remains stable. This is + especially necessary if solving the problem can take days or even weeks. +1. Pick the revert commit into the appropriate stable branches, ensuring we + don't block any future releases until the problem is resolved. + +As history has shown, these steps are time consuming, complex, often involve +many developers, and worst of all: our users will have a bad experience using +GitLab.com until the problem is resolved. + +Now let's say that all of this has an associated cost of 10. This means that in +the worst case scenario, which we should optimise for, our total cost is now 20. + +If we had used a feature flag, things would have been very different. We don't +need to revert a release, and because feature flags are disabled by default we +don't need to revert and pick any Git commits. In fact, all we have to do is +disable the feature, and _maybe_ perform some cleanup. Let's say that the cost +of this is 1. In this case, our best case cost is 11: 10 to build the feature, +and 1 to add the feature flag. The worst case cost is now 12: 10 to build the +feature, 1 to add the feature flag, and 1 to disable it. + +Here we can see that in the best case scenario the work necessary is only a tiny +bit more compared to not using a feature flag. Meanwhile, the process of +reverting our changes has been made significantly cheaper, to the point of being +trivial. + +In other words, feature flags do not slow down the development process. Instead, +they speed up the process as managing incidents now becomes _much_ easier. Once +continuous deployments are easier to perform, the time to iterate on a feature +is reduced even further, as you no longer need to wait weeks before your changes +are available on GitLab.com. + +## Rolling out changes + +The procedure of using feature flags is straightforward, and similar to not +using them. You add the necessary tests (make sure to test both the on and off +states of your feature flag(s)), make sure they all pass, have the code +reviewed, etc. You then submit your merge request, and add the ~"feature flag" +label. This label is used to signal to release managers that your changes are +hidden behind a feature flag and that it is safe to pick the MR into a stable +branch, without the need for an exception request. + +When the changes are deployed it is time to start rolling out the feature to our +users. The exact procedure of rolling out a change is unspecified, as this can +vary from change to change. However, in general we recommend rolling out changes +incrementally, instead of enabling them for everybody right away. We also +recommend you to _not_ enable a feature _before_ the code is being deployed. +This allows you to separate rolling out a feature from a deploy, making it +easier to measure the impact of both separately. + +GitLab's feature library (using +[Flipper](https://github.com/jnunemaker/flipper), and covered in the [Feature +Flags](feature_flags.md) guide) supports rolling out changes to a percentage of +users. This in turn can be controlled using [GitLab +chatops](https://docs.gitlab.com/ee/ci/chatops/). + +For example, to enable a feature for 25% of all users, run the following in +Slack: + +``` +/chatops run feature set new_navigation_bar 25 +``` + +This will enable the feature for GitLab.com, with `new_navigation_bar` being the +name of the feature. We can also enable the feature for <https://dev.gitlab.org> +or <https://staging.gitlab.com>: + +``` +/chatops run feature set new_navigation_bar 25 --dev +/chatops run feature set new_navigation_bar 25 --staging +``` + +If you are not certain what percentages to use, simply use the following steps: + +1. 25% +1. 50% +1. 75% +1. 100% + +Between every step you'll want to wait a little while and monitor the +appropriate graphs on <https://dashboards.gitlab.net>. The exact time to wait +may differ. For some features a few minutes is enough, while for others you may +want to wait several hours or even days. This is entirely up to you, just make +sure it is clearly communicated to your team, and the Production team if you +anticipate any potential problems. + +Once a change is deemed stable, submit a new merge request to remove the +feature flag. This ensures the change is available to all users and self-hosted +instances. Make sure to add the ~"feature flag" label to this merge request so +release managers are aware the changes are hidden behind a feature flag. If the +merge request has to be picked into a stable branch (e.g. after the 7th), make +sure to also add the appropriate "Pick into X" label (e.g. "Pick into 11.4"). + +One might be tempted to think this will delay the release of a feature by at +least one month (= one release). This is not the case. A feature flag does not +have to stick around for a specific amount of time (e.g. at least one release), +instead they should stick around until the feature is deemed stable. Stable +means it works on GitLab.com without causing any problems, such as outages. In +most cases this will translate to a feature (with a feature flag) being shipped +in RC1, followed by the feature flag being removed in RC2. This in turn means +the feature will be stable by the time we publish a stable package around the +22nd of the month. diff --git a/doc/development/sidekiq_debugging.md b/doc/development/sidekiq_debugging.md index d6d770e27c1..84b61bd7e61 100644 --- a/doc/development/sidekiq_debugging.md +++ b/doc/development/sidekiq_debugging.md @@ -3,8 +3,7 @@ ## Log arguments to Sidekiq jobs If you want to see what arguments are being passed to Sidekiq jobs you can set -the `SIDEKIQ_LOG_ARGUMENTS` [environment variable] -(https://docs.gitlab.com/omnibus/settings/environment-variables.html) to `1` (true). +the `SIDEKIQ_LOG_ARGUMENTS` [environment variable](https://docs.gitlab.com/omnibus/settings/environment-variables.html) to `1` (true). Example: diff --git a/doc/development/testing_guide/ci.md b/doc/development/testing_guide/ci.md index 0d8e150e090..8d9706a9501 100644 --- a/doc/development/testing_guide/ci.md +++ b/doc/development/testing_guide/ci.md @@ -5,23 +5,23 @@ Our current CI parallelization setup is as follows: 1. The `knapsack` job in the prepare stage that is supposed to ensure we have a - `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file: - - The `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file is fetched - from S3, if it's not here we initialize the file with `{}`. + `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file: + - The `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file is fetched + from S3, if it's not here we initialize the file with `{}`. 1. Each `rspec x y` job are run with `knapsack rspec` and should have an evenly - distributed share of tests: - - It works because the jobs have access to the - `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` since the "artifacts - from all previous stages are passed by default". [^1] - - the jobs set their own report path to - `KNAPSACK_REPORT_PATH=knapsack/${CI_PROJECT_NAME}/${JOB_NAME[0]}_node_${CI_NODE_INDEX}_${CI_NODE_TOTAL}_report.json`. - - if knapsack is doing its job, test files that are run should be listed under - `Report specs`, not under `Leftover specs`. + distributed share of tests: + - It works because the jobs have access to the + `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` since the "artifacts + from all previous stages are passed by default". + - the jobs set their own report path to + `KNAPSACK_REPORT_PATH=knapsack/${CI_PROJECT_NAME}/${JOB_NAME[0]}_node_${CI_NODE_INDEX}_${CI_NODE_TOTAL}_report.json`. + - if knapsack is doing its job, test files that are run should be listed under + `Report specs`, not under `Leftover specs`. 1. The `update-knapsack` job takes all the - `knapsack/${CI_PROJECT_NAME}/${JOB_NAME[0]}_node_${CI_NODE_INDEX}_${CI_NODE_TOTAL}_report.json` - files from the `rspec x y` jobs and merge them all together into a single - `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file that is then - uploaded to S3. + `knapsack/${CI_PROJECT_NAME}/${JOB_NAME[0]}_node_${CI_NODE_INDEX}_${CI_NODE_TOTAL}_report.json` + files from the `rspec x y` jobs and merge them all together into a single + `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file that is then + uploaded to S3. After that, the next pipeline will use the up-to-date `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file. diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md index 0cd63a54b55..67e4cfeda0e 100644 --- a/doc/development/testing_guide/index.md +++ b/doc/development/testing_guide/index.md @@ -59,6 +59,12 @@ parallelization, monitoring. --- +## [Review apps](review_apps.md) + +How review apps are set up for GitLab CE/EE and how to use them. + +--- + ## [Testing Rake tasks](testing_rake_tasks.md) Everything you should know about how to test Rake tasks. diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md new file mode 100644 index 00000000000..25c6371f3d7 --- /dev/null +++ b/doc/development/testing_guide/review_apps.md @@ -0,0 +1,82 @@ +# Review apps + +We currently have review apps available as a manual job in EE pipelines. Here is +[the first implementation](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6259). + +That said, [the Quality team is working](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6665) +on making Review Apps automatically deployed by each pipeline, both in CE and EE. + +## How does it work? + +1. On every EE [pipeline][gitlab-pipeline] during the `test` stage, you can + start the [`review` job][review-job] +1. The `review` job [triggers a pipeline][cng-pipeline] in the + [`CNG-mirror`][cng-mirror] [^1] project +1. The `CNG-mirror` pipeline creates the Docker images of each component (e.g. `gitlab-rails-ee`, + `gitlab-shell`, `gitaly` etc.) based on the commit from the + [GitLab pipeline][gitlab-pipeline] and store them in its + [registry][cng-mirror-registry] +1. Once all images are built, the review app is deployed using + [the official GitLab Helm chart][helm-chart] [^2] to the + [`review-apps-ee` Kubernetes cluster on GCP][review-apps-ee] + - The actual scripts used to deploy the review app can be found at + [`scripts/review_apps/review-apps.sh`][review-apps.sh] + - These scripts are basically + [our official Auto DevOps scripts][Auto-DevOps.gitlab-ci.yml] where the + default CNG images are overriden with the images built and stored in the + [`CNG-mirror` project's registry][cng-mirror-registry] +1. Once the `review` job succeeds, you should be able to use your review app + thanks to the direct link to it from the MR widget. The default username is + `root` and its password can be found in the 1Password secure note named + **gitlab-{ce,ee} review app's root password**. + +**Additional notes:** + +- The Kubernetes cluster is connected to the `gitlab-ee` project using [GitLab's + Kubernetes integration][gitlab-k8s-integration]. This basically allows to have + a link to the review app directly from the merge request widget. +- The manual `stop_review` in the `post-cleanup` stage can be used to stop a + review app manually, and is also started by GitLab once a branch is deleted +- [TBD] Review apps are cleaned up regularly using a pipeline schedule that runs + the [`scripts/review_apps/automated_cleanup.rb`][automated_cleanup.rb] script + +[^1]: We use the `CNG-mirror` project so that the `CNG`, (**C**loud **N**ative **G**itLab), project's registry is + not overloaded with a lot of transient Docker images. +[^2]: Since we're using [the official GitLab Helm chart][helm-chart], this means + you get the a dedicated environment for your branch that's very close to what it + would look in production + +## Frequently Asked Questions + +**Will it be too much to trigger CNG image builds on every test run? This could create thousands of unused docker images.** + + > We have to start somewhere and improve later. If we see this getting out of hand, we will revisit. + +**How big is the Kubernetes cluster?** + + > The cluster is currently setup with a single pool of preemptible + nodes, with a minimum of 1 node and a maximum of 30 nodes. + +**What are the machine running on the cluster?** + + > We're currently using `n1-standard-4` (4 vCPUs, 15 GB memory) machines. + +**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.** + + > This won't work for forks. We will add a root password to 1password shared vault. + +[gitlab-pipeline]: https://gitlab.com/gitlab-org/gitlab-ee/pipelines/29302122 +[review-job]: https://gitlab.com/gitlab-org/gitlab-ee/-/jobs/94294136 +[cng-mirror]: https://gitlab.com/gitlab-org/build/CNG-mirror +[cng-pipeline]: https://gitlab.com/gitlab-org/build/CNG-mirror/pipelines/29307727 +[cng-mirror-registry]: https://gitlab.com/gitlab-org/build/CNG-mirror/container_registry +[helm-chart]: https://gitlab.com/charts/gitlab/ +[review-apps-ee]: https://console.cloud.google.com/kubernetes/clusters/details/us-central1-b/review-apps-ee?project=gitlab-review-apps +[review-apps.sh]: https://gitlab.com/gitlab-org/gitlab-ee/blob/master/scripts/review_apps/review-apps.sh +[automated_cleanup.rb]: https://gitlab.com/gitlab-org/gitlab-ee/blob/master/scripts/review_apps/automated_cleanup.rb +[Auto-DevOps.gitlab-ci.yml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml +[gitlab-k8s-integration]: https://docs.gitlab.com/ee/user/project/clusters/index.html + +--- + +[Return to Testing documentation](index.md) diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index 4403072e96f..32ed22ca3ed 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -153,7 +153,7 @@ trade-off: - Unit tests are usually cheap, and you should consider them like the basement of your house: you need them to be confident that your code is behaving correctly. However if you run only unit tests without integration / system - tests, you might [miss] the [big] [picture]! + tests, you might [miss] the [big] / [picture] ! - Integration tests are a bit more expensive, but don't abuse them. A system test is often better than an integration test that is stubbing a lot of internals. - System tests are expensive (compared to unit tests), even more if they require diff --git a/doc/development/ux_guide/users.md b/doc/development/ux_guide/users.md index 6afb33cfc36..f9c395b2dff 100644 --- a/doc/development/ux_guide/users.md +++ b/doc/development/ux_guide/users.md @@ -154,7 +154,7 @@ He credits himself as being entirely responsible for moving his company to GitLa #### Updating to the latest release Matthieu introduced his company to GitLab. He is responsible for maintaining and managing the company's installation in addition to his day job. He feels updates are too frequent and he doesn't always have sufficient time to update GitLab. As a result, he's not up to date with releases. -Matthieu tried to set up automatic updates, however, as he isn't a Systems Administrator, he wasn't confident in his set-up. He feels he should be able to "upgrade without users even noticing" but hasn't figured out how to do this yet. Matthieu would like the "update process to be triggered from the Admin Panel, perhaps accompanied with a changelog and the option to skip updates." +Matthieu tried to set up automatic updates, however, as he isn't a Systems Administrator, he wasn't confident in his setup. He feels he should be able to "upgrade without users even noticing" but hasn't figured out how to do this yet. Matthieu would like the "update process to be triggered from the Admin Panel, perhaps accompanied with a changelog and the option to skip updates." Matthieu is looking for confirmation that his update procedure is "secure and efficient" so more tutorials related to this topic would be useful to him. @@ -242,7 +242,7 @@ Some of GitLab EE's features are too basic, in particular, issues boards which d James and his team use CI quite heavily for several projects. Whilst they've welcomed improvements to the builds and pipelines interface, they still have some difficulty following build process on the different tabs under Pipelines. Some confusion has arisen from not knowing where to find different pieces of information or how to get to the next stages logs from the current stage's log output screen. They feel more intuitive linking and flow may alleviate the problem. Generally, they feel GitLab's navigation needs to reviewed and optimized. #### Permissions ->"There is no granular control over user or group permissions. The permissions for a project are too tightly coupled to the permissions for Gitlab CI/build pipelines." +>"There is no granular control over user or group permissions. The permissions for a project are too tightly coupled to the permissions for GitLab CI/build pipelines." ### Goals @@ -290,7 +290,7 @@ JavaScript and SQL Web development, mobile development, UX, open source, gaming, and travel. ### Motivations -Karolina has been using GitLab.com for around a year. She roughly spends 8 hours every week programming, of that, 2 hours is spent contributing to open source projects. Karolina contributes to open source projects to gain programming experience and to give back to the community. She likes GitLab.com for its free private repositories and range of features which provide her with everything she needs for her personal projects. Karolina is also a massive fan of GitLab's values and the fact that it isn't a "behemoth of a company". She explains that "displaying every single thing (doc, culture, assumptions, development...) in the open gives me greater confidence to choose Gitlab personally and to recommend it at work." She's also an avid reader of GitLab's blog. +Karolina has been using GitLab.com for around a year. She roughly spends 8 hours every week programming, of that, 2 hours is spent contributing to open source projects. Karolina contributes to open source projects to gain programming experience and to give back to the community. She likes GitLab.com for its free private repositories and range of features which provide her with everything she needs for her personal projects. Karolina is also a massive fan of GitLab's values and the fact that it isn't a "behemoth of a company". She explains that "displaying every single thing (doc, culture, assumptions, development...) in the open gives me greater confidence to choose GitLab personally and to recommend it at work." She's also an avid reader of GitLab's blog. Karolina works for a software development company which currently hires around 500 people. Karolina would love to use GitLab at work but the company has used GitHub Enterprise for a number of years. She describes management at her company as "old fashioned" and explains that it's "less of a technical issue and more of a cultural issue" to convince upper management to move to GitLab. Karolina is also relatively new to the company so she's apprehensive about pushing too hard to change version control platforms. diff --git a/doc/gitlab-basics/add-image.md b/doc/gitlab-basics/add-image.md index 1a44123aa81..17c210c43e0 100644 --- a/doc/gitlab-basics/add-image.md +++ b/doc/gitlab-basics/add-image.md @@ -5,7 +5,7 @@ in Windows, or...), put the image file into the GitLab project. You can find the project as a regular folder in your files. Go to your [shell](command-line-commands.md), and move into the folder of your -Gitlab project. This usually means running the following command until you get +GitLab project. This usually means running the following command until you get to the desired destination: ``` diff --git a/doc/gitlab-basics/command-line-commands.md b/doc/gitlab-basics/command-line-commands.md index 4666511d747..a0111be0767 100644 --- a/doc/gitlab-basics/command-line-commands.md +++ b/doc/gitlab-basics/command-line-commands.md @@ -125,3 +125,6 @@ pwd ``` clear ``` +### Sample Git taskflow + +If you are completely new to Git, looking through some [sample taskflows](https://rogerdudler.github.io/git-guide/) will help you understand best practices for using these commands as you work. diff --git a/doc/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md index 2517908e5b1..33f46e8d4f3 100644 --- a/doc/gitlab-basics/create-project.md +++ b/doc/gitlab-basics/create-project.md @@ -1,8 +1,8 @@ # How to create a project in GitLab ->**Notes:** -- For a list of words that are not allowed to be used as project names see the - [reserved names][reserved]. +> **Notes:** +> - For a list of words that are not allowed to be used as project names see the +> [reserved names][reserved]. 1. In your dashboard, click the green **New project** button or use the plus icon in the upper right corner of the navigation bar. diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index 21694b02d18..7835401cc0b 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -71,17 +71,19 @@ The first items we need to configure are the basic settings of the underlying vi 1. Enter a `User name` - e.g. **"gitlab-admin"** 1. Select an `Authentication type`, either **SSH public key** or **Password**: - >**Note:** if you're unsure which authentication type to use, select **Password** + > **Note:** if you're unsure which authentication type to use, select **Password** 1. If you chose **SSH public key** - enter your `SSH public key` into the field provided - _(read the [SSH documentation][GitLab-Docs-SSH] to learn more about how to setup SSH + _(read the [SSH documentation][GitLab-Docs-SSH] to learn more about how to set up SSH public keys)_ 1. If you chose **Password** - enter the password you wish to use _(this is the password that you will use later in this tutorial to [SSH] into the VM, so make sure it's a strong password/passphrase)_ 1. Choose the appropriate `Subscription` tier for your Azure account 1. Choose an existing `Resource Group` or create a new one - e.g. **"GitLab-CE-Azure"** ->**Note:** a "Resource group" is a way to group related resources together for easier administration. -We chose "GitLab-CE-Azure", but your resource group can have the same name as your VM. + + > **Note:** a "Resource group" is a way to group related resources together for easier administration. + > We chose "GitLab-CE-Azure", but your resource group can have the same name as your VM. + 1. Choose a `Location` - if you're unsure, select the default location Here are the settings we've used: @@ -95,7 +97,7 @@ Check the settings you have entered, and then click **"OK"** when you're ready t Next, you need to choose the size of your VM - selecting features such as the number of CPU cores, the amount of RAM, the size of storage (and its speed), etc. ->**Note:** in common with other cloud vendors, Azure operates a resource/usage pricing model, i.e. +> **Note:** in common with other cloud vendors, Azure operates a resource/usage pricing model, i.e. the more resources your VM consumes the more it will cost you to run, so make your selection carefully. You'll see that Azure provides an _estimated_ monthly cost beneath each VM Size to help guide your selection. @@ -106,7 +108,7 @@ ahead and select this one, but please choose the size which best meets your own  ->**Note:** be aware that whilst your VM is active (known as "allocated"), it will incur +> **Note:** be aware that whilst your VM is active (known as "allocated"), it will incur "compute charges" which, ultimately, you will be billed for. So, even if you're using the free trial credits, you'll likely want to learn [how to properly shutdown an Azure VM to save money][Azure-Properly-Shutdown-VM]. @@ -132,7 +134,7 @@ new VM. You'll be billed only for the VM itself (e.g. "Standard DS1 v2") because  ->**Note:** at this stage, you can review and modify the any of the settings you have made during all +> **Note:** at this stage, you can review and modify the any of the settings you have made during all previous steps, just click on any of the four steps to re-open them. When you have read and agreed to the terms of use and are ready to proceed, click **"Purchase"**. @@ -152,7 +154,7 @@ on the Azure Dashboard (you may need to refresh the page): The new VM can also be accessed by clicking the `All resources` or `Virtual machines` icons in the Azure Portal sidebar navigation menu. -## Setup a domain name +## Set up a domain name The VM will have a public IP address (static by default), but Azure allows us to assign a friendly DNS name to the VM, so let's go ahead and do that. @@ -174,7 +176,7 @@ _(the full domain name of your own VM will be different, of course)_. Click **"Save"** for the changes to take effect. ->**Note:** if you want to use your own domain name, you will need to add a DNS `A` record at your +> **Note:** if you want to use your own domain name, you will need to add a DNS `A` record at your domain registrar which points to the public IP address of your Azure VM. If you do this, you'll need to make sure your VM is configured to use a _static_ public IP address (i.e. not a _dynamic_ one) or you will have to reconfigure the DNS `A` record each time Azure reassigns your VM a new public IP @@ -190,7 +192,7 @@ Ports are opened by adding _security rules_ to the **"Network security group"** has been assigned to. If you followed the process above, then Azure will have automatically created an NSG named `GitLab-CE-nsg` and assigned the `GitLab-CE` VM to it. ->**Note:** if you gave your VM a different name then the NSG automatically created by Azure will +> **Note:** if you gave your VM a different name then the NSG automatically created by Azure will also have a different name - the name you have your VM, with `-nsg` appended to it. You can navigate to the NSG settings via many different routes in the Azure Portal, but one of the @@ -294,7 +296,7 @@ homepage for the project:  If you scroll further down the project's home page, you'll see some basic instructions on how to -setup a local clone of your new repository and push and pull from it: +set up a local clone of your new repository and push and pull from it:  @@ -321,7 +323,7 @@ Under the **"Components"** section, we can see that our VM is currently running GitLab. This is the version of GitLab which was contained in the Azure Marketplace **"GitLab Community Edition"** offering we used to build the VM when we wrote this tutorial. ->**Note:** The version of GitLab in your own VM instance may well be different, but the update +> **Note:** The version of GitLab in your own VM instance may well be different, but the update process will still be the same. ### Connect via SSH @@ -333,11 +335,11 @@ connect to it using SSH ([Secure Shell][SSH]). If you're running Windows, you'll need to connect using [PuTTY] or an equivalent Windows SSH client. 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 -[how to reset SSH credentials for a user on an Azure VM][Azure-Troubleshoot-SSH-Connection]. +> **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 +> [how to reset SSH credentials for a user on an Azure VM][Azure-Troubleshoot-SSH-Connection]. #### SSH from the command-line @@ -345,7 +347,7 @@ If you're running [SSH] from the command-line (terminal), then type in the follo connect to your VM, substituting `username` and `your-azure-domain-name.com` for the correct values. Again, remember that your Azure VM domain name will be the one you -[setup previously in the tutorial](#set-up-a-domain-name). If you didn't setup a domain name for +[set up previously in the tutorial](#set-up-a-domain-name). If you didn't set up a domain name for your VM, you can use the IP address in its place in the following command: ```bash @@ -399,7 +401,7 @@ is now showing **"up-to-date"**: Naturally, we believe that GitLab is a great git repository tool. However, GitLab is a whole lot more than that too. GitLab unifies issues, code review, CI and CD into a single UI, helping you to move faster from idea to production, and in this tutorial we showed you how quick and easy it is to -setup and run your own instance of GitLab on Azure, Microsoft's cloud service. +set up and run your own instance of GitLab on Azure, Microsoft's cloud service. Azure is a great way to experiment with GitLab, and if you decide (as we hope) that GitLab is for you, you can continue to use Azure as your secure, scalable cloud provider or of course run GitLab @@ -422,7 +424,7 @@ Check out our other [Technical Articles][GitLab-Technical-Articles] or browse th - [Azure - Properly Shutdown an Azure VM][Azure-Properly-Shutdown-VM] - [SSH], [PuTTY] and [Using SSH in PuTTY][Using-SSH-In-Putty] -[Original-Blog-Post]: https://about.gitlab.com/2016/07/13/how-to-setup-a-gitlab-instance-on-microsoft-azure/ "How to Setup a GitLab Instance on Microsoft Azure" +[Original-Blog-Post]: https://about.gitlab.com/2016/07/13/how-to-setup-a-gitlab-instance-on-microsoft-azure/ "How to Set up a GitLab Instance on Microsoft Azure" [GitLab-Docs]: https://docs.gitlab.com/ce/README.html "GitLab Documentation" [GitLab-Technical-Articles]: https://docs.gitlab.com/ce/articles/index.html "GitLab Technical Articles" [GitLab-Docs-SSH]: https://docs.gitlab.com/ce/ssh/README.html "GitLab Documentation: SSH" diff --git a/doc/install/database_mysql.md b/doc/install/database_mysql.md index e1af086f418..acaed53e052 100644 --- a/doc/install/database_mysql.md +++ b/doc/install/database_mysql.md @@ -1,11 +1,11 @@ # Database MySQL ->**Note:** -- We do not recommend using MySQL due to various issues. For example, case -[(in)sensitivity](https://dev.mysql.com/doc/refman/5.0/en/case-sensitivity.html) -and [problems](https://bugs.mysql.com/bug.php?id=65830) that -[suggested](https://bugs.mysql.com/bug.php?id=50909) -[fixes](https://bugs.mysql.com/bug.php?id=65830) [have](https://bugs.mysql.com/bug.php?id=63164). +> **Note:** +> - We do not recommend using MySQL due to various issues. For example, case + [(in)sensitivity](https://dev.mysql.com/doc/refman/5.0/en/case-sensitivity.html) + and [problems](https://bugs.mysql.com/bug.php?id=65830) that + [suggested](https://bugs.mysql.com/bug.php?id=50909) + [fixes](https://bugs.mysql.com/bug.php?id=65830) [have](https://bugs.mysql.com/bug.php?id=63164). ## Initial database setup @@ -79,7 +79,7 @@ After installation or upgrade, remember to [convert any new tables](#tables-and- --- -GitLab 8.14 has introduced [a feature](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7420) requiring `utf8mb4` encoding to be supported in your GitLab MySQL Database, which is not the case if you have setup your database before GitLab 8.16. +GitLab 8.14 has introduced [a feature](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7420) requiring `utf8mb4` encoding to be supported in your GitLab MySQL Database, which is not the case if you have set up your database before GitLab 8.16. Follow the below instructions to ensure you use the most up to date requirements for your GitLab MySQL Database. @@ -146,10 +146,12 @@ Congrats, your GitLab database uses the right InnoDB tablespace format. However, you must still ensure that any **future tables** created by GitLab will still use the right format: - If `SELECT @@innodb_file_per_table` returned **1** previously, your server is running correctly. -> It's however a requirement to check *now* that this setting is indeed persisted in your [my.cnf](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) file! + + > It's however a requirement to check *now* that this setting is indeed persisted in your [my.cnf](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) file! - If `SELECT @@innodb_file_per_table` returned **0** previously, your server is not running correctly. -> [Enable innodb_file_per_table](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) by running in a MySQL session as root the command `SET GLOBAL innodb_file_per_table=1, innodb_file_format=Barracuda;` and persist the two settings in your [my.cnf](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) file + + > [Enable innodb_file_per_table](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) by running in a MySQL session as root the command `SET GLOBAL innodb_file_per_table=1, innodb_file_format=Barracuda;` and persist the two settings in your [my.cnf](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) file Now, if you have a **different result** returned by the 2 commands above, it means you have a **mix of tables format** uses in your GitLab database. This can happen if your MySQL server had different values for `innodb_file_per_table` in its life and you updated GitLab at different moments with those inconsistent values. So keep reading. diff --git a/doc/install/digitaloceandocker.md b/doc/install/digitaloceandocker.md index 8efc0530b8a..676392eacf2 100644 --- a/doc/install/digitaloceandocker.md +++ b/doc/install/digitaloceandocker.md @@ -87,7 +87,7 @@ You can add this to your `~/.bash_profile` file to ensure the `docker` client us + Container name: `gitlab-test-8.10` + GitLab version: **EE** `8.10.8-ee.0` -##### Setup container settings +##### Set up container settings ``` export SSH_PORT=2222 diff --git a/doc/install/installation.md b/doc/install/installation.md index 2d657163721..7df81fbc46f 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -12,7 +12,7 @@ Since installations from source don't have Runit, Sidekiq can't be terminated an ## Select Version to Install -Make sure you view [this installation guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md) from the branch (version) of GitLab you would like to install (e.g., `11-2-stable`). +Make sure you view [this installation guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md) from the branch (version) of GitLab you would like to install (e.g., `11-3-stable`). You can select the branch in the version dropdown in the top left corner of GitLab (below the menu bar). If the highest number stable branch is unclear please check the [GitLab Blog](https://about.gitlab.com/blog/) for installation guide links by version. @@ -300,9 +300,9 @@ sudo usermod -aG redis git ### Clone the Source # Clone GitLab repository - sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 11-2-stable gitlab + sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 11-3-stable gitlab -**Note:** You can change `11-2-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! +**Note:** You can change `11-3-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! ### Configure It @@ -483,7 +483,7 @@ For more information about configuring Gitaly see sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production # Type 'yes' to create the database tables. - + # or you can skip the question by adding force=yes sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production force=yes @@ -515,7 +515,7 @@ Make GitLab start on boot: sudo update-rc.d gitlab defaults 21 -### Setup Logrotate +### Set up Logrotate sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md index 5a6f26319c7..6d1bc4aedc4 100644 --- a/doc/install/kubernetes/gitlab_chart.md +++ b/doc/install/kubernetes/gitlab_chart.md @@ -40,9 +40,9 @@ In order to deploy GitLab on Kubernetes, the following are required: 1. `helm` and `kubectl` [installed on your computer](preparation/tools_installation.md). 1. A Kubernetes cluster, version 1.8 or higher. 6vCPU and 16GB of RAM is recommended. - - [Google GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-container-cluster) - - [Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html) - - [Microsoft AKS](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal) + - [Google GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-container-cluster) + - [Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html) + - [Microsoft AKS](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal) 1. A [wildcard DNS entry and external IP address](preparation/networking.md) 1. [Authenticate and connect](preparation/connect.md) to the cluster 1. Configure and initialize [Helm Tiller](preparation/tiller.md). @@ -52,7 +52,7 @@ In order to deploy GitLab on Kubernetes, the following are required: To deploy GitLab, the following three parameters are required: - `global.hosts.domain`: the [base domain](preparation/networking.md) of the - wildcard host entry. For example, `exampe.com` if the wild card entry is + wildcard host entry. For example, `example.com` if the wild card entry is `*.example.com`. - `global.hosts.externalIP`: the [external IP](preparation/networking.md) which the wildcard DNS resolves to. @@ -93,7 +93,7 @@ You can access the GitLab instance by visiting the domain name beginning with above, the URL would be `https://gitlab.example.com`. If you manually created the secret for initial root password, you -can use that to sign in as `root` user. If not, Gitlab automatically +can use that to sign in as `root` user. If not, GitLab automatically created a random password for `root` user. This can be extracted by the following command (replace `<name>` by name of the release - which is `gitlab` if you used the command above): @@ -123,6 +123,8 @@ To deploy the Community Edition, include these options in your `helm install` co --set gitlab.migrations.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-rails-ce --set gitlab.sidekiq.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-sidekiq-ce --set gitlab.unicorn.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-unicorn-ce +--set gitlab.unicorn.workhorse.image=registry.gitlab.com/gitlab-org/build/cng/gitlab-workhorse-ce +--set gitlab.task-runner.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-task-runner-ce ``` ## Updating GitLab using the Helm Chart @@ -131,6 +133,7 @@ Once your GitLab Chart is installed, configuration changes and chart updates should be done using `helm upgrade`: ```sh +helm repo update helm upgrade --reuse-values gitlab gitlab/gitlab ``` diff --git a/doc/install/kubernetes/gitlab_omnibus.md b/doc/install/kubernetes/gitlab_omnibus.md index d80cb6ad374..498b702cab1 100644 --- a/doc/install/kubernetes/gitlab_omnibus.md +++ b/doc/install/kubernetes/gitlab_omnibus.md @@ -101,7 +101,7 @@ Other common configuration options: - `provider`: Optimizes the deployment for a cloud provider. The default is `gke` for [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/), with `acs` also supported for the [Azure Container Service](https://azure.microsoft.com/en-us/services/container-service/). For additional configuration options, consult the -[`values.yaml`](https://gitlab.com/charts/charts.gitlab.io/blob/master/charts/gitlab-omnibus/values.yaml). +[`values.yaml`](https://gitlab.com/charts/gitlab-omnibus/blob/master/values.yaml). ### Choosing a different GitLab release version @@ -228,7 +228,7 @@ helm upgrade gitlab --set gitlab=ee,gitlabEEImage=gitlab/gitlab-ee:9.5.5-ee.0 gi To uninstall the GitLab Chart, run the following: ```bash -helm delete gitlab +helm delete --purge gitlab ``` ## Troubleshooting diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md index e67d5ba4d4c..69171fbb341 100644 --- a/doc/install/kubernetes/index.md +++ b/doc/install/kubernetes/index.md @@ -4,23 +4,12 @@ description: 'Read through the different methods to deploy GitLab on Kubernetes. # Installing GitLab on Kubernetes -NOTE: **Note**: These charts have been tested on Google Kubernetes Engine. Other -Kubernetes installations may work as well, if not please [open an issue](https://gitlab.com/charts/issues). - The easiest method to deploy GitLab on [Kubernetes](https://kubernetes.io/) is to take advantage of GitLab's Helm charts. [Helm] is a package management tool for Kubernetes, allowing apps to be easily managed via their Charts. A [Chart] is a detailed description of the application including how it should be deployed, upgraded, and configured. -## Chart Overview - -- **[GitLab Chart](gitlab_chart.html)**: Deploys GitLab on Kubernetes. Includes all the required components to get started, and can scale to large deployments. -- **[GitLab Runner Chart](gitlab_runner_chart.md)**: For deploying just the GitLab Runner. -- Other Charts - - [GitLab-Omnibus](gitlab_omnibus.md): Chart based on the Omnibus GitLab package, only suitable for small deployments. Deprecated, we strongly recommend using the [gitlab](#gitlab-chart) chart. - - [Community contributed charts](#community-contributed-charts): Community contributed charts. - ## GitLab Chart This chart contains all the required components to get started, and can scale to @@ -30,6 +19,7 @@ large deployments. It offers a number of benefits: - No requirement for shared storage to scale - Containers do not need `root` permissions - Automatic SSL with Let's Encrypt +- An unprivileged GitLab Runner - and plenty more. Learn more about the [GitLab chart](gitlab_chart.md). @@ -43,13 +33,13 @@ it can be deployed with the GitLab Runner chart. Learn more about [gitlab-runner chart](gitlab_runner_chart.md). -## Other Charts - -### GitLab-Omnibus Chart +## Deprecated Charts CAUTION: **Deprecated:** -This chart is **deprecated**. We recommend using the [GitLab Chart](gitlab_chart.md) -instead. A comparison of the two charts is available in [this video](https://youtu.be/Z6jWR8Z8dv8). +These charts are **deprecated**. We recommend using the [GitLab Chart](gitlab_chart.md) +instead. + +### GitLab-Omnibus Chart This chart is based on the [GitLab Omnibus Docker images](https://docs.gitlab.com/omnibus/docker/). It deploys and configures nearly all features of GitLab, including: @@ -64,7 +54,7 @@ Learn more about the [gitlab-omnibus chart](gitlab_omnibus.md). ### Community Contributed Charts -The community has also contributed GitLab [CE](https://github.com/kubernetes/charts/tree/master/stable/gitlab-ce) and [EE](https://github.com/kubernetes/charts/tree/master/stable/gitlab-ee) charts to the [Helm Stable Repository](https://github.com/kubernetes/charts#repository-structure). These charts should be considered [deprecated](https://github.com/kubernetes/charts/issues/1138) in favor of the [official Charts](gitlab_omnibus.md). +The community has also contributed GitLab [CE](https://github.com/kubernetes/charts/tree/master/stable/gitlab-ce) and [EE](https://github.com/kubernetes/charts/tree/master/stable/gitlab-ee) charts to the [Helm Stable Repository](https://github.com/kubernetes/charts#repository-structure). These charts are [deprecated](https://github.com/kubernetes/charts/issues/1138) in favor of the [official Chart](gitlab_chart.md). [chart]: https://github.com/kubernetes/charts [helm]: https://github.com/kubernetes/helm/blob/master/README.md diff --git a/doc/install/openshift_and_gitlab/index.md b/doc/install/openshift_and_gitlab/index.md index 60e1e2b5f8a..5c8a830ac8f 100644 --- a/doc/install/openshift_and_gitlab/index.md +++ b/doc/install/openshift_and_gitlab/index.md @@ -63,22 +63,24 @@ what we will use in this tutorial. In short: 1. Open a terminal and in a new directory run: - ```sh - vagrant init openshift/origin-all-in-one - ``` + + ```sh + vagrant init openshift/origin-all-in-one + ``` + 1. This will generate a Vagrantfile based on the all-in-one VM image 1. In the same directory where you generated the Vagrantfile enter: - ```sh - vagrant up - ``` + ```sh + vagrant up + ``` This will download the VirtualBox image and fire up the VM with some preconfigured values as you can see in the Vagrantfile. As you may have noticed, you need plenty of RAM (5GB in our example), so make sure you have enough. -Now that OpenShift is setup, let's see how the web console looks like. +Now that OpenShift is set up, let's see how the web console looks like. ### Explore the OpenShift web console @@ -187,22 +189,22 @@ In that case, the OpenShift service might not be running, so in order to fix it: 1. SSH into the VM by going to the directory where the Vagrantfile is and then run: - ```sh - vagrant ssh - ``` + ```sh + vagrant ssh + ``` 1. Run `systemctl` and verify by the output that the `openshift` service is not running (it will be in red color). If that's the case start the service with: - ```sh - sudo systemctl start openshift - ``` + ```sh + sudo systemctl start openshift + ``` 1. Verify the service is up with: - ```sh - systemctl status openshift -l - ``` + ```sh + systemctl status openshift -l + ``` Now you will be able to login using `oc` (like we did before) and visit the web console. @@ -385,55 +387,55 @@ Let's see how to do that using the following steps. 1. Make sure you are in the `gitlab` project: - ```sh - oc project gitlab - ``` + ```sh + oc project gitlab + ``` 1. See what services are used for this project: - ```sh - oc get svc - ``` + ```sh + oc get svc + ``` - The output will be similar to: + The output will be similar to: - ``` - NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE - gitlab-ce 172.30.243.177 <none> 22/TCP,80/TCP 5d - gitlab-ce-postgresql 172.30.116.75 <none> 5432/TCP 5d - gitlab-ce-redis 172.30.105.88 <none> 6379/TCP 5d - ``` + ``` + NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE + gitlab-ce 172.30.243.177 <none> 22/TCP,80/TCP 5d + gitlab-ce-postgresql 172.30.116.75 <none> 5432/TCP 5d + gitlab-ce-redis 172.30.105.88 <none> 6379/TCP 5d + ``` 1. We need to see the replication controllers of the `gitlab-ce` service. Get a detailed view of the current ones: - ```sh - oc describe rc gitlab-ce - ``` + ```sh + oc describe rc gitlab-ce + ``` - This will return a large detailed list of the current replication controllers. - Search for the name of the GitLab controller, usually `gitlab-ce-1` or if - that failed at some point and you spawned another one, it will be named - `gitlab-ce-2`. + This will return a large detailed list of the current replication controllers. + Search for the name of the GitLab controller, usually `gitlab-ce-1` or if + that failed at some point and you spawned another one, it will be named + `gitlab-ce-2`. 1. Scale GitLab using the previous information: - ```sh - oc scale --replicas=2 replicationcontrollers gitlab-ce-2 - ``` + ```sh + oc scale --replicas=2 replicationcontrollers gitlab-ce-2 + ``` 1. Get the new replicas number to make sure scaling worked: - ```sh - oc get rc gitlab-ce-2 - ``` + ```sh + oc get rc gitlab-ce-2 + ``` - which will return something like: + which will return something like: - ``` - NAME DESIRED CURRENT AGE - gitlab-ce-2 2 2 5d - ``` + ``` + NAME DESIRED CURRENT AGE + gitlab-ce-2 2 2 5d + ``` And that's it! We successfully scaled the replicas to 2 using the CLI. @@ -469,9 +471,10 @@ GitLab service account to the `anyuid` [Security Context Constraints][scc]. For OpenShift v3.0, you will need to do this manually: 1. Edit the Security Context: - ```sh - oc edit scc anyuid - ``` + + ```sh + oc edit scc anyuid + ``` 1. Add `system:serviceaccount:<project>:gitlab-ce-user` to the `users` section. If you changed the Application Name from the default the user will diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md index 2f5d4142d04..5f129fd3bd1 100644 --- a/doc/install/relative_url.md +++ b/doc/install/relative_url.md @@ -124,5 +124,5 @@ To disable the relative URL: 1. Follow the same as above starting from 2. and set up the GitLab URL to one that doesn't contain a relative path. -[omnibus-rel]: http://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab "How to setup relative URL in Omnibus GitLab" +[omnibus-rel]: http://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab "How to set up relative URL in Omnibus GitLab" [restart gitlab]: ../administration/restart_gitlab.md#installations-from-source "How to restart GitLab" diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 5531dcde4e9..13a6a1c68ad 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -27,7 +27,7 @@ Please see the [installation from source guide](installation.md) and the [instal ### Non-Unix operating systems such as Windows -GitLab is developed for Unix operating systems. +GitLab is developed for Unix operating systems. It does **not** run on Windows, and we have no plans to support it in the near future. For the latest development status view this [issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/46567). Please consider using a virtual machine to run GitLab. @@ -103,19 +103,21 @@ features of GitLab work with MySQL/MariaDB: 1. MySQL support for subgroups was [dropped with GitLab 9.3][post]. See [issue #30472][30472] for more information. -1. GitLab Geo does [not support MySQL](https://docs.gitlab.com/ee/gitlab-geo/database.html#mysql-replication). -1. [Zero downtime migrations][zero] do not work with MySQL +1. Geo does [not support MySQL](https://docs.gitlab.com/ee/administration/geo/replication/database.html#mysql-replication). This means no supported Disaster Recovery solution if using MySQL. **[PREMIUM ONLY]** +1. [Zero downtime migrations][../update/README.md#upgrading-without-downtime] do not work with MySQL. 1. GitLab [optimizes the loading of dashboard events](https://gitlab.com/gitlab-org/gitlab-ce/issues/31806) using [PostgreSQL LATERAL JOINs](https://blog.heapanalytics.com/postgresqls-powerful-new-join-type-lateral/). 1. In general, SQL optimized for PostgreSQL may run much slower in MySQL due to differences in query planners. For example, subqueries that work well in PostgreSQL - may not be [performant in MySQL](https://dev.mysql.com/doc/refman/5.7/en/optimizing-subqueries.html) + may not be [performant in MySQL](https://dev.mysql.com/doc/refman/5.7/en/optimizing-subqueries.html). +1. Binary column index length is limited to 20 bytes. This is accomplished with [a hack](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/initializers/mysql_set_length_for_binary_indexes.rb). +1. MySQL requires a variety of hacks to increase limits on various columns, [for example](https://gitlab.com/gitlab-org/gitlab-ce/issues/49583). +1. [The milestone filter runs slower queries on MySQL](https://gitlab.com/gitlab-org/gitlab-ce/issues/51173#note_99391731). 1. We expect this list to grow over time. Existing users using GitLab with MySQL/MariaDB are advised to [migrate to PostgreSQL](../update/mysql_to_postgresql.md) instead. [30472]: https://gitlab.com/gitlab-org/gitlab-ce/issues/30472 -[zero]: ../update/README.md#upgrading-without-downtime [post]: https://about.gitlab.com/2017/06/22/gitlab-9-3-released/#dropping-support-for-subgroups-in-mysql ### PostgreSQL Requirements diff --git a/doc/integration/azure.md b/doc/integration/azure.md index f3c9c498634..634dd952448 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -2,7 +2,7 @@ To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your application with Azure. Azure will generate a client ID and secret key for you to use. -1. Sign in to the [Azure Management Portal](https://manage.windowsazure.com>). +1. Sign in to the [Azure Management Portal](https://manage.windowsazure.com). 1. Select "Active Directory" on the left and choose the directory you want to use to register GitLab. diff --git a/doc/integration/github.md b/doc/integration/github.md index 680712f9e01..7a83b8e4b35 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -19,7 +19,7 @@ GitHub will generate an application ID and secret key for you to use. - Application name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. - Homepage URL: The URL to your GitLab installation. 'https://gitlab.company.com' - Application description: Fill this in if you wish. - - Authorization callback URL is 'http(s)://${YOUR_DOMAIN}'. Please make sure the port is included if your Gitlab instance is not configured on default port. + - Authorization callback URL is 'http(s)://${YOUR_DOMAIN}'. Please make sure the port is included if your GitLab instance is not configured on default port. 1. Select "Register application". 1. You should now see a Client ID and Client Secret near the top right of the page (see screenshot). @@ -154,7 +154,7 @@ You will also need to disable Git SSL verification on the server hosting GitLab. $ git config --global http.sslVerify false ``` -For the changes to take effect, [reconfigure Gitlab] if you installed +For the changes to take effect, [reconfigure GitLab] if you installed via Omnibus, or [restart GitLab] if you installed from source. [reconfigure GitLab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 05a91d9bef9..c19320471e3 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -2,7 +2,7 @@ GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview). -If correctly setup, emails that require an action will be marked in Gmail. +If correctly set up, emails that require an action will be marked in Gmail.  diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index e71706fef7d..3e72589ce12 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -24,11 +24,11 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc 1. Register your application in the OAuth2 provider you wish to authenticate with. - The redirect URI you provide when registering the application should be: + The redirect URI you provide when registering the application should be: - ``` - http://your-gitlab.host.com/users/auth/oauth2_generic/callback - ``` + ``` + http://your-gitlab.host.com/users/auth/oauth2_generic/callback + ``` 1. You should now be able to get a Client ID and Client Secret. Where this shows up will differ for each provider. @@ -36,18 +36,18 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc 1. On your GitLab server, open the configuration file. - For Omnibus package: + For Omnibus package: - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` - For installations from source: + For installations from source: - ```sh - cd /home/git/gitlab - sudo -u git -H editor config/gitlab.yml - ``` + ```sh + cd /home/git/gitlab + sudo -u git -H editor config/gitlab.yml + ``` 1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 82e8fbdb93e..4e1d5ba9b35 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -39,7 +39,10 @@ contains some settings that are common for all providers. Before configuring individual OmniAuth providers there are a few global settings that are in common for all providers that we need to consider. -- Omniauth needs to be enabled, see details below for example. +> **NOTE:** +> Starting from GitLab 11.4, Omniauth is enabled by default. If you're using an +> earlier version, you'll need to explicitly enable it. + - `allow_single_sign_on` allows you to specify the providers you want to allow to automatically create an account. It defaults to `false`. If `false` users must be created manually or they will not be able to sign in via OmniAuth. @@ -50,16 +53,16 @@ that are in common for all providers that we need to consider. be blocked by default and will have to be unblocked by an administrator before they are able to sign in. ->**Note:** -If you set `block_auto_created_users` to `false`, make sure to only -define providers under `allow_single_sign_on` that you are able to control, like -SAML, Shibboleth, Crowd or Google, or set it to `false` otherwise any user on -the Internet will be able to successfully sign in to your GitLab without -administrative approval. - ->**Note:** -`auto_link_ldap_user` requires the `uid` of the user to be the same in both LDAP -and the OmniAuth provider. +> **Note:** +> If you set `block_auto_created_users` to `false`, make sure to only +> define providers under `allow_single_sign_on` that you are able to control, like +> SAML, Shibboleth, Crowd or Google, or set it to `false` otherwise any user on +> the Internet will be able to successfully sign in to your GitLab without +> administrative approval. +> +> **Note:** +> `auto_link_ldap_user` requires the `uid` of the user to be the same in both LDAP +> and the OmniAuth provider. To change these settings: @@ -74,7 +77,8 @@ To change these settings: and change: ```ruby - gitlab_rails['omniauth_enabled'] = true + # Versions prior to 11.4 require this to be set to true + # gitlab_rails['omniauth_enabled'] = nil # CAUTION! # This allows users to login without having a user account first. Define the allowed providers @@ -101,7 +105,8 @@ To change these settings: ## OmniAuth settings omniauth: # Allow login via Twitter, Google, etc. using OmniAuth providers - enabled: true + # Versions prior to 11.4 require this to be set to true + # enabled: true # CAUTION! # This allows users to login without having a user account first. Define the allowed providers @@ -227,21 +232,42 @@ In order to enable/disable an OmniAuth provider, go to Admin Area -> Settings ->  +## Disabling Omniauth + +Starting from version 11.4 of GitLab, Omniauth is enabled by default. This only +has an effect if providers are configured and [enabled](#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources). + +If omniauth providers are causing problems even when individually disabled, you +can disable the entire omniauth subsystem by modifying the configuration file: + +**For Omnibus installations** + +```ruby +gitlab_rails['omniauth_enabled'] = false +``` + +**For installations from source** + +```yaml + omniauth: + enabled: false +``` + ## Keep OmniAuth user profiles up to date You can enable profile syncing from selected OmniAuth providers and for all or for specific user information. When authenticating using LDAP, the user's email is always synced. - ```ruby - gitlab_rails['sync_profile_from_provider'] = ['twitter', 'google_oauth2'] - gitlab_rails['sync_profile_attributes'] = ['name', 'email', 'location'] +```ruby + gitlab_rails['sync_profile_from_provider'] = ['twitter', 'google_oauth2'] + gitlab_rails['sync_profile_attributes'] = ['name', 'email', 'location'] ``` - **For installations from source** +**For installations from source** - ```yaml - omniauth: - sync_profile_from_provider: ['twitter', 'google_oauth2'] - sync_profile_attributes: ['email', 'location'] - ``` +```yaml + omniauth: + sync_profile_from_provider: ['twitter', 'google_oauth2'] + sync_profile_attributes: ['email', 'location'] +``` diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 25f396bc9c4..e2eea57d694 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -123,9 +123,10 @@ in your SAML IdP: To ease configuration, most IdP accept a metadata URL for the application to provide configuration information to the IdP. To build the metadata URL for GitLab, append `users/auth/saml/metadata` to the HTTPS URL of your GitLab installation, for instance: - ``` - https://gitlab.example.com/users/auth/saml/metadata - ``` + +``` +https://gitlab.example.com/users/auth/saml/metadata +``` At a minimum the IdP *must* provide a claim containing the user's email address, using claim name `email` or `mail`. The email will be used to automatically generate the GitLab diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md index 7f028565412..fc7b97b3cc2 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/maintenance.md @@ -44,7 +44,7 @@ This decision is made on a case-by-case basis. ## Upgrade recommendations -We encourage everyone to run the [latest stable release](https://about.gitlab.com/blog/categories/release/) to ensure that you can +We encourage everyone to run the [latest stable release](https://about.gitlab.com/blog/categories/releases/) to ensure that you can easily upgrade to the most secure and feature-rich GitLab experience. In order to make sure you can easily run the most recent stable release, we are working hard to keep the update process simple and reliable. diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index f1881e0f767..2b9cce6539f 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -16,17 +16,27 @@ and is flexible enough to fit your needs. ### Requirements -If you're using GitLab with the Omnibus package, you're all set. If you -installed GitLab from source, make sure the following packages are installed: - * rsync +If you're using GitLab with the Omnibus package, you're all set. If you +installed GitLab from source, make sure you have rsync installed. + If you're using Ubuntu, you could run: ``` sudo apt-get install -y rsync ``` +* tar + +Backup and restore tasks use `tar` under the hood to create and extract +archives. Ensure you have version 1.30 or above of `tar` available in your +system. To check the version, run: + +``` +tar --version +``` + ### Backup timestamp >**Note:** @@ -124,7 +134,7 @@ To use the `copy` strategy instead of the default streaming strategy, specify ### Excluding specific directories from the backup -You can choose what should be backed up by adding the environment variable `SKIP`. +You can choose what should be exempt from the backup up by adding the environment variable `SKIP`. The available options are: - `db` (database) @@ -138,6 +148,9 @@ The available options are: Use a comma to specify several options at the same time: +All wikis will be backed up as part of the `repositories` group. Non-existent wikis +will be skipped during a backup. + ``` # use this command if you've installed GitLab with the Omnibus package sudo gitlab-rake gitlab:backup:create SKIP=db,uploads @@ -510,7 +523,7 @@ more of the following options: - `BACKUP=timestamp_of_backup` - Required if more than one backup exists. Read what the [backup timestamp is about](#backup-timestamp). -- `force=yes` - Does not ask if the authorized_keys file should get regenerated and assumes 'yes' for warning that database tables will be removed. +- `force=yes` - Does not ask if the authorized_keys file should get regenerated and assumes 'yes' for warning that database tables will be removed, enabling the "Write to authorized_keys file" setting, and updating LDAP providers. If you are restoring into directories that are mountpoints you will need to make sure these directories are empty before attempting a restore. Otherwise GitLab @@ -578,10 +591,11 @@ This procedure assumes that: First make sure your backup tar file is in the backup directory described in the `gitlab.rb` configuration `gitlab_rails['backup_path']`. The default is -`/var/opt/gitlab/backups`. +`/var/opt/gitlab/backups`. It needs to be owned by the `git` user. ```shell sudo cp 11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar /var/opt/gitlab/backups/ +sudo chown git.git /var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar ``` Stop the processes that are connected to the database. Leave the rest of GitLab diff --git a/doc/security/README.md b/doc/security/README.md index d397ff104ab..e22dc00759d 100644 --- a/doc/security/README.md +++ b/doc/security/README.md @@ -10,6 +10,7 @@ comments: false - [Webhooks and insecure internal web services](webhooks.md) - [Information exclusivity](information_exclusivity.md) - [Reset your root password](reset_root_password.md) +- [Unlock a locked user](unlock_user.md) - [User File Uploads](user_file_uploads.md) - [How we manage the CRIME vulnerability](crime_vulnerability.md) - [Enforce Two-factor authentication](two_factor_authentication.md) diff --git a/doc/security/reset_root_password.md b/doc/security/reset_root_password.md index 3c13f262677..6a882ed6fe5 100644 --- a/doc/security/reset_root_password.md +++ b/doc/security/reset_root_password.md @@ -37,4 +37,4 @@ Don't forget to save the changes. user.save! ``` -Exit the console and try to login with your new password.
\ No newline at end of file +Exit the console and try to login with your new password. diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index f02f7b807cf..cd290a80314 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -11,7 +11,7 @@ You can read more about it here: ## Enforcing 2FA for all users Users on GitLab, can enable it without any admin's intervention. If you want to -enforce everyone to setup 2FA, you can choose from two different ways: +enforce everyone to set up 2FA, you can choose from two different ways: 1. Enforce on next login 2. Suggest on next login, but allow a grace period before enforcing. diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md new file mode 100644 index 00000000000..d5ecef7f605 --- /dev/null +++ b/doc/security/unlock_user.md @@ -0,0 +1,31 @@ +# How to unlock a locked user + +Log into your server with root privileges. Then start a Ruby on Rails console. + +Start the console with this command: + +```bash +gitlab-rails console production +``` + +Wait until the console has loaded. + +There are multiple ways to find your user. You can search for email or username. + +```bash +user = User.where(id: 1).first +``` + +or + +```bash +user = User.find_by(email: 'admin@local.host') +``` + +Unlock the user: + +```bash +user.unlock_access! +``` + +Exit the console, the user should now be able to log in again. diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md index 4293944ae8b..8c07e11dcb1 100644 --- a/doc/security/user_email_confirmation.md +++ b/doc/security/user_email_confirmation.md @@ -1,7 +1,7 @@ # User email confirmation at sign-up -Gitlab admin can enable email confirmation on sign-up, if you want to confirm all +GitLab admin can enable email confirmation on sign-up, if you want to confirm all user emails before they are able to sign-in. In the Admin area under **Settings** (`/admin/application_settings`), go to section -**Sign-in Restrictions** and look for **Send confirmation email on sign-up** option. +**Sign-up Restrictions** and look for **Send confirmation email on sign-up** option. diff --git a/doc/ssh/README.md b/doc/ssh/README.md index 63f0a654fcf..5db042326f3 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -48,9 +48,11 @@ Note that Public SSH key may also be named as follows: **Git Bash on Windows / GNU/Linux / macOS:** ```bash - ssh-keygen -t rsa -C "your.email@example.com" -b 4096 + ssh-keygen -o -t rsa -C "your.email@example.com" -b 4096 ``` + (Note: the `-o` option was introduced in 2014; if this command does not work for you, simply remove the `-o` option and try again) + **Windows:** Alternatively on Windows you can download @@ -75,7 +77,9 @@ Note that Public SSH key may also be named as follows: NOTE: **Note:** If you want to change the password of your SSH key pair, you can use - `ssh-keygen -p <keyname>`. + `ssh-keygen -p -o -f <keyname>`. + The `-o` option was added in 2014, so if this command does not work for you, + simply remove the `-o` option and try again. ## Adding a SSH key to your GitLab account @@ -191,15 +195,15 @@ project. ### Global shared deploy keys -Global Shared Deploy keys allow read-only or read-write (if enabled) access to +Global Shared Deploy keys allow read-only or read-write (if enabled) access to be configured on any repository in the entire GitLab installation. This is really useful for integrating repositories to secured, shared Continuous -Integration (CI) services or other shared services. -GitLab administrators can set up the Global Shared Deploy key in GitLab and +Integration (CI) services or other shared services. +GitLab administrators can set up the Global Shared Deploy key in GitLab and add the private key to any shared systems. Individual repositories opt into exposing their repository using these keys when a project maintainers (or higher) -authorizes a Global Shared Deploy key to be used with their project. +authorizes a Global Shared Deploy key to be used with their project. Global Shared Keys can provide greater security compared to Per-Project Deploy Keys since an administrator of the target integrated system is the only one @@ -211,13 +215,13 @@ the primary way for project maintainers and owners to identify the correct Globa Deploy key to add. For instance, if the key gives access to a SaaS CI instance, use the name of that service in the key name if that is all it is used for. When creating Global Shared Deploy keys, give some thought to the granularity -of keys - they could be of very narrow usage such as just a specific service or -of broader usage for something like "Anywhere you need to give read access to +of keys - they could be of very narrow usage such as just a specific service or +of broader usage for something like "Anywhere you need to give read access to your repository". -Once a GitLab administrator adds the Global Deployment key, project maintainers -and owners can add it in project's **Settings > Repository** section by expanding the -**Deploy Key** section and clicking **Enable** next to the appropriate key listed +Once a GitLab administrator adds the Global Deployment key, project maintainers +and owners can add it in project's **Settings > Repository** section by expanding the +**Deploy Key** section and clicking **Enable** next to the appropriate key listed under **Public deploy keys available to any project**. NOTE: **Note:** diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index a8aa11265d0..a645f65938f 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -44,6 +44,6 @@ This page gathers all the resources for the topic **Authentication** within GitL - [Kanboard Plugin GitLab Authentication](https://kanboard.net/plugin/gitlab-auth) - [Jenkins GitLab OAuth Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+OAuth+Plugin) -- [Setup Gitlab CE with Active Directory authentication](https://www.caseylabs.com/setup-gitlab-ce-with-active-directory-authentication/) +- [Set up Gitlab CE with Active Directory authentication](https://www.caseylabs.com/setup-gitlab-ce-with-active-directory-authentication/) - [How to customize GitLab to support OpenID authentication](http://eric.van-der-vlist.com/blog/2013/11/23/how-to-customize-gitlab-to-support-openid-authentication/) - [Openshift - Configuring Authentication and User Agent](https://docs.openshift.org/latest/install_config/configuring_authentication.html#GitLab) diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 0474182e324..0d1ba3e8f9a 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -71,11 +71,6 @@ For an overview on the creation of Auto DevOps, read the blog post [From 2/3 of ## Requirements -TIP: **Tip:** -For self-hosted installations, the easiest way to make use of Auto DevOps is to -install GitLab inside a Kubernetes cluster using the [GitLab Omnibus Helm Chart] -which automatically installs and configures everything you need! - To make full use of Auto DevOps, you will need: 1. **GitLab Runner** (needed for all stages) - Your Runner needs to be @@ -101,10 +96,6 @@ To make full use of Auto DevOps, you will need: Kubernetes cluster using the [`nginx-ingress`](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress) Helm chart. - 1. **Wildcard TLS termination** - You can deploy the - [`kube-lego`](https://github.com/kubernetes/charts/tree/master/stable/kube-lego) - Helm chart to your Kubernetes cluster to automatically issue certificates - for your domains using Let's Encrypt. 1. **Prometheus** (needed 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 @@ -148,18 +139,13 @@ Auto DevOps base domain to `1.2.3.4.nip.io`. Once set up, all requests will hit the load balancer, which in turn will route them to the Kubernetes pods that run your application(s). -NOTE: **Note:** -If GitLab is installed using the [GitLab Omnibus Helm Chart], there are two -options: provide a static IP, or have one assigned. For more information see the -relevant docs on the [network prerequisites](../../install/kubernetes/gitlab_omnibus.md#networking-prerequisites). - ## Using multiple Kubernetes clusters **[PREMIUM]** When using Auto DevOps, you may want to deploy different environments to different Kubernetes clusters. This is possible due to the 1:1 connection that [exists between them](../../user/project/clusters/index.md#multiple-kubernetes-clusters). -In the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Auto-DevOps.gitlab-ci.yml) +In the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) (used behind the scenes by Auto DevOps), there are currently 3 defined environment names that you need to know: - `review/` (every environment starting with `review/`) @@ -238,6 +224,12 @@ There is also a feature flag to enable Auto DevOps to a percentage of projects which can be enabled from the console with `Feature.get(:force_autodevops_on_by_default).enable_percentage_of_actors(10)`. +NOTE: **Enabled by default:** +Starting with GitLab 11.3, the Auto DevOps pipeline will be enabled by default for all +projects. If it's not explicitly enabled for the project, Auto DevOps will be automatically +disabled on the first pipeline failure. Your project will continue to use an alternative +[CI/CD configuration file](../../ci/yaml/README.md) if one is found. + ### Deployment strategy > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/38542) in GitLab 11.0. @@ -247,14 +239,19 @@ project's **Settings > CI/CD > Auto DevOps**. The available options are: -- **Continuous deployment to production** - enables [Auto Deploy](#auto-deploy) - by setting the [`STAGING_ENABLED`](#deploy-policy-for-staging-and-production-environments) and - [`INCREMENTAL_ROLLOUT_ENABLED`](#incremental-rollout-to-production) variables - to false. -- **Automatic deployment to staging, manual deployment to production** - sets the +- **Continuous deployment to production**: Enables [Auto Deploy](#auto-deploy) + with `master` branch directly deployed to production. +- **Continuous deployment to production using timed incremental rollout**: Sets the + [`INCREMENTAL_ROLLOUT_MODE`](#timed-incremental-rollout-to-production) variable + to `timed`, and production deployment will be executed with a 5 minute delay between + each increment in rollout. +- **Automatic deployment to staging, manual deployment to production**: Sets the [`STAGING_ENABLED`](#deploy-policy-for-staging-and-production-environments) and - [`INCREMENTAL_ROLLOUT_ENABLED`](#incremental-rollout-to-production) variables - to true, and the user is responsible for manually deploying to staging and production. + [`INCREMENTAL_ROLLOUT_MODE`](#incremental-rollout-to-production) variables + to `1` and `manual`. This means: + + - `master` branch is directly deployed to staging. + - Manual actions are provided for incremental rollout to production. ## Stages of Auto DevOps @@ -448,9 +445,33 @@ no longer be valid as soon as the deployment job finishes. This means that Kubernetes can run the application, but in case it should be restarted or executed somewhere else, it cannot be accessed again. +> [Introduced][ce-21955] in GitLab 11.4 + +Database initialization and migrations for PostgreSQL can be configured to run +within the application pod by setting the project variables `DB_INITIALIZE` and +`DB_MIGRATE` respectively. + +If present, `DB_INITIALIZE` will be run as a shell command within an application pod as a helm +post-install hook. Note that this means that if any deploy succeeds, +`DB_INITIALIZE` will not be processed thereafter. + +If present, `DB_MIGRATE` will be run as a shell command within an application pod as +a helm pre-upgrade hook. + +For example, in a Rails application: + +* `DB_INITIALIZE` can be set to `cd /app && RAILS_ENV=production + bin/setup` +* `DB_MIGRATE` can be set to `cd /app && RAILS_ENV=production bin/update` + +NOTE: **Note:** +The `/app` path is the directory of your project inside the docker image +as [configured by +Herokuish](https://github.com/gliderlabs/herokuish#paths) + > [Introduced][ce-19507] in GitLab 11.0. -For internal and private projects a [GitLab Deploy Token](../../user/project/deploy_tokens/index.md###gitlab-deploy-token) +For internal and private projects a [GitLab Deploy Token](../../user/project/deploy_tokens/index.md###gitlab-deploy-token) will be automatically created, when Auto DevOps is enabled and the Auto DevOps settings are saved. This Deploy Token can be used for permanent access to the registry. @@ -476,10 +497,7 @@ The metrics include: - **Response Metrics:** latency, throughput, error rate - **System Metrics:** CPU utilization, memory utilization -If GitLab has been deployed using the [GitLab Omnibus Helm Chart], no -configuration is required. - -If you have installed GitLab using a different method, you need to: +In order to make use of monitoring you need to: 1. [Deploy Prometheus](../../user/project/integrations/prometheus.md#configuring-your-own-prometheus-server-within-kubernetes) into your Kubernetes cluster 1. If you would like response metrics, ensure you are running at least version @@ -574,13 +592,13 @@ postgres://user:password@postgres-host:postgres-port/postgres-database ### Environment variables The following variables can be used for setting up the Auto DevOps domain, -providing a custom Helm chart, or scaling your application. PostgreSQL can be +providing a custom Helm chart, or scaling your application. PostgreSQL can also be customized, and you can easily use a [custom buildpack](#custom-buildpacks). | **Variable** | **Description** | | ------------ | --------------- | | `AUTO_DEVOPS_DOMAIN` | The [Auto DevOps domain](#auto-devops-domain); by default set automatically by the [Auto DevOps setting](#enabling-auto-devops). | -| `AUTO_DEVOPS_CHART` | The Helm Chart used to deploy your apps; defaults to the one [provided by GitLab](https://gitlab.com/charts/charts.gitlab.io/tree/master/charts/auto-deploy-app). | +| `AUTO_DEVOPS_CHART` | The Helm Chart used to deploy your apps; defaults to the one [provided by GitLab](https://gitlab.com/charts/auto-deploy-app). | | `REPLICAS` | The number of replicas to deploy; defaults to 1. | | `PRODUCTION_REPLICAS` | The number of replicas to deploy in the production environment. This takes precedence over `REPLICAS`; defaults to 1. | | `CANARY_REPLICAS` | The number of canary replicas to deploy for [Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html); defaults to 1 | @@ -592,9 +610,11 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | `BUILDPACK_URL` | The buildpack's full URL. It can point to either Git repositories or a tarball URL. For Git repositories, it is possible to point to a specific `ref`, for example `https://github.com/heroku/heroku-buildpack-ruby.git#v142` | | `SAST_CONFIDENCE_LEVEL` | The minimum confidence level of security issues you want to be reported; `1` for Low, `2` for Medium, `3` for High; defaults to `3`.| | `DEP_SCAN_DISABLE_REMOTE_CHECKS` | Whether remote Dependency Scanning checks are disabled; defaults to `"false"`. Set to `"true"` to disable checks that send data to GitLab central servers. [Read more about remote checks](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks).| +| `DB_INITIALIZE` | From GitLab 11.4, this variable can be used to specify the command to run to initialize the application's PostgreSQL database. It runs inside the application pod. | +| `DB_MIGRATE` | From GitLab 11.4, this variable can be used to specify the command to run to migrate the application's PostgreSQL database. It runs inside the application pod. | | `STAGING_ENABLED` | From GitLab 10.8, this variable can be used to define a [deploy policy for staging and production environments](#deploy-policy-for-staging-and-production-environments). | | `CANARY_ENABLED` | From GitLab 11.0, this variable can be used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments). | -| `INCREMENTAL_ROLLOUT_ENABLED`| From GitLab 10.8, this variable can be used to enable an [incremental rollout](#incremental-rollout-to-production) of your application for the production environment. | +| `INCREMENTAL_ROLLOUT_MODE`| From GitLab 11.4, this variable, if present, can be used to enable an [incremental rollout](#incremental-rollout-to-production) of your application for the production environment.<br/>Set to: <ul><li>`manual`, for manual deployment jobs.</li><li>`timed`, for automatic rollout deployments with a 5 minute delay each one.</li></ul> | | `TEST_DISABLED` | From GitLab 11.0, this variable can be used to disable the `test` job. If the variable is present, the job will not be created. | | `CODE_QUALITY_DISABLED` | From GitLab 11.0, this variable can be used to disable the `codequality` job. If the variable is present, the job will not be created. | | `SAST_DISABLED` | From GitLab 11.0, this variable can be used to disable the `sast` job. If the variable is present, the job will not be created. | @@ -715,9 +735,8 @@ to use an incremental rollout to replace just a few pods with the latest code. This will allow you to first check how the app is behaving, and later manually increasing the rollout up to 100%. -If `INCREMENTAL_ROLLOUT_ENABLED` is defined in your project (e.g., set -`INCREMENTAL_ROLLOUT_ENABLED` to `1` as a secret variable), then instead of the -standard `production` job, 4 different +If `INCREMENTAL_ROLLOUT_MODE` is set to `manual` in your project, then instead +of the standard `production` job, 4 different [manual jobs](../../ci/pipelines.md#manual-actions-from-the-pipeline-graph) will be created: @@ -741,21 +760,45 @@ environment page. Below, you can see how the pipeline will look if the rollout or staging variables are defined. -- **Without `INCREMENTAL_ROLLOUT_ENABLED` and without `STAGING_ENABLED`** +Without `INCREMENTAL_ROLLOUT_MODE` and without `STAGING_ENABLED`: + + + +Without `INCREMENTAL_ROLLOUT_MODE` and with `STAGING_ENABLED`: + + + +With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and without `STAGING_ENABLED`: -  + -- **Without `INCREMENTAL_ROLLOUT_ENABLED` and with `STAGING_ENABLED`** +With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and with `STAGING_ENABLED` -  + -- **With `INCREMENTAL_ROLLOUT_ENABLED` and without `STAGING_ENABLED`** +CAUTION: **Caution:** +Before GitLab 11.4 this feature was enabled by the presence of the +`INCREMENTAL_ROLLOUT_ENABLED` environment variable. +This configuration is deprecated and will be removed in the future. + +#### Timed incremental rollout to production **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7545) in GitLab 11.4. + +TIP: **Tip:** +You can also set this inside your [project's settings](#deployment-strategy). -  +This configuration based on +[incremental rollout to production](#incremental-rollout-to-production). -- **With `INCREMENTAL_ROLLOUT_ENABLED` and with `STAGING_ENABLED`** +Everything behaves the same way, except: -  +- It's enabled by setting the `INCREMENTAL_ROLLOUT_MODE` variable to `timed`. +- Instead of the standard `production` job, the following jobs with a 5 minute delay between each are created: + 1. `timed rollout 10%` + 1. `timed rollout 25%` + 1. `timed rollout 50%` + 1. `timed rollout 100%` ## Currently supported languages @@ -843,7 +886,7 @@ curl --data "value=true" --header "PRIVATE-TOKEN: personal_access_token" https:/ [review-app]: ../../ci/review_apps/index.md [container-registry]: ../../user/project/container_registry.md [postgresql]: https://www.postgresql.org/ -[Auto DevOps template]: https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Auto-DevOps.gitlab-ci.yml -[GitLab Omnibus Helm Chart]: ../../install/kubernetes/gitlab_omnibus.md +[Auto DevOps template]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml [ee]: https://about.gitlab.com/pricing/ +[ce-21955]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21955 [ce-19507]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19507 diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 44b0cf758dc..7ca441a2f74 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -143,7 +143,7 @@ In the next section we'll break down the pipeline and explain what each job does By now you should see the pipeline running, but what is it running exactly? -To navigate inside the pipeline, click its status badge. (It's status should be "running"). +To navigate inside the pipeline, click its status badge. (Its status should be "running"). The pipeline is split into 4 stages, each running a couple of jobs.  @@ -194,7 +194,7 @@ applications. In the rightmost column for the production environment, you can ma - The first icon will open the URL of the application that is deployed in production. It's a very simple page, but the important part is that it works! -- The next icon with the small graph will take you to the metrics page where +- The next icon, with the small graph, will take you to the metrics page where Prometheus collects data about the Kubernetes cluster and how the application affects it (in terms of memory/CPU usage, latency, etc.). @@ -217,7 +217,7 @@ under **Settings > CI/CD > Variables**. ### Working with branches -Following the [GitLab flow](../../workflow/gitlab_flow.md#working-with-feature-branches) +Following the [GitLab flow](../../workflow/gitlab_flow.md#working-with-feature-branches), let's create a feature branch that will add some content to the application. Under your repository, navigate to the following file: `app/views/welcome/index.html.erb`. @@ -235,7 +235,7 @@ by clicking **Commit**.  Once you submit the merge request, you'll see the pipeline running. This will -run all the jobs as [described previously](#deploying-the-application), as well +run all the jobs as [described previously](#deploying-the-application), as well as a few more that run only on branches other than `master`.  @@ -278,7 +278,7 @@ and the application will be eventually deployed straight to production. After implementing this project, you should now have a solid understanding of the basics of Auto DevOps. We started from building and testing to deploying and monitoring an application -all within GitLab. Despite its automatic nature, Audo DevOps can also be configured +all within GitLab. Despite its automatic nature, Auto DevOps can also be configured and customized to fit your workflow. Here are some helpful resources for further reading: 1. [Auto DevOps](index.md) diff --git a/doc/topics/git/numerous_undo_possibilities_in_git/index.md b/doc/topics/git/numerous_undo_possibilities_in_git/index.md index 4cb8f083fb5..7195b0f0f04 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -41,10 +41,9 @@ Here's what we'll cover in this tutorial: - [Without history modification](#undo-remote-changes-without-changing-history) (preferred way) - [With history modification](#undo-remote-changes-with-modifying-history) (requires coordination with team and force pushes). - - - [Usecases when modifying history is generally acceptable](#where-modifying-history-is-generally-acceptable) - - [How to modify history](#how-modifying-history-is-done) - - [How to remove sensitive information from repository](#deleting-sensitive-information-from-commits) + - [Usecases when modifying history is generally acceptable](#where-modifying-history-is-generally-acceptable) + - [How to modify history](#how-modifying-history-is-done) + - [How to remove sensitive information from repository](#deleting-sensitive-information-from-commits) ### Branching strategy @@ -101,24 +100,23 @@ no changes added to commit (use "git add" and/or "git commit -a") At this point there are 3 options to undo the local changes you have: - - Discard all local changes, but save them for possible re-use [later](#quickly-save-local-changes) - - ```shell - git stash - ``` +- Discard all local changes, but save them for possible re-use [later](#quickly-save-local-changes) - - Discarding local changes (permanently) to a file + ```shell + git stash + ``` - ```shell - git checkout -- <file> - ``` +- Discarding local changes (permanently) to a file - - Discard all local changes to all files permanently + ```shell + git checkout -- <file> + ``` - ```shell - git reset --hard - ``` +- Discard all local changes to all files permanently + ```shell + git reset --hard + ``` Before executing `git reset --hard`, keep in mind that there is also a way to just temporary store the changes without committing them using `git stash`. @@ -140,10 +138,10 @@ them. This is achieved by Git stashing command `git stash`, which in fact saves current work and runs `git reset --hard`, but it also has various additional options like: - - `git stash save`, which enables including temporary commit message, which will help you identify changes, among with other options - - `git stash list`, which lists all previously stashed commits (yes, there can be more) that were not `pop`ed - - `git stash pop`, which redoes previously stashed changes and removes them from stashed list - - `git stash apply`, which redoes previously stashed changes, but keeps them on stashed list +- `git stash save`, which enables including temporary commit message, which will help you identify changes, among with other options +- `git stash list`, which lists all previously stashed commits (yes, there can be more) that were not `pop`ed +- `git stash pop`, which redoes previously stashed changes and removes them from stashed list +- `git stash apply`, which redoes previously stashed changes, but keeps them on stashed list ### Staged local changes (before you commit) @@ -174,29 +172,29 @@ Changes to be committed: Now you have 4 options to undo your changes: - - Unstage the file to current commit (HEAD) +- Unstage the file to current commit (HEAD) - ```shell - git reset HEAD <file> - ``` + ```shell + git reset HEAD <file> + ``` - - Unstage everything - retain changes +- Unstage everything - retain changes - ```shell - git reset - ``` + ```shell + git reset + ``` - - Discard all local changes, but save them for [later](#quickly-save-local-changes) +- Discard all local changes, but save them for [later](#quickly-save-local-changes) - ```shell - git stash - ``` + ```shell + git stash + ``` - - Discard everything permanently +- Discard everything permanently - ```shell - git reset --hard - ``` + ```shell + git reset --hard + ``` ## Committed local changes @@ -232,42 +230,42 @@ In our example we will end up with commit `B`, that introduced bug/error. We hav - Undo (swap additions and deletions) changes introduced by commit `B`. - ```shell - git revert commit-B-id - ``` + ```shell + git revert commit-B-id + ``` - Undo changes on a single file or directory from commit `B`, but retain them in the staged state - ```shell - git checkout commit-B-id <file> - ``` + ```shell + git checkout commit-B-id <file> + ``` - Undo changes on a single file or directory from commit `B`, but retain them in the unstaged state - ```shell - git reset commit-B-id <file> - ``` - - - There is one command we also must not forget: **creating a new branch** - from the point where changes are not applicable or where the development has hit a - dead end. For example you have done commits `A-B-C-D` on your feature-branch - and then you figure `C` and `D` are wrong. At this point you either reset to `B` - and do commit `F` (which will cause problems with pushing and if forced pushed also with other developers) - since branch now looks `A-B-F`, which clashes with what other developers have locally (you will - [change history](#with-history-modification)), or you simply checkout commit `B` create - a new branch and do commit `F`. In the last case, everyone else can still do their work while you - have your new way to get it right and merge it back in later. Alternatively, with GitLab, - you can [cherry-pick](../../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) - that commit into a new merge request. - -  - - ```shell - git checkout commit-B-id - git checkout -b new-path-of-feature - # Create <commit F> - git commit -a - ``` + ```shell + git reset commit-B-id <file> + ``` + +- There is one command we also must not forget: **creating a new branch** + from the point where changes are not applicable or where the development has hit a + dead end. For example you have done commits `A-B-C-D` on your feature-branch + and then you figure `C` and `D` are wrong. At this point you either reset to `B` + and do commit `F` (which will cause problems with pushing and if forced pushed also with other developers) + since branch now looks `A-B-F`, which clashes with what other developers have locally (you will + [change history](#with-history-modification)), or you simply checkout commit `B` create + a new branch and do commit `F`. In the last case, everyone else can still do their work while you + have your new way to get it right and merge it back in later. Alternatively, with GitLab, + you can [cherry-pick](../../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) + that commit into a new merge request. + +  + + ```shell + git checkout commit-B-id + git checkout -b new-path-of-feature + # Create <commit F> + git commit -a + ``` ### With history modification @@ -287,9 +285,9 @@ delete commit `B`. - Rebase the range from current commit D to A: - ```shell - git rebase -i A - ``` + ```shell + git rebase -i A + ``` - Command opens your favorite editor where you write `drop` in front of commit `B`, but you leave default `pick` with all other commits. Save and exit the diff --git a/doc/university/README.md b/doc/university/README.md index 595fc480887..5edf92b3b09 100644 --- a/doc/university/README.md +++ b/doc/university/README.md @@ -11,7 +11,7 @@ and [Blog Articles](https://about.gitlab.com/blog/). Would you like to contribute to GitLab University? Then please take a look at our contribution [process](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/PROCESS.md) for more information. -## Gitlab University Curriculum +## GitLab University Curriculum The curriculum is composed of GitLab videos, screencasts, presentations, projects and external GitLab content hosted on other services and has been organized into the following sections. @@ -73,10 +73,10 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project #### 1.7 Community and Support 1. [Getting Help](https://about.gitlab.com/getting-help/) - - Proposing Features and Reporting and Tracking bugs for GitLab - - The GitLab IRC channel, Gitter Chat Room, Community Forum and Mailing List - - Getting Technical Support - - Being part of our Great Community and Contributing to GitLab + - Proposing Features and Reporting and Tracking bugs for GitLab + - The GitLab IRC channel, Gitter Chat Room, Community Forum and Mailing List + - Getting Technical Support + - Being part of our Great Community and Contributing to GitLab 1. [Getting Started with the GitLab Development Kit (GDK)](https://about.gitlab.com/2016/06/08/getting-started-with-gitlab-development-kit/) 1. [Contributing Technical Articles to the GitLab Blog](https://about.gitlab.com/2016/01/26/call-for-writers/) 1. [GitLab Training Workshops](https://docs.gitlab.com/ce/university/training/end-user/) diff --git a/doc/university/glossary/README.md b/doc/university/glossary/README.md index 89516dba60b..6ff27e495fb 100644 --- a/doc/university/glossary/README.md +++ b/doc/university/glossary/README.md @@ -395,7 +395,7 @@ Allow you to [organize issues](../../user/project/milestones/index.md) and merge ### Mirror Repositories -A project that is setup to automatically have its branches, tags, and commits [updated from an upstream repository](https://docs.gitlab.com/ee/workflow/repository_mirroring.html). This is useful when a repository you're interested in is located on a different server, and you want to be able to browse its content and activity using the familiar GitLab interface. +A project that is set up to automatically have its branches, tags, and commits [updated from an upstream repository](https://docs.gitlab.com/ee/workflow/repository_mirroring.html). This is useful when a repository you're interested in is located on a different server, and you want to be able to browse its content and activity using the familiar GitLab interface. ### MIT License @@ -673,7 +673,7 @@ Version control is a system that records changes to a file or set of files over ### Virtual Private Cloud (VPC) -A [VPC](https://docs.gitlab.com/ce/university/glossary/README.html#virtual-private-cloud-vpc) is an on demand configurable pool of shared computing resources allocated within a public cloud environment, providing some isolation between the different users using the resources. GitLab users need to create a new Amazon VPC in order to [setup High Availability](https://docs.gitlab.com/ce/university/high-availability/aws/). +A [VPC](https://docs.gitlab.com/ce/university/glossary/README.html#virtual-private-cloud-vpc) is an on demand configurable pool of shared computing resources allocated within a public cloud environment, providing some isolation between the different users using the resources. GitLab users need to create a new Amazon VPC in order to [set up High Availability](https://docs.gitlab.com/ce/university/high-availability/aws/). ### Virtual private server (VPS) diff --git a/doc/university/high-availability/aws/README.md b/doc/university/high-availability/aws/README.md index 4e7eae19844..0a7ce922de1 100644 --- a/doc/university/high-availability/aws/README.md +++ b/doc/university/high-availability/aws/README.md @@ -286,7 +286,7 @@ to make the EFS integration easier to manage. gitlab_rails['redis_port'] = 6379 Finally run reconfigure, you might find it useful to run a check and -a service status to make sure everything has been setup correctly. +a service status to make sure everything has been set up correctly. sudo gitlab-ctl reconfigure sudo gitlab-rake gitlab:check @@ -395,5 +395,5 @@ some redundancy options but it might also imply Geographic replication. There is a lot of ground yet to cover so have a read through these other resources and feel free to open an issue to request additional material. - * [GitLab High Availability](http://docs.gitlab.com/ce/administration/high_availability/README.html#sts=High Availability) - * [GitLab Geo](http://docs.gitlab.com/ee/gitlab-geo/README.html) +* [GitLab High Availability](http://docs.gitlab.com/ce/administration/high_availability/README.html#sts=High%20Availability) +* [GitLab Geo](http://docs.gitlab.com/ee/gitlab-geo/README.html) diff --git a/doc/university/support/README.md b/doc/university/support/README.md index d1d5db6bbcd..805af253367 100644 --- a/doc/university/support/README.md +++ b/doc/university/support/README.md @@ -37,7 +37,7 @@ Continue to look over remaining portions of the [University Overview](../README. Get your development machine ready to familiarize yourself with the codebase, the components, and to be prepared to reproduce issues that our users encounter - Install the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) - - [Setup OpenLDAP as part of this](https://gitlab.com/gitlab-org/gitlab-development-kit#openldap) + - [Set up OpenLDAP as part of this](https://gitlab.com/gitlab-org/gitlab-development-kit#openldap) #### Become comfortable with the Installation processes that we support @@ -55,13 +55,13 @@ Sometimes we need to upgrade customers from old versions of GitLab to latest, so - Keep this up-to-date as patch and version releases become available, just like our customers would - Try out the following installation path - [Install GitLab 4.2 from source](https://gitlab.com/gitlab-org/gitlab-ce/blob/d67117b5a185cfb15a1d7e749588ff981ffbf779/doc/install/installation.md) - - External MySQL database - - External NGINX + - External MySQL database + - External NGINX - Create some test data - - Populated Repos - - Users - - Groups - - Projects + - Populated Repos + - Users + - Groups + - Projects - [Backup using our Backup rake task](https://docs.gitlab.com/ce/raketasks/backup_restore.html#create-a-backup-of-the-gitlab-system) - [Upgrade to 5.0 source using our Upgrade documentation](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/update/4.2-to-5.0.md) - [Upgrade to 5.1 source](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/update/5.0-to-5.1.md) @@ -72,7 +72,7 @@ Sometimes we need to upgrade customers from old versions of GitLab to latest, so - [Upgrade to Omnibus 7.14](https://docs.gitlab.com/omnibus/update/README.html#upgrading-from-a-non-omnibus-installation-to-an-omnibus-installation) - [Restore backup using our Restore rake task](https://docs.gitlab.com/ce/raketasks/backup_restore.html#restore-a-previously-created-backup) - [Upgrade to latest EE](https://about.gitlab.com/downloads-ee) - - (GitLab inc. only) Acquire and apply a license for the Enterprise Edition product, ask in #support + - (GitLab inc. only) Acquire and apply a license for the Enterprise Edition product, ask in #support - Perform a downgrade from [EE to CE](https://docs.gitlab.com/ee/downgrade_ee_to_ce/README.html) #### Start to learn about some of the integrations that we support @@ -98,9 +98,9 @@ Our integrations add great value to GitLab. User questions often relate to integ - [Environment Information and maintenance checks](https://docs.gitlab.com/ce/raketasks/maintenance.html) - [GitLab check](https://docs.gitlab.com/ce/raketasks/check.html) - Omnibus commands - - [Status](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/maintenance/README.md#get-service-status) - - [Starting and stopping services](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/maintenance/README.md#starting-and-stopping) - - [Starting a rails console](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/maintenance/README.md#invoking-rake-tasks) + - [Status](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/maintenance/README.md#get-service-status) + - [Starting and stopping services](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/maintenance/README.md#starting-and-stopping) + - [Starting a rails console](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/maintenance/README.md#invoking-rake-tasks) #### Learn about the Support process @@ -118,16 +118,16 @@ Zendesk is our Support Centre and our main communication line with our Customers - Here you will find a large variety of queries mainly from our Users who are self hosting GitLab CE - Understand the questions that are asked and dig in to try to find a solution - [Proceed on to the GitLab.com Support Forum](https://about.gitlab.com/handbook/support/#gitlabcom-support-trackera-namesupp-foruma) - - Here you will find queries regarding our own GitLab.com - - Helping Users here will give you an understanding of our Admin interface and other tools + - Here you will find queries regarding our own GitLab.com + - Helping Users here will give you an understanding of our Admin interface and other tools - [Proceed on to the Twitter tickets in Zendesk](https://about.gitlab.com/handbook/support/#twitter) - - Here you will gain a great insight into our userbase - - Learn from any complaints and problems and feed them back to the team - - Tweets can range from help needed with GitLab installations, the API and just general queries + - Here you will gain a great insight into our userbase + - Learn from any complaints and problems and feed them back to the team + - Tweets can range from help needed with GitLab installations, the API and just general queries - [Proceed on to Regular email Support tickets](https://about.gitlab.com/handbook/support/#regular-zendesk-tickets-a-nameregulara) - - Here you will find tickets from our GitLab EE Customers and GitLab CE Users - - Tickets here are extremely varied and often very technical - - You should be prepared for these tickets, given the knowledge gained from previous tiers and your training + - Here you will find tickets from our GitLab EE Customers and GitLab CE Users + - Tickets here are extremely varied and often very technical + - You should be prepared for these tickets, given the knowledge gained from previous tiers and your training - Check out your colleagues' responses - Hop on to the #support-live-feed channel in Slack and see the tickets as they come in and are updated - Read through old tickets that your colleagues have worked on @@ -135,10 +135,10 @@ Zendesk is our Support Centre and our main communication line with our Customers - [Learn about Cisco WebEx](https://about.gitlab.com/handbook/support/onboarding/#webexa-namewebexa) - Training calls - Information gathering calls - - It's good to find out how new and prospective customers are going to be using the product and how they will set up their infrastructure + - It's good to find out how new and prospective customers are going to be using the product and how they will set up their infrastructure - Diagnosis calls - - When email isn't enough we may need to hop on a call and do some debugging along side the customer - - These paired calls are a great learning experience + - When email isn't enough we may need to hop on a call and do some debugging along side the customer + - These paired calls are a great learning experience - Upgrade calls - Emergency calls diff --git a/doc/university/training/end-user/README.md b/doc/university/training/end-user/README.md index 9b8a8db58e2..e5eb5d97e3b 100644 --- a/doc/university/training/end-user/README.md +++ b/doc/university/training/end-user/README.md @@ -80,7 +80,7 @@ git config --global user.name "Your Name" git config --global user.email you@example.com ``` -- If you don't use the global flag you can setup a different author for +- If you don't use the global flag you can set up a different author for each project - Check settings with: diff --git a/doc/university/training/topics/bisect.md b/doc/university/training/topics/bisect.md index 2d5ab107fe6..01e93e4dcb0 100644 --- a/doc/university/training/topics/bisect.md +++ b/doc/university/training/topics/bisect.md @@ -10,7 +10,7 @@ comments: false - Find a commit that introduced a bug - Works through a process of elimination -- Specify a known good and bad revision to begin +- Specify a known good and bad revision to begin ---------- diff --git a/doc/university/training/topics/env_setup.md b/doc/university/training/topics/env_setup.md index b7bec83ed8a..bdf805711e0 100644 --- a/doc/university/training/topics/env_setup.md +++ b/doc/university/training/topics/env_setup.md @@ -16,10 +16,10 @@ comments: false - **Linux** ```bash - sudo yum install git-all + sudo yum install git-all ``` ```bash - sudo apt-get install git-all + sudo apt-get install git-all ``` ---------- diff --git a/doc/university/training/topics/getting_started.md b/doc/university/training/topics/getting_started.md index 153b45fb4da..1441e4b89b2 100644 --- a/doc/university/training/topics/getting_started.md +++ b/doc/university/training/topics/getting_started.md @@ -9,13 +9,15 @@ comments: false ## Instantiating Repositories * Create a new repository by instantiating it through -```bash -git init -``` + + ```bash + git init + ``` * Copy an existing project by cloning the repository through -```bash -git clone <url> -``` + + ```bash + git clone <url> + ``` ---------- @@ -24,17 +26,18 @@ git clone <url> * To instantiate a central repository a `--bare` flag is required. * Bare repositories don't allow file editing or committing changes. * Create a bare repo with -```bash -git init --bare project-name.git -``` + + ```bash + git init --bare project-name.git + ``` ---------- ## Instantiate workflow with clone 1. Create a project in your user namespace - - Choose to import from 'Any Repo by URL' and use - https://gitlab.com/gitlab-org/training-examples.git + - Choose to import from 'Any Repo by URL' and use + https://gitlab.com/gitlab-org/training-examples.git 2. Create a '`Workspace`' directory in your home directory. 3. Clone the '`training-examples`' project diff --git a/doc/university/training/topics/git_add.md b/doc/university/training/topics/git_add.md index 651366e0d49..b1483e725fe 100644 --- a/doc/university/training/topics/git_add.md +++ b/doc/university/training/topics/git_add.md @@ -11,27 +11,35 @@ comments: false Adds content to the index or staging area. * Adds a list of file -```bash -git add <files> -``` + + ```bash + git add <files> + ``` + * Adds all files including deleted ones -```bash -git add -A -``` + + ```bash + git add -A + ``` ---------- ## Git add continued * Add all text files in current dir -```bash -git add *.txt -``` + + ```bash + git add *.txt + ``` + * Add all text file in the project -```bash -git add "*.txt*" -``` + + ```bash + git add "*.txt*" + ``` + * Adds all files in directory -```bash -git add views/layouts/ -``` + + ```bash + git add views/layouts/ + ``` diff --git a/doc/university/training/topics/git_log.md b/doc/university/training/topics/git_log.md index f2709ae3890..3e39ea5cc9a 100644 --- a/doc/university/training/topics/git_log.md +++ b/doc/university/training/topics/git_log.md @@ -9,31 +9,36 @@ comments: false Git log lists commit history. It allows searching and filtering. * Initiate log -``` -git log -``` + + ``` + git log + ``` * Retrieve set number of records: -``` -git log -n 2 -``` + + ``` + git log -n 2 + ``` * Search commits by author. Allows user name or a regular expression. -``` -git log --author="user_name" -``` + + ``` + git log --author="user_name" + ``` ---------- * Search by comment message. -``` -git log --grep="<pattern>" -``` + + ``` + git log --grep="<pattern>" + ``` * Search by date -``` -git log --since=1.month.ago --until=3.weeks.ago -``` + + ``` + git log --since=1.month.ago --until=3.weeks.ago + ``` ---------- diff --git a/doc/university/training/topics/rollback_commits.md b/doc/university/training/topics/rollback_commits.md index 0db1d93d1dc..11cb557651f 100644 --- a/doc/university/training/topics/rollback_commits.md +++ b/doc/university/training/topics/rollback_commits.md @@ -9,26 +9,30 @@ comments: false ## Undo Commits * Undo last commit putting everything back into the staging area. -``` -git reset --soft HEAD^ -``` + + ``` + git reset --soft HEAD^ + ``` * Add files and change message with: -``` -git commit --amend -m "New Message" -``` + + ``` + git commit --amend -m "New Message" + ``` ---------- * Undo last and remove changes -``` -git reset --hard HEAD^ -``` + + ``` + git reset --hard HEAD^ + ``` * Same as last one but for two commits back -``` -git reset --hard HEAD^^ -``` + + ``` + git reset --hard HEAD^^ + ``` ** Don't reset after pushing ** diff --git a/doc/university/training/topics/stash.md b/doc/university/training/topics/stash.md index 5b27ac12f77..315ced1a196 100644 --- a/doc/university/training/topics/stash.md +++ b/doc/university/training/topics/stash.md @@ -10,50 +10,52 @@ We use git stash to store our changes when they are not ready to be committed and we need to change to a different branch. * Stash -``` -git stash save -# or -git stash -# or with a message -git stash save "this is a message to display on the list" -``` + + ``` + git stash save + # or + git stash + # or with a message + git stash save "this is a message to display on the list" + ``` * Apply stash to keep working on it -``` -git stash apply -# or apply a specific one from out stack -git stash apply stash@{3} -``` + + ``` + git stash apply + # or apply a specific one from out stack + git stash apply stash@{3} + ``` ---------- * Every time we save a stash it gets stacked so by using list we can see all our stashes. -``` -git stash list -# or for more information (log methods) -git stash list --stat -``` + ``` + git stash list + # or for more information (log methods) + git stash list --stat + ``` * To clean our stack we need to manually remove them. -``` -# drop top stash -git stash drop -# or -git stash drop <name> -# to clear all history we can use -git stash clear -``` + ``` + # drop top stash + git stash drop + # or + git stash drop <name> + # to clear all history we can use + git stash clear + ``` ---------- * Apply and drop on one command -``` - git stash pop -``` + ``` + git stash pop + ``` * If we meet conflicts we need to either reset or commit our changes. diff --git a/doc/university/training/topics/unstage.md b/doc/university/training/topics/unstage.md index fc72949ade9..ee7913637b9 100644 --- a/doc/university/training/topics/unstage.md +++ b/doc/university/training/topics/unstage.md @@ -10,26 +10,27 @@ comments: false * To remove files from stage use reset HEAD. Where HEAD is the last commit of the current branch. -```bash -git reset HEAD <file> -``` + ```bash + git reset HEAD <file> + ``` * This will unstage the file but maintain the modifications. To revert the file back to the state it was in before the changes we can use: -```bash -git checkout -- <file> -``` + ```bash + git checkout -- <file> + ``` ---------- * To remove a file from disk and repo use 'git rm' and to rm a dir use the '-r' flag. -``` -git rm '*.txt' -git rm -r <dirname> -``` + ``` + git rm '*.txt' + git rm -r <dirname> + ``` * If we want to remove a file from the repository but keep it on disk, say we forgot to add it to our `.gitignore` file then use `--cache`. -``` -git rm <filename> --cache -``` + + ``` + git rm <filename> --cache + ``` diff --git a/doc/update/11.2-to-11-3.md b/doc/update/11.2-to-11-3.md new file mode 100644 index 00000000000..d77f879ee57 --- /dev/null +++ b/doc/update/11.2-to-11-3.md @@ -0,0 +1,378 @@ +--- +comments: false +--- + +# From 11.2 to 11.3 + +Make sure you view this update guide from the branch (version) of GitLab you would +like to install (e.g., `11-3-stable`. You can select the branch in the version +dropdown at the top left corner of GitLab (below the menu bar). + +If the highest number stable branch is unclear please check the +[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation +guide links by version. + +### 1. Stop server + +```bash +sudo service gitlab stop +``` + +### 2. Backup + +NOTE: If you installed GitLab from source, make sure `rsync` is installed. + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production +``` + +### 3. Update Ruby + +NOTE: GitLab 11.0 and higher only support Ruby 2.4.x and dropped support for Ruby 2.3.x. Be +sure to upgrade your interpreter if necessary. + +You can check which version you are running with `ruby -v`. + +Download Ruby and compile it: + +```bash +mkdir /tmp/ruby && cd /tmp/ruby +curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.4.tar.gz +echo 'ec82b0d53bd0adad9b19e6b45e44d54e9ec3f10c ruby-2.4.4.tar.gz' | shasum -c - && tar xzf ruby-2.4.4.tar.gz +cd ruby-2.4.4 + +./configure --disable-install-rdoc +make +sudo make install +``` + +Install Bundler: + +```bash +sudo gem install bundler --no-ri --no-rdoc +``` + +### 4. Update Node + +GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. +This requires a minimum version of node v6.0.0. + +You can check which version you are running with `node -v`. If you are running +a version older than `v6.0.0` you will need to update to a newer version. You +can find instructions to install from community maintained packages or compile +from source at the nodejs.org website. + +<https://nodejs.org/en/download/> + +GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript +dependencies. + +```bash +curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - +echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list +sudo apt-get update +sudo apt-get install yarn +``` + +More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). + +### 5. Update Go + +NOTE: GitLab 11.0 and higher only supports Go 1.9.x and newer, and dropped support for Go +1.5.x through 1.8.x. Be sure to upgrade your installation if necessary. + +You can check which version you are running with `go version`. + +Download and install Go: + +```bash +# Remove former Go installation folder +sudo rm -rf /usr/local/go + +curl --remote-name --progress https://dl.google.com/go/go1.10.3.linux-amd64.tar.gz +echo 'fa1b0e45d3b647c252f51f5e1204aba049cde4af177ef9f2181f43004f901035 go1.10.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ + sudo tar -C /usr/local -xzf go1.10.3.linux-amd64.tar.gz +sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ +rm go1.10.3.linux-amd64.tar.gz +``` + +### 6. Get latest code + +```bash +cd /home/git/gitlab + +sudo -u git -H git fetch --all --prune +sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically +sudo -u git -H git checkout -- locale +``` + +For GitLab Community Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 11-3-stable +``` + +OR + +For GitLab Enterprise Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 11-3-stable-ee +``` + +### 7. Update gitlab-shell + +```bash +cd /home/git/gitlab-shell + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) +sudo -u git -H bin/compile +``` + +### 8. Update gitlab-workhorse + +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. + +```bash +cd /home/git/gitlab-workhorse + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) +sudo -u git -H make +``` + +### 9. Update Gitaly + +#### New Gitaly configuration options required + +In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. + +```shell +echo ' +[gitaly-ruby] +dir = "/home/git/gitaly/ruby" + +[gitlab-shell] +dir = "/home/git/gitlab-shell" +' | sudo -u git tee -a /home/git/gitaly/config.toml +``` + +#### Check Gitaly configuration + +Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly +configuration file may contain syntax errors. The block name +`[[storages]]`, which may occur more than once in your `config.toml` +file, should be `[[storage]]` instead. + +```shell +sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml +``` + +#### Compile Gitaly + +```shell +cd /home/git/gitaly +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) +sudo -u git -H make +``` + +### 10. Update gitlab-pages + +#### Only needed if you use GitLab Pages. + +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. + +```bash +cd /home/git/gitlab-pages + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) +sudo -u git -H make +``` + +### 11. Update MySQL permissions + +If you are using MySQL you need to grant the GitLab user the necessary +permissions on the database: + +```bash +mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" +``` + +If you use MySQL with replication, or just have MySQL configured with binary logging, +you will need to also run the following on all of your MySQL servers: + +```bash +mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" +``` + +You can make this setting permanent by adding it to your `my.cnf`: + +``` +log_bin_trust_function_creators=1 +``` + +### 12. Update configuration files + +#### New configuration options for `gitlab.yml` + +There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: + +```sh +cd /home/git/gitlab + +git diff origin/11-1-stable:config/gitlab.yml.example origin/11-3-stable:config/gitlab.yml.example +``` + +#### Nginx configuration + +Ensure you're still up-to-date with the latest NGINX configuration changes: + +```sh +cd /home/git/gitlab + +# For HTTPS configurations +git diff origin/11-1-stable:lib/support/nginx/gitlab-ssl origin/11-3-stable:lib/support/nginx/gitlab-ssl + +# For HTTP configurations +git diff origin/11-1-stable:lib/support/nginx/gitlab origin/11-3-stable:lib/support/nginx/gitlab +``` + +If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx +configuration as GitLab application no 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]. + +[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/11-3-stable/lib/support/init.d/gitlab.default.example#L38 + +#### SMTP configuration + +If you're installing from source and use SMTP to deliver mail, you will need to add the following line +to config/initializers/smtp_settings.rb: + +```ruby +ActionMailer::Base.delivery_method = :smtp +``` + +See [smtp_settings.rb.sample] as an example. + +[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-3-stable/config/initializers/smtp_settings.rb.sample#L13 + +#### Init script + +There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: + +```sh +cd /home/git/gitlab + +git diff origin/11-1-stable:lib/support/init.d/gitlab.default.example origin/11-3-stable:lib/support/init.d/gitlab.default.example +``` + +Ensure you're still up-to-date with the latest init script changes: + +```bash +cd /home/git/gitlab + +sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab +``` + +For Ubuntu 16.04.1 LTS: + +```bash +sudo systemctl daemon-reload +``` + +### 13. Install libs, migrations, etc. + +```bash +cd /home/git/gitlab + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --without postgres development test --deployment + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --without mysql development test --deployment + +# Optional: clean up old gems +sudo -u git -H bundle clean + +# Run database migrations +sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + +# Compile GetText PO files + +sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production + +# Update node dependencies and recompile assets +sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production + +# Clean up cache +sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production +``` + +**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). + +### 14. Start application + +```bash +sudo service gitlab start +sudo service nginx restart +``` + +### 15. Check application status + +Check if GitLab and its environment are configured correctly: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production +``` + +To make sure you didn't miss anything run a more thorough check: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production +``` + +If all items are green, then congratulations, the upgrade is complete! + +## Things went south? Revert to previous version (11.2) + +### 1. Revert the code to the previous version + +Follow the [upgrade guide from 11.1 to 11.2](11.1-to-11.2.md), except for the +database migration (the backup is already migrated to the previous version). + +### 2. Restore from the backup + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + +If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. + +[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-3-stable/config/gitlab.yml.example +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-3-stable/lib/support/init.d/gitlab.default.example diff --git a/doc/update/4.2-to-5.0.md b/doc/update/4.2-to-5.0.md index 311664b2bc1..d292327efbd 100644 --- a/doc/update/4.2-to-5.0.md +++ b/doc/update/4.2-to-5.0.md @@ -32,7 +32,7 @@ cd /home/git/ sudo -u git -H git clone https://github.com/gitlabhq/gitlab-shell.git /home/git/gitlab-shell ``` -## 3. setup gitlab-shell +## 3. set up gitlab-shell ```bash # chmod all repos and files under git diff --git a/doc/update/7.5-to-7.6.md b/doc/update/7.5-to-7.6.md index f0dfb177b79..0d45a9528b9 100644 --- a/doc/update/7.5-to-7.6.md +++ b/doc/update/7.5-to-7.6.md @@ -82,7 +82,7 @@ git diff origin/7-5-stable:config/gitlab.yml.example origin/7-6-stable:config/gi * HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`][nginx] but with your settings * HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your setting -#### Setup time zone (optional) +#### Set up time zone (optional) Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. diff --git a/doc/update/7.6-to-7.7.md b/doc/update/7.6-to-7.7.md index 85de6b0c546..5e0b2ca7bcd 100644 --- a/doc/update/7.6-to-7.7.md +++ b/doc/update/7.6-to-7.7.md @@ -82,7 +82,7 @@ git diff origin/7-6-stable:config/gitlab.yml.example origin/7-7-stable:config/gi * HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`][nginx] but with your settings * HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your setting -#### Setup time zone (optional) +#### Set up time zone (optional) Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. diff --git a/doc/update/7.7-to-7.8.md b/doc/update/7.7-to-7.8.md index 7cee5f79a13..f5b1ebf0a9c 100644 --- a/doc/update/7.7-to-7.8.md +++ b/doc/update/7.7-to-7.8.md @@ -83,7 +83,7 @@ git diff origin/7-7-stable:config/gitlab.yml.example origin/7-8-stable:config/gi * HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your settings. * A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. -#### Setup time zone (optional) +#### Set up time zone (optional) Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. diff --git a/doc/update/7.8-to-7.9.md b/doc/update/7.8-to-7.9.md index 5a8b689dbc1..0db7698936b 100644 --- a/doc/update/7.8-to-7.9.md +++ b/doc/update/7.8-to-7.9.md @@ -85,7 +85,7 @@ git diff origin/7-8-stable:config/gitlab.yml.example origin/7-9-stable:config/gi * HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your settings. * A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. -#### Setup time zone (optional) +#### Set up time zone (optional) Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. diff --git a/doc/update/7.9-to-7.10.md b/doc/update/7.9-to-7.10.md index 99df51dbb99..782fb0736e6 100644 --- a/doc/update/7.9-to-7.10.md +++ b/doc/update/7.9-to-7.10.md @@ -81,7 +81,7 @@ git diff origin/7-9-stable:config/gitlab.yml.example origin/7-10-stable:config/g * HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your settings. * A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. -#### Setup time zone (optional) +#### Set up time zone (optional) Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. diff --git a/doc/update/8.17-to-9.0.md b/doc/update/8.17-to-9.0.md index 2e0c26a9092..74ce52859fa 100644 --- a/doc/update/8.17-to-9.0.md +++ b/doc/update/8.17-to-9.0.md @@ -150,48 +150,48 @@ Update your current configuration as follows, replacing with your storages names 1. Update your `gitlab.yml`, from - ```yaml - repositories: - storages: # You must have at least a 'default' storage path. - default: /home/git/repositories - nfs: /mnt/nfs/repositories - cephfs: /mnt/cephfs/repositories - ``` - - to - - ```yaml - repositories: - storages: # You must have at least a 'default' storage path. - default: - path: /home/git/repositories - nfs: - path: /mnt/nfs/repositories - cephfs: - path: /mnt/cephfs/repositories - ``` + ```yaml + repositories: + storages: # You must have at least a 'default' storage path. + default: /home/git/repositories + nfs: /mnt/nfs/repositories + cephfs: /mnt/cephfs/repositories + ``` + + to + + ```yaml + repositories: + storages: # You must have at least a 'default' storage path. + default: + path: /home/git/repositories + nfs: + path: /mnt/nfs/repositories + cephfs: + path: /mnt/cephfs/repositories + ``` **For Omnibus installations** 1. Update your `/etc/gitlab/gitlab.rb`, from - ```ruby - git_data_dirs({ - "default" => "/var/opt/gitlab/git-data", - "nfs" => "/mnt/nfs/git-data", - "cephfs" => "/mnt/cephfs/git-data" - }) - ``` - - to - - ```ruby - git_data_dirs({ - "default" => { "path" => "/var/opt/gitlab/git-data" }, - "nfs" => { "path" => "/mnt/nfs/git-data" }, - "cephfs" => { "path" => "/mnt/cephfs/git-data" } - }) - ``` + ```ruby + git_data_dirs({ + "default" => "/var/opt/gitlab/git-data", + "nfs" => "/mnt/nfs/git-data", + "cephfs" => "/mnt/cephfs/git-data" + }) + ``` + + to + + ```ruby + git_data_dirs({ + "default" => { "path" => "/var/opt/gitlab/git-data" }, + "nfs" => { "path" => "/mnt/nfs/git-data" }, + "cephfs" => { "path" => "/mnt/cephfs/git-data" } + }) + ``` #### Git configuration diff --git a/doc/update/9.0-to-9.1.md b/doc/update/9.0-to-9.1.md index f60bd92e236..3a806d2f8c8 100644 --- a/doc/update/9.0-to-9.1.md +++ b/doc/update/9.0-to-9.1.md @@ -150,48 +150,48 @@ Update your current configuration as follows, replacing with your storages names 1. Update your `gitlab.yml`, from - ```yaml - repositories: - storages: # You must have at least a 'default' storage path. - default: /home/git/repositories - nfs: /mnt/nfs/repositories - cephfs: /mnt/cephfs/repositories - ``` - - to - - ```yaml - repositories: - storages: # You must have at least a 'default' storage path. - default: - path: /home/git/repositories - nfs: - path: /mnt/nfs/repositories - cephfs: - path: /mnt/cephfs/repositories - ``` + ```yaml + repositories: + storages: # You must have at least a 'default' storage path. + default: /home/git/repositories + nfs: /mnt/nfs/repositories + cephfs: /mnt/cephfs/repositories + ``` + + to + + ```yaml + repositories: + storages: # You must have at least a 'default' storage path. + default: + path: /home/git/repositories + nfs: + path: /mnt/nfs/repositories + cephfs: + path: /mnt/cephfs/repositories + ``` **For Omnibus installations** 1. Update your `/etc/gitlab/gitlab.rb`, from - - ```ruby - git_data_dirs({ - "default" => "/var/opt/gitlab/git-data", - "nfs" => "/mnt/nfs/git-data", - "cephfs" => "/mnt/cephfs/git-data" - }) - ``` - - to - - ```ruby - git_data_dirs({ - "default" => { "path" => "/var/opt/gitlab/git-data" }, - "nfs" => { "path" => "/mnt/nfs/git-data" }, - "cephfs" => { "path" => "/mnt/cephfs/git-data" } - }) - ``` + + ```ruby + git_data_dirs({ + "default" => "/var/opt/gitlab/git-data", + "nfs" => "/mnt/nfs/git-data", + "cephfs" => "/mnt/cephfs/git-data" + }) + ``` + + to + + ```ruby + git_data_dirs({ + "default" => { "path" => "/var/opt/gitlab/git-data" }, + "nfs" => { "path" => "/mnt/nfs/git-data" }, + "cephfs" => { "path" => "/mnt/cephfs/git-data" } + }) + ``` #### Git configuration diff --git a/doc/update/9.4-to-9.5.md b/doc/update/9.4-to-9.5.md index 1bfc1167c36..6a655f77a55 100644 --- a/doc/update/9.4-to-9.5.md +++ b/doc/update/9.4-to-9.5.md @@ -154,7 +154,7 @@ sudo -u git -H make #### New Gitaly configuration options required -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell'. +In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. ```shell echo ' diff --git a/doc/update/9.5-to-10.0.md b/doc/update/9.5-to-10.0.md index 8d1cf0f737b..7790d192a82 100644 --- a/doc/update/9.5-to-10.0.md +++ b/doc/update/9.5-to-10.0.md @@ -154,7 +154,7 @@ sudo -u git -H make #### New Gitaly configuration options required -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell'. +In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. ```shell echo ' diff --git a/doc/update/README.md b/doc/update/README.md index c98e20686e0..7d3c4c310a4 100644 --- a/doc/update/README.md +++ b/doc/update/README.md @@ -41,7 +41,8 @@ However, for this to work there are the following requirements: 1. You can only upgrade 1 minor release at a time. So from 9.1 to 9.2, not to 9.3. 2. You have to use [post-deployment - migrations](../development/post_deployment_migrations.md). + migrations](../development/post_deployment_migrations.md) (included in + zero downtime update steps below) 3. You are using PostgreSQL. If you are using MySQL please look at the release post to see if downtime is required. @@ -142,4 +143,4 @@ possible. [ee-ce]: ../downgrade_ee_to_ce/README.md [ce]: https://about.gitlab.com/features/#community [ee]: https://about.gitlab.com/features/#enterprise -[omni-ce-ee]: http://docs.gitlab.com/omnibus/update/README.html#from-community-edition-to-enterprise-edition +[omni-ce-ee]: https://docs.gitlab.com/omnibus/update/README.html#updating-community-edition-to-enterprise-edition diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md new file mode 100644 index 00000000000..9205860ef1f --- /dev/null +++ b/doc/user/admin_area/diff_limits.md @@ -0,0 +1,21 @@ +# Diff limits administration + +NOTE: **Note:** +Merge requests and branch comparison views will be affected. + +CAUTION: **Caution:** +These settings are currently under experimental state. They'll +increase the resource consumption of your instance and should +be edited mindfully. + +1. Access **Admin area > Settings > General** +1. Expand **Diff limits** + +### Maximum diff patch size + +This is the content size each diff file (patch) is allowed to reach before +it's collapsed, without the possibility of being expanded. A link redirecting +to the blob view will be presented for the patches that surpass this limit. + +Patches surpassing 10% of this content size will be automatically collapsed, +but expandable (a link to expand the diff will be presented). diff --git a/doc/user/admin_area/img/admin_area_settings_button.png b/doc/user/admin_area/img/admin_area_settings_button.png Binary files differnew file mode 100644 index 00000000000..315ef40a375 --- /dev/null +++ b/doc/user/admin_area/img/admin_area_settings_button.png diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 1b676bfb383..43b1190fb48 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -1,12 +1,12 @@ # Health Check ->**Notes:** - - 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 will - be deprecated in GitLab 9.1. Read more in the [old behavior](#old-behavior) - section. - - [Access token](#access-token) has been deprecated in GitLab 9.4 - in favor of [IP whitelist](#ip-whitelist) +> **Notes:** +> - 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 will +> be deprecated in GitLab 9.1. Read more in the [old behavior](#old-behavior) +> section. +> - [Access token](#access-token) has been deprecated in GitLab 9.4 +> in favor of [IP whitelist](#ip-whitelist) GitLab provides liveness and readiness probes to indicate service health and reachability to required services. These probes report on the status of the diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 76d9a4ceb03..6025a5bbcda 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -1,39 +1,51 @@ -# Continuous integration Admin settings +# Continuous Integration and Deployment Admin settings **[CORE ONLY]** -## Maximum artifacts size +In this area, you will find settings for Auto DevOps, Runners and job artifacts. +You can find it in the admin area, under **Settings > Continuous Integration and Deployment**. -The maximum size of the [job artifacts][art-yml] can be set in the Admin area -of your GitLab instance. The value is in *MB* and the default is 100MB. Note -that this setting is set for each job. - -1. Go to **Admin area > Settings** (`/admin/application_settings`). + -  +## Auto DevOps **[CORE ONLY]** -1. Change the value of maximum artifacts size (in MB): +To enable (or disable) [Auto DevOps](../../../topics/autodevops/index.md) +for all projects: -  +1. Go to **Admin area > Settings > Continuous Integration and Deployment**. +1. Check (or uncheck to disable) the box that says "Default to Auto DevOps pipeline for all projects". +1. Optionally, set up the [Auto DevOps base domain](../../../topics/autodevops/index.md#auto-devops-base-domain) + which is going to be used for Auto Deploy and Auto Review Apps. +1. Hit **Save changes** for the changes to take effect. -1. Hit **Save** for the changes to take effect. +From now on, every existing project and newly created ones that don't have a +`.gitlab-ci.yml`, will use the Auto DevOps pipelines. -## Default artifacts expiration +If you want to disable it for a specific project, you can do so in +[its settings](../../../topics/autodevops/index.md#enabling-auto-devops). -The default expiration time of the [job artifacts][art-yml] can be set in -the Admin area of your GitLab instance. The syntax of duration is described -in [artifacts:expire_in][duration-syntax]. The default is `30 days`. Note that -this setting is set for each job. Set it to `0` if you don't want default -expiration. The default unit is in seconds. +## Maximum artifacts size **[CORE ONLY]** +The maximum size of the [job artifacts][art-yml] can be set in the Admin area +of your GitLab instance. The value is in *MB* and the default is 100MB per job; +on GitLab.com it's [set to 1G](../../gitlab_com/index.md#gitlab-ci-cd). -1. Go to **Admin area > Settings** (`/admin/application_settings`). +To change it: -  +1. Go to **Admin area > Settings > Continuous Integration and Deployment**. +1. Change the value of maximum artifacts size (in MB). +1. Hit **Save changes** for the changes to take effect. -1. Change the value of default expiration time ([syntax][duration-syntax]): +## Default artifacts expiration **[CORE ONLY]** -  +The default expiration time of the [job artifacts](../../../administration/job_artifacts.md) +can be set in the Admin area of your GitLab instance. The syntax of duration is +described in [`artifacts:expire_in`](../../../ci/yaml/README.md#artifacts-expire_in) +and the default value is `30 days`. On GitLab.com they +[never expire](../../gitlab_com/index.md#gitlab-ci-cd). -1. Hit **Save** for the changes to take effect. +1. Go to **Admin area > Settings > Continuous Integration and Deployment**. +1. Change the value of default expiration time. +1. Hit **Save changes** for the changes to take effect. -[art-yml]: ../../../administration/job_artifacts.md -[duration-syntax]: ../../../ci/yaml/README.md#artifactsexpire_in +This setting is set per job and can be overridden in +[`.gitlab-ci.yml`](../../../ci/yaml/README.md#artifacts-expire_in). +To disable the expiration, set it to `0`. The default unit is in seconds. diff --git a/doc/user/admin_area/settings/img/admin_area_settings_button.png b/doc/user/admin_area/settings/img/admin_area_settings_button.png Binary files differdeleted file mode 100644 index 1d2c0ac04bc..00000000000 --- a/doc/user/admin_area/settings/img/admin_area_settings_button.png +++ /dev/null diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md new file mode 100644 index 00000000000..93767aefb51 --- /dev/null +++ b/doc/user/admin_area/settings/index.md @@ -0,0 +1,22 @@ +# Admin area settings **[CORE ONLY]** + +In the admin area settings, you can find various options for your GitLab +instance like sign-up restrictions, account limits and quota, metrics, etc. + +Navigate to it by going to **Admin area > Settings**. Some of the settings +include: + +- [Continuous Integration and Deployment](continuous_integration.md) +- [Email](email.md) +- [Sign up restrictions](sign_up_restrictions.md) +- [Terms](terms.md) +- [Third party offers](third_party_offers.md) +- [Usage statistics](usage_statistics.md) +- [Visibility and access controls](visibility_and_access_controls.md) + +## GitLab.com admin area settings + +Most of the settings under the admin area change the behavior of the whole +GitLab instance. For GitLab.com, the admin settings are available only for the +GitLab.com administrators, and the parameters can be found on the +[GitLab.com settings](../../gitlab_com/index.md) documentation. diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index b7427592e10..35a9d7adb28 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -23,7 +23,7 @@ GitLab Inc. collects your instance's version and hostname (through the HTTP referer) as part of the version check. No other information is collected. This information is used, among other things, to identify to which versions -patches will need to be back ported, making sure active GitLab instances remain +patches will need to be backported, making sure active GitLab instances remain secure. If you disable version check, this information will not be collected. Enable or @@ -33,7 +33,8 @@ disable the version check at **Admin area > Settings > Usage statistics**. > [Introduced][ee-557] in GitLab Enterprise Edition 8.10. More statistics [were added][ee-735] in GitLab Enterprise Edition -8.12. [Moved to GitLab Community Edition][ce-23361] in 9.1. +8.12. [Moved to GitLab Core][ce-23361] in 9.1. More statistics +[were added][ee-6602] in GitLab Ultimate 11.2. GitLab sends a weekly payload containing usage data to GitLab Inc. The usage ping uses high-level data to help our product, support, and sales teams. It does @@ -79,3 +80,4 @@ Statistics visibility section under **Admin area > Settings > Usage statistics** [ee-557]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/557 [ee-735]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/735 [ce-23361]: https://gitlab.com/gitlab-org/gitlab-ce/issues/23361 +[ee-6602]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6602 diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index acbd2a66d37..93be3da44d4 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -1,10 +1,10 @@ # Award emoji ->**Notes:** -- First [introduced][1825] in GitLab 8.2. -- GitLab 9.0 [introduced][ce-9570] the usage of native emojis if the platform - supports them and falls back to images or CSS sprites. This change greatly - improved the award emoji performance overall. +> **Notes:** +> - First [introduced][1825] in GitLab 8.2. +> - GitLab 9.0 [introduced][ce-9570] the usage of native emojis if the platform +> supports them and falls back to images or CSS sprites. This change greatly +> improved the award emoji performance overall. When you're collaborating online, you get fewer opportunities for high-fives and thumbs-ups. Emoji can be awarded to issues, merge requests, snippets, and diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 9b0ff02f227..1b3fb9db4ec 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -23,9 +23,9 @@ in the form of a resolvable or threaded discussion. ## Resolvable discussions ->**Notes:** -- The main feature was [introduced][ce-5022] in GitLab 8.11. -- Resolvable discussions can be added only to merge request diffs. +> **Notes:** +> - The main feature was [introduced][ce-5022] in GitLab 8.11. +> - Resolvable discussions can be added only to merge request diffs. Discussion resolution helps keep track of progress during planning or code review. Resolving comments prevents you from forgetting to address feedback and lets you @@ -271,6 +271,8 @@ edit existing comments. Non-team members are restricted from adding or editing c | :-----------: | :----------: | |  |  | +Additionally locked issues can not be reopened. + [ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022 [ce-7125]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7125 [ce-7527]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7527 diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 20886faf418..e14e716a5eb 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -74,22 +74,17 @@ or over the size limit, you can [reduce your repository size with Git](../projec ## Shared Runners Shared Runners on GitLab.com run in [autoscale mode] and powered by -Google Cloud Platform and DigitalOcean. Autoscaling means reduced +Google Cloud Platform. Autoscaling means reduced waiting times to spin up CI/CD jobs, and isolated VMs for each project, thus maximizing security. They're free to use for public open source projects and limited to 2000 CI minutes per month per group for private projects. Read about all [GitLab.com plans](https://about.gitlab.com/pricing/). -In case of DigitalOcean based Runners, all your CI/CD jobs run on ephemeral -instances with 2GB of RAM, CoreOS and the latest Docker Engine installed. -Instances provide 2 vCPUs and 60GB of SSD disk space. The default region of the -VMs is NYC1. - -In case of Google Cloud Platform based Runners, all your CI/CD jobs run on -ephemeral instances with 3.75GB of RAM, CoreOS and the latest Docker Engine +All your CI/CD jobs run on [n1-standard-1 instances](https://cloud.google.com/compute/docs/machine-types) with 3.75GB of RAM, CoreOS and the latest Docker Engine installed. Instances provide 1 vCPU and 25GB of HDD disk space. The default region of the VMs is US East1. +Each instance is used only for one job, this ensures any sensitive data left on the system can't be accessed by other people their CI jobs. Jobs handled by the shared Runners on GitLab.com (`shared-runners-manager-X.gitlab.com`), **will be timed out after 3 hours**, regardless of the timeout configured in a @@ -104,7 +99,7 @@ Below are the shared Runners settings. | Default Docker image | `ruby:2.5` | - | | `privileged` (run [Docker in Docker]) | `true` | `false` | -[ci_version_dashboard]: https://monitor.gitlab.net/dashboard/db/ci?from=now-1h&to=now&refresh=5m&orgId=1&panelId=12&fullscreen&theme=light +[ci_version_dashboard]: https://dashboards.gitlab.com/dashboard/db/ci?from=now-1h&to=now&refresh=5m&orgId=1&panelId=12&fullscreen&theme=light ### `config.toml` @@ -226,7 +221,7 @@ and the following environment variables: ## Cron jobs -Periodically executed jobs by Sidekiq, to self-heal Gitlab, do external +Periodically executed jobs by Sidekiq, to self-heal GitLab, do external synchronizations, run scheduled pipelines, etc.: | Setting | GitLab.com | Default | diff --git a/doc/user/group/index.md b/doc/user/group/index.md index e6bf32a2dc5..b14377a72b6 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -22,14 +22,14 @@ group and grant access to all their projects at once - Create a group, include members of your team, and make it easier to `@mention` all the team at once in issues and merge requests - Create a group for your company members, and create [subgroups](subgroups/index.md) - for each individual team. Let's say you create a group called `company-team`, and among others, - you created subgroups in this group for each individual team `backend-team`, - `frontend-team`, and `production-team`: - 1. When you start a new implementation from an issue, you add a comment: + for each individual team. Let's say you create a group called `company-team`, and among others, + you created subgroups in this group for each individual team `backend-team`, + `frontend-team`, and `production-team`: + 1. When you start a new implementation from an issue, you add a comment: _"`@company-team`, let's do it! `@company-team/backend-team` you're good to go!"_ - 1. When your backend team needs help from frontend, they add a comment: + 1. When your backend team needs help from frontend, they add a comment: _"`@company-team/frontend-team` could you help us here please?"_ - 1. When the frontend team completes their implementation, they comment: + 1. When the frontend team completes their implementation, they comment: _"`@company-team/backend-team`, it's done! Let's ship it `@company-team/production-team`!"_ ## Namespaces @@ -64,8 +64,8 @@ together in a single list view. ## Create a new group > **Notes:** -- For a list of words that are not allowed to be used as group names see the - [reserved names](../reserved_names.md). +> - For a list of words that are not allowed to be used as group names see the +> [reserved names](../reserved_names.md). You can create a group in GitLab from: diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 08849ac1df4..8db36c4a0e8 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,9 +1,8 @@ # Subgroups ->**Notes:** -- [Introduced][ce-2772] in GitLab 9.0. -- Not available when using MySQL as external database (support removed in - GitLab 9.3 [due to performance reasons][issue]). +NOTE: **Note:** +[Introduced][ce-2772] in GitLab 9.0. Not available when using MySQL as external +database (support removed in GitLab 9.3 [due to performance reasons][issue]). With subgroups (aka nested groups or hierarchical groups) you can have up to 20 levels of nested groups, which among other things can help you to: @@ -79,14 +78,14 @@ structure. ## Creating a subgroup ->**Notes:** -- You need to be an Owner of a group in order to be able to create - a subgroup. For more information check the [permissions table][permissions]. -- For a list of words that are not allowed to be used as group names see the - [reserved names][reserved]. -- Users can always create subgroups if they are explicitly added as an Owner to - a parent group even if group creation is disabled by an administrator in their - settings. +NOTE: **Note:** +You need to be an Owner of a group in order to be able to create a subgroup. For +more information check the [permissions table][permissions]. +For a list of words that are not allowed to be used as group names see the +[reserved names][reserved]. +Users can always create subgroups if they are explicitly added as an Owner to +a parent group even if group creation is disabled by an administrator in their +settings. To create a subgroup: @@ -136,12 +135,15 @@ From the image above, we can deduct the following things: ### Overriding the ancestor group membership ->**Note:** +NOTE: **Note:** You need to be an Owner of a group in order to be able to add members to it. +NOTE: **Note:** +A user's permissions in a subgroup cannot be lower than in any of its ancestor groups. +Therefore, you cannot reduce a user's permissions in a subgroup with respect to its ancestor groups. + To override a user's membership of an ancestor group (the first group they were -added to), simply add the user in the new subgroup again, but with different -permissions. +added to), add the user to the new subgroup again with a higher set of permissions. For example, if User0 was first added to group `group-1/group-1-1` with Developer permissions, then they will inherit those permissions in every other subgroup diff --git a/doc/user/index.md b/doc/user/index.md index 649c0b664a5..08995032cb1 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -96,7 +96,7 @@ directly from GitLab. No third-party integrations needed. - [GitLab Auto Deploy](../ci/autodeploy/index.md): Deploy your application out-of-the-box with GitLab Auto Deploy. - [Review Apps](../ci/review_apps/index.md): Live-preview the changes introduced by a merge request with Review Apps. - [GitLab Pages](project/pages/index.md): Publish your static site directly from -GitLab with Gitlab Pages. You can build, test, and deploy any Static Site Generator with Pages. +GitLab with GitLab Pages. You can build, test, and deploy any Static Site Generator with Pages. - [GitLab Container Registry](project/container_registry.md): Build and deploy Docker images with Container Registry. diff --git a/doc/user/instance_statistics/index.md b/doc/user/instance_statistics/index.md index a4eca89b7fe..22f76f728e3 100644 --- a/doc/user/instance_statistics/index.md +++ b/doc/user/instance_statistics/index.md @@ -10,9 +10,6 @@ and can be accessed via the top bar.  -For the statistics to show up, [usage ping must be enabled](../admin_area/settings/usage_statistics.md#usage-ping) -by an admin in the admin settings area. - There are two kinds of statistics: - [Conversational Development (ConvDev) Index](convdev.md): Provides an overview of your entire instance's feature usage. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 6203561265b..fb132f0613b 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -7,13 +7,13 @@ > this document currently work on our documentation website. > > For the best result, we encourage you to check this document out as rendered -by GitLab: [markdown.md] +> by GitLab: [markdown.md] -_GitLab uses (as of 11.1) the [CommonMark Ruby Library][commonmarker] for Markdown processing of all new issues, merge requests, comments, and other Markdown content in the GitLab system. Previous content, wiki pages and Markdown files (`.md`) in the repositories are still processed using the [Redcarpet Ruby library][redcarpet]._ +_GitLab uses (as of 11.1) the [CommonMark Ruby Library][commonmarker] for Markdown processing of all new issues, merge requests, comments, and other Markdown content in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the repositories are also processed with CommonMark. Older content in issues/comments are still processed using the [Redcarpet Ruby library][redcarpet]._ _Where there are significant differences, we will try to call them out in this document._ -GitLab uses "GitLab Flavored Markdown" (GFM). It extends the standard Markdown in a few significant ways to add some useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). +GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification][commonmark-spec] (which is based on standard Markdown) in a few significant ways to add some useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). You can use GFM in the following areas: @@ -22,31 +22,59 @@ You can use GFM in the following areas: - merge requests - milestones - snippets (the snippet must be named with a `.md` extension) -- wiki pages (currently only rendered by Redcarpet) -- markdown documents inside the repository (currently only rendered by Redcarpet) +- wiki pages +- markdown documents inside the repository You can also use other rich text files in GitLab. You might have to install a dependency to do so. Please see the [github-markup gem readme](https://github.com/gitlabhq/markup#markups) for more information. +### Transitioning to CommonMark + +You may have Markdown documents in your repository that were written using some of the nuances of RedCarpet's version of Markdown. Since CommonMark uses a slightly stricter syntax, these documents may now display a little strangely since we've transitioned to CommonMark. Numbered lists with nested lists in particular can be displayed incorrectly. + +It is usually quite easy to fix. In the case of a nested list such as this: + +```markdown +1. Chocolate + - dark + - milk +``` + +simply add a space to each nested item: + +```markdown +1. Chocolate + - dark + - milk +``` + +In the documentation below, we try to highlight some of the differences. + +If you have a need to view a document using RedCarpet, you can add the token `legacy_render=1` to the end of the url, like this: + +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md?legacy_render=1 + +If you have a large volume of Markdown files, it can be tedious to determine if they will be displayed correctly or not. You can use the [diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) tool (not an officially supported product) to generate a list of files and differences between how RedCarpet and CommonMark render the files. It can give you a great idea if anything needs to be changed - many times nothing will need to changed. + ### Newlines > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#newlines -GFM honors the markdown specification in how [paragraphs and line breaks are handled](https://daringfireball.net/projects/markdown/syntax#p). +GFM honors the markdown specification in how [paragraphs and line breaks are handled][commonmark-spec]. A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. Line-breaks, or soft returns, are rendered if you end a line with two or more spaces: -[//]: # (Do *NOT* remove the two ending whitespaces in the following line.) -[//]: # (They are needed for the Markdown text to render correctly.) +<!-- (Do *NOT* remove the two ending whitespaces in the following line.) --> +<!-- (They are needed for the Markdown text to render correctly.) --> Roses are red [followed by two or more spaces] Violets are blue Sugar is sweet -[//]: # (Do *NOT* remove the two ending whitespaces in the following line.) -[//]: # (They are needed for the Markdown text to render correctly.) +<!-- (Do *NOT* remove the two ending whitespaces in the following line.) --> +<!-- (They are needed for the Markdown text to render correctly.) --> Roses are red Violets are blue @@ -444,7 +472,7 @@ Become: > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15107) in GitLab 10.3. - +> > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#mermaid @@ -979,8 +1007,9 @@ A link starting with a `/` is relative to the wiki root. ## References - This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). -- The [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard markdown. -- [Dillinger.io](http://dillinger.io) is a handy tool for testing standard markdown. +- The original [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard markdown. +- The detailed specification for CommonMark can be found in the [CommonMark Spec][commonmark-spec] +- The [CommonMark Dingus](http://try.commonmark.org) is a handy tool for testing CommonMark syntax. [^1]: This link will be broken if you see this document from the Help page or docs.gitlab.com [^2]: This is my awesome footnote. @@ -993,3 +1022,4 @@ A link starting with a `/` is relative to the wiki root. [katex-subset]: https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX "Macros supported by KaTeX" [asciidoctor-manual]: http://asciidoctor.org/docs/user-manual/#activating-stem-support "Asciidoctor user manual" [commonmarker]: https://github.com/gjtorikian/commonmarker +[commonmark-spec]: https://spec.commonmark.org/current/ diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 10ac6301aa1..4359592905d 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -42,11 +42,14 @@ The following table depicts the various user permission levels in a project. | See a job log | ✓ [^3] | ✓ | ✓ | ✓ | ✓ | | Download and browse job artifacts | ✓ [^3] | ✓ | ✓ | ✓ | ✓ | | View wiki pages | ✓ [^1] | ✓ | ✓ | ✓ | ✓ | +| View license management reports **[ULTIMATE]** | ✓ [^1] | ✓ | ✓ | ✓ | ✓ | +| View Security reports **[ULTIMATE]** | ✓ [^1] | ✓ | ✓ | ✓ | ✓ | | Pull project code | [^1] | ✓ | ✓ | ✓ | ✓ | | Download project | [^1] | ✓ | ✓ | ✓ | ✓ | | Assign issues | | ✓ | ✓ | ✓ | ✓ | | Assign merge requests | | | ✓ | ✓ | ✓ | -| Label issues and merge requests | | ✓ | ✓ | ✓ | ✓ | +| Label issues | | ✓ | ✓ | ✓ | ✓ | +| Label merge requests | | | ✓ | ✓ | ✓ | | Create code snippets | | ✓ | ✓ | ✓ | ✓ | | Manage issue tracker | | ✓ | ✓ | ✓ | ✓ | | Manage labels | | ✓ | ✓ | ✓ | ✓ | @@ -56,6 +59,7 @@ The following table depicts the various user permission levels in a project. | See a list of merge requests | | ✓ | ✓ | ✓ | ✓ | | Manage related issues **[STARTER]** | | ✓ | ✓ | ✓ | ✓ | | Lock issue discussions | | ✓ | ✓ | ✓ | ✓ | +| Create issue from vulnerability **[ULTIMATE]** | | ✓ | ✓ | ✓ | ✓ | | Lock merge request discussions | | | ✓ | ✓ | ✓ | | Create new environments | | | ✓ | ✓ | ✓ | | Stop environments | | | ✓ | ✓ | ✓ | @@ -72,6 +76,9 @@ The following table depicts the various user permission levels in a project. | Update a container registry | | | ✓ | ✓ | ✓ | | Remove a container registry image | | | ✓ | ✓ | ✓ | | Create/edit/delete project milestones | | | ✓ | ✓ | ✓ | +| View approved/blacklisted licenses **[ULTIMATE]** | | | ✓ | ✓ | ✓ | +| Use security dashboard **[ULTIMATE]** | | | ✓ | ✓ | ✓ | +| Dismiss vulnerability **[ULTIMATE]** | | | ✓ | ✓ | ✓ | | Use environment terminals | | | | ✓ | ✓ | | Add new team members | | | | ✓ | ✓ | | Push to protected branches | | | | ✓ | ✓ | @@ -89,6 +96,7 @@ The following table depicts the various user permission levels in a project. | Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | | Remove GitLab Pages | | | | | ✓ | | Manage clusters | | | | ✓ | ✓ | +| Manage license policy **[ULTIMATE]** | | | | ✓ | ✓ | | Edit comments (posted by any user) | | | | ✓ | ✓ | | Switch visibility level | | | | | ✓ | | Transfer project to another namespace | | | | | ✓ | @@ -97,7 +105,7 @@ The following table depicts the various user permission levels in a project. | Remove pages | | | | | ✓ | | Force push to protected branches [^4] | | | | | | | Remove protected branches [^4] | | | | | | -| View project Audit Events | | | | ✓ | ✓ | +| View project Audit Events | | | | ✓ | ✓ | ## Project features permissions @@ -109,6 +117,7 @@ which visibility level you select on project settings. - Disabled: disabled for everyone - Only team members: only team members will see even if your project is public or internal - Everyone with access: everyone can see depending on your project visibility level +- Everyone: enabled for everyone (only available for GitLab Pages) ### Protected branches @@ -241,6 +250,7 @@ which visibility level you select on project settings. - Disabled: disabled for everyone - Only team members: only team members will see even if your project is public or internal - Everyone with access: everyone can see depending on your project visibility level +- Everyone: enabled for everyone (only available for GitLab Pages) ## GitLab CI/CD permissions diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 910bd20f882..49f0ce2cd79 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -1,5 +1,8 @@ # Deleting a User Account +NOTE: **Note:** +Deleting a user will delete all projects in that user namespace. + - As a user, you can delete your own account by navigating to **Settings** > **Account** and selecting **Delete account** - As an admin, you can delete a user account by navigating to the **Admin Area**, selecting the **Users** tab, selecting a user, and clicking on **Delete user** diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index e25e1e19b13..bc6ecdf4f32 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -2,18 +2,18 @@ Two-factor Authentication (2FA) provides an additional level of security to your GitLab account. Once enabled, in addition to supplying your username and -password to login, you'll be prompted for a code generated by an application on -your phone. +password to login, you'll be prompted for a code generated by your one time password +authenticator. For example, a password manager on one of your devices. By enabling 2FA, the only way someone other than you can log into your account -is to know your username and password *and* have access to your phone. +is to know your username and password *and* have access to your one time password secret. ## Overview > **Note:** When you enable 2FA, don't forget to back up your recovery codes. -In addition to a phone application, GitLab supports U2F (universal 2nd factor) devices as +In addition to one time authenticators (TOTP), GitLab supports U2F (universal 2nd factor) devices as the second factor of authentication. Once enabled, in addition to supplying your username and password to login, you'll be prompted to activate your U2F device (usually by pressing a button on it), and it will perform secure authentication on your behalf. @@ -24,10 +24,10 @@ from other browsers. ## Enabling 2FA -There are two ways to enable two-factor authentication: via a mobile application +There are two ways to enable two-factor authentication: via a one time password authenticator or a U2F device. -### Enable 2FA via mobile application +### Enable 2FA via one time password authenticator **In GitLab:** @@ -59,8 +59,8 @@ of recovery codes. ### Enable 2FA via U2F device > **Notes:** -- GitLab officially only supports [Yubikey] U2F devices. -- Support for U2F devices was added in GitLab 8.8. +> - GitLab officially only supports [Yubikey] U2F devices. +> - Support for U2F devices was added in GitLab 8.8. **In GitLab:** @@ -69,7 +69,7 @@ of recovery codes. 1. Go to **Account**. 1. Click **Enable Two-Factor Authentication**. 1. Plug in your U2F device. -1. Click on **Setup New U2F Device**. +1. Click on **Set up New U2F Device**. 1. A light will start blinking on your device. Activate it by pressing its button. You will see a message indicating that your device was successfully set up. @@ -82,7 +82,7 @@ Click on **Register U2F Device** to complete the process. > **Note:** Recovery codes are not generated for U2F devices. -Should you ever lose access to your phone, you can use one of the ten provided +Should you ever lose access to your one time password authenticator, you can use one of the ten provided backup codes to login to your account. We suggest copying or printing them for storage in a safe place. **Each code can be used only once** to log in to your account. @@ -98,7 +98,7 @@ be presented with a second prompt, depending on which type of 2FA you've enabled ### Log in via mobile application -Enter the pin from your phone's application or a recovery code to log in. +Enter the pin from your one time password authenticator's application or a recovery code to log in.  @@ -145,7 +145,7 @@ codes. If you saved these codes, you can use one of them to sign in. To use a recovery code, enter your username/email and password on the GitLab sign-in page. When prompted for a two-factor code, enter the recovery code. ->**Note:** +> **Note:** Once you use a recovery code, you cannot re-use it. You can still use the other recovery codes you saved. @@ -187,7 +187,7 @@ a new set of recovery codes with SSH. When prompted for a two-factor code, enter one of the recovery codes obtained from the command-line output. ->**Note:** +> **Note:** After signing in, visit your **Profile settings > Account** immediately to set up two-factor authentication with a new device. diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index b1b822f25bd..ab62762f343 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -37,6 +37,7 @@ From there, you can: [use GitLab as an OAuth provider](../../integration/oauth_provider.md#introduction-to-oauth) - Manage [personal access tokens](personal_access_tokens.md) to access your account via API and authorized applications - Add and delete emails linked to your account +- Choose which email to use for notifications, web-based commits, and display on your public profile - Manage [SSH keys](../../ssh/README.md#ssh) to access your account via SSH - Manage your [preferences](preferences.md#syntax-highlighting-theme) to customize your own GitLab experience @@ -91,6 +92,18 @@ To enable private profile: NOTE: **Note:** You and GitLab admins can see your the abovementioned information on your profile even if it is private. +## Private contributions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/14078) in GitLab 11.3. + +Enabling private contributions will include contributions to private projects, in the user contribution calendar graph and user recent activity. + +To enable private contributions: + +1. Navigate to your personal [profile settings](#profile-settings). +2. Check the "Private contributions" option. +3. Hit **Update profile settings**. + ## Current status > Introduced in GitLab 11.2. @@ -102,6 +115,13 @@ Please be aware that your status is publicly visible even if your [profile is pr To set your current status: +1. Open the user menu in the top-right corner of the navigation bar. +1. Hit **Set status**, or **Edit status** if you have already set a status. +1. Set the emoji and/or status message to your liking. +1. Hit **Set status**. Alternatively, you can also hit **Remove status** to remove your user status entirely. + +or + 1. Navigate to your personal [profile settings](#profile-settings). 1. In the text field below `Your status`, enter your status message. 1. Select an emoji from the dropdown if you like. diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index c4e59444ef7..19eb95099ce 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -17,7 +17,7 @@ If you find that you have to add the same badges to several projects, you may wa To add a new badge to a project: -1. Navigate to your project's **Settings > Badges**. +1. Navigate to your project's **Settings > General > Badges**. 1. Under "Link", enter the URL that the badges should point to and under "Badge image URL" the URL of the image that should be displayed. 1. Submit the badge by clicking the **Add badge** button. @@ -39,7 +39,7 @@ project, consider adding them on the [project level](#project-badges) or use To add a new badge to a group: -1. Navigate to your group's **Settings > Project Badges**. +1. Navigate to your group's **Settings > General > Badges**. 1. Under "Link", enter the URL that the badges should point to and under "Badge image URL" the URL of the image that should be displayed. 1. Submit the badge by clicking the **Add badge** button. diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index 4261293b06f..fead99c5e88 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -1,11 +1,10 @@ # Bulk editing issues and merge requests -> -**Notes:** -- A permission level of `Reporter` or higher is required in order to manage -issues. -- A permission level of `Developer` or higher is required in order to manage -merge requests. +> **Notes:** +> - A permission level of `Reporter` or higher is required in order to manage +> issues. +> - A permission level of `Developer` or higher is required in order to manage +> merge requests. Attributes can be updated simultaneously across multiple issues or merge requests by using the bulk editing feature. diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md index ec8467da14f..10f0cdb333e 100644 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ b/doc/user/project/clusters/eks_and_gitlab/index.md @@ -43,9 +43,9 @@ From the left side bar, hover over `Operations` and select `Kubernetes`, then cl A few details from the EKS cluster will be required to connect it to GitLab. 1. A valid Kubernetes certificate and token are needed to authenticate to the EKS cluster. A pair is created by default, which can be used. Open a shell and use `kubectl` to retrieve them: - * 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 with `kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 -D` - * Retrieve the token with `kubectl get secret <secret name> -o jsonpath="{['data']['token']}" | base64 -D`. + * 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 with `kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 -D` + * Retrieve the token with `kubectl get secret <secret name> -o jsonpath="{['data']['token']}" | base64 -D`. 1. The API server endpoint is also required, so GitLab can connect to the cluster. This is displayed on the AWS EKS console, when viewing the EKS cluster details. You now have all the information needed to connect the EKS cluster: diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 7c552103412..3ec17806490 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -54,16 +54,16 @@ new Kubernetes cluster to your project: 1. Connect your Google account if you haven't done already by clicking the **Sign in with Google** button. 1. From there on, choose your cluster's settings: - - **Kubernetes cluster name** - The name you wish to give the cluster. - - **Environment scope** - The [associated environment](#setting-the-environment-scope) to this cluster. - - **Google Cloud Platform project** - Choose the project you created in your GCP - console that will host the Kubernetes cluster. Learn more about - [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). - - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) - under which the cluster will be created. - - **Number of nodes** - Enter the number of nodes you wish the cluster to have. - - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) - of the Virtual Machine instance that the cluster will be based on. + - **Kubernetes cluster name** - The name you wish to give the cluster. + - **Environment scope** - The [associated environment](#setting-the-environment-scope) to this cluster. + - **Google Cloud Platform project** - Choose the project you created in your GCP + console that will host the Kubernetes cluster. Learn more about + [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). + - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) + under which the cluster will be created. + - **Number of nodes** - Enter the number of nodes you wish the cluster to have. + - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) + of the Virtual Machine instance that the cluster will be based on. 1. Finally, click the **Create Kubernetes cluster** button. After a couple of minutes, your cluster will be ready to go. You can now proceed @@ -127,8 +127,56 @@ applications running on the cluster. When GitLab creates the cluster, it enables and uses the legacy [Attribute-based access control (ABAC)](https://kubernetes.io/docs/admin/authorization/abac/). The newer [RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) -authorization will be supported in a -[future release](https://gitlab.com/gitlab-org/gitlab-ce/issues/29398). +authorization is [experimental](#role-based-access-control-rbac). + +### Role-based access control (RBAC) **[CORE ONLY]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21401) in GitLab 11.4. + +CAUTION: **Warning:** +The RBAC authorization is experimental. + +Once RBAC is enabled for a cluster, GitLab will create the necessary service accounts +and privileges in order to install and run [GitLab managed applications](#installing-applications). + +If you are creating a [new GKE cluster via +GitLab](#adding-and-creating-a-new-gke-cluster-via-gitlab), you will be +asked if you would like to create an RBAC-enabled cluster. Enabling this +setting will create a `gitlab` service account which will be used by +GitLab to manage the newly created cluster. To enable this, this service +account will have the `cluster-admin` privilege. + +If you are [adding an existing Kubernetes +cluster](#adding-an-existing-kubernetes-cluster), you will be asked if +the cluster you are adding is a RBAC-enabled cluster. Ensure the +token of the account has administrator privileges for the cluster. + +In both cases above, when you install Helm Tiller into your cluster, an +RBAC-enabled cluster will create a `tiller` service account, with `cluster-admin` +privileges in the `gitlab-managed-apps` namespace. This service account will be +added to the installed Helm Tiller and will be used by Helm to install and run +[GitLab managed applications](#installing-applications). + +The table below summarizes which resources will be created in a +RBAC-enabled cluster : + +| Name | Kind | Details | Created when | +| --- | --- | --- | --- | +| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | +| `gitlab-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Creating a new GKE Cluster | +| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | +| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | +| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | + + +Helm Tiller will also create additional service accounts and other RBAC +resources for each installed application. Consult the documentation for the +Helm charts for each application for details. + +NOTE: **Note:** +Auto DevOps will not successfully complete in a cluster that only has RBAC +authorization enabled. RBAC support for Auto DevOps is planned in a +[future release](https://gitlab.com/gitlab-org/gitlab-ce/issues/44597). ### Security of GitLab Runners @@ -161,13 +209,13 @@ with Tiller already installed, you should be careful as GitLab cannot detect it. By installing it via the applications will result into having it twice, which can lead to confusion during deployments. -| Application | GitLab version | Description | -| ----------- | :------------: | ----------- | -| [Helm Tiller](https://docs.helm.sh/) | 10.2+ | Helm is a package manager for Kubernetes and is required to install all the other applications. It is installed in its own pod inside the cluster which can run the `helm` CLI in a safe environment. | -| [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) | 10.2+ | Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications and is useful if you want to use [Auto DevOps] or deploy your own web apps. | -| [Prometheus](https://prometheus.io/docs/introduction/overview/) | 10.4+ | Prometheus is an open-source monitoring and alerting system useful to supervise your deployed applications. | -| [GitLab Runner](https://docs.gitlab.com/runner/) | 10.6+ | GitLab Runner is the open source project that is used to run your jobs and send the results back to GitLab. It is used in conjunction with [GitLab CI/CD](https://about.gitlab.com/features/gitlab-ci-cd/), the open-source continuous integration service included with GitLab that coordinates the jobs. When installing the GitLab Runner via the applications, it will run in **privileged mode** by default. Make sure you read the [security implications](#security-implications) before doing so. | -| [JupyterHub](http://jupyter.org/) | 11.0+ | [JupyterHub](https://jupyterhub.readthedocs.io/en/stable/) is a multi-user service for managing notebooks across a team. [Jupyter Notebooks](https://jupyter-notebook.readthedocs.io/en/latest/) provide a web-based interactive programming environment used for data analysis, visualization, and machine learning. We use [this](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) custom Jupyter image that installs additional useful packages on top of the base Jupyter. **Note**: Authentication will be enabled for any user of the GitLab server via OAuth2. HTTPS will be supported in a future release. | +| Application | GitLab version | Description | Helm Chart | +| ----------- | :------------: | ----------- | --------------- | +| [Helm Tiller](https://docs.helm.sh/) | 10.2+ | Helm is a package manager for Kubernetes and is required to install all the other applications. It is installed in its own pod inside the cluster which can run the `helm` CLI in a safe environment. | n/a | +| [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) | 10.2+ | Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications and is useful if you want to use [Auto DevOps] or deploy your own web apps. | [stable/nginx-ingress](https://github.com/helm/charts/tree/master/stable/nginx-ingress) | +| [Prometheus](https://prometheus.io/docs/introduction/overview/) | 10.4+ | Prometheus is an open-source monitoring and alerting system useful to supervise your deployed applications. | [stable/prometheus](https://github.com/helm/charts/tree/master/stable/prometheus) | +| [GitLab Runner](https://docs.gitlab.com/runner/) | 10.6+ | GitLab Runner is the open source project that is used to run your jobs and send the results back to GitLab. It is used in conjunction with [GitLab CI/CD](https://about.gitlab.com/features/gitlab-ci-cd/), the open-source continuous integration service included with GitLab that coordinates the jobs. When installing the GitLab Runner via the applications, it will run in **privileged mode** by default. Make sure you read the [security implications](#security-implications) before doing so. | [runner/gitlab-runner](https://gitlab.com/charts/gitlab-runner) | +| [JupyterHub](http://jupyter.org/) | 11.0+ | [JupyterHub](https://jupyterhub.readthedocs.io/en/stable/) is a multi-user service for managing notebooks across a team. [Jupyter Notebooks](https://jupyter-notebook.readthedocs.io/en/latest/) provide a web-based interactive programming environment used for data analysis, visualization, and machine learning. We use [this](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) custom Jupyter image that installs additional useful packages on top of the base Jupyter. You will also see ready-to-use DevOps Runbooks built with [Rubix](https://github.com/amit1rrr/rubix). **Note**: Authentication will be enabled for any user of the GitLab server via OAuth2. HTTPS will be supported in a future release. | [jupyter/jupyterhub](https://jupyterhub.github.io/helm-chart/) | ## Getting the external IP address diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index 03302b3815d..2709ebb6f05 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -1,16 +1,16 @@ # GitLab Container Registry ->**Notes:** +> **Notes:** > [Introduced][ce-4040] in GitLab 8.8. -- Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker - versions earlier than 1.10. -- This document is about the user guide. To learn how to enable GitLab Container - Registry across your GitLab instance, visit the - [administrator documentation](../../administration/container_registry.md). -- Starting from GitLab 8.12, if you have 2FA enabled in your account, you need - to pass a [personal access token][pat] instead of your password in order to - login to GitLab's Container Registry. -- Multiple level image names support was added in GitLab 9.1 +> - Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker +> versions earlier than 1.10. +> - This document is about the user guide. To learn how to enable GitLab Container +> Registry across your GitLab instance, visit the +> [administrator documentation](../../administration/container_registry.md). +> - Starting from GitLab 8.12, if you have 2FA enabled in your account, you need +> to pass a [personal access token][pat] instead of your password in order to +> login to GitLab's Container Registry. +> - Multiple level image names support was added in GitLab 9.1 With the Docker Container Registry integrated into GitLab, every project can have its own space to store its Docker images. @@ -27,7 +27,7 @@ to enable it. 1. First, ask your system administrator to enable GitLab Container Registry following the [administration documentation](../../administration/container_registry.md). If you are using GitLab.com, this is enabled by default so you can start using - the Registry immediately. Currently there is a soft (10GB) size restriction for + the Registry immediately. Currently there is a soft (10GB) size restriction for registry on GitLab.com, as part of the [repository size limit](repository/index.html#repository-size). 1. Go to your [project's General settings](settings/index.md#sharing-and-permissions) and enable the **Container Registry** feature on your project. For new @@ -40,12 +40,12 @@ to enable it. ## Build and push images ->**Notes:** -- Moving or renaming existing container registry repositories is not supported -once you have pushed images because the images are signed, and the -signature includes the repository name. -- To move or rename a repository with a container registry you will have to -delete all existing images. +> **Notes:** +> - Moving or renaming existing container registry repositories is not supported +> once you have pushed images because the images are signed, and the +> signature includes the repository name. +> - To move or rename a repository with a container registry you will have to +> delete all existing images. If you visit the **Registry** link under your project's menu, you can see the @@ -216,7 +216,7 @@ needs to trust the mitmproxy SSL certificates for this to work. The following installation instructions assume you are running Ubuntu: -1. Install mitmproxy (see http://docs.mitmproxy.org/en/stable/install.html) +1. [Install mitmproxy](https://docs.mitmproxy.org/stable/overview-installation/). 1. Run `mitmproxy --port 9000` to generate its certificates. Enter <kbd>CTRL</kbd>-<kbd>C</kbd> to quit. 1. Install the certificate from `~/.mitmproxy` to your system: @@ -245,7 +245,7 @@ This will run mitmproxy on port `9000`. In another window, run: curl --proxy http://localhost:9000 https://httpbin.org/status/200 ``` -If everything is setup correctly, you will see information on the mitmproxy window and +If everything is set up correctly, you will see information on the mitmproxy window and no errors from the curl commands. #### Running the Docker daemon with a proxy @@ -293,4 +293,4 @@ Once the right permissions were set, the error will go away. [docker-docs]: https://docs.docker.com/engine/userguide/intro/ [pat]: ../profile/personal_access_tokens.md [pdt]: ../project/deploy_tokens/index.md -[reconfigure]: ../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure
\ No newline at end of file +[reconfigure]: ../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md index 8f6b530c033..ea843054f8e 100644 --- a/doc/user/project/cycle_analytics.md +++ b/doc/user/project/cycle_analytics.md @@ -72,7 +72,7 @@ Here's a little explanation of how this works behind the scenes: `<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 +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, @@ -154,7 +154,7 @@ You can [read more about permissions][permissions] in general. Learn more about Cycle Analytics in the following resources: -- [Cycle Analytics feature page](https://about.gitlab.com/solutions/cycle-analytics/) +- [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/) diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 0b9b49f326f..ff647b2f0a2 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -51,7 +51,7 @@ To download a repository using a Deploy Token, you just need to: ```bash -git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git +git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git ``` Just replace `<username>` and `<deploy_token>` with the proper values diff --git a/doc/user/project/img/issue_board_milestone_lists.png b/doc/user/project/img/issue_board_milestone_lists.png Binary files differnew file mode 100644 index 00000000000..91926f58f87 --- /dev/null +++ b/doc/user/project/img/issue_board_milestone_lists.png diff --git a/doc/user/project/img/issue_board_summed_weights.png b/doc/user/project/img/issue_board_summed_weights.png Binary files differnew file mode 100644 index 00000000000..2288d767d8c --- /dev/null +++ b/doc/user/project/img/issue_board_summed_weights.png diff --git a/doc/user/project/img/issue_boards_core.png b/doc/user/project/img/issue_boards_core.png Binary files differnew file mode 100755 index 00000000000..9e819160861 --- /dev/null +++ b/doc/user/project/img/issue_boards_core.png diff --git a/doc/user/project/img/issue_boards_premium.png b/doc/user/project/img/issue_boards_premium.png Binary files differnew file mode 100755 index 00000000000..bd9164b2961 --- /dev/null +++ b/doc/user/project/img/issue_boards_premium.png diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index 7a3628a39d7..a5923986292 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -8,7 +8,7 @@ between the two, for more information consult your favorite search engine. There are two approaches to SVN to Git migration: -1. [Git/SVN Mirror](#smooth-migration-with-a-gitsvn-mirror-using-subgit) which: +1. [Git/SVN Mirror](#smooth-migration-with-a-git-svn-mirror-using-subgit) which: - Makes the GitLab repository to mirror the SVN project. - Git and SVN repositories are kept in sync; you can use either one. - Smoothens the migration process and allows to manage migration risks. @@ -29,7 +29,7 @@ directly in a filesystem level. 1. Install Oracle JRE 1.8 or newer. On Debian-based Linux distributions you can follow [this article](http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html). -1. Download SubGit from https://subgit.com/download/. +1. Download SubGit from <https://subgit.com/download/>. 1. Unpack the downloaded SubGit zip archive to the `/opt` directory. The `subgit` command will be available at `/opt/subgit-VERSION/bin/subgit`. @@ -71,7 +71,7 @@ edit $GIT_REPO_PATH/subgit/config ``` For more information regarding the SubGit configuration options, refer to -[SubGit's documentation](https://subgit.com/documentation.html) website. +[SubGit's documentation](https://subgit.com/documentation/) website. ### Initial translation @@ -97,7 +97,7 @@ subgit import $GIT_REPO_PATH ### SubGit licensing Running SubGit in a mirror mode requires a -[registration](https://subgit.com/pricing.html). Registration is free for open +[registration](https://subgit.com/pricing/). Registration is free for open source, academic and startup projects. We're currently working on deeper GitLab/SubGit integration. You may track our @@ -179,5 +179,6 @@ git push --tags origin ``` ## Contribute to this guide + We welcome all contributions that would expand this guide with instructions on how to migrate from SVN and other version control systems. diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 9b18eb15599..70c0d434f1f 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -57,6 +57,6 @@ 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:** +> - Starting with GitLab 8.14.0, builds are triggered on push events. diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 47525617d95..20a71da927c 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -15,7 +15,7 @@ See also [the Hangouts Chat documentation for configuring incoming webhooks](htt ## On GitLab -When you have the **Webhook URL** for your Hangouts Chat room webhook, you can setup the GitLab service. +When you have the **Webhook URL** for your Hangouts Chat room webhook, you can set up the GitLab service. 1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services) in your project's settings, i.e. **Project > Settings > Integrations**. 1. Select the **Hangouts Chat** project service to configure it. diff --git a/doc/user/project/integrations/img/webhooks_ssl.png b/doc/user/project/integrations/img/webhooks_ssl.png Binary files differindex f023e9665f2..e5777a2e99b 100644 --- a/doc/user/project/integrations/img/webhooks_ssl.png +++ b/doc/user/project/integrations/img/webhooks_ssl.png diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 67c543e00fb..30f49fefc41 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -1,123 +1,129 @@ -# GitLab JIRA integration +# GitLab Jira integration -GitLab can be configured to interact with [JIRA], a project management platform. +GitLab Issues are a powerful tool for discussing ideas and planning and tracking work. +However, many organizations have been using Jira for these purposes and have +extensive data and business processes built into it. -Once your GitLab project is connected to JIRA, you can reference and close the -issues in JIRA directly from GitLab. +While you can always migrate content and process from Jira to GitLab Issues, +you can also opt to continue using Jira and use it together with GitLab through +our integration. -For a use case, check out this article of [How and why to integrate GitLab with -JIRA](https://www.programmableweb.com/news/how-and-why-to-integrate-gitlab-jira/how-to/2017/04/25). +Once you integrate your GitLab project with your Jira instance, you can automatically +detect and cross-reference activity between the GitLab project and any of your projects +in Jira. This includes the ability to close or transition Jira issues when the work +is completed in GitLab. + +Here's how the integration responds when you take the following actions in GitLab: + +- **Mention a Jira issue ID** in a commit message or MR (merge request). + - GitLab hyperlinks to the Jira issue. + - The Jira issue adds an issue link to the commit/MR in GitLab. + - The Jira issue adds a comment reflecting the comment made in GitLab, the comment author, and a link to the commit/MR in GitLab. +- **Mention that a commit or MR 'closes', 'resolves', or 'fixes' a Jira issue ID**. When the commit is made on master or the change is merged to master: + - GitLab's merge request page displays a note that it "Closed" the Jira issue, with a link to the issue. (Note: Before the merge, an MR will display that it "Closes" the Jira issue.) + - The Jira issue shows the activity and the Jira issue is closed, or otherwise transitioned. + +You can also use [Jira's Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-298976812.html) +directly from GitLab, as covered in the article +[How and why to integrate GitLab with Jira](https://www.programmableweb.com/news/how-and-why-to-integrate-gitlab-Jira/how-to/2017/04/25). ## Configuration -Each GitLab project can be configured to connect to a different JIRA instance. That -means one GitLab project maps to _all_ JIRA projects in that JIRA instance once -the configuration is set up. Therefore, you don't have to explicitly associate -one GitLab project to any JIRA project. Once the configuration is set up, any JIRA -projects in the JIRA instance are already mapped to the GitLab project. +Each GitLab project can be configured to connect to an entire Jira instance. That +means one GitLab project can interact with _all_ Jira projects in that instance, once +configured. Therefore, you will not have to explicitly associate +a GitLab project with any single Jira project. -If you have one JIRA instance you can pre-fill the settings page with a default -template, see the [Services Templates][services-templates] docs. +If you have one Jira instance, you can pre-fill the settings page with a default +template. See the [Services Templates][services-templates] docs. -Configuration happens via user name and password. Connecting to a JIRA server +Configuration happens via user name and password. Connecting to a Jira server via CAS is not possible. -In order to enable the JIRA service in GitLab, you need to first configure the -project in JIRA and then enter the correct values in GitLab. +In order to enable the Jira service in GitLab, you need to first configure the +project in Jira and then enter the correct values in GitLab. -### Configuring JIRA +### Configuring Jira -We need to create a user in JIRA which will have access to all projects that -need to integrate with GitLab. Login to your JIRA instance as admin and under -Administration go to User Management and create a new user. +We need to create a user in Jira which will have access to all projects that +need to integrate with GitLab. Login to your Jira instance as admin and under +*Administration*, go to *User Management* and create a new user. -As an example, we'll create a user named `gitlab` and add it to `JIRA-developers` +As an example, we'll create a user named `gitlab` and add it to the `Jira-developers` group. -**It is important that the user `GitLab` has write-access to projects in JIRA** +**It is important that the user `gitlab` has 'write' access to projects in Jira** We have split this stage in steps so it is easier to follow. ---- - -1. Login to your JIRA instance as an administrator and under **Administration** +1. Log in to your Jira instance as an administrator and under **Administration** go to **User Management** to create a new user. -  - - --- +  1. The next step is to create a new user (e.g., `gitlab`) who has write access - to projects in JIRA. Enter the user's name and a _valid_ e-mail address - since JIRA sends a verification e-mail to set-up the password. - _**Note:** JIRA creates the username automatically by using the e-mail - prefix. You can change it later if you want._ + to projects in Jira. Enter the user's name and a _valid_ e-mail address + since Jira sends a verification e-mail to set up the password. + _**Note:** Jira creates the username automatically by using the e-mail + prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You will need to create + an HTTP basic authentication password. You can do this by visiting the user + profile, looking up the username, and setting a password._ -  - - --- +  1. Now, let's create a `gitlab-developers` group which will have write access - to projects in JIRA. Go to the **Groups** tab and select **Create group**. - -  - - --- - - Give it an optional description and hit **Create group**. + to projects in Jira. Go to the **Groups** tab and select **Create group**. -  +  - --- + Give it an optional description and click **Create group**. -1. Give the newly-created group write access by going to - **Application access ➔ View configuration** and adding the `gitlab-developers` - group to JIRA Core. +  -  +1. To give the newly-created group 'write' access, go to + **Application access ➔ View configuration** and add the `gitlab-developers` + group to Jira Core. - --- +  1. Add the `gitlab` user to the `gitlab-developers` group by going to **Users ➔ GitLab user ➔ Add group** and selecting the `gitlab-developers` - group from the dropdown menu. Notice that the group says _Access_ which is - what we aim for. + group from the dropdown menu. Notice that the group says _Access_, which is + intended as part of this process. -  +  - --- - -The JIRA configuration is over. Write down the new JIRA username and its +The Jira configuration is complete. Write down the new Jira username and its password as they will be needed when configuring GitLab in the next section. ### Configuring GitLab ->**Notes:** -- The currently supported JIRA versions are `v6.x` and `v7.x.`. GitLab 7.8 or - higher is required. -- GitLab 8.14 introduced a new way to integrate with JIRA which greatly simplified - the configuration options you have to enter. If you are using an older version, - [follow this documentation][jira-repo-old-docs]. -- In order to support Oracle's Access Manager, GitLab will send additional cookies - to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with - a value of `fromDialog`. - -To enable JIRA integration in a project, navigate to the +> **Notes:** +> - The currently supported Jira versions are `v6.x` and `v7.x.`. GitLab 7.8 or +> higher is required. +> - GitLab 8.14 introduced a new way to integrate with Jira which greatly simplified +> the configuration options you have to enter. If you are using an older version, +> [follow this documentation][jira-repo-old-docs]. +> - In order to support Oracle's Access Manager, GitLab will send additional cookies +> to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with +> a value of `fromDialog`. + +To enable Jira integration in a project, navigate to the [Integrations page](project_services.md#accessing-the-project-services), click -the **JIRA** service, and fill in the required details on the page as described +the **Jira** service, and fill in the required details on the page as described in the table below. | Field | Description | | ----- | ----------- | -| `Web URL` | The base URL to the JIRA instance web interface which is being linked to this GitLab project. E.g., `https://jira.example.com`. | -| `JIRA API URL` | The base URL to the JIRA instance API. Web URL value will be used if not set. E.g., `https://jira-api.example.com`. | -| `Username` | The user name created in [configuring JIRA step](#configuring-jira). Using the email address will cause `401 unauthorized`. | -| `Password` |The password of the user created in [configuring JIRA step](#configuring-jira). | -| `Transition ID` | This is the ID of a transition that moves issues to the desired state. It is possible to insert transition ids separated by `,` or `;` which means the issue will be moved to each state after another using the given order. **Closing JIRA issues via commits or Merge Requests won't work if you don't set the ID correctly.** | +| `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. E.g., `https://Jira.example.com`. | +| `Jira API URL` | The base URL to the Jira instance API. Web URL value will be used if not set. E.g., `https://jira-api.example.com`. | +| `Username` | The user name created in [configuring Jira step](#configuring-jira). Using the email address will cause `401 unauthorized`. | +| `Password` |The password of the user created in [configuring Jira step](#configuring-jira). | +| `Transition ID` | This is the ID of a transition that moves issues to the desired state. It is possible to insert transition ids separated by `,` or `;` which means the issue will be moved to each state after another using the given order. **Closing Jira issues via commits or Merge Requests won't work if you don't set the ID correctly.** | -### Getting a transition ID +### Obtaining a transition ID -In the most recent JIRA UI, you can no longer see transition IDs in the workflow +In the most recent Jira user interface, you can no longer see transition IDs in the workflow administration UI. You can get the ID you need in either of the following ways: 1. By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions` @@ -129,25 +135,23 @@ Note that the transition ID may vary between workflows (e.g., bug vs. story), 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. - - +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 +## Jira issues -By now you should have [configured JIRA](#configuring-jira) and enabled the -[JIRA service in GitLab](#configuring-gitlab). If everything is set up correctly -you should be able to reference and close JIRA issues by just mentioning their +By now you should have [configured Jira](#configuring-jira) and enabled the +[Jira service in GitLab](#configuring-gitlab). If everything is set up correctly +you should be able to reference and close Jira issues by just mentioning their ID in GitLab commits and merge requests. -### Referencing JIRA Issues +### Referencing Jira Issues -When GitLab project has JIRA issue tracker configured and enabled, mentioning -JIRA issue in GitLab will automatically add a comment in JIRA issue with the +When GitLab project has Jira issue tracker configured and enabled, mentioning +Jira issue in GitLab will automatically add a comment in Jira issue with the link back to GitLab. This means that in comments in merge requests and commits -referencing an issue, e.g., `PROJECT-7`, will add a comment in JIRA issue in the +referencing an issue, e.g., `PROJECT-7`, will add a comment in Jira issue in the format: ``` @@ -156,21 +160,19 @@ ENTITY_TITLE ``` * `USER` A user that mentioned the issue. This is the link to the user profile in GitLab. -* `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where JIRA issue was mentioned. +* `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where Jira issue was mentioned. * `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request. * `PROJECT_NAME` GitLab project name. * `ENTITY_TITLE` Merge request title or commit message first line. - + ---- +### Closing Jira Issues -### Closing JIRA Issues - -JIRA issues can be closed directly from GitLab by using trigger words in +Jira issues can be closed directly from GitLab by using trigger words in commits and merge requests. When a commit which contains the trigger word -followed by the JIRA issue ID in the commit message is pushed, GitLab will -add a comment in the mentioned JIRA issue and immediately close it (provided +followed by the Jira issue ID in the commit message is pushed, GitLab will +add a comment in the mentioned Jira issue and immediately close it (provided the transition ID was set up correctly). There are currently three trigger words, and you can use either one to achieve @@ -180,66 +182,66 @@ the same goal: - `Closes PROJECT-1` - `Fixes PROJECT-1` -where `PROJECT-1` is the issue ID of the JIRA project. +where `PROJECT-1` is the issue ID of the Jira project. ->**Note:** -- Only commits and merges into the project's default branch (usually **master**) will - close an issue in Jira. You can change your projects default branch under - [project settings](img/jira_project_settings.png). -- The JIRA issue will not be transitioned if it has a resolution. +> **Notes:** +> - Only commits and merges into the project's default branch (usually **master**) will +> close an issue in Jira. You can change your projects default branch under +> [project settings](img/jira_project_settings.png). +> - The Jira issue will not be transitioned if it has a resolution. -### JIRA issue closing example +### Jira issue closing example Let's consider the following example: -1. For the project named `PROJECT` in JIRA, we implemented a new feature +1. For the project named `PROJECT` in Jira, we implemented a new feature and created a merge request in GitLab. -1. This feature was requested in JIRA issue `PROJECT-7` and the merge request +1. This feature was requested in Jira issue `PROJECT-7` and the merge request in GitLab contains the improvement 1. In the merge request description we use the issue closing trigger `Closes PROJECT-7`. -1. Once the merge request is merged, the JIRA issue will be automatically closed +1. Once the merge request is merged, the Jira issue will be automatically closed with a comment and an associated link to the commit that resolved the issue. ---- - -In the following screenshot you can see what the link references to the JIRA +In the following screenshot you can see what the link references to the Jira issue look like. - + ---- - -Once this merge request is merged, the JIRA issue will be automatically closed +Once this merge request is merged, the Jira issue will be automatically closed with a link to the commit that resolved the issue. - - ---- + - + ## Troubleshooting -If things don't work as expected that's usually because you have configured -incorrectly the JIRA-GitLab integration. +If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured. + +### GitLab is unable to comment on a Jira issue + +Make sure that the Jira user you set up for the integration has the +correct access permission to post comments on a Jira issue and also to transition +the issue, if you'd like GitLab to also be able to do so. +Jira issue references and update comments will not work if the GitLab issue tracker is disabled. -### GitLab is unable to comment on a ticket +### GitLab is unable to close a Jira issue -Make sure that the user you set up for GitLab to communicate with JIRA has the -correct access permission to post comments on a ticket and to also transition -the ticket, if you'd like GitLab to also take care of closing them. -JIRA issue references and update comments will not work if the GitLab issue tracker is disabled. +Make sure the `Transition ID` you set within the Jira settings matches the one +your project needs to close an issue. -### GitLab is unable to close a ticket +Make sure that the Jira issue is not already marked as resolved; that is, +the Jira issue resolution field is not set. (It should not be struck through in +Jira lists.) -Make sure the `Transition ID` you set within the JIRA settings matches the one -your project needs to close a ticket. +### CAPTCHA -Make sure that the JIRA issue is not already marked as resolved, in other words that -the JIRA issue resolution field is not set. (It should not be struck through in -JIRA lists.) +CAPTCHA may be triggered after several consecutive failed login attempts +which may lead to a `401 unauthorized` error when testing your Jira integration. +If CAPTCHA has been triggered, you will not be able to use Jira's REST API to +authenticate with the Jira site. You will need to log in to your Jira instance +and complete the CAPTCHA. [services-templates]: services_templates.md [jira-repo-old-docs]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-13-stable/doc/project_services/jira.md -[jira]: https://www.atlassian.com/software/jira diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 3e77823a6aa..89de1fe4dcb 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -38,7 +38,7 @@ At the end, fill in your Mattermost details: | Field | Description | | ----- | ----------- | -| **Webhook** | The incoming webhook URL which you have to setup on Mattermost, it will be something like: http://mattermost.example/hooks/5xo… | +| **Webhook** | The incoming webhook URL which you have to set up on Mattermost, it will be something like: http://mattermost.example/hooks/5xo… | | **Username** | Optional username which can be on messages sent to Mattermost. Fill this in if you want to change the username of the bot. | | **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 488f61c77a3..e031dcad2c3 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -102,7 +102,7 @@ in a new slash command.  -1. After you setup all the values, copy the token (we will use it below) and +1. After you set up all the values, copy the token (we will use it below) and click **Done**.  diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 140c6738a49..ca32689910c 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -25,7 +25,7 @@ At the end fill in your Microsoft Teams details: | Field | Description | | ----- | ----------- | -| **Webhook** | The incoming webhook URL which you have to setup on Microsoft Teams. | +| **Webhook** | The incoming webhook URL which you have to set up on Microsoft Teams. | | **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | After you are all done, click **Save changes** for the changes to take effect. diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 6aefe5dbded..8b1908c46fe 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -2,7 +2,7 @@ **NB: This service is only listed if you are in a development environment!** -To setup the mock CI service server, respond to the following endpoints +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'] }` diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index f687027e8c8..0b61a41aab0 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -8,7 +8,7 @@ within the GitLab interface.  -There are two ways to setup Prometheus integration, depending on where your apps are running: +There are two ways to set up Prometheus integration, depending on where your apps are running: * For deployments on Kubernetes, GitLab can automatically [deploy and manage Prometheus](#managed-prometheus-on-kubernetes) * For other deployment targets, simply [specify the Prometheus server](#manual-configuration-of-prometheus). diff --git a/doc/user/project/integrations/prometheus_library/metrics.md b/doc/user/project/integrations/prometheus_library/metrics.md index 96a22316265..ec16902fcc8 100644 --- a/doc/user/project/integrations/prometheus_library/metrics.md +++ b/doc/user/project/integrations/prometheus_library/metrics.md @@ -17,9 +17,3 @@ GitLab retrieves performance data from the configured Prometheus server, and att In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do that, GitLab uses the defined queries and fills in the environment specific variables. Typically this involves looking for the [$CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-variables-environment-variables), but may also include other information such as the project's Kubernetes namespace. Each search query is defined in the [exporter specific documentation](#prometheus-metrics-library). - -## Adding to the library - -We strive to support the 2-4 most important metrics for each common system service that supports Prometheus. If you are looking for support for a particular exporter which has not yet been added to the library, additions can be made [to the `additional_metrics.yml`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/prometheus/additional_metrics.yml) file. - -> Note: The library is only for monitoring public, common, system services which all customers can benefit from. Support for monitoring [customer proprietary metrics](https://gitlab.com/gitlab-org/gitlab-ee/issues/2273) will be added in a subsequent release. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 770b1810da1..7d12cd8f7c2 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1,21 +1,21 @@ # Webhooks ->**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 - ->**Note:** -Starting from GitLab 11.1, the logs of web hooks are automatically removed after -one month. - ->**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 - [image URL rewriting](#image-url-rewriting) for more details. +> **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 +> +> **Note:** +> Starting from GitLab 11.1, the logs of web hooks are automatically removed after +> one month. +> +> **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 +> [image URL rewriting](#image-url-rewriting) for more details. Project webhooks allow you to trigger a URL if for example new code is pushed or a new issue is created. You can configure webhooks to listen for specific events @@ -57,6 +57,14 @@ You can turn this off in the webhook settings in your GitLab projects.  +## Branch filtering + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/20338) in GitLab 11.3. + +Push events can be filtered by branch using a branch name or wildcard pattern +to limit which push events are sent to your webhook endpoint. By default the +field is blank causing all push events to be sent to your webhook endpoint. + ## Events Below are described the supported events. @@ -65,8 +73,8 @@ 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` web hook - attribute will only contain the first 20 for performance reasons. Loading +> **Note:** When more than 20 commits are pushed at once, the `commits` web hook + 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. @@ -320,7 +328,7 @@ X-Gitlab-Event: Issue Hook } ``` -**Note**: `assignee` and `assignee_id` keys are deprecated and now show the first assignee only. +> **Note**: `assignee` and `assignee_id` keys are deprecated and now show the first assignee only. ### Comment events @@ -619,7 +627,7 @@ X-Gitlab-Event: Note Hook } ``` -**Note**: `assignee_id` field is deprecated and now shows the first assignee only. +> **Note**: `assignee_id` field is deprecated and now shows the first assignee only. #### Comment on code snippet @@ -935,7 +943,13 @@ X-Gitlab-Event: Pipeline Hook ], "created_at": "2016-08-12 15:23:28 UTC", "finished_at": "2016-08-12 15:26:29 UTC", - "duration": 63 + "duration": 63, + "variables": [ + { + "key": "NESTOR_PROD_ENVIRONMENT", + "value": "us-west-1" + } + ] }, "user":{ "name": "Administrator", @@ -1162,7 +1176,7 @@ You can trigger the webhook manually. Sample data from the project will be used. ## Troubleshoot webhooks -Gitlab stores each perform of the webhook. +GitLab stores each perform of the webhook. You can find records for last 2 days in "Recent Deliveries" section on the edit page of each webhook.  @@ -1174,7 +1188,7 @@ On this page, you can see data that GitLab sends (request headers and body) and From this page, you can repeat delivery with the same data by clicking `Resend Request` button. ->**Note:** If URL or secret token of the webhook were updated, data will be delivered to the new address. +> **Note:** If URL or secret token of the webhook were updated, data will be delivered to the new address. ### Receiving duplicate or multiple web hook requests triggered by one event diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 0e847be79c2..464fa5987c1 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -2,13 +2,44 @@ > [Introduced][ce-5554] in [GitLab 8.11](https://about.gitlab.com/2016/08/22/gitlab-8-11-released/#issue-board). +## Overview + The GitLab Issue Board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. It can be used as a [Kanban] or a [Scrum] board. - +It provides perfect pairing between issue tracking and project management, +keeping everything in the same place, so that you don't need to jump +between different platforms to organize your workflow. -## Overview +With GitLab Issue Boards, you organize your issues in lists that correspond to +their assigned labels, visualizing issues designed as cards throughout that 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 +you're ready, you can drag and drop your issue cards from one step to the next. + + + +**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +Watch a [video presentation](https://youtu.be/UWsJ8tkHAa8) of +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) 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) and +[milestones](#milestone-lists). **[PREMIUM]** + +Check all the [advanced features of Issue Boards](#gitlab-enterprise-features-for-issue-boards) +below. + + + +## How it works The Issue Board builds on GitLab's existing [issue tracking functionality](issues/index.md#issue-tracker) and @@ -28,15 +59,12 @@ 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 [GitLab Enterprise Edition](#features-per-tier), +only in [different tiers of GitLab Enterprise Edition](#gitlab-enterprise-features-for-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 multiple Issue Boards within the same project. -For a visual overview, see our [Issue Board feature page](https://about.gitlab.com/features/issueboard/) -on about.gitlab.com or our [video introduction to Issue Boards](https://www.youtube.com/watch?v=UWsJ8tkHAa8). - ## Use cases There are many ways to use GitLab Issue Boards tailored to your own preferred workflow. @@ -111,11 +139,6 @@ to improve their workflow with multiple boards. Create lists for each of your team members and quickly drag-and-drop issues onto each team member. -## Permissions - -[Developers and up](../permissions.md) can use all the functionality of the -Issue Board, that is, create or delete lists and drag issues from one list to another. - ## Issue Board terminology - **Issue Board** - Each board represents a unique view for your issues. It can have multiple lists with each list consisting of issues represented by cards. @@ -126,6 +149,139 @@ Issue Board, that is, create or delete lists and drag issues from one list to an - **Closed** (default): shows all closed issues. Always appears as the rightmost list. - **Card** - A box in the list that represents an individual issue. The information you can see on a card consists of the issue number, the issue title, the assignee, and the labels associated with the issue. You can drag cards from one list to another to change their label or assignee from that of the source list to that of the destination list. +## Permissions + +[Developers and up](../permissions.md) can use all the functionality of the +Issue Board, that is, create or delete lists and drag issues from one list to another. + +## GitLab Enterprise features for Issue Boards + +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. + +For a collection of [features per tier](#summary-of-features-per-tier), check the summary below. + +### Multiple Issue Boards **[STARTER]** + +> 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, 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 +or in situations where a repository is used to host the code of multiple +products. + +Clicking on the current board name in the upper left corner will reveal a +menu from where you can create another Issue Board and rename or delete the +existing one. + +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). + +An Issue Board can be associated with a GitLab [Milestone](milestones/index.md#milestones), +[Labels](labels.md), Assignee and Weight +which will automatically filter the Board issues according to these fields. +This allows you to create unique boards according to your team's need. + + + +You can define the scope of your board when creating it or by clicking on the "Edit board" button. Once a milestone, assignee or weight is assigned to an Issue Board, you will no longer be able to filter +through these in the search bar. In order to do that, you need to remove the desired scope (e.g. milestone, assignee or weight) from the Issue Board. + + + +If you don't have editing permission in a board, you're still able to see the configuration by clicking on "View scope". + + + +### Focus mode **[STARTER]** + +> Introduced in [GitLab Starter 9.1](https://about.gitlab.com/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep). + +Click the button at the top right to toggle focus mode on and off. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. + + + +### Sum of Issue Weights **[STARTER]** + +The top of each list indicates the sum of issue weights for the issues that +belong to that list. This is useful when using boards for capacity allocation, +especially in combination with [assignee lists](#assignee-lists). + + + +### Group Issue Boards **[PREMIUM]** + +> Introduced in [GitLab Premium 10.0](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards). + +Accessible at the group navigation level, a group issue board offers the same features as a project-level board, +but it can display issues from all projects in that +group and its descendant subgroups. Similarly, you can only filter by group labels for these +boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only +group-level objects are available. + +NOTE: **Note:** +Multiple group issue boards were originally introduced in [GitLab 10.0 Premium](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards) and +one group issue board per group was made available in GitLab 10.6 Core. + + + +### Assignee lists **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5784) in GitLab 11.0 Premium. + +Like a regular list that shows all issues that have the list label, you can add +an assignee list that shows all issues assigned to the given user. +You can have a board with both label lists and assignee lists. To add an +assignee list: + +1. Click **Add list**. +1. Select the **Assignee list** tab. +1. Search and click on the user you want to add as an assignee. + +Now that the assignee list is added, you can assign or unassign issues to that user +by [dragging issues](#dragging-issues-between-lists) to and/or from an assignee list. +To remove an assignee list, just as with a label list, click the trash icon. + + + +### Milestone lists **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6469) in GitLab 11.2 Premium. + +As of 11.2, you're also able to create lists of a milestone. As the name states, +these are lists that filter issues by the assigned milestone, giving you more +freedom and visibility on the Issue Board. To do so: + +1. Click **Add list**. +1. Select the **Milestone** tab. +1. Search and click on the milestone. + +Similar to the assignee lists, you're now able to [drag issues](#dragging-issues-between-lists) +to and/or from a milestone list to manipulate the milestone of the dragged issues. +As on another list types, click on the trash icon to remove it. + + + +### Summary of features per tier + +Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: + +| Tier | Number of Project Issue Boards | Number of Group Issue Boards | Configurable Issue Boards | Assignee Lists | +|----------|--------------------------------|------------------------------|---------------------------|----------------| +| Core / Free | 1 | 1 | No | No | +| Starter / Bronze | Multiple | 1 | Yes | No | +| Premium / Silver | Multiple | Multiple | Yes | Yes | +| Ultimate / Gold | Multiple | Multiple | Yes | Yes | + ## Actions you can take on an Issue Board - [Create a new list](#creating-a-new-list). @@ -142,7 +298,7 @@ Issue Board, that is, create or delete lists and drag issues from one list to an If you are not able to perform one or more of the things above, make sure you have the right [permissions](#permissions). -## First time using the Issue Board +### First time using the Issue Board The first time you navigate to your Issue Board, you will be presented with a default list (**Done**) and a welcoming message that gives @@ -157,7 +313,7 @@ which means the system has no way of populating them automatically. That's of course if the predefined labels don't already exist. If any of them does exist, the list will be created and filled with the issues that have that label. -## Creating a new list +### Creating a new list Create a new list by clicking on the **Add list** button at the upper right corner of the Issue Board. @@ -172,7 +328,7 @@ To create a list for a label that doesn't yet exist, simply create the label by choosing **Create new label**. The label will be created on-the-fly and it will be immediately added to the dropdown. You can now choose it to create a list. -## Deleting a list +### Deleting a list To delete a list from the Issue Board use the small trash icon that is present in the list's heading. A confirmation dialog will appear for you to confirm. @@ -180,7 +336,7 @@ in the list's heading. A confirmation dialog will appear for you to confirm. Deleting a list doesn't have any effect in issues and labels, it's just the list view that is removed. You can always add it back later if you need. -## Adding issues to a list +### Adding issues to a list You can add issues to a list by clicking the **Add issues** button that is present in the upper right corner of the Issue Board. This will open up a modal @@ -192,7 +348,7 @@ the list by filtering by author, assignee, milestone and label.  -## Removing an issue from a list +### Removing an issue from a list Removing an issue from a list can be done by clicking on the issue card and then clicking the **Remove from board** button in the sidebar. Under the hood, the @@ -201,7 +357,7 @@ board itself.  -## Issue ordering in a list +### Issue ordering in a list When visiting a board, issues appear ordered in any list. You are able to change that order simply by dragging and dropping the issues. The changed order will be saved @@ -224,7 +380,7 @@ a given board inside your GitLab instance, any time those two issues are subsequ loaded in any board in the same instance (could be a different project board or a different group board, for example), that ordering will be maintained. -## Filtering issues +### Filtering issues You should be able to use the filters on top of your Issue Board to show only the results you want. This is similar to the filtering used in the issue tracker @@ -232,7 +388,7 @@ since the metadata from the issues and labels are re-used in the Issue Board. You can filter by author, assignee, milestone and label. -## Creating workflows +### Creating workflows By reordering your lists, you can create workflows. As lists in Issue Boards are based on labels, it works out of the box with your existing issues. So if you've @@ -267,109 +423,16 @@ to another list the label changes and a system not is recorded.  -## Multiple Issue Boards **[STARTER]** - -> 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, 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 -or in situations where a repository is used to host the code of multiple -products. - -Clicking on the current board name in the upper left corner will reveal a -menu from where you can create another Issue Board and rename or delete the -existing one. - -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). - -An Issue Board can be associated with GitLab [Milestone](milestones/index.md#milestones), -[Labels](labels.md), Assignee and Weight -which will automatically filter the Board issues according to these fields. -This allows you to create unique boards according to your team's need. - - - -You can define the scope of your board when creating it or by clicking on the "Edit board" button. Once a milestone, assignee or weight is assigned to an Issue Board, you will no longer be able to filter -through these in the search bar. In order to do that, you need to remove the desired scope (e.g. milestone, assignee or weight) from the Issue Board. - - - -If you don't have editing permission in a board, you're still able to see the configuration by clicking on "View scope". - - - -## Focus mode **[STARTER]** - -> Introduced in [GitLab Starter 9.1](https://about.gitlab.com/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep). - -Click the button at the top right to toggle focus mode on and off. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. - - - -## Group Issue Boards **[PREMIUM]** - -> Introduced in [GitLab Premium 10.0](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards). - -Accessible at the group navigation level, a group issue board offers the same features as a project-level board, -but it can display issues from all projects in that -group and its descendant subgroups. Similarly, you can only filter by group labels for these -boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only -group-level objects are available. - -NOTE: **Note:** -Multiple group issue boards were originally introduced in [GitLab 10.0 Premium](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards) and -one group issue board per group was made available in GitLab 10.6 Core. - - - -## Assignee lists **[PREMIUM]** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5784) in GitLab 11.0 Premium. - -Like a regular list that shows all issues that have the list label, you can add -an assignee list that shows all issues assigned to the given user. -You can have a board with both label lists and assignee lists. To add an -assignee list: - -1. Click **Add list**. -1. Select the **Assignee list** tab. -1. Search and click on the user you want to add as an assignee. - -Now that the assignee list is added, you can assign or unassign issues to that user -by [dragging issues](#dragging-issues-between-lists) to and/or from an assignee list. -To remove an assignee list, just as with a label list, click the trash icon. - - - -## Dragging issues between lists +### Dragging issues between lists When dragging issues between lists, different behavior occurs depending on the source list and the target list. -| | To Open | To Closed | To label `B` list | To assignee `Bob` list | -| --- | --- | --- | --- | --- | -| From Open | - | Issue closed | `B` added | `Bob` assigned | -| From Closed | Issue reopened | - | Issue reopened<br/>`B` added | Issue reopened<br/>`Bob` assigned | -| From label `A` list | `A` removed | Issue closed | `A` removed<br/>`B` added | `Bob` assigned | -| From assignee `Alice` list | `Alice` unassigned | Issue closed | `B` added | `Alice` unassigned<br/>`Bob` assigned | - -## Features per tier - -Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: - -| Tier | Number of Project Issue Boards | Number of Group Issue Boards | Configurable Issue Boards | Assignee Lists -| --- | --- | --- | --- | --- | --- | -| Core | 1 | 1 | No | No | -| Starter | Multiple | 1 | Yes | No | -| Premium | Multiple | Multiple | Yes | Yes | -| Ultimate | Multiple | Multiple | Yes | Yes | +| | To Open | To Closed | To label `B` list | To assignee `Bob` list | +|----------------------------|--------------------|--------------|------------------------------|---------------------------------------| +| From Open | - | Issue closed | `B` added | `Bob` assigned | +| From Closed | Issue reopened | - | Issue reopened<br/>`B` added | Issue reopened<br/>`Bob` assigned | +| From label `A` list | `A` removed | Issue closed | `A` removed<br/>`B` added | `Bob` assigned | +| From assignee `Alice` list | `Alice` unassigned | Issue closed | `B` added | `Alice` unassigned<br/>`Bob` assigned | ## Tips diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md index b9607243c8a..b6570c777ae 100644 --- a/doc/user/project/issues/automatic_issue_closing.md +++ b/doc/user/project/issues/automatic_issue_closing.md @@ -26,8 +26,10 @@ used: ``` Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's -source code that can match a reference to 1) a local issue (`#123`), -2) a cross-project issue (`group/project#123`) or 3) a link to an issue +source code that can match references to: +1. a local issue (`#123`), +2. a cross-project issue (`group/project#123`) +3. a link to an issue (`https://gitlab.example.com/group/project/issues/123`). --- diff --git a/doc/user/project/issues/issues_functionalities.md b/doc/user/project/issues/issues_functionalities.md index 46f25417fde..631f511b5fa 100644 --- a/doc/user/project/issues/issues_functionalities.md +++ b/doc/user/project/issues/issues_functionalities.md @@ -69,7 +69,7 @@ Learn more on the [Time Tracking documentation](../../../workflow/time_tracking. #### 6. Due date When you work on a tight schedule, and it's important to -have a way to setup a deadline for implementations and for solving +have a way to set up a deadline for implementations and for solving problems. This can be facilitated by the [due date](due_dates.md)). Due dates can be changed as many times as needed. diff --git a/doc/user/project/koding.md b/doc/user/project/koding.md index 86e06a39e59..2c886d7916a 100644 --- a/doc/user/project/koding.md +++ b/doc/user/project/koding.md @@ -1,9 +1,9 @@ # Koding integration ->**Notes:** -- **As of GitLab 10.0, the Koding integration is deprecated and will be removed - in a future version.** -- [Introduced][ce-5909] in GitLab 8.11. +> **Notes:** +> - **As of GitLab 10.0, the Koding integration is deprecated and will be removed +> in a future version.** +> - [Introduced][ce-5909] in GitLab 8.11. This document will guide you through using Koding integration on GitLab in detail. For configuring and installing please follow the diff --git a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png Binary files differnew file mode 100644 index 00000000000..40913718385 --- /dev/null +++ b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 610250ccf12..90500fd9c21 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -1,12 +1,12 @@ # Merge requests versions ->**Notes:** -- [Introduced][ce-5467] in GitLab 8.12. -- Comments are disabled while viewing outdated merge versions or comparing to - versions other than base. -- Merge request versions are based on push not on commit. So, if you pushed 5 - commits in a single push, it will be a single option in the dropdown. If you - pushed 5 times, that will count for 5 options. +> **Notes:** +> - [Introduced][ce-5467] in GitLab 8.12. +> - Comments are disabled while viewing outdated merge versions or comparing to +> versions other than base. +> - Merge request versions are based on push not on commit. So, if you pushed 5 +> commits in a single push, it will be a single option in the dropdown. If you +> pushed 5 times, that will count for 5 options. Every time you push to a branch that is tied to a merge request, a new version of merge request diff is created. When you visit a merge request that contains diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index f01da06fa6e..66ac7740157 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -7,7 +7,7 @@ have been marked a **Work In Progress**.  To mark a merge request a Work In Progress, simply start its title with `[WIP]` -or `WIP:`. As an alternative, you're also able to do it by sending a commit +or `WIP:`. As an alternative, you're also able to do it by sending a commit with its title starting with `wip` or `WIP` to the merge request's source branch.  @@ -15,4 +15,11 @@ with its title starting with `wip` or `WIP` to the merge request's source branch To allow a Work In Progress merge request to be accepted again when it's ready, simply remove the `WIP` prefix. - + + +## Filtering merge requests with WIP Status + +To filter merge requests with the `WIP` status, you can type `wip` +and select the value for your filter from the merge request search input. + + diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 15455a54627..23d5b34504c 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -205,16 +205,16 @@ With the update permission model we also extended the support for accessing 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 - 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 - latest changes in GitLab Runner 1.8 which receives GitLab credentials with - build data. -- Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need - to pass a [personal access token][pat] instead of your password in order to - login to GitLab's Container Registry. +> - 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 +> 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 +> latest changes in GitLab Runner 1.8 which receives GitLab credentials with +> build data. +> - Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need +> to pass a [personal access token][pat] instead of your password in order to +> login to GitLab's Container Registry. Your jobs can access all container images that you would normally have access to. The only implication is that you can push to the Container Registry of the diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index 556bf1db116..b0560c2f44c 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -94,7 +94,7 @@ where you'll find its default URL. > > - GitLab Pages [supports any SSG](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/), but, if you don't find yours among the templates, you'll need -to configure your own `.gitlab-ci.yml`. Do do that, please +to configure your own `.gitlab-ci.yml`. To do that, please read through the article [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md). New SSGs are very welcome among the [example projects](https://gitlab.com/pages). If you set up a new one, please diff --git a/doc/user/project/pages/img/icons/click.png b/doc/user/project/pages/img/icons/click.png Binary files differnew file mode 100644 index 00000000000..daaf760ec08 --- /dev/null +++ b/doc/user/project/pages/img/icons/click.png diff --git a/doc/user/project/pages/img/icons/cogs.png b/doc/user/project/pages/img/icons/cogs.png Binary files differnew file mode 100644 index 00000000000..a12da1b5e8c --- /dev/null +++ b/doc/user/project/pages/img/icons/cogs.png diff --git a/doc/user/project/pages/img/icons/fork.png b/doc/user/project/pages/img/icons/fork.png Binary files differnew file mode 100644 index 00000000000..e2c9577e7ce --- /dev/null +++ b/doc/user/project/pages/img/icons/fork.png diff --git a/doc/user/project/pages/img/icons/free.png b/doc/user/project/pages/img/icons/free.png Binary files differnew file mode 100644 index 00000000000..3b8f8f6863e --- /dev/null +++ b/doc/user/project/pages/img/icons/free.png diff --git a/doc/user/project/pages/img/icons/lock.png b/doc/user/project/pages/img/icons/lock.png Binary files differnew file mode 100644 index 00000000000..1c1f0b4457b --- /dev/null +++ b/doc/user/project/pages/img/icons/lock.png diff --git a/doc/user/project/pages/img/icons/monitor.png b/doc/user/project/pages/img/icons/monitor.png Binary files differnew file mode 100644 index 00000000000..7b99d430eef --- /dev/null +++ b/doc/user/project/pages/img/icons/monitor.png diff --git a/doc/user/project/pages/img/icons/terminal.png b/doc/user/project/pages/img/icons/terminal.png Binary files differnew file mode 100644 index 00000000000..ab5ae11310c --- /dev/null +++ b/doc/user/project/pages/img/icons/terminal.png diff --git a/doc/user/project/pages/img/ssgs_pages.png b/doc/user/project/pages/img/ssgs_pages.png Binary files differnew file mode 100644 index 00000000000..608881c8e31 --- /dev/null +++ b/doc/user/project/pages/img/ssgs_pages.png diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 205f0283107..60144fa1971 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -4,71 +4,180 @@ description: 'Learn how to use GitLab Pages to deploy a static website at no add # GitLab Pages -With GitLab Pages it's easy to publish your project website. GitLab Pages is a hosting service for static websites, at no additional cost. - -## Getting Started - -[Create a project from scratch](getting_started_part_two.md#create-a-project-from-scratch) -to get you started quickly, or, -alternatively, start from an existing project as follows: - -- 1. [Fork](../../../gitlab-basics/fork-project.md#how-to-fork-a-project) an [example project](https://gitlab.com/pages): -by forking a project, you create a copy of the codebase you're forking from to start from a template instead of starting from scratch. -- 2. Change a file to trigger a GitLab CI/CD pipeline: GitLab CI/CD will build and deploy your site to GitLab Pages. -- 3. Visit your project's **Settings > Pages** to see your **website link**, and click on it. Bam! Your website is live! :) - -_Further steps (optional):_ - -- 4. Remove the [fork relationship](getting_started_part_two.md#fork-a-project-to-get-started-from) -(_You don't need the relationship unless you intent to contribute back to the example project you forked from_). -- 5. Make it a [user/group website](getting_started_part_one.md#user-and-group-websites) - -**Watch a video with the steps above: https://www.youtube.com/watch?v=TWqh9MtT4Bg** +**GitLab Pages is a feature that allows you to publish static websites +directly from a repository in GitLab.** + +You can use it either for personal or business websites, such as +portfolios, documentation, manifestos, and business presentations, +and attribute any license to your content. + +<table class="borderless-table center fixed-table"> + <tr> + <td style="width: 22%"><img src="img/icons/cogs.png" alt="SSGs" class="image-noshadow half-width"></td> + <td style="width: 4%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 22%"><img src="img/icons/monitor.png" alt="Websites" class="image-noshadow half-width"></td> + <td style="width: 4%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 22%"><img src="img/icons/free.png" alt="Pages is free" class="image-noshadow half-width"></td> + <td style="width: 4%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 22%"><img src="img/icons/lock.png" alt="Secure your website" class="image-noshadow half-width"></td> + </tr> + <tr> + <td><em>Use any static website generator or plain HTML</em></td> + <td></td> + <td><em>Create websites for your projects, groups, or user account</em></td> + <td></td> + <td><em>Host on GitLab.com for free, or on your own GitLab instance</em></td> + <td></td> + <td><em>Connect your custom domain(s) and TLS certificates</em></td> + </tr> +</table> + +Pages is available for free for all GitLab.com users as well as for self-managed +instances (GitLab Core, Starter, Premium, and Ultimate). + +## Overview + +<div class="row"> +<div class="col-md-9"> +<p style="margin-top: 18px;"> +To publish a website with Pages, you can use any Static Site Generator (SSG), +such as Jekyll, Hugo, Middleman, Harp, Hexo, and Brunch, just to name a few. You can also +publish any website written directly in plain HTML, CSS, and JavaScript.</p> +<p>Pages does <strong>not</strong> support dynamic server-side processing, for instance, as <code>.php</code> and <code>.asp</code> requires. See this article to learn more about +<a href="https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/">static websites vs dynamic websites</a>.</p> +</div> +<div class="col-md-3"><img src="img/ssgs_pages.png" alt="Examples of SSGs supported by Pages" class="image-noshadow middle display-block"></div> +</div> + +### Availability + +If you're using GitLab.com, your website will be publicly available to the internet. +If you're using self-managed instances (Core, Starter, Premium, or Ultimate), +your websites will be published on your own server, according to the +[Pages admin settings](../../../administration/pages/index.md) chosen by your sysdamin, +who can opt for making them public or internal to your server. + +### How it works + +To use GitLab Pages, first you need to create a project in GitLab to upload your website's +files to. These projects can be either public, internal, or private, at your own choice. +GitLab will always deploy your website from a very specific folder called `public` in your +repository. Note that when you create a new project in GitLab, a [repository](../repository/index.md) +becomes available automatically. + +To deploy your site, GitLab will use its built-in tool called [GitLab CI/CD](../../../ci/README.md), +that will build your site and publish it to the GitLab Pages server. The sequence of +scripts that GitLab CI/CD runs to accomplish this task is created from a file named +`.gitlab-ci.yml`, which you can [create and modify](getting_started_part_four.md) at will. + +You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-domain), +`*.gitlab.io`, or your own domain (`example.com`). In that case, you'll +need admin access to your domain's registrar (or control panel) to set it up with Pages. + +Optionally, when adding your own domain, you can add an SSL/TLS certificate to secure your +site under the HTTPS protocol. + +## Getting started + +To get started with GitLab Pages, you can either [create a project from scratch](getting_started_part_two.md#create-a-project-from-scratch) +or quickly start from copying an existing example project, as follows: + +1. Choose an [example project](https://gitlab.com/pages) to [fork](../../../gitlab-basics/fork-project.md#how-to-fork-a-project): + by forking a project, you create a copy of the codebase you're forking from to start from a template instead of starting from scratch. +1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** and click +**Run pipeline** so that GitLab CI/CD will 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**. + +<table class="borderless-table center fixed-table middle width-80"> + <tr> + <td style="width: 30%"><img src="img/icons/fork.png" alt="Fork" class="image-noshadow half-width"></td> + <td style="width: 10%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 30%"><img src="img/icons/terminal.png" alt="Deploy" class="image-noshadow half-width"></td> + <td style="width: 10%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 30%"><img src="img/icons/click.png" alt="Visit" class="image-noshadow half-width"></td> + </tr> + <tr> + <td><em>Fork an example project</em></td> + <td></td> + <td><em>Deploy your website</em></td> + <td></td> + <td><em>Visit your website's URL</em></td> + </tr> +</table> + +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. + +You can also take some optional further steps: + +- Remove the [fork relationship](getting_started_part_two.md#fork-a-project-to-get-started-from) + (_You don't need the relationship unless you intent to contribute back to the example project you forked from_). +- Make it a [user/group website](getting_started_part_one.md#user-and-group-websites) + +**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) with all the steps above!** _Advanced options:_ - [Use a custom domain](getting_started_part_three.md#adding-your-custom-domain-to-gitlab-pages) - Apply [SSL/TLS certification](getting_started_part_three.md#ssl-tls-certificates) to your custom domain -## How Does It Work? - -With GitLab Pages you can create [static websites](getting_started_part_one.md#what-you-need-to-know-before-getting-started) -for your GitLab projects, groups, or user accounts. - -It supports plain static content, such as HTML, and **all** [static site generators (SSGs)](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/), such as Jekyll, Middleman, Hexo, Hugo, and Pelican. - -Connect as many custom domains as you like and bring your own TLS certificate -to secure them. - -Your files live in a project [repository](../repository/index.md) on GitLab. -[GitLab CI](../../../ci/README.md) picks up those files and makes them available at, typically, -`https://<username>.gitlab.io/<projectname>`. Please read through the docs on -[GitLab Pages domains](getting_started_part_one.md#gitlab-pages-domain) for more info. - ## Explore GitLab Pages -Read the following tutorials to know more about: +To learn more about GitLab Pages, read the following tutorials: - [Static websites and GitLab Pages domains](getting_started_part_one.md): Understand what is a static website, and how GitLab Pages default domains work - [Projects for GitLab Pages and URL structure](getting_started_part_two.md): Forking projects and creating new ones from scratch, understanding URLs structure and baseurls -- [GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md): How to add custom domains and subdomains to your website, configure DNS records, and SSL/TLS certificates +- [GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md): How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates - [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md): Understand how to create your own `.gitlab-ci.yml` for your site - [Technical aspects, custom 404 pages, limitations](introduction.md) -- [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/) (outdated) -_Blog posts series about Static Site Generators (SSGs):_ +### GitLab Pages with Static Site Generators (SSGs) + +To understand more about SSGs, their advantages, and how to get the most from them +with Pages, read through this series: - [SSGs part 1: Static vs dynamic websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) - [SSGs part 2: Modern static site generators](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/) - [SSGs part 3: Build any SSG site with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) -_Blog posts for securing GitLab Pages custom domains with SSL/TLS certificates:_ +### GitLab Pages with SSL/TLS certificates + +If you're using GitLab Pages default domain (`.gitlab.io`), your website will be +automatically secure and available under HTTPS. If you're using your own domain, you can +optionally secure it with with SSL/TLS certificates. You can read the following +tutorials to learn how to use these third-party certificates with GitLab Pages: - [CloudFlare](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) -- [Let's Encrypt](https://about.gitlab.com/2016/04/11/tutorial-securing-your-gitlab-pages-with-tls-and-letsencrypt/) (outdated) +- [Let's Encrypt](https://about.gitlab.com/2016/04/11/tutorial-securing-your-gitlab-pages-with-tls-and-letsencrypt/) (mind that although this article is out-of-date, it can still be useful to guide you through the basic steps) ## Advanced use +There are quite some great examples of GitLab Pages websites built for some +specific reasons. These examples can teach you some advanced techniques +to use and adapt to your own needs: + - [Posting to your GitLab Pages blog from iOS](https://about.gitlab.com/2016/08/19/posting-to-your-gitlab-pages-blog-from-ios/) - [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/) - [GitLab CI: Deployment & environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) @@ -80,10 +189,9 @@ _Blog posts for securing GitLab Pages custom domains with SSL/TLS certificates:_ Enable and configure GitLab Pages on your own instance (GitLab Community Edition and Enterprise Editions) with the [admin guide](../../../administration/pages/index.md). -**Watch the video: https://www.youtube.com/watch?v=dD8c7WNcc6s** +**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=dD8c7WNcc6s) for getting started with GitLab Pages admin!** ## More information about GitLab Pages -- For an overview, visit the [feature webpage](https://about.gitlab.com/features/pages/) - Announcement (2016-12-24): ["We're bringing GitLab Pages to CE"](https://about.gitlab.com/2016/12/24/were-bringing-gitlab-pages-to-community-edition/) - Announcement (2017-03-06): ["We are changing the IP of GitLab Pages on GitLab.com"](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index 402989f4508..a8b47558c99 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -1,18 +1,18 @@ # Introduction to job artifacts ->**Notes:** ->- Since GitLab 8.2 and GitLab Runner 0.7.0, job artifacts that are created by - GitLab Runner are uploaded to GitLab and are downloadable as a single archive - (`tar.gz`) using the GitLab UI. ->- Starting with GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format - changed to `ZIP`, and it is now possible to browse its contents, with the added - ability of downloading the files separately. ->- Starting with GitLab 8.17, builds are renamed to jobs. ->- The artifacts browser will be available only for new artifacts that are sent - to GitLab using GitLab Runner version 1.0 and up. It will not be possible to - browse old artifacts already uploaded to GitLab. +> **Notes:** +> - Since GitLab 8.2 and GitLab Runner 0.7.0, job artifacts that are created by +> GitLab Runner are uploaded to GitLab and are downloadable as a single archive +> (`tar.gz`) using the GitLab UI. +> - Starting with GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format +> changed to `ZIP`, and it is now possible to browse its contents, with the added +> ability of downloading the files separately. +> - Starting with GitLab 8.17, builds are renamed to jobs. +> - The artifacts browser will be available only for new artifacts that are sent +> to GitLab using GitLab Runner version 1.0 and up. It will not be possible to +> browse old artifacts already uploaded to GitLab. >- This is the user documentation. For the administration guide see - [administration/job_artifacts](../../../administration/job_artifacts.md). +> [administration/job_artifacts](../../../administration/job_artifacts.md). Artifacts is a list of files and directories which are attached to a job after it completes successfully. This feature is enabled by default in all @@ -46,14 +46,14 @@ For more examples on artifacts, follow the [artifacts reference in ## Browsing artifacts ->**Note:** -With GitLab 9.2, PDFs, images, videos and other formats can be previewed -directly in the job artifacts browser without the need to download them. - ->**Note:** -With [GitLab 10.1][ce-14399], HTML files in a public project can be previewed -directly in a new tab without the need to download them when -[GitLab Pages](../../../administration/pages/index.md) is enabled +> **Note:** +> With GitLab 9.2, PDFs, images, videos and other formats can be previewed +> directly in the job artifacts browser without the need to download them. +> +> **Note:** +> With [GitLab 10.1][ce-14399], HTML files in a public project can be previewed +> directly in a new tab without the need to download them when +> [GitLab Pages](../../../administration/pages/index.md) is enabled After a job finishes, if you visit the job's specific page, there are three buttons. You can download the artifacts archive or browse its contents, whereas @@ -151,6 +151,20 @@ For example: https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/artifacts/master/browse?job=coverage ``` +There is also a URL to specific files, including html files that +are shown in [GitLab Pages](../../../administration/pages/index.md): + +``` +https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/file/<path>?job=<job_name> +``` + +For example, when a job `coverage` creates the artifact `htmlcov/index.html`, +you can access it at: + +``` +https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/artifacts/master/file/htmlcov/index.html?job=coverage +``` + The latest builds are also exposed in the UI in various places. Specifically, look for the download button in: diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md index a13b1b4561c..9daacc37994 100644 --- a/doc/user/project/pipelines/schedules.md +++ b/doc/user/project/pipelines/schedules.md @@ -1,9 +1,9 @@ # Pipeline Schedules > **Notes**: -- This feature was introduced in 9.1 as [Trigger Schedule][ce-10533]. -- In 9.2, the feature was [renamed to Pipeline Schedule][ce-10853]. -- Cron notation is parsed by [Rufus-Scheduler](https://github.com/jmettraux/rufus-scheduler). +> - This feature was introduced in 9.1 as [Trigger Schedule][ce-10533]. +> - In 9.2, the feature was [renamed to Pipeline Schedule][ce-10853]. +> - Cron notation is parsed by [Rufus-Scheduler](https://github.com/jmettraux/rufus-scheduler). Pipeline schedules can be used to run a pipeline at specific intervals, for example every month on the 22nd for a certain branch. @@ -19,7 +19,7 @@ In order to schedule a pipeline:  ->**Attention:** +> **Attention:** The pipelines won't be executed precisely, because schedules are handled by Sidekiq, which runs according to its interval. See [advanced admin configuration](#advanced-admin-configuration) for more @@ -83,7 +83,7 @@ The next time a pipeline is scheduled, your credentials will be used.  ->**Note:** +> **Note:** When the owner of the schedule doesn't have the ability to create pipelines anymore, due to e.g., being blocked or removed from the project, or lacking the permission to run on protected branches or tags. When this happened, the diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index 14f2e522f01..15eacc48dfe 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -157,6 +157,10 @@ into your `README.md`:  ``` +### Environment Variables + +[Environment variables](../../../ci/variables/README.html#variables) can be set in an environment to be available to a runner. + [var]: ../../../ci/yaml/README.md#git-strategy [coverage report]: #test-coverage-parsing [timeout overriding]: ../../../ci/runners/README.html#setting-maximum-job-timeout-for-a-runner diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 3bf63a22963..db706e5020e 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -76,7 +76,7 @@ You can specify a wildcard protected branch, which will protect all branches matching the wildcard. For example: | Wildcard Protected Branch | Matching Branches | -|---------------------------+--------------------------------------------------------| +|---------------------------|--------------------------------------------------------| | `*-stable` | `production-stable`, `staging-stable` | | `production/*` | `production/app-server`, `production/load-balancer` | | `*gitlab*` | `gitlab`, `gitlab/staging`, `master/gitlab/production` | diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index a5eaf2e9835..3d8fff9f733 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -37,7 +37,7 @@ You can specify a wildcard protected tag, which will protect all tags matching the wildcard. For example: | Wildcard Protected Tag | Matching Tags | -|------------------------+-------------------------------| +|------------------------|-------------------------------| | `v*` | `v1.0.0`, `version-9.1` | | `*-deploy` | `march-deploy`, `1.0-deploy` | | `*gitlab*` | `gitlab`, `gitlab/v1` | diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 8fdfd2a6f4d..c2f53540089 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -1,46 +1,83 @@ # GitLab quick actions -Quick actions are textual shortcuts for common actions on issues, merge requests -or commits that are usually done by clicking buttons or dropdowns in GitLab's UI. -You can enter these commands while creating a new issue or merge request, and -in comments. Each command should be on a separate line in order to be properly -detected and executed. The commands are removed from the issue, merge request or -comment body before it is saved and will not be visible to anyone else. - -Below is a list of all of the available commands and descriptions about what they -do. - -| Command | Action | -|:---------------------------|:-------------| -| `/close` | Close the issue or merge request | -| `/reopen` | Reopen the issue or merge request | -| `/merge` | Merge (when pipeline succeeds) | -| `/title <New title>` | Change title | -| `/assign @username` | Assign | -| `/unassign` | Remove assignee | -| `/milestone %milestone` | Set milestone | -| `/remove_milestone` | Remove milestone | -| `/label ~foo ~"bar baz"` | Add label(s) | -| `/unlabel ~foo ~"bar baz"` | Remove all or specific label(s) | -| `/relabel ~foo ~"bar baz"` | Replace all label(s) | -| `/todo` | Add a todo | -| `/done` | Mark todo as done | -| `/subscribe` | Subscribe | -| `/unsubscribe` | Unsubscribe | -| <code>/due <in 2 days | this Friday | December 31st></code> | Set due date | -| `/remove_due_date` | Remove due date | -| `/wip` | Toggle the Work In Progress status | -| <code>/estimate <1w 3d 2h 14m></code> | Set time estimate | -| `/remove_estimate` | Remove estimated time | -| <code>/spend <time(1h 30m | -1h 5m)> <date(YYYY-MM-DD)></code> | Add or subtract spent time; optionally, specify the date that time was spent on | -| `/remove_time_spent` | Remove time spent | -| `/target_branch <Branch Name>` | Set target branch for current merge request | -| `/award :emoji:` | Toggle award for :emoji: | -| `/board_move ~column` | Move issue to column on the board | -| `/duplicate #issue` | Closes this issue and marks it as a duplicate of another issue | -| `/move path/to/project` | Moves issue to another project | -| `/tag v1.2.3 <message>` | Tags a commit with a given tag name and optional message | -| `/tableflip` | Append the comment with `(╯°□°)╯︵ ┻━┻` | -| `/shrug` | Append the comment with `¯\＿(ツ)＿/¯` | -| <code>/copy_metadata #issue | !merge_request</code> | Copy labels and milestone from other issue or merge request | -| `/confidential` | Makes the issue confidential | +Quick actions are textual shortcuts for common actions on issues, epics, merge requests, +and commits that are usually done by clicking buttons or dropdowns in GitLab's UI. +You can enter these commands while creating a new issue or merge request, or +in comments of issues, epics, merge requests, and commits. Each command should be +on a separate line in order to be properly detected and executed. Once executed, +the commands are removed from the text body and not visible to anyone else. + +## Quick actions for issues and merge requests + +The following quick actions are applicable to both issues and merge requests threads, +discussions, and descriptions: + +| Command | Action | Issue | Merge request | +|:---------------------------|:------------------------------ |:------|:--------------| +| `/tableflip <Comment>` | Append the comment with `(╯°□°)╯︵ ┻━┻` | ✓ | ✓ | +| `/shrug <Comment>` | Append the comment with `¯\＿(ツ)＿/¯` | ✓ | ✓ | +| `/todo` | Add a todo | ✓ | ✓ | +| `/done` | Mark todo as done | ✓ | ✓ | +| `/subscribe` | Subscribe | ✓ | ✓ | +| `/unsubscribe` | Unsubscribe | ✓ | ✓ | +| `/close` | Close | ✓ | ✓ | +| `/reopen` | Reopen | ✓ | ✓ | +| `/title <New title>` | Change title | ✓ | ✓ | +| `/award :emoji:` | Toggle emoji award | ✓ | ✓ | +| `/assign @user` | Assign one user | ✓ | ✓ | +| `/assign @user1 @user2` | Assign multiple users **[STARTER]** | ✓ | | +| `/unassign` | Remove assignee(s) | ✓ | ✓ | +| `/reassign @user1 @user2` | Change assignee | ✓ | ✓ | +| `/milestone %milestone` | Set milestone | ✓ | ✓ | +| `/remove_milestone` | Remove milestone | ✓ | ✓ | +| `/label ~label1 ~label2` | Add label(s) | ✓ | ✓ | +| `/unlabel ~label1 ~label2` | Remove all or specific label(s)| ✓ | ✓ | +| `/relabel ~label1 ~label2` | Replace label | ✓ | ✓ | +| <code>/copy_metadata #issue | !merge_request</code> | Copy labels and milestone from other issue or merge request | ✓ | ✓ | +| <code>/estimate <1w 3d 2h 14m></code> | Set time estimate | ✓ | ✓ | +| `/remove_estimate` | Remove time estimate | ✓ | ✓ | +| <code>/spend <time(1h 30m | -1h 5m)> <date(YYYY-MM-DD)></code> | Add or subtract spent time; optionally, specify the date that time was spent on | ✓ | ✓ | +| `/remove_time_spent` | Remove time spent | ✓ | ✓ | +| `/lock` | Lock the discussion | ✓ | ✓ | +| `/unlock` | Unlock the discussion | ✓ | ✓ | +| <code>/due <in 2 days | this Friday | December 31st></code>| Set due date | ✓ | | +| `/remove_due_date` | Remove due date | ✓ | | +| `/weight 0,1,2, ...` | Set weight **[STARTER]** | ✓ | | +| `/clear_weight` | Clears weight **[STARTER]** | ✓ | | +| `/epic <group&epic | Epic URL>` | Add to epic **[ULTIMATE]** | ✓ | | +| `/remove_epic` | Removes from epic **[ULTIMATE]** | ✓ | | +| `/confidential` | Make confidential | ✓ | | +| `/duplicate #issue` | Mark this issue as a duplicate of another issue | ✓ | +| `/move path/to/project` | Move this issue to another project | ✓ | | +| `/target_branch <Local branch Name>` | Set target branch | | ✓ | +| `/wip` | Toggle the Work In Progress status | | ✓ | +| `/merge` | Merge (when pipeline succeeds) | | ✓ | + + +## Quick actions for commit messages + +The following quick actions are applicable for commit messages: + +| Command | Action | +|:------------------------|:------------------------------------------| +| `/tag v1.2.3 <message>` | Tags this commit with an optional message | + +## Quick actions for Epics **[ULTIMATE]** + +The following quick actions are applicable for epics threads and description: + +| Command | Action | +|:---------------------------|:----------------------------------------| +| `/tableflip <Comment>` | Append the comment with `(╯°□°)╯︵ ┻━┻` | +| `/shrug <Comment>` | Append the comment with `¯\＿(ツ)＿/¯` | +| `/todo` | Add a todo | +| `/done` | Mark todo as done | +| `/subscribe` | Subscribe | +| `/unsubscribe` | Unsubscribe | +| `/close` | Close | +| `/reopen` | Reopen | +| `/title <New title>` | Change title | +| `/award :emoji:` | Toggle emoji award | +| `/label ~label1 ~label2` | Add label(s) | +| `/unlabel ~label1 ~label2` | Remove all or specific label(s) | +| `/relabel ~label1 ~label2` | Replace label | diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 9d16a4c74f2..19417d91fec 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -16,7 +16,7 @@ See also: When you create a new [project](../../index.md), GitLab sets `master` as the default branch for your project. You can choose another branch to be your project's -default under your project's **Settings > General**. +default under your project's **Settings > Repository**. The default branch is the branch affected by the [issue closing pattern](../../issues/automatic_issue_closing.md), diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index d41be0989d2..4f076ee01b8 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -36,15 +36,16 @@ to be met: ## Generating a GPG key ->**Notes:** -- If your Operating System has `gpg2` installed, replace `gpg` with `gpg2` in - the following commands. -- If Git is using `gpg` and you get errors like `secret key not available` or - `gpg: signing failed: secret key not available`, run the following command to - change to `gpg2`: - ``` - git config --global gpg.program gpg2 - ``` +> **Notes:** +> - If your Operating System has `gpg2` installed, replace `gpg` with `gpg2` in +> the following commands. +> - If Git is using `gpg` and you get errors like `secret key not available` or +> `gpg: signing failed: secret key not available`, run the following command to +> change to `gpg2`: +> +> ``` +> git config --global gpg.program gpg2 +> ``` If you don't already have a GPG key, the following steps will help you get started: @@ -55,6 +56,8 @@ started: ```sh gpg --full-gen-key ``` + +_NOTE: In some cases like Gpg4win on Windows and other Mac OS versions the command here may be ` gpg --gen-key`_ This will spawn a series of questions. diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 1c3915a5fdd..4d016277824 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -158,7 +158,9 @@ Find it under your project's **Repository > Graph**. ## Repository Languages For the default branch of each repository, GitLab will determine what programming languages -were used and display this on the projects pages. +were used and display this on the projects pages. If this information is missing, it will +be added after updating the default branch on the project. This process can take up to 5 +minutes.  diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index a06ecc3220f..d534c8cbe4b 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -33,11 +33,10 @@ following method. ## Using `git filter-branch` to purge files -> -**Warning:** -Make sure to first make a copy of your repository since rewriting history will -purge the files and information you are about to delete. Also make sure to -inform any collaborators to not use `pull` after your changes, but use `rebase`. +> **Warning:** +> Make sure to first make a copy of your repository since rewriting history will +> purge the files and information you are about to delete. Also make sure to +> inform any collaborators to not use `pull` after your changes, but use `rebase`. 1. Navigate to your repository: @@ -71,10 +70,10 @@ inform any collaborators to not use `pull` after your changes, but use `rebase`. Your repository should now be below the size limit. ->**Note:** -As an alternative to `filter-branch`, you can use the `bfg` tool with a -command like: `bfg --delete-files path/to/big_file.mpg`. Read the -[BFG Repo-Cleaner][bfg] documentation for more information. +> **Note:** +> As an alternative to `filter-branch`, you can use the `bfg` tool with a +> command like: `bfg --delete-files path/to/big_file.mpg`. Read the +> [BFG Repo-Cleaner][bfg] documentation for more information. [admin-repo-size]: https://docs.gitlab.com/ee/user/admin_area/settings/account_and_limit_settings.html#repository-size-limit [bfg]: https://rtyley.github.io/bfg-repo-cleaner/ diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 33c9a1a4d6b..035028c9266 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -177,5 +177,9 @@ you commit the changes you will be taken to a new merge request form.  +If you'd prefer _not_ to use your primary email address for commits created +through the web editor, you can choose to use another of your linked email +addresses from the **User Settings > Edit Profile** page. + [ce-2808]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2808 [issue closing pattern]: ../issues/automatic_issue_closing.md diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 16969b2c527..9429b1268f0 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -78,13 +78,14 @@ switching to a different branch. The Web IDE can be used to preview JavaScript projects right in the browser. This feature uses CodeSandbox to compile and bundle the JavaScript used to -preview the web application. On public projects, an `Open in CodeSandbox` -button is visible which will transfer the contents of the project into a -CodeSandbox project to share with others. -**Note** this button is not visible on private or internal projects. +preview the web application.  +Additionally, for public projects an `Open in CodeSandbox` button is available +to transfer the contents of the project into a public CodeSandbox project to +quickly share your project with others. + ### Enabling Client Side Evaluation The Client Side Evaluation feature needs to be enabled in the GitLab instances diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index ad0ef60373c..127a30d6669 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -40,11 +40,6 @@ support Markdown, RDoc and AsciiDoc. For Markdown based pages, all the [Markdown features](../../markdown.md) are supported and for links there is some [wiki specific](../../markdown.md#wiki-specific-markdown) behavior. ->**Note:** -The wiki is based on a Git repository and contains only text files. Uploading -files via the web interface will upload them in GitLab itself, and they will -not be available if you clone the wiki repo locally. - In the web interface the commit message is optional, but the GitLab Wiki is based on Git and needs a commit message, so one will be created for you if you do not enter one. @@ -53,6 +48,14 @@ When you're ready, click the **Create page** and the new page will be created.  +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33475) in GitLab 11.3. + +Starting with GitLab 11.3, any file that is uploaded to the wiki via GitLab's +interface will be stored in the wiki Git repository, and it will be available +if you clone the wiki repository locally. All uploaded files prior to GitLab +11.3 are stored in GitLab itself. If you want them to be part of the wiki's Git +repository, you will have to upload them again. + ## Editing a wiki page To edit a page, simply click on the **Edit** button. From there on, you can diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index 918daee5d9f..52610378ad5 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -13,7 +13,7 @@ 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 @@ -40,7 +40,7 @@ It is currently not possible to create a project with the following names: Currently the following names are reserved as top level groups: - 503.html -- - +- \- - .well-known - 404.html - 422.html @@ -88,7 +88,7 @@ Currently the following names are reserved as top level groups: These group names are unavailable as subgroup names: -- - +- \- - activity - analytics - audit_events diff --git a/doc/workflow/lfs/lfs_administration.md b/doc/workflow/lfs/lfs_administration.md index 6ac3bb8c0b4..ec5943fd51b 100644 --- a/doc/workflow/lfs/lfs_administration.md +++ b/doc/workflow/lfs/lfs_administration.md @@ -24,7 +24,7 @@ There are various configuration options to help GitLab server administrators: In `/etc/gitlab/gitlab.rb`: ```ruby -# Change to true to enable lfs +# Change to true to enable lfs - enabled by default if not defined gitlab_rails['lfs_enabled'] = false # Optionally, change the storage path location. Defaults to @@ -54,7 +54,7 @@ to offload local hard disk R/W operations, and free up disk space significantly. GitLab is tightly integrated with `Fog`, so you can refer to its [documentation](http://fog.io/about/provider_documentation.html) to check which storage services can be integrated with GitLab. You can also use external object storage in a private local network. For example, -[Minio](https://www.minio.io/) is a standalone object storage service, is easy to setup, and works well with GitLab instances. +[Minio](https://www.minio.io/) is a standalone object storage service, is easy to set up, and works well with GitLab instances. GitLab provides two different options for the uploading mechanism: "Direct upload" and "Background upload". @@ -95,6 +95,7 @@ Here is a configuration example with S3. | `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) | | `path_style` | Set to true to use `host/bucket_name/object` style paths instead of `bucket_name.host/object`. Leave as false for AWS S3 | false | +| `use_iam_profile` | Set to true to use IAM profile instead of access keys | false Here is a configuration example with GCS. 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 ae161e43233..d02e921fa84 100644 --- a/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md +++ b/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md @@ -61,11 +61,12 @@ 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**: 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 @@ -77,10 +78,10 @@ git clone git@gitlab.example.com:group/project.git ``` If you already cloned the repository and you want to get the latest LFS object -that are on the remote repository, eg. from branch `master`: +that are on the remote repository, eg. for a branch from origin: ```bash -git lfs fetch master +git lfs fetch origin master ``` ## File Locking diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md index 5dc62a30128..731c9209224 100644 --- a/doc/workflow/notifications.md +++ b/doc/workflow/notifications.md @@ -77,10 +77,8 @@ In most of the below cases, the notification will be sent to: - the author and assignee of the issue/merge request - authors of comments on the issue/merge request - anyone mentioned by `@username` in the issue/merge request title or description - - anyone mentioned by `@username` in any of the comments on the issue/merge request - - ...with notification level "Participating" or higher - + - anyone mentioned by `@username` in any of the comments on the issue/merge request + ...with notification level "Participating" or higher - Watchers: users with notification level "Watch" - Subscribers: anyone who manually subscribed to the issue/merge request - Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below diff --git a/doc/workflow/timezone.md b/doc/workflow/timezone.md index 7e08c0e51ac..338b3a32265 100644 --- a/doc/workflow/timezone.md +++ b/doc/workflow/timezone.md @@ -9,6 +9,7 @@ Uncomment and customize if you want to change the default time zone of GitLab ap To see all available time zones, run `bundle exec rake time:zones:all`. +With Omnibus installations, run `gitlab-rake time:zones:all`. ## Changing time zone in omnibus installations diff --git a/doc/workflow/todos.md b/doc/workflow/todos.md index dda82352c67..f94d592d0db 100644 --- a/doc/workflow/todos.md +++ b/doc/workflow/todos.md @@ -14,7 +14,7 @@ in a simple dashboard. --- -You can quickly access the Todos dashboard using the bell icon next to the +You can quickly access the Todos dashboard using the checkmark icon next to the search bar in the upper right corner. The number in blue is the number of Todos you still have open if the count is < 100, else it's 99+. The exact number will still be shown in the body of the _To do_ tab. |
