diff options
Diffstat (limited to 'doc')
135 files changed, 1356 insertions, 826 deletions
diff --git a/doc/README.md b/doc/README.md index f87ff925e94..14e8d2edb90 100644 --- a/doc/README.md +++ b/doc/README.md @@ -284,6 +284,7 @@ The following documentation relates to the DevOps **Configure** stage: | [Auto DevOps](topics/autodevops/index.md) | Automatically employ a complete DevOps lifecycle. | | [Easy creation of Kubernetes<br/>clusters on GKE](user/project/clusters/index.md#adding-and-creating-a-new-gke-cluster-via-gitlab) | Use Google Kubernetes Engine and GitLab. | | [Executable Runbooks](user/project/clusters/runbooks/index.md) | Documented procedures that explain how to carry out particular processes. | +| [GitLab ChatOps](ci/chatops/README.md) | Interact with CI/CD jobs through chat services. | | [Installing Applications](user/project/clusters/index.md#installing-applications) | Deploy Helm, Ingress, and Prometheus on Kubernetes. | | [Mattermost slash commands](user/project/integrations/mattermost_slash_commands.md) | Enable and use slash commands from within Mattermost. | | [Protected variables](ci/variables/README.md#protected-variables) | Restrict variables to protected branches and tags. | diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md index 94a8803fff1..726622d8599 100644 --- a/doc/administration/auth/authentiq.md +++ b/doc/administration/auth/authentiq.md @@ -51,7 +51,7 @@ Authentiq will generate a Client ID and the accompanying Client Secret for you t ``` 1. The `scope` is set to request the user's name, email (required and signed), and permission to send push notifications to sign in on subsequent visits. -See [OmniAuth Authentiq strategy](https://github.com/AuthentiqID/omniauth-authentiq/wiki/Scopes,-callback-url-configuration-and-responses) for more information on scopes and modifiers. + See [OmniAuth Authentiq strategy](https://github.com/AuthentiqID/omniauth-authentiq/wiki/Scopes,-callback-url-configuration-and-responses) for more information on scopes and modifiers. 1. Change `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` to the Client credentials you received in step 1. diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md index 37e596f198f..d5d0d99ac24 100644 --- a/doc/administration/auth/ldap.md +++ b/doc/administration/auth/ldap.md @@ -451,7 +451,7 @@ ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt -b "$ba ### Invalid credentials when logging in - Make sure the user you are binding with has enough permissions to read the user's -tree and traverse it. + tree and traverse it. - Check that the `user_filter` is not blocking otherwise valid users. - Run the following check command to make sure that the LDAP settings are correct and GitLab can see your users: diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md index bf5d064d79d..55d85ad86e6 100644 --- a/doc/administration/high_availability/redis.md +++ b/doc/administration/high_availability/redis.md @@ -359,6 +359,12 @@ following section assumes you are using Omnibus GitLab Enterprise Edition. For the Omnibus Community Edition and installations from source, follow the [Redis HA source install](redis_source.md) guide. +NOTE: **Note:** If you are using an external Redis Sentinel instance, be sure +to exclude the `requirepass` parameter from the Sentinel +configuration. This parameter will cause clients to report `NOAUTH +Authentication required.`. [Redis Sentinel 3.2.x does not support +password authentication](https://github.com/antirez/redis/issues/3279). + Now that the Redis servers are all set up, let's configure the Sentinel servers. diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 05873e01a08..658b2f55d30 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -95,244 +95,249 @@ for a real-world example of this exploit. ### Omnibus package installations -1. Find the `incoming_email` section in `/etc/gitlab/gitlab.rb`, enable the - feature and fill in the details for your specific IMAP server and email account: +1. Find the `incoming_email` section in `/etc/gitlab/gitlab.rb`, enable the feature + and fill in the details for your specific IMAP server and email account (see [examples](#config-examples) below). - Configuration for Postfix mail server, assumes mailbox - incoming@gitlab.example.com +1. Reconfigure GitLab for the changes to take effect: - ```ruby - gitlab_rails['incoming_email_enabled'] = true + ```sh + sudo gitlab-ctl reconfigure + sudo gitlab-ctl restart + ``` - # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. - # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). - gitlab_rails['incoming_email_address'] = "incoming+%{key}@gitlab.example.com" +1. Verify that everything is configured correctly: - # Email account username - # With third party providers, this is usually the full email address. - # With self-hosted email servers, this is usually the user part of the email address. - gitlab_rails['incoming_email_email'] = "incoming" - # Email account password - gitlab_rails['incoming_email_password'] = "[REDACTED]" + ```sh + sudo gitlab-rake gitlab:incoming_email:check + ``` - # IMAP server host - gitlab_rails['incoming_email_host'] = "gitlab.example.com" - # IMAP server port - gitlab_rails['incoming_email_port'] = 143 - # Whether the IMAP server uses SSL - gitlab_rails['incoming_email_ssl'] = false - # Whether the IMAP server uses StartTLS - gitlab_rails['incoming_email_start_tls'] = false +Reply by email should now be working. - # The mailbox where incoming mail will end up. Usually "inbox". - gitlab_rails['incoming_email_mailbox_name'] = "inbox" - # The IDLE command timeout. - gitlab_rails['incoming_email_idle_timeout'] = 60 +### Installations from source + +1. Go to the GitLab installation directory: + + ```sh + cd /home/git/gitlab ``` - Configuration for Gmail / Google Apps, assumes mailbox - gitlab-incoming@gmail.com +1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature + and fill in the details for your specific IMAP server and email account (see [examples](#config-examples) below). - ```ruby - gitlab_rails['incoming_email_enabled'] = true +1. Enable `mail_room` in the init script at `/etc/default/gitlab`: + + ```sh + sudo mkdir -p /etc/default + echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab + ``` + +1. Restart GitLab: + + ```sh + sudo service gitlab restart + ``` + +1. Verify that everything is configured correctly: + + ```sh + sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production + ``` + +Reply by email should now be working. + +### Config examples + +#### Postfix + +Example configuration for Postfix mail server. Assumes mailbox incoming@gitlab.example.com. + +Example for Omnibus installs: + +```ruby +gitlab_rails['incoming_email_enabled'] = true + +# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. +# The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). +gitlab_rails['incoming_email_address'] = "incoming+%{key}@gitlab.example.com" + +# Email account username +# With third party providers, this is usually the full email address. +# With self-hosted email servers, this is usually the user part of the email address. +gitlab_rails['incoming_email_email'] = "incoming" +# Email account password +gitlab_rails['incoming_email_password'] = "[REDACTED]" + +# IMAP server host +gitlab_rails['incoming_email_host'] = "gitlab.example.com" +# IMAP server port +gitlab_rails['incoming_email_port'] = 143 +# Whether the IMAP server uses SSL +gitlab_rails['incoming_email_ssl'] = false +# Whether the IMAP server uses StartTLS +gitlab_rails['incoming_email_start_tls'] = false + +# The mailbox where incoming mail will end up. Usually "inbox". +gitlab_rails['incoming_email_mailbox_name'] = "inbox" +# The IDLE command timeout. +gitlab_rails['incoming_email_idle_timeout'] = 60 +``` + +Example for source installs: + +```yaml +incoming_email: + enabled: true # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). - gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@gmail.com" + address: "incoming+%{key}@gitlab.example.com" # Email account username # With third party providers, this is usually the full email address. # With self-hosted email servers, this is usually the user part of the email address. - gitlab_rails['incoming_email_email'] = "gitlab-incoming@gmail.com" + user: "incoming" # Email account password - gitlab_rails['incoming_email_password'] = "[REDACTED]" + password: "[REDACTED]" # IMAP server host - gitlab_rails['incoming_email_host'] = "imap.gmail.com" + host: "gitlab.example.com" # IMAP server port - gitlab_rails['incoming_email_port'] = 993 + port: 143 # Whether the IMAP server uses SSL - gitlab_rails['incoming_email_ssl'] = true + ssl: false # Whether the IMAP server uses StartTLS - gitlab_rails['incoming_email_start_tls'] = false + start_tls: false # The mailbox where incoming mail will end up. Usually "inbox". - gitlab_rails['incoming_email_mailbox_name'] = "inbox" + mailbox: "inbox" # The IDLE command timeout. - gitlab_rails['incoming_email_idle_timeout'] = 60 - ``` + idle_timeout: 60 +``` + +#### Gmail + +Example configuration for Gmail/G Suite. Assumes mailbox gitlab-incoming@gmail.com. + +Example for Omnibus installs: + +```ruby +gitlab_rails['incoming_email_enabled'] = true - Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the - catch-all mailbox incoming@exchange.example.com +# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. +# The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). +gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@gmail.com" - ```ruby - gitlab_rails['incoming_email_enabled'] = true +# Email account username +# With third party providers, this is usually the full email address. +# With self-hosted email servers, this is usually the user part of the email address. +gitlab_rails['incoming_email_email'] = "gitlab-incoming@gmail.com" +# Email account password +gitlab_rails['incoming_email_password'] = "[REDACTED]" + +# IMAP server host +gitlab_rails['incoming_email_host'] = "imap.gmail.com" +# IMAP server port +gitlab_rails['incoming_email_port'] = 993 +# Whether the IMAP server uses SSL +gitlab_rails['incoming_email_ssl'] = true +# Whether the IMAP server uses StartTLS +gitlab_rails['incoming_email_start_tls'] = false + +# The mailbox where incoming mail will end up. Usually "inbox". +gitlab_rails['incoming_email_mailbox_name'] = "inbox" +# The IDLE command timeout. +gitlab_rails['incoming_email_idle_timeout'] = 60 +``` + +Example for source installs: + +```yaml +incoming_email: + enabled: true # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). - # Exchange does not support sub-addressing, so a catch-all mailbox must be used. - gitlab_rails['incoming_email_address'] = "incoming-%{key}@exchange.example.com" + address: "gitlab-incoming+%{key}@gmail.com" # Email account username - # Typically this is the userPrincipalName (UPN) - gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com" + # With third party providers, this is usually the full email address. + # With self-hosted email servers, this is usually the user part of the email address. + user: "gitlab-incoming@gmail.com" # Email account password - gitlab_rails['incoming_email_password'] = "[REDACTED]" + password: "[REDACTED]" # IMAP server host - gitlab_rails['incoming_email_host'] = "exchange.example.com" + host: "imap.gmail.com" # IMAP server port - gitlab_rails['incoming_email_port'] = 993 + port: 993 # Whether the IMAP server uses SSL - gitlab_rails['incoming_email_ssl'] = true - ``` - -1. Reconfigure GitLab for the changes to take effect: + ssl: true + # Whether the IMAP server uses StartTLS + start_tls: false - ```sh - sudo gitlab-ctl reconfigure - sudo gitlab-ctl restart - ``` + # The mailbox where incoming mail will end up. Usually "inbox". + mailbox: "inbox" + # The IDLE command timeout. + idle_timeout: 60 +``` -1. Verify that everything is configured correctly: +#### MS Exchange - ```sh - sudo gitlab-rake gitlab:incoming_email:check - ``` +Example configuration for Microsoft Exchange mail server with IMAP enabled. Assumes the +catch-all mailbox incoming@exchange.example.com. -1. Reply by email should now be working. +Example for Omnibus installs: -### Installations from source +```ruby +gitlab_rails['incoming_email_enabled'] = true -1. Go to the GitLab installation directory: +# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. +# The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). +# Exchange does not support sub-addressing, so a catch-all mailbox must be used. +gitlab_rails['incoming_email_address'] = "incoming-%{key}@exchange.example.com" - ```sh - cd /home/git/gitlab - ``` +# Email account username +# Typically this is the userPrincipalName (UPN) +gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com" +# Email account password +gitlab_rails['incoming_email_password'] = "[REDACTED]" -1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature - and fill in the details for your specific IMAP server and email account: +# IMAP server host +gitlab_rails['incoming_email_host'] = "exchange.example.com" +# IMAP server port +gitlab_rails['incoming_email_port'] = 993 +# Whether the IMAP server uses SSL +gitlab_rails['incoming_email_ssl'] = true +``` - ```sh - sudo editor config/gitlab.yml - ``` +Example for source installs: - Configuration for Postfix mail server, assumes mailbox - incoming@gitlab.example.com - - ```yaml - incoming_email: - enabled: true - - # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. - # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). - address: "incoming+%{key}@gitlab.example.com" - - # Email account username - # With third party providers, this is usually the full email address. - # With self-hosted email servers, this is usually the user part of the email address. - user: "incoming" - # Email account password - password: "[REDACTED]" - - # IMAP server host - host: "gitlab.example.com" - # IMAP server port - port: 143 - # Whether the IMAP server uses SSL - ssl: false - # Whether the IMAP server uses StartTLS - start_tls: false - - # The mailbox where incoming mail will end up. Usually "inbox". - mailbox: "inbox" - # The IDLE command timeout. - idle_timeout: 60 - ``` +```yaml +incoming_email: + enabled: true - Configuration for Gmail / Google Apps, assumes mailbox - gitlab-incoming@gmail.com - - ```yaml - incoming_email: - enabled: true - - # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. - # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). - address: "gitlab-incoming+%{key}@gmail.com" - - # Email account username - # With third party providers, this is usually the full email address. - # With self-hosted email servers, this is usually the user part of the email address. - user: "gitlab-incoming@gmail.com" - # Email account password - password: "[REDACTED]" - - # IMAP server host - host: "imap.gmail.com" - # IMAP server port - port: 993 - # Whether the IMAP server uses SSL - ssl: true - # Whether the IMAP server uses StartTLS - start_tls: false - - # The mailbox where incoming mail will end up. Usually "inbox". - mailbox: "inbox" - # The IDLE command timeout. - idle_timeout: 60 - ``` - - Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the - catch-all mailbox incoming@exchange.example.com - - ```yaml - incoming_email: - enabled: true - - # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. - # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). - # Exchange does not support sub-addressing, so a catch-all mailbox must be used. - address: "incoming-%{key}@exchange.example.com" - - # Email account username - # Typically this is the userPrincipalName (UPN) - user: "incoming@ad-domain.example.com" - # Email account password - password: "[REDACTED]" - - # IMAP server host - host: "exchange.example.com" - # IMAP server port - port: 993 - # Whether the IMAP server uses SSL - ssl: true - # Whether the IMAP server uses StartTLS - start_tls: false - - # The mailbox where incoming mail will end up. Usually "inbox". - mailbox: "inbox" - # The IDLE command timeout. - idle_timeout: 60 - ``` - -1. Enable `mail_room` in the init script at `/etc/default/gitlab`: - - ```sh - sudo mkdir -p /etc/default - echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab - ``` - -1. Restart GitLab: - - ```sh - sudo service gitlab restart - ``` + # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. + # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). + # Exchange does not support sub-addressing, so a catch-all mailbox must be used. + address: "incoming-%{key}@exchange.example.com" -1. Verify that everything is configured correctly: + # Email account username + # Typically this is the userPrincipalName (UPN) + user: "incoming@ad-domain.example.com" + # Email account password + password: "[REDACTED]" - ```sh - sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production - ``` + # IMAP server host + host: "exchange.example.com" + # IMAP server port + port: 993 + # Whether the IMAP server uses SSL + ssl: true + # Whether the IMAP server uses StartTLS + start_tls: false -1. Reply by email should now be working. + # The mailbox where incoming mail will end up. Usually "inbox". + mailbox: "inbox" + # The IDLE command timeout. + idle_timeout: 60 +``` diff --git a/doc/administration/index.md b/doc/administration/index.md index ef692ea47ee..6e08d4633cd 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -51,8 +51,9 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [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. -- [Merge request diffs](merge_request_diffs.md): Configure the diffs shown on merge requests +- [Merge request diffs storage](merge_request_diffs.md): Configure merge requests diffs external storage. - [Broadcast Messages](../user/admin_area/broadcast_messages.md): Send messages to GitLab users through the UI. +- [Admin Area](../user/admin_area/index.md): for self-managed instance-wide configuration and maintenance. #### Customizing GitLab's appearance @@ -130,7 +131,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Job traces](job_traces.md): Information about the job traces (logs). - [Register Shared and specific Runners](../ci/runners/README.md#registering-a-shared-runner): Learn how to register and configure Shared and specific Runners to your own instance. - [Shared Runners pipelines quota](../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota): Limit the usage of pipeline minutes for Shared Runners. -- [Enable/disable Auto DevOps](../topics/autodevops/index.md#enabling-auto-devops): Enable or disable Auto DevOps for your instance. +- [Enable/disable Auto DevOps](../topics/autodevops/index.md#enablingdisabling-auto-devops): Enable or disable Auto DevOps for your instance. ## Git configuration options diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md index 94620c3d3a0..c34a9519ace 100644 --- a/doc/administration/merge_request_diffs.md +++ b/doc/administration/merge_request_diffs.md @@ -1,7 +1,6 @@ -# Merge request diffs administration +# Merge request diffs storage **[CORE ONLY]** -> **Notes:** -> - External merge request diffs introduced in GitLab 11.8 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/52568) in GitLab 11.8. Merge request diffs are size-limited copies of diffs associated with merge requests. When viewing a merge request, diffs are sourced from these copies @@ -16,9 +15,7 @@ large, in which case, switching to external storage is recommended. Merge request diffs can be stored on disk, or in object storage. In general, it is better to store the diffs in the database than on disk. -To enable external storage of merge request diffs: - ---- +To enable external storage of merge request diffs, follow the instructions below. **In Omnibus installations:** @@ -29,17 +26,15 @@ To enable external storage of merge request diffs: ``` 1. _The external diffs will be stored in in - `/var/opt/gitlab/gitlab-rails/shared/external-diffs`._ To change the path, - for example to `/mnt/storage/external-diffs`, edit `/etc/gitlab/gitlab.rb` + `/var/opt/gitlab/gitlab-rails/shared/external-diffs`._ To change the path, + for example, to `/mnt/storage/external-diffs`, edit `/etc/gitlab/gitlab.rb` and add the following line: ```ruby gitlab_rails['external_diffs_storage_path'] = "/mnt/storage/external-diffs" ``` -1. Save the file and [reconfigure GitLab][] for the changes to take effect. - ---- +1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. **In installations from source:** @@ -52,7 +47,7 @@ To enable external storage of merge request diffs: ``` 1. _The external diffs will be stored in - `/home/git/gitlab/shared/external-diffs`._ To change the path, for example + `/home/git/gitlab/shared/external-diffs`._ To change the path, for example, to `/mnt/storage/external-diffs`, edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines: @@ -62,18 +57,18 @@ To enable external storage of merge request diffs: storage_path: /mnt/storage/external-diffs ``` -1. Save the file and [restart GitLab][] for the changes to take effect. +1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. ### Using object storage -Instead of storing the external diffs on disk, we recommended you use an object +Instead of storing the external diffs on disk, we recommended the use of an object store like AWS S3 instead. This configuration relies on valid AWS credentials to be configured already. ### Object Storage Settings For source installations, these settings are nested under `external_diffs:` and -then `object_store:`. On omnibus installs, they are prefixed by +then `object_store:`. On Omnibus installations, they are prefixed by `external_diffs_object_store_`. | Setting | Description | Default | @@ -118,7 +113,7 @@ The connection settings match those provided by [Fog](https://github.com/fog), a } ``` - NOTE: if you are using AWS IAM profiles, be sure to omit the + Note that, if you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs. For example: ```ruby @@ -129,9 +124,7 @@ The connection settings match those provided by [Fog](https://github.com/fog), a } ``` -1. Save the file and [reconfigure GitLab][] for the changes to take effect. - ---- +1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. **In installations from source:** @@ -151,4 +144,4 @@ The connection settings match those provided by [Fog](https://github.com/fog), a region: eu-central-1 ``` -1. Save the file and [restart GitLab][] for the changes to take effect. +1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index 1f431f8bd62..ab43ec2cc4f 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -34,7 +34,7 @@ Test Connection to ensure the configuration is correct. - **Default**: Checked - **Type**: InfluxDB 0.9.x (Even if you're using InfluxDB 0.10.x) - **Url**: `https://localhost:8086` (Or the remote URL if you've installed InfluxDB -on a separate server) + on a separate server) - **Access**: proxy - **Database**: gitlab - **User**: admin (Or the username configured when setting up InfluxDB) diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md index 6a55dbe1eb4..95f497a1470 100644 --- a/doc/administration/monitoring/performance/performance_bar.md +++ b/doc/administration/monitoring/performance/performance_bar.md @@ -10,11 +10,11 @@ It allows you to see (from left to right): - the current host serving the page - the timing of the page (backend, frontend) - time taken and number of DB queries, click through for details of these queries - +  - time taken and number of [Gitaly] calls, click through for details of these calls - +  - profile of the code used to generate the page, line by line. In the profile view, the numbers in the left panel represent wall time, cpu time, and number of calls (based on [rblineprof](https://github.com/tmm1/rblineprof)). - +  - time taken and number of calls to Redis - time taken and number of background jobs created by Sidekiq - time taken and number of Ruby GC calls diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 6ea0ac0d495..3bfcc9a289e 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -17,10 +17,7 @@ GitLab monitors its own internal service metrics, and makes them available at th `/-/metrics` endpoint. Unlike other [Prometheus] exporters, in order to access it, the client IP needs to be [included in a whitelist][whitelist]. -Currently the embedded Prometheus server is not automatically configured to -collect metrics from this endpoint. We recommend setting up another Prometheus -server, because the embedded server configuration is overwritten once every -[reconfigure of GitLab][reconfigure]. In the future this will not be required. +For Omnibus and Chart installations, these metrics are automatically enabled and collected as of [GitLab 9.4](https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/1702). For source installations or earlier versions, these metrics will need to be enabled manually and collected by a Prometheus server. ## Unicorn Metrics available diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index a16fc7ae74f..32f36d68c50 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/index.md @@ -3,20 +3,20 @@ Keep your GitLab instance up and running smoothly. - [Clean up Redis sessions](cleaning_up_redis_sessions.md): Prior to GitLab 7.3, -user sessions did not automatically expire from Redis. If -you have been running a large GitLab server (thousands of users) since before -GitLab 7.3 we recommend cleaning up stale sessions to compact the Redis -database after you upgrade to GitLab 7.3. + user sessions did not automatically expire from Redis. If + you have been running a large GitLab server (thousands of users) since before + GitLab 7.3 we recommend cleaning up stale sessions to compact the Redis + database after you upgrade to GitLab 7.3. - [Moving repositories](moving_repositories.md): Moving all repositories managed -by GitLab to another file system or another server. + by GitLab to another file system or another server. - [Sidekiq MemoryKiller](sidekiq_memory_killer.md): Configure Sidekiq MemoryKiller -to restart Sidekiq. + to restart Sidekiq. - [Unicorn](unicorn.md): Understand Unicorn and unicorn-worker-killer. - Speed up SSH operations by [Authorizing SSH users via a fast, -indexed lookup to the GitLab database](fast_ssh_key_lookup.md), and/or -by [doing away with user SSH keys stored on GitLab entirely in favor -of SSH certificates](ssh_certificates.md). + indexed lookup to the GitLab database](fast_ssh_key_lookup.md), and/or + by [doing away with user SSH keys stored on GitLab entirely in favor + of SSH certificates](ssh_certificates.md). - [Filesystem Performance Benchmarking](filesystem_benchmarking.md): Filesystem -performance can have a big impact on GitLab performance, especially for actions -that read or write Git repositories. This information will help benchmark -filesystem performance against known good and bad real-world systems. + performance can have a big impact on GitLab performance, especially for actions + that read or write Git repositories. This information will help benchmark + filesystem performance against known good and bad real-world systems. diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 5c809f25fbd..279ad018aed 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -337,10 +337,10 @@ The default is 100MB. You may want to run GitLab Pages daemon on a separate server in order to decrease the load on your main application server. Follow the steps below to configure GitLab Pages in a separate server. -1. Suppose you have the main GitLab application server named `app1`. Prepare -new Linux server (let's call it `app2`), create NFS share there and configure access to -this share from `app1`. Let's use the default GitLab Pages folder `/var/opt/gitlab/gitlab-rails/shared/pages` -as the shared folder on `app2` and mount it to `/mnt/pages` on `app1`. +1. Suppose you have the main GitLab application server named `app1`. Prepare + new Linux server (let's call it `app2`), create NFS share there and configure access to + this share from `app1`. Let's use the default GitLab Pages folder `/var/opt/gitlab/gitlab-rails/shared/pages` + as the shared folder on `app2` and mount it to `/mnt/pages` on `app1`. 1. On `app2` install GitLab omnibus and modify `/etc/gitlab/gitlab.rb` this way: @@ -365,7 +365,7 @@ as the shared folder on `app2` and mount it to `/mnt/pages` on `app1`. pages_external_url "http://<your-pages-domain>" gitlab_rails['pages_path'] = "/mnt/pages" ``` - + 1. Run `sudo gitlab-ctl reconfigure`. ## Backup diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 9f2b4d9075a..60800d445b8 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -88,12 +88,13 @@ since that is needed in all configurations. ### Wildcard domains ->**Requirements:** -> - [Wildcard DNS setup](#dns-configuration) -> -> --- -> -> URL scheme: `http://page.example.io` +**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 other setups as described below. Nginx will proxy all requests to the daemon. diff --git a/doc/administration/polling.md b/doc/administration/polling.md index 35aaa20df2c..a1077614677 100644 --- a/doc/administration/polling.md +++ b/doc/administration/polling.md @@ -10,15 +10,15 @@ say that issue notes poll every 2 seconds, and issue titles poll every 5 seconds; these are _not_ the actual values. - 1 is the default, and recommended for most installations. (Issue notes poll -every 2 seconds, and issue titles poll every 5 seconds.) + every 2 seconds, and issue titles poll every 5 seconds.) - 0 will disable UI polling completely. (On the next poll, clients will stop -polling for updates.) + polling for updates.) - A value greater than 1 will slow polling down. If you see issues with -database load from lots of clients polling for updates, increasing the -multiplier from 1 can be a good compromise, rather than disabling polling -completely. (For example: If this is set to 2, then issue notes poll every 4 -seconds, and issue titles poll every 10 seconds.) + database load from lots of clients polling for updates, increasing the + multiplier from 1 can be a good compromise, rather than disabling polling + completely. (For example: If this is set to 2, then issue notes poll every 4 + seconds, and issue titles poll every 10 seconds.) - A value between 0 and 1 will make the UI poll more frequently (so updates -will show in other sessions faster), but is **not recommended**. 1 should be -fast enough. (For example, if this is set to 0.5, then issue notes poll every -1 second, and issue titles poll every 2.5 seconds.) + will show in other sessions faster), but is **not recommended**. 1 should be + fast enough. (For example, if this is set to 0.5, then issue notes poll every + 1 second, and issue titles poll every 2.5 seconds.) diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index 0d863594fc7..b295b7d5dc4 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.md @@ -60,6 +60,7 @@ Runs the following rake tasks: 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 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) diff --git a/doc/api/README.md b/doc/api/README.md index 89069fe60e1..48d9ad8f30d 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -134,7 +134,7 @@ Endpoints are available for: ## Road to GraphQL Going forward, we will start on moving to -[GraphQL](http://graphql.org/learn/best-practices/) and deprecate the use of +[GraphQL](graphql/index.md) and deprecate the use of controller-specific endpoints. GraphQL has a number of benefits: 1. We avoid having to maintain two different APIs. diff --git a/doc/api/boards.md b/doc/api/boards.md index 2a2622736c3..28c73db6b98 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -37,7 +37,7 @@ Example response: "web_url": "http://example.com/diaspora/diaspora-project-site" }, "milestone": { - "id": 12 + "id": 12, "title": "10.0" }, "lists" : [ @@ -95,7 +95,7 @@ Example response: ```json { "id": 1, - "name:": "project issue board", + "name": "project issue board", "project": { "id": 5, "name": "Diaspora Project Site", @@ -106,7 +106,7 @@ Example response: "web_url": "http://example.com/diaspora/diaspora-project-site" }, "milestone": { - "id": 12 + "id": 12, "title": "10.0" }, "lists" : [ diff --git a/doc/api/issues.md b/doc/api/issues.md index 0571f280d2a..d8b2ff07e30 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -32,6 +32,7 @@ GET /issues?author_id=5 GET /issues?assignee_id=5 GET /issues?my_reaction_emoji=star GET /issues?search=foo&in=title +GET /issues?confidential=true ``` | Attribute | Type | Required | Description | @@ -52,6 +53,7 @@ GET /issues?search=foo&in=title | `created_before` | datetime | no | Return issues created on or before the given time | | `updated_after` | datetime | no | Return issues updated on or after the given time | | `updated_before` | datetime | no | Return issues updated on or before the given time | +| `confidential ` | Boolean | no | Filter confidential or public issues. | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/issues @@ -148,6 +150,7 @@ GET /groups/:id/issues?search=issue+title+or+description GET /groups/:id/issues?author_id=5 GET /groups/:id/issues?assignee_id=5 GET /groups/:id/issues?my_reaction_emoji=star +GET /groups/:id/issues?confidential=true ``` | Attribute | Type | Required | Description | @@ -168,6 +171,7 @@ GET /groups/:id/issues?my_reaction_emoji=star | `created_before` | datetime | no | Return issues created on or before the given time | | `updated_after` | datetime | no | Return issues updated on or after the given time | | `updated_before` | datetime | no | Return issues updated on or before the given time | +| `confidential ` | Boolean | no | Filter confidential or public issues. | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4/issues @@ -264,6 +268,7 @@ GET /projects/:id/issues?search=issue+title+or+description GET /projects/:id/issues?author_id=5 GET /projects/:id/issues?assignee_id=5 GET /projects/:id/issues?my_reaction_emoji=star +GET /projects/:id/issues?confidential=true ``` | Attribute | Type | Required | Description | @@ -284,6 +289,8 @@ GET /projects/:id/issues?my_reaction_emoji=star | `created_before` | datetime | no | Return issues created on or before the given time | | `updated_after` | datetime | no | Return issues updated on or after the given time | | `updated_before` | datetime | no | Return issues updated on or before the given time | +| `confidential ` | Boolean | no | Filter confidential or public issues. | + ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/issues @@ -639,6 +646,37 @@ Example response: **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. +## Bulk update issues + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21368) in GitLab 11.9. + +Update multiple issues using a single API call. Returns the number of successfully updated issues. + +``` +PUT /projects/:id/issues/bulk_update +``` + +| 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. | +| `issuable_ids` | Array[integer] | yes | The IDs of issues to be updated. | +| `assignee_ids` | Array[integer] | no | The ID of the user(s) to assign the issue to. Set to `0` or provide an empty value to unassign all assignees. | +| `milestone_id` | integer | no | The global ID of a milestone to assign the issue to. Set to `0` or provide an empty value to unassign a milestone.| +| `add_label_ids` | Array[integer] | no | Comma-separated label IDs to be added. | +| `remove_label_ids` | Array[integer] | no | Comma-separated label IDs to be added. | +| `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it. | +| `subscription_event` | string | no | The subscription_event event of an issue. Set `subscribe` to subscribe to the issue and `unsubscribe` to unsubscribe from it. | + +```bash +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/issues/bulk_update?issuable_ids[]=1&issuable_ids[]=2&state_event=close +``` + +Example response: + +```json +{ "message": "2 issues updated" } +``` + ## Delete an issue Only for admins and project owners. Soft deletes the issue in question. diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index e176cdffc5f..ba47e507b79 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -956,6 +956,37 @@ Must include at least one non-required attribute from above. } ``` +## Bulk update merge requests + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21368) in GitLab 11.9. + +Update multiple merge requests using a single API call. Returns the number of successfully updated merge requests. + +``` +PUT /projects/:id/merge_requests/bulk_update +``` + +| 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. | +| `issuable_ids` | Array[integer] | yes | The IDs of merge requests to be updated. | +| `assignee_ids` | Array[integer] | no | The ID of the user(s) to assign the issue to. Set to `0` or provide an empty value to unassign all assignees. | +| `milestone_id` | integer | no | The global ID of a milestone to assign the issue to. Set to `0` or provide an empty value to unassign a milestone.| +| `add_label_ids` | Array[integer] | no | Comma-separated label IDs to be added. | +| `remove_label_ids` | Array[integer] | no | Comma-separated label IDs to be added. | +| `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it. | +| `subscription_event` | string | no | The subscription_event event of an issue. Set `subscribe` to subscribe to the issue and `unsubscribe` to unsubscribe from it. | + +```bash +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/merge_requests/bulk_update?issuable_ids[]=1&issuable_ids[]=2&state_event=close +``` + +Example response: + +```json +{ "message": "2 merge_requests updated" } +``` + ## Delete a merge request Only for admins and project owners. Soft deletes the merge request in question. diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index 8c1d982f394..6fcc06ea8cd 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -171,6 +171,7 @@ Parameters: If the commit fails for any reason we return a 400 error with a non-specific error message. Possible causes for a failed commit include: + - the `file_path` contained `/../` (attempted directory traversal); - the new file contents were identical to the current file contents, i.e. the user tried to make an empty commit; diff --git a/doc/api/runners.md b/doc/api/runners.md index 4aa0e4543e5..35c18649fec 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -478,7 +478,7 @@ Example response: ## Delete a registered Runner -Deletes a registed Runner. +Deletes a registered Runner. ``` DELETE /runners diff --git a/doc/api/services.md b/doc/api/services.md index 5d5aa3e5b3e..9275a1ccda8 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -522,6 +522,7 @@ Parameters: | `project_key` | string | yes | The short identifier for your JIRA project, all uppercase, e.g., `PROJ`. | | `username` | string | yes | The username of the user created to be used with GitLab/JIRA. | | `password` | string | yes | The password of the user created to be used with GitLab/JIRA. | +| `active` | boolean | no | Activates or deactivates the service. Defaults to false (deactivated). | | `jira_issue_transition_id` | integer | no | The ID of a transition that moves issues to a closed state. You can find this number under the JIRA workflow administration (**Administration > Issues > Workflows**) by selecting **View** under **Operations** of the desired workflow of your project. The ID of each state can be found inside the parenthesis of each transition name under the **Transitions (id)** column ([see screenshot][trans]). By default, this ID is set to `2`. | ### Delete JIRA service diff --git a/doc/ci/README.md b/doc/ci/README.md index 4e066a0df97..4c3c9920b93 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -5,131 +5,194 @@ description: "Learn how to use GitLab CI/CD, the GitLab built-in Continuous Inte # GitLab Continuous Integration (GitLab CI/CD) - +GitLab provides tools for continuously integrating and delivering code. + +Within the [entire DevOps lifecycle](../README.md#the-entire-devops-lifecycle), GitLab CI/CD spans +the [Verify (CI)](../README.md#verify) and [Release (CD)](../README.md#release) stages. -The benefits of Continuous Integration are huge when automation plays an -integral part of your workflow. GitLab comes with built-in Continuous -Integration, Continuous Deployment, and Continuous Delivery support -to build, test, and deploy your application. +## Overview -Here's some info we've gathered to get you started. +CI/CD is a vast area, so GitLab provides documentation for all levels of expertise. Consult the following table to find the right documentation for you: -## Getting started +| Level of expertise | Resource | +|:------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------| +| New to the concepts of CI and CD | For a high-level overview, see the [GitLab Continuous Integration & Delivery](https://about.gitlab.com/product/continuous-integration/) product page. | +| Familiar with the purpose of CI/CD | Delve into GitLab CI/CD by continuing down the page, starting with our [introduction](#introduction). | +| Familiar with GitLab CI/CD concepts | After getting familiar with GitLab CI/CD, let us walk you through a simple example in our [quick start guide](quick_start/README.md). | +| A GitLab CI/CD expert | Jump straight to our [`.gitlab.yml`](yaml/README.md) reference. | -The first steps towards your GitLab CI/CD journey. +## Introduction -- [Getting started with GitLab CI/CD](quick_start/README.md): understand how GitLab CI/CD works. -- [GitLab CI/CD configuration file: `.gitlab-ci.yml`](yaml/README.md) - Learn all about the ins and outs of `.gitlab-ci.yml`. -- [Pipelines and jobs](pipelines.md): configure your GitLab CI/CD pipelines to build, test, and deploy your application. -- Runners: The [GitLab Runner](https://docs.gitlab.com/runner/) is responsible by running the jobs in your CI/CD pipeline. On GitLab.com, Shared Runners are enabled by default, so -you don't need to set up anything to start to use them with GitLab CI/CD. +The following introduces the process of continuous integration (CI) and continuous delivery (CD): -### Introduction to GitLab CI/CD + -- Article (2016-08-05): [Continuous Integration, Delivery, and Deployment with GitLab - Intro to CI/CD](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) -- Article (2015-12-14): [Getting started with GitLab and GitLab CI - Intro to CI](https://about.gitlab.com/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/) -- Article (2017-07-13): [Making CI Easier with GitLab](https://about.gitlab.com/2017/07/13/making-ci-easier-with-gitlab/) -- Article (2017-05-22): [Fast and Natural Continuous Integration with GitLab CI](https://about.gitlab.com/2017/05/22/fast-and-natural-continuous-integration-with-gitlab-ci/) -- **Videos:** - - Demo (Streamed live on Jul 17, 2017): [GitLab CI/CD Deep Dive](https://youtu.be/pBe4t1CD8Fc?t=195) - - Demo (March, 2017): [How to get started using CI/CD with GitLab](https://about.gitlab.com/2017/03/13/ci-cd-demo/) - - Webcast (April, 2016): [Getting started with CI in GitLab](https://about.gitlab.com/2016/04/20/webcast-recording-and-slides-introduction-to-ci-in-gitlab/) -- **Third-party videos:** - - [Intégration continue avec GitLab (September, 2016)](https://www.youtube.com/watch?v=URcMBXjIr24&t=13s) - - [GitLab CI for Minecraft Plugins (July, 2016)](https://www.youtube.com/watch?v=Z4pcI9F8yf8) +In this illustration: -### Why GitLab CI/CD? +- New code is combined with existing code through a commit to a project's [repository](../user/project/repository/index.md). +- The newly combined code is sent to a CI [pipeline](pipelines.md) where: + - The code is [built](../user/project/pipelines/job_artifacts.md). + - Unit and integration tests are run over the built code. +- Assuming the build and tests are successful, a CD pipeline is triggered to allow for: + - Review using [Review Apps](review_apps/index.md). + - Deploying to configured [environments](environments.md). - - Article (2016-10-17): [Why We Chose GitLab CI for our CI/CD Solution](https://about.gitlab.com/2016/10/17/gitlab-ci-oohlala/) - - Article (2016-07-22): [Building our web-app on GitLab CI: 5 reasons why Captain Train migrated from Jenkins to GitLab CI](https://about.gitlab.com/2016/07/22/building-our-web-app-on-gitlab-ci/) +The benefits of CI/CD are vast, allowing automation to be an integral part of your workflow for testing, building, deploying, and monitoring your code. -## Exploring GitLab CI/CD +Because CI and CD with GitLab is broad topic with many possibilities, the rest of this section provides +links to topics and resources needed to make use of GitLab CI/CD. -- [CI/CD Variables](variables/README.md) - Learn how to use variables defined in - your `.gitlab-ci.yml` or the ones defined in your project's settings - - [Where variables can be used](variables/where_variables_can_be_used.md) - A - deeper look on where and how the CI/CD variables can be used -- **The permissions model** - Learn about the access levels a user can have for - performing certain CI actions - - [User permissions](../user/permissions.md#gitlab-ci) - - [Job permissions](../user/permissions.md#job-permissions) -- [Configure a Runner, the application that runs your jobs](runners/README.md) -- Article (2016-03-01): [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/) -- Article (2016-07-29): [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/) -- Article (2016-08-26): [GitLab CI: Deployment & environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) -- Article (2016-05-23): [Introduction to GitLab Container Registry](https://about.gitlab.com/2016/05/23/gitlab-container-registry/) +## Essentials -## Advanced use +The following documentation provides the minimum required knowledge for making use of GitLab CI/CD: -Once you get familiar with the basics of GitLab CI/CD, it's time to dive in and -learn how to leverage its potential even more. +| Topic | Description | +|:------------------------------------------------------------------------|:---------------------------------------------------------| +| [Getting started with GitLab CI/CD](quick_start/README.md) | Outlines the first steps for configuring GitLab CI/CD. | +| [Introduction to pipelines and jobs](pipelines.md) | Provides an overview of GitLab CI/CD and jobs. | +| [Configuration of your pipelines with `.gitlab-ci.yml`](yaml/README.md) | A comprehensive reference for the `.gitlab-ci.yml` file. | -- [Environments and deployments](environments.md): Separate your jobs into - environments and use them for different purposes like testing, building and - deploying -- [Job artifacts](../user/project/pipelines/job_artifacts.md) -- [Caching dependencies](caching/index.md) -- [Git submodules](git_submodules.md) - How to run your CI jobs when Git - submodules are involved -- [Pipelines for merge requests](merge_request_pipelines/index.md) -- [Use SSH keys in your build environment](ssh_keys/README.md) -- [Trigger pipelines through the GitLab API](triggers/README.md) -- [Trigger pipelines on a schedule](../user/project/pipelines/schedules.md) -- [Kubernetes clusters](../user/project/clusters/index.md) - Integrate one or - more Kubernetes clusters to your project -- [Interactive web terminal](interactive_web_terminal/index.md) - Open an interactive - web terminal to debug the running jobs +NOTE: **Note:** +Familiarity with [GitLab Runner](https://docs.gitlab.com/runner/) is useful because it is +responsible for running the jobs in your CI/CD pipeline. On GitLab.com, shared Runners are enabled +by default so you don't need to set up anything to get started. -## GitLab CI/CD for Docker +### Auto DevOps -Leverage the power of Docker to run your CI pipelines. +An alternative to manually configuring CI/CD, GitLab supports [Auto DevOps](../topics/autodevops/index.md), +which: -- [Use Docker images with GitLab Runner](docker/using_docker_images.md) -- [Use CI to build Docker images](docker/using_docker_build.md) -- [CI services (linked Docker containers)](services/README.md) -- Article (2016-03-01): [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/) +- Provides simplified setup and execution of CI/CD. +- Allows GitLab to automatically detect, build, test, deploy, and monitor your applications. -## Review Apps +## Basic usage -- [Review Apps documentation](review_apps/index.md) -- Article (2016-11-22): [Introducing Review Apps](https://about.gitlab.com/2016/11/22/introducing-review-apps/) -- [Example project that shows how to use Review Apps](https://gitlab.com/gitlab-examples/review-apps-nginx/) +With basic knowledge of how GitLab CI/CD works, the following documentation extends your knowledge +into more features: -## Auto DevOps +| Topic | Description | +|:-------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------| +| [CI/CD Variables](variables/README.md) | How environment variables can be configured and made available in pipelines. | +| [Where variables can be used](variables/where_variables_can_be_used.md) | A deeper look into where and how CI/CD variables can be used. | +| [User](../user/permissions.md#gitlab-ci) and [job](../user/permissions.md#job-permissions) permissions | Learn about the access levels a user can have for performing certain CI actions. | +| [Configuring GitLab Runners](runners/README.md) | Documentation for configuring [GitLab Runner](https://docs.gitlab.com/runner/). | -- [Auto DevOps](../topics/autodevops/index.md): Auto DevOps automatically detects, builds, tests, deploys, and monitors your applications. +## Advanced usage -## GitLab CI for GitLab Pages +Once you get familiar with the basics of GitLab CI/CD, consult the following documentation to make +use of advanced features: -See the documentation on [GitLab Pages](../user/project/pages/index.md). +| Topic | Description | +|:---------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------| +| [Introduction to environments and deployments](environments.md) | Learn how to separate your jobs into environments and use them for different purposes like testing, building and, deploying. | +| [Job artifacts](../user/project/pipelines/job_artifacts.md) | Learn about the output of jobs. | +| [Cache dependencies in GitLab CI/CD](caching/index.md) | Discover how to speed up pipelines using caching. | +| [Using Git submodules with GitLab CI](git_submodules.md) | How to run your CI jobs when using Git submodules. | +| [Pipelines for merge requests](merge_request_pipelines/index.md) | Create pipelines specifically for merge requests. | +| [Using SSH keys with GitLab CI/CD](ssh_keys/README.md) | Use SSH keys in your build environment. | +| [Triggering pipelines through the API](triggers/README.md) | Use the GitLab API to trigger a pipeline. | +| [Pipeline schedules](../user/project/pipelines/schedules.md) | Trigger pipelines on a schedule. | +| [Connecting GitLab with a Kubernetes cluster](../user/project/clusters/index.md) | Integrate one or more Kubernetes clusters to your project. | +| [ChatOps](chatops/README.md) | Trigger CI jobs from chat, with results sent back to the channel. | +| [Interactive web terminals](interactive_web_terminal/index.md) | Open an interactive web terminal to debug the running jobs. | + +### GitLab Pages + +GitLab CI/CD can be used to build and host static websites. For more information, see the +documentation on [GitLab Pages](../user/project/pages/index.md). ## Examples -Check the [GitLab CI/CD examples](examples/README.md) for a collection of tutorials and guides on setting up your CI/CD pipeline for various programming languages, frameworks, -and operating systems. +Check out the [GitLab CI/CD examples](examples/README.md) for a collection of tutorials and guides on +setting up your CI/CD pipeline for various programming languages, frameworks, and operating systems. + +## Administration + +As a GitLab administrator, you can change the default behavior of GitLab CI/CD for: + +- An [entire GitLab instance](../user/admin_area/settings/continuous_integration.md). +- Specific projects, using [pipelines settings](../user/project/pipelines/settings.md). + +See also: + +- [How to enable or disable GitLab CI/CD](enable_or_disable_ci.md). +- Other [CI administration settings](../administration/index.md#continuous-integration-settings). + +## Using Docker + +Docker is commonly used with GitLab CI/CD. Learn more about how to to accomplish this with the following +documentation: + +| Topic | Description | +|:-------------------------------------------------------------------------|:-------------------------------------------------------------------------| +| [Using Docker images](docker/using_docker_images.md) | Use GitLab and GitLab Runner with Docker to build and test applications. | +| [Building Docker images with GitLab CI/CD](docker/using_docker_build.md) | Maintain Docker-based projects using GitLab CI/CD. | + +Related topics include: -## Integrations +- [Docker integration](docker/README.md). +- [CI services (linked Docker containers)](services/README.md). +- [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/) (article). -- Article (2016-06-09): [Continuous Delivery with GitLab and Convox](https://about.gitlab.com/2016/06/09/continuous-delivery-with-gitlab-and-convox/) -- Article (2016-05-05): [Getting Started with GitLab and Shippable Continuous Integration](https://about.gitlab.com/2016/05/05/getting-started-gitlab-and-shippable/) -- Article (2016-04-19): [GitLab Partners with DigitalOcean to make Continuous Integration faster, safer, and more affordable](https://about.gitlab.com/2016/04/19/gitlab-partners-with-digitalocean-to-make-continuous-integration-faster-safer-and-more-affordable/) +## Further resources -## Special configuration (GitLab admin) +This section provides further resources to help you get familiar with GitLab CI/CD. -As a GitLab administrator, you can change the default behavior of GitLab CI/CD in -your whole GitLab instance as well as in each project. +### Articles -- [Continuous Integration admin settings](../administration/index.md#continuous-integration-settings) -- **Project specific:** - - [Pipelines settings](../user/project/pipelines/settings.md) - - [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md) -- **Affecting the whole GitLab instance:** - - [Continuous Integration admin settings](../user/admin_area/settings/continuous_integration.md) +The following table provides a list of articles about CI/CD, sorted in reverse chronological order of publish date: + +| Publish Date | Article | +|:-------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 2017-07-13 | [Making CI easier with GitLab](https://about.gitlab.com/2017/07/13/making-ci-easier-with-gitlab/). | +| 2017-05-22 | [Fast and natural continuous integration with GitLab CI](https://about.gitlab.com/2017/05/22/fast-and-natural-continuous-integration-with-gitlab-ci/). | +| 2016-11-22 | [Introducing Review Apps](https://about.gitlab.com/2016/11/22/introducing-review-apps/). | +| 2016-08-26 | [GitLab CI: Deployment & Environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/). | +| 2016-08-05 | [Continuous Integration, Delivery, and Deployment with GitLab](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/). | +| 2016-07-29 | [GitLab CI: Run jobs sequentially, in parallel or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/). | +| 2016-06-09 | [Continuous Delivery with GitLab and Convox](https://about.gitlab.com/2016/06/09/continuous-delivery-with-gitlab-and-convox/) | +| 2016-05-23 | [GitLab Container Registry](https://about.gitlab.com/2016/05/23/gitlab-container-registry/). | +| 2016-05-05 | [Getting Started with GitLab and Shippable Continuous Integration](https://about.gitlab.com/2016/05/05/getting-started-gitlab-and-shippable/) | +| 2016-04-19 | [GitLab Partners with DigitalOcean to make Continuous Integration faster, safer, and more affordable](https://about.gitlab.com/2016/04/19/gitlab-partners-with-digitalocean-to-make-continuous-integration-faster-safer-and-more-affordable/) | +| 2015-03-01 | [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/). | +| 2015-12-14 | [Getting started with GitLab and GitLab CI](https://about.gitlab.com/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/). | + +### Videos + +The following table provides a list of videos about CI/CD, sorted in reverse chronological order of publish date: + +| Publish Date | Video | +|:-------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 2017-07-17 | [GitLab CI/CD Deep Dive](https://youtu.be/pBe4t1CD8Fc?t=195). | +| 2017-03-13 | [Demo: CI/CD with GitLab in action](https://about.gitlab.com/2017/03/13/ci-cd-demo/). | +| 2016-04-20 | [Webcast Recording and Slides: Getting started with CI in GitLab](https://about.gitlab.com/2016/04/20/webcast-recording-and-slides-introduction-to-ci-in-gitlab/). | + +In addition, the following third-party videos are available: + +- [Intégration continue avec GitLab (September 2016)](https://www.youtube.com/watch?v=URcMBXjIr24&t=13s). +- [GitLab CI for Minecraft Plugins (July 2016)](https://www.youtube.com/watch?v=Z4pcI9F8yf8). + +### Example Projects + +[`review-apps-nginx`](https://gitlab.com/gitlab-examples/review-apps-nginx/) provides an example of using Review Apps. + +Other example projects are available at the [`gitlab-examples`](https://gitlab.com/gitlab-examples) group. + +### Why GitLab CI/CD? + +The following articles explain reasons why you might use GitLab CI/CD for your CI/CD infrastructure: + +- [Why we chose GitLab CI for our CI/CD solution](https://about.gitlab.com/2016/10/17/gitlab-ci-oohlala/). +- [Building our web-app on GitLab CI](https://about.gitlab.com/2016/07/22/building-our-web-app-on-gitlab-ci/). + +See also the [Why CI/CD?](https://docs.google.com/presentation/d/1OGgk2Tcxbpl7DJaIOzCX4Vqg3dlwfELC3u2jEeCBbDk) presentation. ## Breaking changes -- [CI variables renaming for GitLab 9.0](variables/README.md#9-0-renaming) Read about the +As GitLab CI/CD has evolved, certain breaking changes have been necessary. These are: + +- [CI variables renaming for GitLab 9.0](variables/README.md#gitlab-90-renaming). Read about the deprecated CI variables and what you should use for GitLab 9.0+. -- [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. +- [New CI job permissions model](../user/project/new_ci_build_permissions_model.md). + See 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. diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index dbe3d9b62c9..e079483e2b5 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -52,7 +52,7 @@ 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 +[expiry time](../yaml/README.md#artifactsexpire_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. @@ -87,7 +87,7 @@ cache, when declaring `cache` in your jobs, use one or a mix of the following: that share their cache. - [Use sticky Runners](../runners/README.md#locking-a-specific-runner-from-being-enabled-for-other-projects) that will be only available to a particular project. -- [Use a `key`](../yaml/README.md#cache-key) that fits your workflow (e.g., +- [Use a `key`](../yaml/README.md#cachekey) that fits your workflow (e.g., different caches on each branch). For that, you can take advantage of the [CI/CD predefined variables](../variables/README.md#predefined-environment-variables). @@ -169,7 +169,7 @@ job: ``` For more fine tuning, read also about the -[`cache: policy`](../yaml/README.md#cache-policy). +[`cache: policy`](../yaml/README.md#cachepolicy). ## Common use cases diff --git a/doc/ci/chatops/README.md b/doc/ci/chatops/README.md new file mode 100644 index 00000000000..6ad1df7bb2a --- /dev/null +++ b/doc/ci/chatops/README.md @@ -0,0 +1,61 @@ +# GitLab ChatOps + +> **Notes:** +> +> * [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24780) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. +> +> * ChatOps is currently in alpha, with some important features missing like access control. + +GitLab ChatOps provides a method to interact with CI/CD jobs through chat services like Slack. Many organizations' discussion, collaboration, and troubleshooting is taking place in chat services these days, and having a method to run CI/CD jobs with output posted back to the channel can significantly augment a team's workflow. + +## How it works + +GitLab ChatOps is built upon two existing features, [GitLab CI/CD](../README.md) and [Slack Slash Commmands](../../user/project/integrations/slack_slash_commands.md). + +A new `run` action has been added to the [slash commands](../../integration/slash_commands.md), which takes two arguments: a `<job name>` to execute and the `<job arguments>`. When executed, ChatOps will look up the specified job name and attempt to match it to a corresponding job in [.gitlab-ci.yml](../yaml/README.md). If a matching job is found on `master`, a pipeline containing just that job is scheduled. Two additional [CI/CD variables](../variables/README.html#predefined-variables-environment-variables) are passed to the job: `CHAT_INPUT` contains any additional arguments, and `CHAT_CHANNEL` is set to the name of channel the action was triggered in. + +After the job has finished, its output is sent back to Slack provided it has completed within 30 minutes. If a job takes more than 30 minutes to run it must use the Slack API to manually send data back to a channel. + +[Developer access and above](../../user/permissions.html#project-members-permissions) is required to use the `run` command. If a job should not be able to be triggered from chat, it can be set to `except: [chat]`. + +## Creating a ChatOps CI job + +Since ChatOps is built upon GitLab CI/CD, the job has all the same features and functions available. There a few best practices to consider however when creating ChatOps jobs: + +* It is strongly recommended to set `only: [chat]` so the job does not run as part of the standard CI pipeline. +* If the job is set to `when: manual`, the pipeline will be created however the job will wait to be started. +* It is important to keep in mind that there is very limited support for access control. If the user who triggered the slash command is a developer in the project, the job will run. The job itself can utilize existing [CI/CD variables](../variables/README.html#predefined-environment-variables) like `GITLAB_USER_ID` to perform additional rights validation, however these variables can be [overridden](https://docs.gitlab.com/ce/ci/variables/README.html#priority-of-variables). + +### Controlling the ChatOps reply + +For jobs with a single command, its output is automatically sent back to the channel as a reply. For example the chat reply of the following job is simply `Hello World.` + +```yaml +hello-world: + stage: chatops + only: [chat] + script: + - echo "Hello World." +``` + +Jobs that contain multiple commands, or have a `before_script`, include additional content in the chat reply. In these cases both the commands and their output are included, with the commands wrapped in ANSI colors codes. + +To selectively reply with the output of one command, its output must be bounded by the `chat_reply` section. For example, the following job will list the files in the current directory. + +```yaml +ls: + stage: chatops + only: [chat] + script: + - echo "This command will not be shown." + - echo -e "section_start:$( date +%s ):chat_reply\r\033[0K\n$( ls -la )\nsection_end:$( date +%s ):chat_reply\r\033[0K" +``` + +## GitLab ChatOps icon + +Say Hi to our ChatOps bot. +You can find and download the official GitLab ChatOps icon here. + + + +[Download bigger image](img/gitlab-chatops-icon.png) diff --git a/doc/ci/chatops/img/gitlab-chatops-icon-small.png b/doc/ci/chatops/img/gitlab-chatops-icon-small.png Binary files differnew file mode 100644 index 00000000000..71cc5dba5cf --- /dev/null +++ b/doc/ci/chatops/img/gitlab-chatops-icon-small.png diff --git a/doc/ci/chatops/img/gitlab-chatops-icon.png b/doc/ci/chatops/img/gitlab-chatops-icon.png Binary files differnew file mode 100644 index 00000000000..3ba8bd308e3 --- /dev/null +++ b/doc/ci/chatops/img/gitlab-chatops-icon.png diff --git a/doc/ci/docker/README.md b/doc/ci/docker/README.md index 8ae80b2bc02..446f5b54f0c 100644 --- a/doc/ci/docker/README.md +++ b/doc/ci/docker/README.md @@ -4,6 +4,8 @@ comments: false # Docker integration -- [Using Docker Images](using_docker_images.md) -- [Using Docker Build](using_docker_build.md) -- [Using kaniko](using_kaniko.md) +The following documentation is available for using GitLab CI/CD with Docker: + +- [Using Docker images](using_docker_images.md). +- [Building Docker images with GitLab CI/CD](using_docker_build.md). +- [Building images with kaniko and GitLab CI/CD](using_kaniko.md). diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 959271d8abc..3314c76d234 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -391,9 +391,9 @@ CI jobs: from `Dockerfile` that may be overridden in `.gitlab-ci.yml`) 1. The Runner attaches itself to a running container. 1. The Runner prepares a script (the combination of - [`before_script`](../yaml/README.md#before_script), + [`before_script`](../yaml/README.md#before_script-and-after_script), [`script`](../yaml/README.md#script), - and [`after_script`](../yaml/README.md#after_script)). + and [`after_script`](../yaml/README.md#before_script-and-after_script)). 1. The Runner sends the script to the container's shell STDIN and receives the output. diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 6a9917f6430..fe66f7e3c28 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -103,7 +103,7 @@ the Git SHA and environment name. To sum up, with the above `.gitlab-ci.yml` we have achieved that: - All branches will run the `test` and `build` jobs. -- The `deploy_staging` job will run [only](yaml/README.md#only) on the `master` +- The `deploy_staging` job will run [only](yaml/README.md#only-and-except-simplified) on the `master` branch which means all merge requests that are created from branches don't get to deploy to the staging server - When a merge request is merged, all jobs will run and the `deploy_staging` @@ -401,7 +401,7 @@ Let's briefly see where URL that's defined in the environments is exposed. ## Making use of the environment URL -The [environment URL](yaml/README.md#environments-url) is exposed in a few +The [environment URL](yaml/README.md#environmenturl) is exposed in a few places within GitLab. | In a merge request widget as a link | In the Environments view as a button | In the Deployments view as a button | @@ -619,9 +619,9 @@ Below are some links you may find interesting: [deployments]: #deployments [permissions]: ../user/permissions.md [variables]: variables/README.md -[env-name]: yaml/README.md#environment-name -[only]: yaml/README.md#only-and-except -[onstop]: yaml/README.md#environment-on_stop +[env-name]: yaml/README.md#environmentname +[only]: yaml/README.md#only-and-except-simplified +[onstop]: yaml/README.md#environmenton_stop [ce-7015]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7015 [gitlab-flow]: ../workflow/gitlab_flow.md [gitlab runner]: https://docs.gitlab.com/runner/ diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/index.md b/doc/ci/examples/end_to_end_testing_webdriverio/index.md index 9f3b8d9ad14..d7afe11f41f 100644 --- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -89,7 +89,7 @@ page and to interact with them - for example, to click on the link back to the h The simple test shown above can already give us a lot of confidence if it passes: we know our deployment has succeeded, that the elements are visible on the page and that actual browsers can interact with it, and that routing -works as expected. And all that in just 10 lines with gratituous whitespace! Add to that succeeding +works as expected. And all that in just 10 lines with gratuitous whitespace! Add to that succeeding unit tests and a successfully completed pipeline, and you can be fairly confident that the dependency upgrade did not break anything without even having to look at your website. 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 c0346d78141..f24e79355aa 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 @@ -75,7 +75,7 @@ When we call `mix` command, we'll pass two arguments: - The task we want it to run: `phoenix.new` - And the parameter `phoenix.new` requires, which is the name of the new project. In this case, -we're calling it `hello_gitlab_ci`, but you're free to set your own name: + we're calling it `hello_gitlab_ci`, but you're free to set your own name: ```bash mix phoenix.new hello_gitlab_ci @@ -249,7 +249,7 @@ project.  - On next screen, we can select a template ready to go. Click on **Apply a GitLab CI/CD Yaml -template** and select **Elixir**: + template** and select **Elixir**:  diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index b7b5c660586..2af0a03cbe4 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -106,10 +106,10 @@ flow, external contributors follow the following steps: 1. Fork a parent project. 1. Create a merge request from the forked project that targets the `master` branch -in the parent project. + in the parent project. 1. A pipeline runs on the merge request. 1. A maintainer from the parent project checks the pipeline result, and merge -into a target branch if the latest pipeline has passed. + into a target branch if the latest pipeline has passed. Currently, those pipelines are created in a **forked** project, not in the parent project. This means you cannot completely trust the pipeline result, diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index c41f3b7e82d..4f3106c6dc6 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -197,7 +197,7 @@ stage has a job with a manual action. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21767) in GitLab 11.4. -When you do not want to run a job immediately, you can [delay the job to run after a certain period](yaml/README.md#when-delayed). +When you do not want to run a job immediately, you can [delay the job to run after a certain period](yaml/README.md#whendelayed). This is especially useful for timed incremental rollout that new code is rolled out gradually. For example, if you start rolling out new code and users do not experience trouble, GitLab automatically completes the deployment from 0% to 100%. Alternatively, if you start rolling out and you noticed that a few users experience trouble with the version, diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index 0c3b0bf6990..ff63d0bd69f 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -92,7 +92,7 @@ to access it. This is where an SSH key pair comes in handy. ``` NOTE: **Note:** - The [`before_script`](../yaml/README.md#before-script) can be set globally + The [`before_script`](../yaml/README.md#before_script-and-after_script) can be set globally or per-job. 1. Make sure the private server's [SSH host keys are verified](#verifying-the-ssh-host-keys). diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 7498617ed2c..ca668ac526f 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -53,6 +53,8 @@ future GitLab releases.** | Variable | GitLab | Runner | Description | |-------------------------------------------|--------|--------|-------------| | **ARTIFACT_DOWNLOAD_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to download artifacts running a job | +| **CHAT_INPUT** | 10.6 | all | Additional arguments passed in the [ChatOps](../chatops/README.md) command | +| **CHAT_CHANNEL** | 10.6 | all | Source chat channel which triggered the [ChatOps](../chatops/README.md) command | | **CI** | all | 0.4 | Mark that job is executed in CI environment | | **CI_COMMIT_BEFORE_SHA** | 11.2 | all | The previous latest commit present on a branch before a push request. | | **CI_COMMIT_DESCRIPTION** | 10.8 | all | The description of the commit: the message without first line, if the title is shorter than 100 characters; full message in other case. | diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 31f99cd5e68..e5668c140fa 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -1,7 +1,7 @@ -# Configuration of your jobs with .gitlab-ci.yml +# Configuration of your pipelines with .gitlab-ci.yml This document describes the usage of `.gitlab-ci.yml`, the file that is used by -GitLab Runner to manage your project's jobs. +GitLab Runner to manage your project's pipelines. From version 7.12, GitLab CI uses a [YAML](https://en.wikipedia.org/wiki/YAML) file (`.gitlab-ci.yml`) for the project configuration. It is placed in the root @@ -1206,7 +1206,7 @@ job: `expire_in` allows you to specify how long artifacts should live before they expire and therefore deleted, counting from the time they are uploaded and stored on GitLab. If the expiry time is not defined, it defaults to the -[instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration) +[instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration-core-only) (30 days by default, forever on GitLab.com). You can use the **Keep** button on the job page to override expiration and @@ -1245,7 +1245,7 @@ this with [JUnit reports](#artifactsreportsjunit). NOTE: **Note:** The test reports are collected regardless of the job results (success or failure). -You can use [`artifacts:expire_in`](#artifacts-expire_in) to set up an expiration +You can use [`artifacts:expire_in`](#artifactsexpire_in) to set up an expiration date for their artifacts. NOTE: **Note:** @@ -1425,7 +1425,7 @@ deploy: > Introduced in GitLab 10.3. If the artifacts of the job that is set as a dependency have been -[expired](#artifacts-expire_in) or +[expired](#artifactsexpire_in) or [erased](../../user/project/pipelines/job_artifacts.md#erasing-artifacts), then the dependent job will fail. diff --git a/doc/customization/system_header_and_footer_messages.md b/doc/customization/system_header_and_footer_messages.md new file mode 100644 index 00000000000..cf7d8b3f3e8 --- /dev/null +++ b/doc/customization/system_header_and_footer_messages.md @@ -0,0 +1,18 @@ +# Adding a system message to every page + +> [Introduced][ee-1283] in [GitLab Premium][eep] 10.7. + +Navigate to the **Admin** area and go to the **Appearance** page. + +Under **System header and footer** insert your header message and/or footer message. +Both background and font color of the header and footer are customizable. + + + +After saving, all GitLab pages will contain the custom system header and/or footer messages: + + + +The GitLab sign in page will also show the header and the footer messages: + + diff --git a/doc/customization/system_header_and_footer_messages/appearance.png b/doc/customization/system_header_and_footer_messages/appearance.png Binary files differnew file mode 100644 index 00000000000..14667f751c4 --- /dev/null +++ b/doc/customization/system_header_and_footer_messages/appearance.png diff --git a/doc/customization/system_header_and_footer_messages/custom_header_footer.png b/doc/customization/system_header_and_footer_messages/custom_header_footer.png Binary files differnew file mode 100644 index 00000000000..691ca8a3484 --- /dev/null +++ b/doc/customization/system_header_and_footer_messages/custom_header_footer.png diff --git a/doc/customization/system_header_and_footer_messages/sign_up_custom_header_and_footer.png b/doc/customization/system_header_and_footer_messages/sign_up_custom_header_and_footer.png Binary files differnew file mode 100644 index 00000000000..a9c59bc9f62 --- /dev/null +++ b/doc/customization/system_header_and_footer_messages/sign_up_custom_header_and_footer.png diff --git a/doc/development/architecture.md b/doc/development/architecture.md index 63574b28edc..e22552fd3a3 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -58,7 +58,7 @@ GitLab can be considered to have two layers from a process perspective: - [Omnibus configuration options](https://gitlab.com/gitlab-org/gitaly/tree/master/doc/configuration) - Layer: Core Service (Data) -Gitaly is a service designed by GitLab to remove our need for NFS for Git storage in distributed deployments of GitLab. (Think GitLab.com or High Availablity Deployments) As of 11.3.0, This service handles all Git level access in GitLab. You can read more about the project [in the project's readme](https://gitlab.com/gitlab-org/gitaly). +Gitaly is a service designed by GitLab to remove our need for NFS for Git storage in distributed deployments of GitLab (Think GitLab.com or High Availability Deployments). As of 11.3.0, this service handles all Git level access in GitLab. You can read more about the project [in the project's readme](https://gitlab.com/gitlab-org/gitaly). ### gitlab-monitor @@ -174,7 +174,7 @@ When making a request to an HTTP Endpoint (Think `/users/sign_in`) the request w - nginx - Acts as our first line reverse proxy - gitlab-workhorse - This determines if it needs to go to the Rails application or somewhere else to reduce load on unicorn. - unicorn - Since this is a web request, and it needs to access the application it will go to Unicorn. -- Postgres/Gitaly/Redis - Depending on the type of request, it may hit these services to store or retreive data. +- Postgres/Gitaly/Redis - Depending on the type of request, it may hit these services to store or retrieve data. ### GitLab Git Request Cycle diff --git a/doc/development/automatic_ce_ee_merge.md b/doc/development/automatic_ce_ee_merge.md index fed772b9240..3ca841353e6 100644 --- a/doc/development/automatic_ce_ee_merge.md +++ b/doc/development/automatic_ce_ee_merge.md @@ -115,16 +115,16 @@ Now, every time you create an MR for CE and EE: 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" + description "Ports [CE-MR-LINK] to EE" 1. Once all the jobs are passing in both CE and EE, you've addressed the -feedback from your own team, and got them approved, the merge requests can be merged. + feedback from your own team, and got them approved, the merge requests can be merged. 1. When both MRs are ready, the EE merge request will be merged first, and the -CE-equivalent will be merged next. + CE-equivalent will be merged next. **Important notes:** - The commit SHA can be easily found from the GitLab UI. From a merge request, -open the tab **Commits** and click the copy icon to copy the commit SHA. + open the tab **Commits** and click the copy icon to copy the commit SHA. - To cherry-pick a **commit range**, such as [A > B > C > D] use: ```shell @@ -140,7 +140,7 @@ open the tab **Commits** and click the copy icon to copy the commit SHA. ``` - To cherry-pick a **merge commit**, use the flag `-m 1`. For example, suppose that the -merge commit SHA is `138f5e2f20289bb376caffa0303adb0cac859ce1`: + merge commit SHA is `138f5e2f20289bb376caffa0303adb0cac859ce1`: ```shell git cherry-pick -m 1 138f5e2f20289bb376caffa0303adb0cac859ce1 @@ -163,12 +163,12 @@ merge commit SHA is `138f5e2f20289bb376caffa0303adb0cac859ce1`: commits and you want to cherry-pick all but the merge commit. - If you push more commits to the CE branch, you can safely repeat the procedure -to cherry-pick them to the EE-equivalent branch. You can do that as many times as -necessary, using the same CE and EE branches. + to cherry-pick them to the EE-equivalent branch. You can do that as many times as + necessary, using the same CE and EE branches. - If you submitted the merge request to the CE repo and the `ee-compat-check` job passed, -you are not required to submit the EE-equivalent MR, but it's still recommended. If the -job failed, you are required to submit the EE MR so that you can fix the conflicts in EE -before merging your changes into CE. + you are not required to submit the EE-equivalent MR, but it's still recommended. If the + job failed, you are required to submit the EE MR so that you can fix the conflicts in EE + before merging your changes into CE. ## FAQ diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 7ac846e4c4d..f7a0fdbeb40 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -4,7 +4,7 @@ Thank you for your interest in contributing to GitLab. This guide details how to contribute to GitLab in a way that is easy for everyone. We want to create a welcoming environment for everyone who is interested in contributing. -Please visit our [Code of Conduct page](https://about.gitlab.com/contributing/code-of-conduct) to learn more about our committment to an open and welcoming environment. +Please visit our [Code of Conduct page](https://about.gitlab.com/contributing/code-of-conduct) to learn more about our commitment to an open and welcoming environment. For a first-time step-by-step guide to the contribution process, please 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 c5344139ab4..4c53643ed9c 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -199,7 +199,7 @@ different way. We add the ~"Accepting merge requests" label to: - Low priority ~bug issues (i.e. we do not add it to the bugs that we want to -solve in the ~"Next Patch Release") + solve in the ~"Next Patch Release") - Small ~feature - Small ~"technical debt" issues @@ -300,17 +300,17 @@ below will make it easy to manage this, without unnecessary overhead. 1. Set weight for any issue at the earliest possible convenience 1. If you don't agree with a set weight, discuss with other developers until -consensus is reached about the weight + consensus is reached about the weight 1. Issue weights are an abstract measurement of complexity of the issue. Do not -relate issue weight directly to time. This is called [anchoring](https://en.wikipedia.org/wiki/Anchoring) -and something you want to avoid. + relate issue weight directly to time. This is called [anchoring](https://en.wikipedia.org/wiki/Anchoring) + and something you want to avoid. 1. Something that has a weight of 1 (or no weight) is really small and simple. -Something that is 9 is rewriting a large fundamental part of GitLab, -which might lead to many hard problems to solve. Changing some text in GitLab -is probably 1, adding a new Git Hook maybe 4 or 5, big features 7-9. + Something that is 9 is rewriting a large fundamental part of GitLab, + which might lead to many hard problems to solve. Changing some text in GitLab + is probably 1, adding a new Git Hook maybe 4 or 5, big features 7-9. 1. If something is very large, it should probably be split up in multiple -issues or chunks. You can simply not set the weight of a parent issue and set -weights to children issues. + issues or chunks. You can simply not set the weight of a parent issue and set + weights to children issues. ## Regression issues diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index b5b325683a3..3f31fe5ca19 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -2,111 +2,178 @@ description: How to add docs for new or enhanced GitLab features. --- -# Documentation process at GitLab +# Documentation process for feature changes At GitLab, developers contribute new or updated documentation along with their code, but product managers and technical writers also have essential roles in the process. - **Developers**: Author/update documentation in the same MR as their code, and -merge it by the feature freeze for the assigned milestone. Request technical writer -assistance if needed. + merge it by the feature freeze for the assigned milestone. Request technical writer + assistance if needed. Other developers typically act as reviewers. - **Product Managers** (PMs): In the issue for all new and enhanced features, -confirm the documentation requirements, plus the mentioned feature description -and use cases, which can be reused in docs. They can bring in a technical -writer for discussion or help, and can be called upon themselves as a doc reviewer. + confirm the documentation requirements, plus the mentioned feature description + and use cases, which can be reused in docs. They can bring in a technical + writer for discussion or collaboration, and can be called upon themselves as a doc reviewer. - **Technical Writers**: Review doc requirements in issues, track issues and MRs -that contain docs changes, help with any questions throughout the authoring/editing process, -and review all new and updated docs content after it's merged (unless a pre-merge -review request is made). + that contain docs changes, help with any questions throughout the authoring/editing process, + work on special projects related to the documentation, and review all new and updated + docs content, whether before or after it is merged. -Beyond this process, any member of the GitLab community can also author documentation +Beyond this process, any member of the GitLab community can also author or request documentation improvements that are not associated with a new or changed feature. See the [Documentation improvement workflow](improvement-workflow.md). ## When documentation is required Documentation must be delivered whenever: -- A new or enhanced feature is shipped that impacts the user/admin experience -- There are changes to the UI or API -- A process, workflow, or previously documented feature is changed -- A feature is deprecated or removed +- A new or enhanced feature is shipped that impacts the user/admin experience. +- There are changes to the UI or API. +- A process, workflow, or previously documented feature is changed. +- A feature is deprecated or removed. + +For example, a UI restyling that offers no difference in functionality may require +documentation updates if screenshots are now needed, or need to be updated. Documentation is not required when a feature is changed on the backend -only and does not directly affect the way that any user or -administrator would interact with GitLab. For example, a UI restyling that offers -no difference in functionality may require documentation updates if screenshots -are now needed, or need to be updated. +only and does not directly affect the way that any user or administrator would +interact with GitLab. NOTE: **Note:** When revamping documentation, if unrelated to the feature change, this should be submitted in its own MR (using the [documentation improvement workflow](improvement-workflow.md)) so that we can ensure the more time-sensitive doc updates are merged with code by the freeze. +## Documentation requirements in feature issues + +Requirements for the documentation of a feature should be included as part of the +issue for planning that feature, in a Documentation section within the issue description. + +This section is provided as part of the Feature Proposal template and should be added +to the issue if it is not already present. + +Anyone can add these details, but the product manager who assigns the issue to a specific release +milestone will ensure these details are present and finalized by the time of that milestone's kickoff. +Developers, technical writers, and others may help further refine this plan at any time. + +### Details to include + +- What concepts and procedures should the docs guide and enable the user to understand or accomplish? +- To this end, what new page(s) are needed, if any? What pages/subsections need updates? Consider user, admin, and API doc changes and additions. +- For any guide or instruction set, should it help address a single use case, or be flexible to address a certain range of use cases? +- Do we need to update a previously recommended workflow? Should we link the new feature from various relevant locations? Consider all ways documentation should be affected. +- Are there any key terms or task descriptions that should be included so that the docs are found in relevant searches? +- Include suggested titles of any pages or subsections, if applicable. + ## Documenting a new or changed feature To follow a consistent workflow every month, documentation changes involve the Product Managers, the developer who shipped the feature, -and the Technical Writing team. Each role is described below. +and the technical writer for the DevOps stage. Each role is described below. + +The Documentation items in the GitLab CE/EE [Feature Proposal issue template](https://gitlab.com/gitlab-org/gitlab-ce/raw/template-improvements-for-documentation/.gitlab/issue_templates/Feature%20proposal.md) +and default merge request template will assist you with following this process. + +### Product Manager role -### 1. Product Manager's role +For issues requiring any new or updated documentation, the Product Manager (PM) +must: -The Product Manager (PM) should confirm or add the following items in the issue: +- Add the `Documentation` label. +- Confirm or add the [documentation requirements](#documentation-requirements). +- Ensure the issue contains any new or updated feature name, overview/description, + and use cases, as required per the [documentation structure and template](structure.md), when applicable. -- New or updated feature name, overview/description, and use cases, all required per the [Documentation structure and template](structure.md). -- The documentation requirements for the developer working on the docs. - - What new page, new subsection of an existing page, or other update to an existing page/subsection is needed. - - Just one page/section/update or multiple (perhaps there's an end user and admin change needing docs, or we need to update a previously recommended workflow, or we want to link the new feature from various places; consider and mention all ways documentation should be affected. - - Suggested title of any page or subsection, if applicable. -- Label the issue with `Documentation` and `docs:P1` in addition to the `Deliverable` label and correct milestone. +Everyone is encouraged to draft the requirements in the issue, but a product manager will +do the following: -Anyone is welcome to draft the items above in the issue, but a product manager must review and update them whenever the issue is assigned a specific milestone. +- When the issue is assigned a release milestone, review and update the Documentation details. +- By the kickoff, finalizie the Documentation details. -### 2. Developer's role +### Developer and maintainer roles + +#### Authoring As a developer, you must ship the documentation with the code of the feature that you are creating or updating. The documentation is an essential part of the product. +Technical writers are happy to help, as requested and planned on an issue-by-issue basis. + +Follow the process below unless otherwise agreed with the product manager and technical writer for a given issue: -- New and edited docs should be included in the MR introducing the code, and planned -in the issue that proposed the feature. However, if the new or changed doc requires -extensive collaboration or conversation, a separate, linked issue can be used for the planning process. +- Include any new and edited docs in the MR introducing the code. +- Use the Documentation requirements confirmed by the Product Manager in the + issue and discuss any further doc plans or ideas as needed. + - If the new or changed doc requires extensive collaboration or conversation, a separate, + linked issue can be used for the planning process. + - We are trying to avoid using a separate MR, so that the docs stay with the code, but the + Technical Writing team is interested in discussing any potential exceptions that may be suggested. - Use the [Documentation guidelines](index.md), as well as other resources linked from there, -including the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). + including the Documentation [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). - If you need any help to choose the correct place for a doc, discuss a documentation -idea or outline, or request any other help, ping the Technical Writer for the relevant -[DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) -in your issue or MR, or write within `#docs` on the GitLab Slack. + idea or outline, or request any other help, ping the Technical Writer for the relevant + [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) + in your issue or MR, or write within `#docs` on the GitLab Slack. - The docs must be merged with the code **by the feature freeze date**, otherwise -- the feature cannot be included with the release.<!-- TODO: Policy/process for feature-flagged issues --> + the feature cannot be included with the release. A policy for documenting feature-flagged + issues is forthcoming and you are welcome to join the [discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/56813). + +#### Reviews and merging + +All reviewers can help ensure accuracy, clarity, completeness, and adherence to the plans in the issue, as well as the [Documentation Guidelines](https://docs.gitlab.com/ee/development/documentation/) and [Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide.html). + +- **Prior to merging**, documentation changes committed by the developer must be reviewed by: + + 1. **The code reviewer** for the MR, to confirm accuracy, clarity, and completeness. + 1. Optionally: Others involved in the work, such as other devs or the PM. + 1. Optionally: The technical writer for the DevOps stage. If not prior to merging, the technical writer will review after the merge. + This helps us ensure that the developer has time to merge good content by the freeze, and that it can be further refined by the release, if needed. + - To decide whether to request this review before the merge, consider the amount of time left before the code freeze, the size of the change, + and your degree of confidence in having users of an RC use your docs as written. + - Pre-merge tech writer reviews should be most common when the code is complete well in advance of the freeze and/or for larger documentation changes. + - You can request a review and if there is not sufficient time to complete it prior to the freeze, + the maintainer can merge the current doc changes (if complete) and create a follow-up doc review issue. + - The technical writer can also help decide what docs to merge before the freeze and whether to work on further changes in a follow up MR. + - **To request a pre-merge technical writer review**, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). + - **To request a post-merge technical writer review**, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR that makes the doc change. + 1. **The maintainer** who is assigned to merge the MR, to verify clarity, completeness, and quality, to the best of their ability. + +- Upon merging, if a technical writer review has not been performed and there is not yet a linked issue for a follow-up review, the maintainer should [create an issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review), link it from the MR, and + mention the original MR author in the new issue. Alternatively, the mainitainer can ask the MR author to create and link this issue before the MR is merged. + +- After merging, documentation changes are reviewed by: + + 1. The technical writer--**if** their review was not performed prior to the merge. + 2. Optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used). + Any party can raise the item to the PM for review at any point: the dev, the technical writer, or the PM, who can request/plan a review at the outset. + +### Technical Writer role + +#### Planning + +- The technical writer monitors the documentation needs of issues assigned to the current and next milestone + for their DevOps stage(s), and participates in any needed discussion on docs planning and requirements refinement + with the dev, PM, and others. +- The technical writer will review these requirements again upon the kickoff and provide feedback, as needed. + This is not a blocking review and developers should not wait to work on docs. -Prior to merge, documentation changes commited by the developer must be reviewed by: -* the person reviewing the code and merging the MR. -* optionally: others involved in the work (such as other devs, the PM, or a technical writer), if requested. +#### Collaboration -After merging, documentation changing are reviewed by: -* a technical writer (for clarity, structure, grammar, etc). -* optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used). -Any party can raise the item to the PM for review at any point: the dev, the technical writer, or the PM, who can request/plan a review at the outset. +By default, the developer will work on documentation changes independently, but +the developer, PM, or technicial writer can propose a broader collaboration for +any given issue. -### 3. Technical Writer's role +Additionally, technical writers are available for questions at any time. -**Planning** -- Once an issue contains a Documentation label and an upcoming milestone, a -technical writer reviews the listed documentation requirements, which should have -already been reviewed by the PM. (These are non-blocking reviews; developers should -not wait to work on docs.) -- Monitor the documentation needs of issues assigned to the current and next milestone, -and participate in any needed discussion on docs planning with the dev, PM, and others. +#### Review -**Review** - Techncial writers provide non-blocking reviews of all documentation changes, -typically after the change is merged. However, if the docs are ready in the MR while -we are awaiting other work in order to merge, the technical writer's review can commence early. + before or after the change is merged. However, if the docs are ready in the MR while + there's time before the freeze, the technical writer's review can commence early, on request. - The technical writer will confirm that the doc is clear, grammatically correct, -and discoverable, while avoiding redundancy, bad file locations, typos, broken links, -etc. The technical writer will review the documentation for the following, which -the developer and code reviewer should have already made a good-faith effort to ensure: + and discoverable, while avoiding redundancy, bad file locations, typos, broken links, + etc. The technical writer will review the documentation for the following, which + the developer and code reviewer should have already made a good-faith effort to ensure: - Clarity. - - Relevance (make sure the content is appropriate given the impact of the feature). - - Location (make sure the doc is in the correct dir and has the correct name). + - Adherence to the plans and goals in the issue. + - Location (make sure the docs are in the correct directorkes and has the correct name). - Syntax, typos, and broken links. - Improvements to the content. - - Accordance to the [Documentation Style Guide](styleguide.md) and [structure/template](structure.md). + - Accordance with the [Documentation Style Guide](styleguide.md), and [Structure and Template](structure.md) doc. diff --git a/doc/development/documentation/improvement-workflow.md b/doc/development/documentation/improvement-workflow.md index ef6392c6f7f..a12c3d5ea7b 100644 --- a/doc/development/documentation/improvement-workflow.md +++ b/doc/development/documentation/improvement-workflow.md @@ -9,26 +9,30 @@ Anyone can contribute a merge request or create an issue for GitLab's documentat This page covers the process for any contributions to GitLab's docs that are not part of feature development. If you are looking for information on updating GitLab's docs as is required with the development and release of a new feature -or feature enhancement, see the [feature-change documentation workflow](feature-change-workflow.md). +or feature enhancement, see the [documentation process for feature changes](feature-change-workflow.md). ## Who updates the docs Anyone can contribute! You can create a merge request with documentation when you find errors or other room for improvement in an existing doc, or when you -have an idea for all-new documentation that would help a GitLab user or admin -to achieve or improve their DevOps workflows. +have an idea for all-new documentation that would help a GitLab user or administrator +to accomplish their work with GitLab. ## How to update the docs -- Follow the described standards and processes listed on the [GitLab Documentation guidelines](index.md) page, -including linked resources: the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). -- Follow GitLab's [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines). -- If you need any help to choose the correct place for a doc, discuss a documentation +1. Click "Edit this Page" at the bottom of any page on docs.gitlab.com, or navigate to + one of the repositories and doc paths listed on the [GitLab Documentation guidelines](index.md) page. + Work in a fork if you do not have developer access to the GitLab project. +1. Follow the described standards and processes listed on that Guidelines page, + including the linked resources: the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). +1. Follow GitLab's [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines). + +If you need any help to choose the correct place for a doc, discuss a documentation idea or outline, or request any other help, ping the Technical Writer for the relevant [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) in your issue or MR, or write within `#docs` if you are a member of GitLab's Slack workspace. -## Merging +## Review and merging Anyone with master access to the affected GitLab project can merge documentation changes. This person must make a good-faith effort to ensure that the content is clear @@ -38,12 +42,22 @@ that it meets the [Documentation Guidelines](index.md) and [Style Guide](stylegu If the author or reviewer has any questions, or would like a techncial writer's review before merging, mention the writer who is assigned to the relevant [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). -## Technical Writer review +The process can involve the following parties/phases, and is replicated in the `Documentation` MR template for GitLab CE and EE, to help with following the process. + +**1. Primary Reviewer** - Review by a [code reviewer](https://about.gitlab.com/handbook/engineering/projects/) or other appropriate colleague to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes. + +**2. Technical Writer** - Optional - If not requested for this MR, must be scheduled post-merge. To request a pre-merge review, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). +To request a post-merge review, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR that makes the doc change. + +**3. Maintainer** -The technical writing team reviews changes after they are merged, unless a prior -review is requested. +1. Review by assigned maintainer, who can always request/require the above reviews. Maintainer review can occur before or after a technical writer review. +2. Ensure a release milestone of the format XX.Y is set. If the freeze for that release has begun, add the label `pick into <XX.Y>` unless this change is not required for the release. In that case, simply change the milestone. +3. If EE and CE MRs exist, merge the EE MR first, then the CE MR. +4. After merging, if there has not been a technical writer review and an issue for a follow-up review was not already created and linked from the MR, [create the issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review) and link it from the MR. ## Other ways to help If you have ideas for further documentation resources that would be best -considered/handled by technical writers, devs, and other SMEs, please create an issue. +considered/handled by technical writers, devs, and other SMEs, please [create an issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Documentation) +using the Documentation template. diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 287a472d0d8..652fe3ea711 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -10,8 +10,8 @@ In addition to this page, the following resources to help craft and contribute d - [Style Guide](styleguide.md) - What belongs in the docs, language guidelines, and more. - [Structure and template](structure.md) - Learn the typical parts of a doc page and how to write each one. -- [Workflow](workflow.md) - A landing page for our key workflows: - - [Feature-change documentation workflow](feature-change-workflow.md) - Adding required documentation when developing a GitLab feature. +- [Workflows](workflow.md) - A landing page for our key workflows: + - [Documentation process for feature changes](feature-change-workflow.md) - Adding required documentation when developing a GitLab feature. - [Documentation improvement workflow](improvement-workflow.md) - New content not associated with a new feature. - [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) - A reference for the markdown implementation used by GitLab's documentation site and about.gitlab.com. - [Site architecture](site_architecture/index.md) - How docs.gitlab.com is built. diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 0ce5825fd61..ee3a9caf9a0 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -44,7 +44,7 @@ read through the [global navigation](global_nav.md) doc. The docs site is deployed to production with GitLab Pages, and previewed in merge requests with Review Apps. -The deployment aspects will be soon transfered from the [original document](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md) +The deployment aspects will be soon transferred from the [original document](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md) to this page. <!-- diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index ee3bd5606a5..95b5fcd99a1 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -20,7 +20,7 @@ Every feature or use case document should include the following content in the f with exceptions and details noted below and in the template included on this page. - **Title**: Top-level heading with the feature name, or a use case name, which would start with -a verb, like Configuring, Enabling, etc. + a verb, like Configuring, Enabling, etc. - **Introduction**: A couple sentences about the subject matter and what's to be found on this page. - **Overview** Describe what it is, what it does, and in what context it should be used. - **Use cases**: describes real use case scenarios for that feature/configuration. @@ -95,7 +95,7 @@ Link each one to an appropriate place for more information. "Instructions" is usually not the name of the heading. This is the part of the document where you can include one or more sets of instructions, each to accomplish a specific task. Headers should describe the task the reader will achieve by following the instructions within, typically starting with a verb. -Larger instruction sets may have subsections covering specific phases of the process. +Larger instruction sets may have subsections covering specific phases of the process. - Write a step-by-step guide, with no gaps between the steps. - Start with an h2 (`##`), break complex steps into small steps using diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 7c32c92b147..0abfe4b82a4 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -2,9 +2,9 @@ description: Learn the processes for contributing to GitLab's documentation. --- -# Documentation workflows at GitLab +# Documentation workflows -Documentation workflows at GitLab differ depending on the reason for the change. The two types of documentation changes are: +Documentation workflows at GitLab differ depending on the reason for the change: -- [Feature-change documentation workflow](feature-change-workflow.md) - The documentation is being created or updated as part of the development and release of a new or enhanced feature. This process involves the developer of the feature (who includes new/updated documentation files as part of the same merge request containing the feature's code) and also involves the product manager and technical writer who are listed for the feature's [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). +- [Documentation process for feature changes](feature-change-workflow.md) - The documentation is being created or updated as part of the development and release of a new or enhanced feature. This process involves the developer of the feature (who includes new/updated documentation files as part of the same merge request containing the feature's code) and also involves the product manager and technical writer who are listed for the feature's [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). - [Documentation improvement workflow](improvement-workflow.md) - All documentation additions not associated with a feature release. Documentation is being created or updated to improve accuracy, completeness, ease of use, or any reason other than a feature change. Anyone (and everyone) can contribute a merge request for this type of change at any time. diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md index 905668eef58..f3fdaa3b883 100644 --- a/doc/development/fe_guide/development_process.md +++ b/doc/development/fe_guide/development_process.md @@ -61,17 +61,19 @@ Please use your best judgement when to use it and please contribute new points t --- ### Share your work early + 1. Before writing code, ensure your vision of the architecture is aligned with -GitLab's architecture. + GitLab's architecture. 1. Add a diagram to the issue and ask a frontend architect in the slack channel `#fe_architectural` about it.  1. Don't take more than one week between starting work on a feature and -sharing a Merge Request with a reviewer or a maintainer. + sharing a Merge Request with a reviewer or a maintainer. ### Vue features + 1. Follow the steps in [Vue.js Best Practices](vue.md) 1. Follow the style guide. 1. Only a handful of people are allowed to merge Vue related features. -Reach out to one of Vue experts early in this process. + Reach out to one of Vue experts early in this process. diff --git a/doc/development/fe_guide/droplab/plugins/filter.md b/doc/development/fe_guide/droplab/plugins/filter.md index ddc6a3386c7..1f188c64fe4 100644 --- a/doc/development/fe_guide/droplab/plugins/filter.md +++ b/doc/development/fe_guide/droplab/plugins/filter.md @@ -9,7 +9,7 @@ Add the `Filter` object to the plugins array of a `DropLab.prototype.init` or `D - `Filter` requires a config value for `template`. - `template` should be the key of the objects within your data array that you want to compare -to the user input string, for filtering. + to the user input string, for filtering. ```html <input href="#" id="trigger" data-dropdown-trigger="#list"> diff --git a/doc/development/fe_guide/droplab/plugins/input_setter.md b/doc/development/fe_guide/droplab/plugins/input_setter.md index e229103e462..e4050213869 100644 --- a/doc/development/fe_guide/droplab/plugins/input_setter.md +++ b/doc/development/fe_guide/droplab/plugins/input_setter.md @@ -9,7 +9,7 @@ Add the `InputSetter` object to the plugins array of a `DropLab.prototype.init` - `InputSetter` requires a config value for `input` and `valueAttribute`. - `input` should be the DOM element that you want to manipulate. - `valueAttribute` should be a string that is the name of an attribute on your list items that is used to get the value -to update the `input` element with. + to update the `input` element with. You can also set the `InputSetter` config to an array of objects, which will allow you to update multiple elements. diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index f55f01720fd..3290f29530a 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -9,7 +9,7 @@ read more about [Feature Flags][feature-flags]. ## Apollo Client To save duplicated clients getting created in different apps, we have a -[default client][defualt-client] that should be used. This setups the +[default client][default-client] that should be used. This setups the Apollo client with the correct URL and also sets the CSRF headers. ## GraphQL Queries @@ -27,11 +27,11 @@ the Vue application is mounted. ```javascript import Vue from 'vue'; import VueApollo from 'vue-apollo'; -import defaultClient from '~/lib/graphql'; +import createDefaultClient from '~/lib/graphql'; Vue.use(VueApollo); const apolloProvider = new VueApollo({ - defaultClient, + defaultClient: createDefaultClient(), }); new Vue({ @@ -43,6 +43,29 @@ new Vue({ Read more about [Vue Apollo][vue-apollo] in the [Vue Apollo documentation][vue-apollo-docs]. +### Local state with `apollo-link-state` + +It is possible to use our Apollo setup with [apollo-link-state][apollo-link-state] by passing +in the client state object when creating the default client. + +```javascript +import Vue from 'vue'; +import VueApollo from 'vue-apollo'; +import createDefaultClient from '~/lib/graphql'; +Vue.use(VueApollo); + +const apolloProvider = new VueApollo({ + defaultClient: createDefaultClient({ + defaults: { + testing: true, + }, + resolvers: { + ... + }, + }), +}); +``` + ### Testing With [Vue test utils][vue-test-utils] it is easy to quickly test components that @@ -81,3 +104,4 @@ Read more about the [Apollo] client in the [Apollo documentation][apollo-client- [default-client]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/lib/graphql.js [apollo-client-docs]: https://www.apollographql.com/docs/tutorial/client.html [vue-test-utils]: https://vue-test-utils.vuejs.org/ +[apollo-link-state]: https://www.apollographql.com/docs/link/links/state.html diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index 0aba38aca8c..2628e95dbc1 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -5,6 +5,7 @@ ### Realtime Components When writing code for realtime features we have to keep a couple of things in mind: + 1. Do not overload the server with requests. 1. It should feel realtime. @@ -12,16 +13,16 @@ Thus, we must strike a balance between sending requests and the feeling of realt Use the following rules when creating realtime solutions. 1. The server will tell you how much to poll by sending `Poll-Interval` in the header. -Use that as your polling interval. This way it is [easy for system administrators to change the -polling rate](../../administration/polling.md). -A `Poll-Interval: -1` means you should disable polling, and this must be implemented. + Use that as your polling interval. This way it is [easy for system administrators to change the + polling rate](../../administration/polling.md). + A `Poll-Interval: -1` means you should disable polling, and this must be implemented. 1. A response with HTTP status different from 2XX should disable polling as well. 1. Use a common library for polling. 1. Poll on active tabs only. Please use [Visibility](https://github.com/ai/visibilityjs). 1. Use regular polling intervals, do not use backoff polling, or jitter, as the interval will be -controlled by the server. + controlled by the server. 1. The backend code will most likely be using etags. You do not and should not check for status -`304 Not Modified`. The browser will transform it for you. + `304 Not Modified`. The browser will transform it for you. ### Lazy Loading Images diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index 1e0529262ad..060cd8baf7f 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -14,9 +14,9 @@ See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/ #### ESlint 1. **Never** disable eslint rules unless you have a good reason. -You may see a lot of legacy files with `/* eslint-disable some-rule, some-other-rule */` -at the top, but legacy files are a special case. Any time you develop a new feature or -refactor an existing one, you should abide by the eslint rules. + You may see a lot of legacy files with `/* eslint-disable some-rule, some-other-rule */` + at the top, but legacy files are a special case. Any time you develop a new feature or + refactor an existing one, you should abide by the eslint rules. 1. **Never Ever EVER** disable eslint globally for a file @@ -53,7 +53,7 @@ refactor an existing one, you should abide by the eslint rules. 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. + followed by any global declarations, then a blank newline prior to any imports or code. ```javascript // bad @@ -125,8 +125,8 @@ followed by any global declarations, then a blank newline prior to any imports o ``` 1. Relative paths: when importing a module in the same directory, a child -directory, or an immediate parent directory prefer relative paths. When -importing a module which is two or more levels up, prefer either `~/` or `ee/`. + directory, or an immediate parent directory prefer relative paths. When + importing a module which is two or more levels up, prefer either `~/` or `ee/`. In **app/assets/javascripts/my-feature/subdir**: @@ -163,9 +163,9 @@ importing a module which is two or more levels up, prefer either `~/` or `ee/`. ``` 1. Avoid using IIFE. Although we have a lot of examples of files which wrap their -contents in IIFEs (immediately-invoked function expressions), -this is no longer necessary after the transition from Sprockets to webpack. -Do not use them anymore and feel free to remove them when refactoring legacy code. + contents in IIFEs (immediately-invoked function expressions), + this is no longer necessary after the transition from Sprockets to webpack. + Do not use them anymore and feel free to remove them when refactoring legacy code. 1. Avoid adding to the global namespace. ```javascript @@ -484,8 +484,8 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. ``` 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. + _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 diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 60f322c6e75..3cd70bd63fa 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -223,6 +223,7 @@ need to test the rendered output. [Vue][vue-test] guide's to unit test show us e ## Vue.js Expert Role One should apply to be a Vue.js expert by opening an MR when the Merge Request's they create and review show: + - Deep understanding of Vue and Vuex reactivy - Vue and Vuex code are structured according to both official and our guidelines - Full understanding of testing a Vue and Vuex application diff --git a/doc/development/import_export.md b/doc/development/import_export.md index e2108605d54..f7f48b03651 100644 --- a/doc/development/import_export.md +++ b/doc/development/import_export.md @@ -222,7 +222,7 @@ bundle exec rake gitlab:import_export:bump_version ### Renaming columns or models -This is a relatively common occurence that will require a version bump. +This is a relatively common occurrence that will require a version bump. There is also the _RC problem_ - GitLab.com runs an RC, prior to any customers, meaning that we want to bump the version up in the next version (or patch release). diff --git a/doc/development/logging.md b/doc/development/logging.md index 5c1d96b9e0c..d61441813b2 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -32,8 +32,8 @@ These logs suffer from a number of problems: 1. They often lack timestamps or other contextual information (e.g. project ID, user) 2. They may span multiple lines, which make them hard to find via Elasticsearch. 3. They lack a common structure, which make them hard to parse by log -forwarders, such as Logstash or Fluentd. This also makes them hard to -search. + forwarders, such as Logstash or Fluentd. This also makes them hard to + search. Note that currently on GitLab.com, any messages in `production.log` will NOT get indexed by Elasticsearch due to the sheer volume and noise. They @@ -61,12 +61,12 @@ importer. You want to log issues created, merge requests, etc. as the importer progresses. Here's what to do: 1. Look at [the list of GitLab Logs](../administration/logs.md) to see -if your log message might belong with one of the existing log files. + if your log message might belong with one of the existing log files. 1. If there isn't a good place, consider creating a new filename, but -check with a maintainer if it makes sense to do so. A log file should -make it easy for people to search pertinent logs in one place. For -example, `geo.log` contains all logs pertaining to GitLab Geo. -To create a new file: + check with a maintainer if it makes sense to do so. A log file should + make it easy for people to search pertinent logs in one place. For + example, `geo.log` contains all logs pertaining to GitLab Geo. + To create a new file: 1. Choose a filename (e.g. `importer_json.log`). 1. Create a new subclass of `Gitlab::JsonLogger`: @@ -130,15 +130,15 @@ To create a new file: ## Additional steps with new log files 1. Consider log retention settings. By default, Omnibus will rotate any -logs in `/var/log/gitlab/gitlab-rails/*.log` every hour and [keep at -most 30 compressed files](https://docs.gitlab.com/omnibus/settings/logs.html#logrotate). -On GitLab.com, that setting is only 6 compressed files. These settings should suffice -for most users, but you may need to tweak them in [omnibus-gitlab](https://gitlab.com/gitlab-org/omnibus-gitlab). + logs in `/var/log/gitlab/gitlab-rails/*.log` every hour and [keep at + most 30 compressed files](https://docs.gitlab.com/omnibus/settings/logs.html#logrotate). + On GitLab.com, that setting is only 6 compressed files. These settings should suffice + for most users, but you may need to tweak them in [omnibus-gitlab](https://gitlab.com/gitlab-org/omnibus-gitlab). 1. If you add a new file, submit an issue to the [production -tracker](https://gitlab.com/gitlab-com/gl-infra/production/issues) or -a merge request to the [gitlab_fluentd](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd) -project. See [this example](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd/merge_requests/51/diffs). + tracker](https://gitlab.com/gitlab-com/gl-infra/production/issues) or + a merge request to the [gitlab_fluentd](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd) + project. See [this example](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd/merge_requests/51/diffs). 1. Be sure to update the [GitLab CE/EE documentation](../administration/logs.md) and the [GitLab.com -runbooks](https://gitlab.com/gitlab-com/runbooks/blob/master/howto/logging.md). + runbooks](https://gitlab.com/gitlab-com/runbooks/blob/master/howto/logging.md). diff --git a/doc/development/new_fe_guide/development/accessibility.md b/doc/development/new_fe_guide/development/accessibility.md index 2a3a126ca5c..8420a504ec4 100644 --- a/doc/development/new_fe_guide/development/accessibility.md +++ b/doc/development/new_fe_guide/development/accessibility.md @@ -2,7 +2,7 @@ Using semantic HTML plays a key role when it comes to accessibility. ## Accessible Rich Internet Applications - ARIA -WAI-ARIA, the Accessible Rich Internet Applications specification, defines a way to make Web content and Web applications more accessible to people with disabilities. +WAI-ARIA, the Accessible Rich Internet Applications specification, defines a way to make Web content and Web applications more accessible to people with disabilities. > Note: It is [recommended][using-aria] to use semantic elements as the primary method to achieve accessibility rather than adding aria attributes. Adding aria attributes should be seen as a secondary method for creating accessible elements. @@ -15,6 +15,7 @@ Check the list of WAI-ARIA roles [here][roles] When using icons or images that aren't absolutely needed to understand the context, we should use `aria-hidden="true"`. On the other hand, if an icon is crucial to understand the context we should do one of the following: + 1. Use `aria-label` in the element with a meaningful description 1. Use `aria-labelledby` to point to an element that contains the explanation for that icon diff --git a/doc/development/new_fe_guide/style/html.md b/doc/development/new_fe_guide/style/html.md index 2d5b7d048ab..035fcbb28df 100644 --- a/doc/development/new_fe_guide/style/html.md +++ b/doc/development/new_fe_guide/style/html.md @@ -3,6 +3,7 @@ ## Buttons <a name="button-type"></a><a name="1.1"></a> + - [1.1](#button-type) **Use button type** Button tags requires a `type` attribute according to the [W3C HTML specification][button-type-spec]. ``` @@ -14,6 +15,7 @@ ``` <a name="button-role"></a><a name="1.2"></a> + - [1.2](#button-role) **Use button role for non buttons** If an HTML element has an onClick handler but is not a button, it should have `role="button"`. This is more [accessible][button-role-accessible]. ``` @@ -27,6 +29,7 @@ ## Links <a name="blank-links"></a><a name="2.1"></a> + - [2.1](#blank-links) **Use rel for target blank** Use `rel="noopener noreferrer"` whenever your links open in a new window i.e. `target="_blank"`. This prevents [the following][jitbit-target-blank] security vulnerability documented by JitBit ``` @@ -38,6 +41,7 @@ ``` <a name="fake-links"></a><a name="2.2"></a> + - [2.2](#fake-links) **Do not use fake links** Use a button tag if a link only invokes JavaScript click event handlers. This is more semantic. ``` diff --git a/doc/development/new_fe_guide/style/javascript.md b/doc/development/new_fe_guide/style/javascript.md index 922fd1e4ea4..7985b893c9e 100644 --- a/doc/development/new_fe_guide/style/javascript.md +++ b/doc/development/new_fe_guide/style/javascript.md @@ -10,6 +10,7 @@ You can run eslint locally by running `yarn eslint` ## Arrays <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]) ``` @@ -17,7 +18,7 @@ You can run eslint locally by running `yarn eslint` users.forEach((user, index) => { user.id = index; }); - + // good const usersWithId = users.map((user, index) => { return Object.assign({}, user, { id: index }); @@ -27,6 +28,7 @@ You can run eslint locally by running `yarn eslint` ## 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. ``` @@ -34,7 +36,7 @@ You can run eslint locally by running `yarn eslint` function a(p1, p2, p3) { // ... }; - + // good function a(p) { // ... @@ -44,6 +46,7 @@ You can run eslint locally by running `yarn eslint` ## 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 @@ -54,23 +57,24 @@ You can run eslint locally by running `yarn eslint` axios.get(this.config.endpoint) } } - + // good class myClass { constructor(config) { this.config = config; } - + makeRequest() { axios.get(this.config.endpoint) } } 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. ``` @@ -79,14 +83,14 @@ You can run eslint locally by running `yarn eslint` constructor(config) { this.config = config; } - + init() { document.addEventListener('click', () => {}); } } - + // good - + const myFunction = () => { document.addEventListener('click', () => { // handle callback here @@ -95,8 +99,9 @@ You can run eslint locally by running `yarn eslint` ``` <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. + This is more maintainable and performant. ``` // bad @@ -105,7 +110,7 @@ This is more maintainable and performant. document.querySelector('.b'); } } - + // good class a { constructor(options) { @@ -117,12 +122,13 @@ This is more maintainable and performant. ## 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); ``` @@ -130,12 +136,13 @@ This is more maintainable and performant. ## 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> ``` @@ -143,44 +150,51 @@ This is more maintainable and performant. ## 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'; ``` <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'; ``` <a name="global-namespace"></a><a name="6.3"></a> + - [6.3](#global-namespace) **Do not add to global namespace** <a name="domcontentloaded"></a><a name="6.4"></a> + - [6.4](#domcontentloaded) **Do not use DOMContentLoaded in non-page modules** Imported modules should act the same each time they are loaded. `DOMContentLoaded` events are only allowed on modules loaded in the `/pages/*` directory because those are loaded dynamically with webpack. ## Security <a name="avoid-xss"></a><a name="7.1"></a> + - [7.1](#avoid-xss) **Avoid XSS** Do not use `innerHTML`, `append()` or `html()` to set content. It opens up too many vulnerabilities. ## ESLint <a name="disable-eslint-file"></a><a name="8.1"></a> + - [8.1](#disable-eslint-file) **Disabling ESLint in new files** Do not disable ESLint when creating new files. Existing files may have existing rules disabled due to legacy compatibility reasons but they are in the process of being refactored. <a name="disable-eslint-rule"></a><a name="8.2"></a> + - [8.2](#disable-eslint-rule) **Disabling ESLint rule** Do not disable specific ESLint rules. Due to technical debt, you may disable the following rules only if you are invoking/instantiating existing code modules - [no-new][no-new] diff --git a/doc/development/ordering_table_columns.md b/doc/development/ordering_table_columns.md index 3e49a65f5ab..cbfd05e731d 100644 --- a/doc/development/ordering_table_columns.md +++ b/doc/development/ordering_table_columns.md @@ -19,7 +19,7 @@ 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. -As a result, the actual size of each column would be (ommiting variable length +As a result, the actual size of each column would be (omitting 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 diff --git a/doc/development/performance.md b/doc/development/performance.md index 32970152911..2a287611bdf 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -410,6 +410,21 @@ there's nothing stopping somebody from doing this elsewhere in the code: SOME_CONSTANT = 'bar' ``` +## How to seed a database with millions of rows + +You might want millions of project rows in your local database, for example, +in order to compare relative query performance, or to reproduce a bug. You could +do this by hand with SQL commands, but since you have ActiveRecord models, you +might find using these gems more convenient: + +- [BulkInsert gem](https://github.com/jamis/bulk_insert) +- [ActiveRecord::PgGenerateSeries gem](https://github.com/ryu39/active_record-pg_generate_series) + +### Examples + +You may find some useful examples in this snippet: +https://gitlab.com/gitlab-org/gitlab-ce/snippets/33946 + [#15607]: https://gitlab.com/gitlab-org/gitlab-ce/issues/15607 [yorickpeterse]: https://gitlab.com/yorickpeterse [anti-pattern]: https://en.wikipedia.org/wiki/Anti-pattern diff --git a/doc/development/policies.md b/doc/development/policies.md index 6a3b90f3604..c4ac42bb40a 100644 --- a/doc/development/policies.md +++ b/doc/development/policies.md @@ -88,10 +88,10 @@ An example debug output would look as follows: Each line represents a rule that was evaluated. There are a few things to note: 1. The `-` or `+` symbol indicates whether the rule block was evaluated to be -`false` or `true`, respectively. + `false` or `true`, respectively. 2. The number inside the brackets indicates the score. 3. The last part of the line (e.g. `@john : Issue/1`) shows the username -and subject for that rule. + and subject for that rule. Here you can see that the first four rules were evaluated `false` for which user and subject. For example, you can see in the last line that diff --git a/doc/development/polling.md b/doc/development/polling.md index 3b34f985cd4..76bb5ae7819 100644 --- a/doc/development/polling.md +++ b/doc/development/polling.md @@ -51,6 +51,7 @@ request path. By doing this we avoid query parameter ordering problems and make route matching easier. For more information see: + - [`Poll-Interval` header](fe_guide/performance.md#realtime-components) - [RFC 7232](https://tools.ietf.org/html/rfc7232) - [ETag proposal](https://gitlab.com/gitlab-org/gitlab-ce/issues/26926) diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index 4cc500ed1b6..dcb32c89f65 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -73,6 +73,7 @@ To make sure that indices still fit. You could find great details in: ## Run tests In order to run the test you can use the following commands: + - `rake spec` to run the rspec suite - `rake karma` to run the karma test suite - `rake gitlab:test` to run all the tests diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index 4cc3812b0f0..2c8d488877b 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -358,16 +358,11 @@ range of inputs, might look like this: describe "#==" do using RSpec::Parameterized::TableSyntax - let(:project1) { create(:project) } - let(:project2) { create(:project) } where(:a, :b, :result) do 1 | 1 | true 1 | 2 | false true | true | true true | false | false - project1 | project1 | true - project2 | project2 | true - project 1 | project2 | false end with_them do @@ -380,6 +375,11 @@ describe "#==" do end ``` +CAUTION: **Caution:** +Only use simple values as input in the `where` block. Using procs, stateful +objects, FactoryBot-created objects etc. can lead to +[unexpected results](https://github.com/tomykaira/rspec-parameterized/issues/8). + ### Prometheus tests Prometheus metrics may be preserved from one test run to another. To ensure that metrics are diff --git a/doc/development/testing_guide/end_to_end_tests.md b/doc/development/testing_guide/end_to_end_tests.md index e9f236c6b3a..a239dc84a1c 100644 --- a/doc/development/testing_guide/end_to_end_tests.md +++ b/doc/development/testing_guide/end_to_end_tests.md @@ -41,24 +41,24 @@ Currently, we are using _multi-project pipeline_-like approach to run QA pipelines. 1. Developer triggers a manual action, that can be found in CE / EE merge -requests. This starts a chain of pipelines in multiple projects. + requests. This starts a chain of pipelines in multiple projects. 1. The script being executed triggers a pipeline in [Omnibus GitLab][omnibus-gitlab] -and waits for the resulting status. We call this a _status attribution_. + and waits for the resulting status. We call this a _status attribution_. 1. GitLab packages are being built in the [Omnibus GitLab][omnibus-gitlab] -pipeline. Packages are then pushed to its Container Registry. + pipeline. Packages are then pushed to its Container Registry. 1. When packages are ready, and available in the registry, a final step in the -[Omnibus GitLab][omnibus-gitlab] pipeline, triggers a new -[GitLab QA pipeline][gitlab-qa-pipelines]. It also waits for a resulting status. + [Omnibus GitLab][omnibus-gitlab] pipeline, triggers a new + [GitLab QA pipeline][gitlab-qa-pipelines]. It also waits for a resulting status. 1. GitLab QA pulls images from the registry, spins-up containers and runs tests -against a test environment that has been just orchestrated by the `gitlab-qa` -tool. + against a test environment that has been just orchestrated by the `gitlab-qa` + tool. 1. The result of the [GitLab QA pipeline][gitlab-qa-pipelines] is being -propagated upstream, through Omnibus, back to the CE / EE merge request. + propagated upstream, through Omnibus, back to the CE / EE merge request. #### How do I write tests? diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 6012f1080ab..0470a071d39 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -141,14 +141,15 @@ module. GitLab has a custom `spyOnDependency` method which utilizes [babel-plugin-rewire](https://github.com/speedskater/babel-plugin-rewire) to achieve this. It can be used like so: -```javascript +```js // my_module.js import { visitUrl } from '~/lib/utils/url_utility'; export default function doSomething() { visitUrl('/foo/bar'); } - +``` +```js // my_module_spec.js import doSomething from '~/my_module'; diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index 85b47f88cc4..703e342fc13 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -70,9 +70,8 @@ subgraph GCP `gitlab-review-apps` project you get a dedicated environment for your branch that's very close to what it would look in production. 1. Once the [`review-deploy`][review-deploy] 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**. + use your Review App thanks to the direct link to it from the MR widget. To log + into the Review App, see "Log into my Review App?" below. **Additional notes:** @@ -98,6 +97,17 @@ Note that both jobs first wait for the `review-deploy` job to be finished. ## How to? +### Log into my Review App? + +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**. + +### Enable a feature flag for my Review App? + +1. Open your Review App and log in as documented above. +1. Create a personal access token. +1. Enable the feature flag using the [Feature flag API](../../api/features.md). + ### Find my Review App slug? 1. Open the `review-deploy` job. diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index 070b6477a7a..a7a3459719b 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -159,6 +159,10 @@ Every new feature should come with a [test plan]. > See [end-to-end tests](end_to_end_tests.md) for more information. +Note that `qa/spec` contains unit tests of the QA framework itself, not to be +confused with the application's [unit tests](#unit-tests) or +[end-to-end tests](#black-box-tests-at-the-system-level-aka-end-to-end-tests). + [multiple pieces]: ../architecture.md#components [GitLab Shell]: https://gitlab.com/gitlab-org/gitlab-shell [GitLab Workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index be14858f4c8..fa5be1d30f9 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -21,14 +21,14 @@ First, you'll need an account on Azure. There are three ways to do this: - If your company (or you) already has an account, then you are ready to go! - You can also open your own Azure account for free. _At time of writing_, you get $200 -of credit to spend on Azure services for 30 days. You can use this credit to try out paid Azure -services, exploring Microsoft's cloud for free. Even after the first 30 days, you never have to pay -anything unless you decide to transition to paid services with a Pay-As-You-Go Azure subscription. -This is a great way to try out Azure and cloud computing, and you can -[read more in their comprehensive FAQ][Azure-Free-Account-FAQ]. + of credit to spend on Azure services for 30 days. You can use this credit to try out paid Azure + services, exploring Microsoft's cloud for free. Even after the first 30 days, you never have to pay + anything unless you decide to transition to paid services with a Pay-As-You-Go Azure subscription. + This is a great way to try out Azure and cloud computing, and you can + [read more in their comprehensive FAQ][Azure-Free-Account-FAQ]. - If you have an MSDN subscription, you can activate your Azure subscriber benefits. Your MSDN -subscription gives you recurring Azure credits every month, so why not put those credits to use and -try out GitLab right now? + subscription gives you recurring Azure credits every month, so why not put those credits to use and + try out GitLab right now? ## Working with Azure @@ -216,10 +216,10 @@ Like all servers, our VM will be running many services. However, we want to open ports to enable public internet access to two services in particular: 1. **HTTP** (port 80) - opening port 80 will enable our VM to respond to HTTP requests, allowing -public access to the instance of GitLab running on our VM. + public access to the instance of GitLab running on our VM. 1. **SSH** (port 22) - opening port 22 will enable our VM to respond to SSH connection requests, -allowing public access (with authentication) to remote terminal sessions -_(you'll see why we need [SSH] access to our VM [later on in this tutorial](#maintaining-your-gitlab-instance))_ + allowing public access (with authentication) to remote terminal sessions + _(you'll see why we need [SSH] access to our VM [later on in this tutorial](#maintaining-your-gitlab-instance))_ ### Open HTTP on Port 80 diff --git a/doc/install/kubernetes/preparation/eks.md b/doc/install/kubernetes/preparation/eks.md index 647b856d54e..ea3b075dd82 100644 --- a/doc/install/kubernetes/preparation/eks.md +++ b/doc/install/kubernetes/preparation/eks.md @@ -5,6 +5,7 @@ There are a few nuances to Amazon EKS which are important to be aware of, when d ## Persistent volume management There are two methods to manage volume claims on Kubernetes: + 1. Manually creating each persistent volume (recommended on EKS) 1. Utilizing dynamic provisioning to automatically create the persistent volumes diff --git a/doc/install/kubernetes/preparation/tiller.md b/doc/install/kubernetes/preparation/tiller.md index 107df074b3b..00b0737402b 100644 --- a/doc/install/kubernetes/preparation/tiller.md +++ b/doc/install/kubernetes/preparation/tiller.md @@ -15,7 +15,7 @@ cannot be normally deployed. Tiller is deployed into the cluster and interacts with the Kubernetes API to deploy your applications. If role based access control (RBAC) is enabled, Tiller will need to be [granted permissions](#preparing-for-helm-with-rbac) to allow it to talk to the Kubernetes API. -If RBAC is not enabled, skip to [initalizing Helm](#initialize-helm). +If RBAC is not enabled, skip to [initializing Helm](#initialize-helm). If you are not sure whether RBAC is enabled in your cluster, or to learn more, read through our [RBAC documentation](rbac.md). @@ -54,19 +54,25 @@ Some clusters require authentication to use `kubectl` to create the Tiller roles #### Upload the RBAC config as an admin user (GKE) -For GKE, you need to grab the admin credentials: +For GKE, you need to obtain the admin credentials. This command will output the admin password: ``` gcloud container clusters describe <cluster-name> --zone <zone> --project <project-id> --format='value(masterAuth.password)' ``` -This command will output the admin password. We need the password to authenticate with `kubectl` and create the role. +Use the admin password to set the admin credentials. Replace the password value below with the output value from the above step: ``` -kubectl --username=admin --password=xxxxxxxxxxxxxx create -f rbac-config.yaml +kubectl config set-credentials admin --username=admin --password=xxxxxxxxxxxxxx ``` -#### Upload the RBAC config (Other clusters) +Once credentials have been set, create the role: + +``` +kubectl --user=admin create -f rbac-config.yaml +``` + +#### Upload the RBAC config (Non-GKE clusters) For other clusters like Amazon EKS, you can directly upload the RBAC configuration. diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 1b7e0d1d0ab..c1f2297f3be 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -33,7 +33,7 @@ Please consider using a virtual machine to run GitLab. ## Ruby versions -GitLab requires Ruby (MRI) 2.3. Support for Ruby versions below 2.3 (2.1, 2.2) will stop with GitLab 8.13. +GitLab requires Ruby (MRI) 2.5. Support for Ruby versions below 2.5 (2.3, 2.4) will stop with GitLab 11.6. You will have to use the standard MRI implementation of Ruby. We love [JRuby](https://www.jruby.org/) and [Rubinius](https://rubinius.com) but GitLab diff --git a/doc/integration/README.md b/doc/integration/README.md index 7941cb42667..f7a624def53 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -12,7 +12,7 @@ See the documentation below for details on how to configure these services. - [Akismet](akismet.md) Configure Akismet to stop spam - [Auth0 OmniAuth](auth0.md) Enable the Auth0 OmniAuth provider - [Bitbucket](bitbucket.md) Import projects from Bitbucket.org and login to your GitLab instance with your -Bitbucket.org account + Bitbucket.org account - [CAS](cas.md) Configure GitLab to sign in using CAS - [External issue tracker](external-issue-tracker.md) Redmine, JIRA, etc. - [Gmail actions buttons](gmail_action_buttons_for_gitlab.md) Adds GitLab actions to messages diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index e2ed7a4b1ab..c67375ede50 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -4,18 +4,18 @@ To enable the Auth0 OmniAuth provider, you must create an Auth0 account, and an application. 1. Sign in to the [Auth0 Console](https://auth0.com/auth/login). If you need to -create an account, you can do so at the same link. + create an account, you can do so at the same link. 1. Select "New App/API". 1. Provide the Application Name ('GitLab' works fine). 1. Once created, you should see the Quick Start options. Disregard them and -select 'Settings' above the Quick Start options. + select 'Settings' above the Quick Start options. 1. At the top of the Settings screen, you should see your Domain, Client ID and -Client Secret. Take note of these as you'll need to put them in the -configuration file. For example: + Client Secret. Take note of these as you'll need to put them in the + configuration file. For example: - Domain: `test1234.auth0.com` - Client ID: `t6X8L2465bNePWLOvt9yi41i` - Client Secret: `KbveM3nqfjwCbrhaUy_gDu2dss8TIlHIdzlyf33pB7dEK5u_NyQdp65O_o02hXs2` @@ -44,7 +44,7 @@ configuration file. For example: ``` 1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) -for initial settings. + for initial settings. 1. Add the provider configuration: @@ -76,10 +76,10 @@ for initial settings. ``` 1. Change `YOUR_AUTH0_CLIENT_ID` to the client ID from the Auth0 Console page -from step 5. + from step 5. 1. Change `YOUR_AUTH0_CLIENT_SECRET` to the client secret from the Auth0 Console -page from step 5. + page from step 5. 1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you installed GitLab via Omnibus or from source respectively. diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index a67de23b17b..fe789a80eed 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -9,7 +9,7 @@ To enable the Facebook OmniAuth provider you must register your application with 1. Select the type "Website" 1. Enter a name for your app. This can be anything. Consider something like "<Organization>'s GitLab" or "<Your Name>'s GitLab" or -something else descriptive. + something else descriptive. 1. Choose "Create New Facebook App ID" diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index 82ba1d7d984..cd755089be8 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -1,5 +1,7 @@ # Slash Commands +> The `run` command was [introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24780) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. + Slash commands in Mattermost and Slack allow you to control GitLab and view GitLab content right inside your chat client, without having to leave it. For Slack, this requires a [project service configuration](../user/project/integrations/slack_slash_commands.md). Simply type the command as a message in your chat client to activate it. Commands are scoped to a project, with a trigger term that is specified during configuration. @@ -16,6 +18,7 @@ Taking the trigger term as `project-name`, the commands are: | `/project-name issue search <query>` | Shows up to 5 issues matching `<query>` | | `/project-name issue move <id> to <project>` | Moves issue ID `<id>` to `<project>` | | `/project-name deploy <from> to <to>` | Deploy from the `<from>` environment to the `<to>` environment | +| `/project-name run <job name> <arguments>` | Execute [ChatOps](../ci/chatops/README.md) job `<job name>` on `master` | Note that if you are using the [GitLab Slack application](https://docs.gitlab.com/ee/user/project/integrations/gitlab_slack_application.html) for your GitLab.com projects, you need to [add the `gitlab` keyword at the beginning of the command](https://docs.gitlab.com/ee/user/project/integrations/gitlab_slack_application.html#usage). diff --git a/doc/public_access/public_access.md b/doc/public_access/public_access.md index 81ee7338e4e..8601551e3bd 100644 --- a/doc/public_access/public_access.md +++ b/doc/public_access/public_access.md @@ -1,6 +1,6 @@ # Public access -GitLab allows you to change your projects' visibility in order be accessed +GitLab allows [Owners](../user/permissions.md) to change a projects' visibility in order to be accessed **publicly** or **internally**. Projects with either of these visibility levels will be listed in the diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 2514ca94775..069c87f921a 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -442,6 +442,8 @@ backups will be copied to, and will be created if it does not exist. If the directory that you want to copy the tarballs to is the root of your mounted directory, just use `.` instead. +NOTE: **Note:** Since file system performance may affect GitLab's overall performance, we do not recommend using EFS for storage. See the [relevant documentation](../administration/high_availability/nfs.md#avoid-using-awss-elastic-file-system-efs) for more details. + For Omnibus GitLab packages: 1. Edit `/etc/gitlab/gitlab.rb`: diff --git a/doc/security/img/ssh_keys_restricted_key_icon.png b/doc/security/img/ssh_keys_restricted_key_icon.png Binary files differnew file mode 100644 index 00000000000..ad3749e8233 --- /dev/null +++ b/doc/security/img/ssh_keys_restricted_key_icon.png diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md index 213fa5bfef5..6b6a8a06cc9 100644 --- a/doc/security/ssh_keys_restrictions.md +++ b/doc/security/ssh_keys_restrictions.md @@ -17,3 +17,11 @@ In the Admin area under **Settings** (`/admin/application_settings`), look for the "Visibility and Access Controls" area:  + +If a restriction is imposed on any key type, users will be unable to upload new SSH keys that don't meet the requirement. Any existing keys that don't meet it will be disabled but not removed and users will be unable to pull or push code using them. + +An icon will be visible to the user of a restricted key in the SSH keys section of their profile: + + + +Hovering over this icon will tell you why the key is restricted. diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index 55b678d6af5..a3698d60f6d 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -147,7 +147,7 @@ Please refer to `group_rename` and `user_rename` for that case. "user_name": "John Smith", "user_username": "johnsmith", "user_id": 41, - "project_visibility": "private" + "project_visibility": "visibilitylevel|private" } ``` @@ -158,7 +158,7 @@ Please refer to `group_rename` and `user_rename` for that case. "created_at": "2012-07-21T07:30:56Z", "updated_at": "2012-07-21T07:38:22Z", "event_name": "user_remove_from_team", - "project_access": "Maintainer", + "access_level": "Maintainer", "project_id": 74, "project_name": "StoreCloud", "project_path": "storecloud", @@ -167,7 +167,7 @@ Please refer to `group_rename` and `user_rename` for that case. "user_name": "John Smith", "user_username": "johnsmith", "user_id": 41, - "project_visibility": "private" + "project_visibility": "visibilitylevel|private" } ``` diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 43d21ab0a02..7a18354bf66 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -13,7 +13,7 @@ Starting with GitLab 11.3, the Auto DevOps pipeline is enabled by default for al projects. If it has not been 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. A GitLab -administrator can [change this setting](../../user/admin_area/settings/continuous_integration.html#auto-devops) +administrator can [change this setting](../../user/admin_area/settings/continuous_integration.html#auto-devops-core-only) in the admin area. With Auto DevOps, the software development process becomes easier to set up @@ -114,7 +114,7 @@ To make full use of Auto DevOps, you will need: will need Prometheus installed somewhere (inside or outside your cluster) and configured to scrape your Kubernetes cluster. To get response metrics (in addition to system metrics), you need to - [configure Prometheus to monitor NGINX](../../user/project/integrations/prometheus_library/nginx_ingress.md#configuring-prometheus-to-monitor-for-nginx-ingress-metrics). + [configure Prometheus to monitor NGINX](../../user/project/integrations/prometheus_library/nginx_ingress.md#configuring-nginx-ingress-monitoring). The [Prometheus service](../../user/project/integrations/prometheus.md) integration needs to be enabled for the project, or enabled as a [default service template](../../user/project/integrations/services_templates.md) @@ -166,7 +166,7 @@ them to the Kubernetes pods that run your application(s). 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). +[exists between them](../../user/project/clusters/index.md#multiple-kubernetes-clusters-premium). 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: @@ -179,7 +179,7 @@ Those environments are tied to jobs that use [Auto Deploy](#auto-deploy), so except for the environment scope, they would also need to have a different domain they would be deployed to. This is why you need to define a separate `KUBE_INGRESS_BASE_DOMAIN` variable for all the above -[based on the environment](../../ci/variables/README.md#limiting-environment-scopes-of-variables). +[based on the environment](https://docs.gitlab.com/ee/ci/variables/index.html#limiting-environment-scopes-of-variables-premium). The following table is an example of how the three different clusters would be configured. @@ -188,7 +188,7 @@ be configured. | ------------ | -------------- | ----------------------------- | ------------- | ------ | | review | `review/*` | `review.example.com` | `review/*` | The review cluster which will run all [Review Apps](../../ci/review_apps/index.md). `*` is a wildcard, which means it will be used by every environment name starting with `review/`. | | staging | `staging` | `staging.example.com` | `staging` | (Optional) The staging cluster which will run the deployments of the staging environments. You need to [enable it first](#deploy-policy-for-staging-and-production-environments). | -| production | `production` | `example.com` | `production` | The production cluster which will run the deployments of the production environment. You can use [incremental rollouts](#incremental-rollout-to-production). | +| production | `production` | `example.com` | `production` | The production cluster which will run the deployments of the production environment. You can use [incremental rollouts](#incremental-rollout-to-production-premium). | To add a different cluster for each environment: @@ -269,12 +269,12 @@ The available options are: - **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 + [`INCREMENTAL_ROLLOUT_MODE`](#timed-incremental-rollout-to-production-premium) 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_MODE`](#incremental-rollout-to-production) variables + [`INCREMENTAL_ROLLOUT_MODE`](#incremental-rollout-to-production-premium) variables to `1` and `manual`. This means: - `master` branch is directly deployed to staging. @@ -503,7 +503,7 @@ Auto Deploy doesn't include deployments to staging or canary by default, but the [Auto DevOps template] contains job definitions for these tasks if you want to enable them. -You can make use of [environment variables](#helm-chart-variables) to automatically +You can make use of [environment variables](#environment-variables) to automatically scale your pod replicas. It's important to note that when a project is deployed to a Kubernetes cluster, @@ -581,7 +581,7 @@ The metrics include: 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. [Deploy Prometheus](../../user/project/integrations/prometheus.md) into your Kubernetes cluster 1. If you would like response metrics, ensure you are running at least version 0.9.0 of NGINX Ingress and [enable Prometheus metrics](https://github.com/kubernetes/ingress-nginx/blob/master/docs/examples/customization/custom-vts-metrics-prometheus/nginx-vts-metrics-conf.yaml). @@ -684,7 +684,7 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | **Variable** | **Description** | | ------------ | --------------- | -| `AUTO_DEVOPS_DOMAIN` | The [Auto DevOps domain](#auto-devops-domain). By default, set automatically by the [Auto DevOps setting](#enabling-auto-devops). This variable is deprecated and [is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959). Use `KUBE_INGRESS_BASE_DOMAIN` instead. | +| `AUTO_DEVOPS_DOMAIN` | The [Auto DevOps domain](#auto-devops-base-domain). By default, set automatically by the [Auto DevOps setting](#enablingdisabling-auto-devops). This variable is deprecated and [is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959). Use `KUBE_INGRESS_BASE_DOMAIN` instead. | | `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). | | `AUTO_DEVOPS_CHART_REPOSITORY` | The Helm Chart repository used to search for charts; defaults to `https://charts.gitlab.io`. | | `REPLICAS` | The number of replicas to deploy; defaults to 1. | @@ -704,8 +704,8 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | `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_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> | +| `CANARY_ENABLED` | From GitLab 11.0, this variable can be used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments-premium). | +| `INCREMENTAL_ROLLOUT_MODE`| From GitLab 11.4, this variable, if present, can be used to enable an [incremental rollout](#incremental-rollout-to-production-premium) 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. | @@ -939,7 +939,7 @@ 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). +[incremental rollout to production](#incremental-rollout-to-production-premium). Everything behaves the same way, except: diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 9749bd63f2b..367e192b85a 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -159,15 +159,15 @@ In the **test** stage, GitLab runs various checks on the application: - The `test` job runs unit and integration tests by detecting the language and framework ([Auto Test](index.md#auto-test)) - The `code_quality` job checks the code quality and is allowed to fail - ([Auto Code Quality](index.md#auto-code-quality)) **[STARTER]** + ([Auto Code Quality](index.md#auto-code-quality-starter)) **[STARTER]** - The `container_scanning` job checks the Docker container if it has any vulnerabilities and is allowed to fail ([Auto Container Scanning](index.md#auto-container-scanning)) - The `dependency_scanning` job checks if the application has any dependencies - susceptible to vulnerabilities and is allowed to fail ([Auto Dependency Scanning](index.md#auto-dependency-scanning)) **[ULTIMATE]** + susceptible to vulnerabilities and is allowed to fail ([Auto Dependency Scanning](index.md#auto-dependency-scanning-ultimate)) **[ULTIMATE]** - The `sast` job runs static analysis on the current code to check for potential - security issues and is allowed to fail([Auto SAST](index.md#auto-sast)) **[ULTIMATE]** + security issues and is allowed to fail([Auto SAST](index.md#auto-sast-ultimate)) **[ULTIMATE]** - The `license_management` job searches the application's dependencies to determine each of their - licenses and is allowed to fail ([Auto License Management](index.md#auto-license-management)) **[ULTIMATE]** + licenses and is allowed to fail ([Auto License Management](index.md#auto-license-management-ultimate)) **[ULTIMATE]** NOTE: **Note:** As you might have noticed, all jobs except `test` are allowed to fail in the @@ -178,7 +178,7 @@ deploys the application in Kubernetes ([Auto Deploy](index.md#auto-deploy)). Lastly, in the **performance** stage, some performance tests will run on the deployed application -([Auto Browser Performance Testing](index.md#auto-browser-performance-testing)). **[PREMIUM]** +([Auto Browser Performance Testing](index.md#auto-browser-performance-testing-premium)). **[PREMIUM]** --- @@ -285,8 +285,8 @@ all within GitLab. Despite its automatic nature, Auto DevOps can also be configu and customized to fit your workflow. Here are some helpful resources for further reading: 1. [Auto DevOps](index.md) -1. [Multiple Kubernetes clusters](index.md#using-multiple-kubernetes-clusters) **[PREMIUM]** -1. [Incremental rollout to production](index.md#incremental-rollout-to-production) **[PREMIUM]** +1. [Multiple Kubernetes clusters](index.md#using-multiple-kubernetes-clusters-premium) **[PREMIUM]** +1. [Incremental rollout to production](index.md#incremental-rollout-to-production-premium) **[PREMIUM]** 1. [Disable jobs you don't need with environment variables](index.md#environment-variables) 1. [Use a static IP for your cluster](../../user/project/clusters/index.md#using-a-static-ip) 1. [Use your own buildpacks to build your application](index.md#custom-buildpacks) diff --git a/doc/university/high-availability/aws/README.md b/doc/university/high-availability/aws/README.md index b4ba5b7a24e..4095f71e501 100644 --- a/doc/university/high-availability/aws/README.md +++ b/doc/university/high-availability/aws/README.md @@ -125,10 +125,10 @@ image below we have the settings for this article but note the following two options which are of particular interest for HA: 1. Multi-AZ-Deployment is recommended as redundancy. Read more at -[High Availability (Multi-AZ)](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html) + [High Availability (Multi-AZ)](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html) 1. While we chose a General Purpose (SSD) for this article a Provisioned -IOPS (SSD) is best suited for HA. Read more about it at -[Storage for Amazon RDS](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Storage.html) + IOPS (SSD) is best suited for HA. Read more about it at + [Storage for Amazon RDS](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Storage.html)  diff --git a/doc/university/training/end-user/README.md b/doc/university/training/end-user/README.md index 60c0eadc572..99fb5e83387 100644 --- a/doc/university/training/end-user/README.md +++ b/doc/university/training/end-user/README.md @@ -86,6 +86,7 @@ git config --global user.email you@example.com ```bash git config --global --list ``` + - You might want or be required to use an SSH key. - Instructions: [SSH](http://doc.gitlab.com/ce/ssh/README.html) @@ -413,6 +414,7 @@ Revert is safer considering we can revert a revert --- ### Version Control + - Local VCS was used with a filesystem or a simple db. - Centralized VCS such as Subversion includes collaboration but still is prone to data loss as the main server is the single point of diff --git a/doc/university/training/topics/stash.md b/doc/university/training/topics/stash.md index f1c91fb1b37..dfd28fbcbc9 100644 --- a/doc/university/training/topics/stash.md +++ b/doc/university/training/topics/stash.md @@ -30,7 +30,7 @@ and we need to change to a different branch. ---------- - Every time we save a stash it gets stacked so by using list we can see all our -stashes. + stashes. ``` git stash list diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md index 1f4b5fbffa7..350072186ee 100644 --- a/doc/update/mysql_to_postgresql.md +++ b/doc/update/mysql_to_postgresql.md @@ -95,7 +95,7 @@ Now, you can use pgloader to migrate the data from MySQL to PostgreSQL: ``` 1. Once the migration finishes, you should see a summary table that looks like -the following: + the following: ``` table name read imported errors total time @@ -242,7 +242,7 @@ Now, you can use pgloader to migrate the data from MySQL to PostgreSQL: ``` 1. Once the migration finishes, you should see a summary table that looks like -the following: + the following: ``` table name read imported errors total time diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md new file mode 100644 index 00000000000..00cea22e4e1 --- /dev/null +++ b/doc/user/admin_area/index.md @@ -0,0 +1,29 @@ +# GitLab Admin Area **[CORE ONLY]** + +The Admin Area provides a web UI for administering some features of GitLab self-managed instances. + +To access the Admin Area, either: + +- Click the Admin Area icon (the spanner or wrench icon). +- Visit `/admin` on your self-managed instance. + +NOTE: **Note:** +Only admin users can access the Admin Area. + +## Admin Area sections + +The Admin Area is made up of the following sections: + +| Section | Description | +|:------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------| +| Overview | View your GitLab Dashboard, and maintain projects, users, groups, jobs, runners, and Gitaly servers. | +| Monitoring | View GitLab system information, and information on background jobs, logs, [health checks](monitoring/health_check.md), request profiles, and audit logs. | +| Messages | Send and manage [broadcast messages](broadcast_messages.md) for your users. | +| System Hooks | Configure [system hooks](../../system_hooks/system_hooks.md) for many events. | +| Applications | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services. | +| Abuse Reports | Manage [abuse reports](abuse_reports.md) submitted by your users. | +| Deploy Keys | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys). | +| Service Templates | Create [service templates](../project/integrations/services_templates.md) for projects. | +| Labels | Create and maintain [labels](labels.md) for your GitLab instance. | +| Appearance | Customize [GitLab's appearance](../../customization/index.md). | +| Settings | Modify the [settings](settings/index.md) for your GitLab instance. | diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index d4853a5842e..01979f12a01 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -20,7 +20,7 @@ From now on, every existing project and newly created ones that don't have a `.gitlab-ci.yml`, will use the Auto DevOps pipelines. If you want to disable it for a specific project, you can do so in -[its settings](../../../topics/autodevops/index.md#enabling-auto-devops). +[its settings](../../../topics/autodevops/index.md##enablingdisabling-auto-devops). ## Maximum artifacts size **[CORE ONLY]** @@ -38,7 +38,7 @@ To change it: 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) +described in [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) and the default value is `30 days`. On GitLab.com they [never expire](../../gitlab_com/index.md#gitlab-ci-cd). @@ -47,7 +47,7 @@ and the default value is `30 days`. On GitLab.com they 1. Hit **Save changes** for the changes to take effect. This setting is set per job and can be overridden in -[`.gitlab-ci.yml`](../../../ci/yaml/README.md#artifacts-expire_in). +[`.gitlab-ci.yml`](../../../ci/yaml/README.md#artifactsexpire_in). To disable the expiration, set it to `0`. The default unit is in seconds. ## Archive jobs **[CORE ONLY]** diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index d202b1260ad..1e2fad1efe9 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -248,10 +248,10 @@ For large projects with many contributors, it may be useful to stop discussions in issues or merge requests in these scenarios: - The project maintainer has already resolved the discussion and it is not helpful -for continued feedback. The project maintainer has already directed new conversation -to newer issues or merge requests. + for continued feedback. The project maintainer has already directed new conversation + to newer issues or merge requests. - The people participating in the discussion are trolling, abusive, or otherwise -being unproductive. + being unproductive. In these cases, a user with Developer permissions or higher in the project can lock (and unlock) an issue or a merge request, using the "Lock" section in the sidebar. For issues, @@ -276,17 +276,17 @@ Additionally locked issues can not be reopened. ## Filtering notes -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/26723) in GitLab 11.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/26723) in GitLab 11.5. -For issues with many comments like activity notes and user comments, sometimes -finding useful information can be hard. There is a way to filter comments from single notes and discussions for merge requests and issues. +For issues with many comments like activity notes and user comments, sometimes +finding useful information can be hard. There is a way to filter comments from single notes and discussions for merge requests and issues. From a merge request's **Discussion** tab, or from an epic/issue overview, find the filter's dropdown menu on the right side of the page, from which you can choose one of the following options: - **Show all activity**: displays all user comments and system notes -(issue updates, mentions from other issues, changes to the description, etc). + (issue updates, mentions from other issues, changes to the description, etc). - **Show comments only**: only displays user comments in the list. -- **Show history only**: only displays activity notes. +- **Show history only**: only displays activity notes.  @@ -298,21 +298,21 @@ from any device you're logged into. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/18008) in GitLab 11.6. -As a reviewer, you're able to suggest code changes with a simple +As a reviewer, you're able to suggest code changes with a simple markdown syntax in Merge Request Diff discussions. Then, the -Merge Request author (or other users with appropriate +Merge Request author (or other users with appropriate [permission](../permissions.md)) is able to apply these -suggestions with a click, which will generate a commit in +suggestions with a click, which will generate a commit in the Merge Request authored by the user that applied them. 1. Choose a line of code to be changed, add a new comment, then click -on the **Insert suggestion** icon in the toolbar: + on the **Insert suggestion** icon in the toolbar:  - + > **Note:** The suggestion will only affect the commented line. Multi-line - suggestions are currently not supported. Will be introduced by + suggestions are currently not supported. Will be introduced by [#53310](https://gitlab.com/gitlab-org/gitlab-ce/issues/53310). 1. In the comment, add your suggestion to the pre-populated code block: @@ -327,9 +327,9 @@ on the **Insert suggestion** icon in the toolbar:  > **Note:** - Discussions are _not_ automatically resolved. Will be introduced by + Discussions are _not_ automatically resolved. Will be introduced by [#54405](https://gitlab.com/gitlab-org/gitlab-ce/issues/54405). - + Once the author applies a suggestion, it will be marked with the **Applied** label, and GitLab will create a new commit with the message `Apply suggestion to <file-name>` and push the suggested change directly into the codebase in the merge request's branch. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index c1c9b8bf43c..762cf911fcf 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -60,7 +60,7 @@ Below are the current settings regarding [GitLab CI/CD](../../ci/README.md). | Setting | GitLab.com | Default | | ----------- | ----------------- | ------------- | | Artifacts maximum size | 1G | 100M | -| Artifacts [expiry time](../../ci/yaml/README.md#artifacts-expire_in) | kept forever | deleted after 30 days unless otherwise specified | +| Artifacts [expiry time](../../ci/yaml/README.md#artifactsexpire_in) | kept forever | deleted after 30 days unless otherwise specified | ## Repository size limit diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 5fea683a7fd..300e0115c60 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -18,9 +18,9 @@ a link to the group settings. By clicking the last button you can leave that gro You can create groups for numerous reasons. To name a few: - Organize related projects under the same [namespace](#namespaces), add members to that -group and grant access to all their projects at once + 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 + `@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`, @@ -43,11 +43,11 @@ In GitLab, a namespace is a unique name to be used as a user name, a group name, For example, consider a user named Alex: 1. Alex creates an account on GitLab.com with the username `alex`; -their profile will be accessed under `https://gitlab.example.com/alex` + their profile will be accessed under `https://gitlab.example.com/alex` 1. Alex creates a group for their team with the groupname `alex-team`; -the group and its projects will be accessed under `https://gitlab.example.com/alex-team` + the group and its projects will be accessed under `https://gitlab.example.com/alex-team` 1. Alex creates a subgroup of `alex-team` with the subgroup name `marketing`; -this subgroup and its projects will be accessed under `https://gitlab.example.com/alex-team/marketing` + this subgroup and its projects will be accessed under `https://gitlab.example.com/alex-team/marketing` By doing so: @@ -107,7 +107,7 @@ Consider we have a group with two projects: - On the **Group Members** page we can now add a new user to the group. - Now because this user is a **Developer** member of the group, he automatically -gets **Developer** access to **all projects** within that group. + gets **Developer** access to **all projects** within that group. If necessary, you can increase the access level of an individual user for a specific project, by adding them again as a new member to the project with the new permission levels. @@ -267,9 +267,9 @@ Define project templates at a group-level by setting a group as a template sourc ### Advanced settings - **Projects**: view all projects within that group, add members to each project, -access each project's settings, and remove any project from the same screen. + access each project's settings, and remove any project from the same screen. - **Webhooks**: configure [webhooks](../project/integrations/webhooks.md) to your group. - **Kubernetes cluster integration**: connect your GitLab group with [Kubernetes clusters](clusters/index.md). - **Audit Events**: view [Audit Events](https://docs.gitlab.com/ee/administration/audit_events.html#audit-events) -for the group. **[STARTER ONLY]** + for the group. **[STARTER ONLY]** - **Pipelines quota**: keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group. diff --git a/doc/user/index.md b/doc/user/index.md index 22506b30498..71378920ed4 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -38,10 +38,10 @@ GitLab is a Git-based platform that integrates a great number of essential tools - Hosting code in repositories with version control - Tracking proposals for new implementations, bug reports, and feedback with a -fully featured [Issue Tracker](project/issues/index.md#issue-tracker) + fully featured [Issue Tracker](project/issues/index.md#issue-tracker) - Organizing and prioritizing with [Issue Boards](project/issues/index.md#issue-boards) - Reviewing code in [Merge Requests](project/merge_requests/index.md) with live-preview changes per -branch with [Review Apps](../ci/review_apps/index.md) + branch with [Review Apps](../ci/review_apps/index.md) - Building, testing and deploying with built-in [Continuous Integration](../ci/README.md) - Deploying personal and professional static websites with [GitLab Pages](project/pages/index.md) - Integrating with Docker by using [GitLab Container Registry](project/container_registry.md) @@ -51,9 +51,9 @@ With GitLab Enterprise Edition, you can also: - Provide support with [Service Desk](https://docs.gitlab.com/ee/user/project/service_desk.html) - Improve collaboration with -[Merge Request Approvals](https://docs.gitlab.com/ee/user/project/merge_requests/index.html#merge-request-approvals), -[Multiple Assignees for Issues](https://docs.gitlab.com/ee/user/project/issues/multiple_assignees_for_issues.html), -and [Multiple Issue Boards](https://docs.gitlab.com/ee/user/project/issue_board.html#multiple-issue-boards) + [Merge Request Approvals](https://docs.gitlab.com/ee/user/project/merge_requests/index.html#merge-request-approvals), + [Multiple Assignees for Issues](https://docs.gitlab.com/ee/user/project/issues/multiple_assignees_for_issues.html), + and [Multiple Issue Boards](https://docs.gitlab.com/ee/user/project/issue_board.html#multiple-issue-boards) - Create formal relationships between issues with [Related Issues](https://docs.gitlab.com/ee/user/project/issues/related_issues.html) - Use [Burndown Charts](https://docs.gitlab.com/ee/user/project/milestones/burndown_charts.html) to track progress during a sprint or while working on a new version of their software. - Leverage [Elasticsearch](https://docs.gitlab.com/ee/integration/elasticsearch.html) with [Advanced Global Search](https://docs.gitlab.com/ee/user/search/advanced_global_search.html) and [Advanced Syntax Search](https://docs.gitlab.com/ee/user/search/advanced_search_syntax.html) for faster, more advanced code search across your entire GitLab instance @@ -77,12 +77,12 @@ build, test, and deploy your app with built-in GitLab CI/CD. Or, you can do it all at once, from one single project. - [Repositories](project/repository/index.md): Host your codebase in -repositories with version control and as part of a fully integrated platform. + repositories with version control and as part of a fully integrated platform. - [Issues](project/issues/index.md): Explore the best of GitLab Issues' features. - [Merge Requests](project/merge_requests/index.md): Collaborate on code, -reviews, live preview changes per branch, and request approvals with Merge Requests. + reviews, live preview changes per branch, and request approvals with Merge Requests. - [Milestones](project/milestones/index.md): Work on multiple issues and merge -requests towards the same target date with Milestones. + requests towards the same target date with Milestones. ## GitLab CI/CD @@ -92,9 +92,9 @@ 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. + images with Container Registry. ## Account @@ -102,13 +102,13 @@ There is a lot you can customize and configure to enjoy the best of GitLab. - [Settings](profile/index.md): Manage your user settings to change your personal info, -personal access tokens, authorized applications, etc. + personal access tokens, authorized applications, etc. - [Authentication](../topics/authentication/index.md): Read through the authentication -methods available in GitLab. + methods available in GitLab. - [Permissions](permissions.md): Learn the different set of permissions levels for each -user type (guest, reporter, developer, maintainer, owner). + user type (guest, reporter, developer, maintainer, owner). - [Feature highlight](feature_highlight.md): Learn more about the little blue dots -around the app that explain certain features + around the app that explain certain features - [Abuse reports](abuse_reports.md): Report abuse from users to GitLab administrators ## Groups diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 0a7c5832a2d..8e5fe4b0fb9 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -41,7 +41,7 @@ or a U2F device. **On your phone:** 1. Install a compatible application. We recommend [Google Authenticator] -\(proprietary\) or [FreeOTP] \(open source\). + \(proprietary\) or [FreeOTP] \(open source\). 1. In the application, add a new entry in one of two ways: - Scan the code with your phone's camera to add the entry automatically. - Enter the details provided to add the entry manually. diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index ba756c4b793..a2b15d058d7 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -35,13 +35,13 @@ From there, you can: - Manage [2FA](account/two_factor_authentication.md) - Change your username and [delete your account](account/delete_account.md) - Manage applications that can -[use GitLab as an OAuth provider](../../integration/oauth_provider.md#introduction-to-oauth) + [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 + to customize your own GitLab experience - [View your active sessions](active_sessions.md) and revoke any of them if necessary - Access your audit log, a security log of important events involving your account diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 7387d1810ca..db68510c46d 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -93,6 +93,12 @@ You can choose between 3 options: ## Localization +### Language + +Select your preferred language from a list of supported languages. + +*This feature is experimental and translations are not complete yet.* + ### First day of the week The first day of the week can be customised for calendar views and date pickers. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 85a4af24dc5..e601d7b2ccc 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -86,15 +86,20 @@ To add an existing Kubernetes cluster to your project: 1. Click **Add Kubernetes cluster**. 1. Click **Add an existing Kubernetes cluster** and fill in the details: - **Kubernetes cluster name** (required) - The name you wish to give the cluster. - - **Environment scope** (required)- The + - **Environment scope** (required) - The [associated environment](#setting-the-environment-scope) to this cluster. - **API URL** (required) - It's the URL that GitLab uses to access the Kubernetes API. Kubernetes exposes several APIs, we want the "base" URL that is common to all of them, e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. - - **CA certificate** (optional) - - If the API is using a self-signed TLS certificate, you'll also need to include - the `ca.crt` contents here. + - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the EKS cluster. We will use the certificate created by default. + - List the secrets with `kubectl get secrets`, and one should named similar to + `default-token-xxxxx`. Copy that token name for use below. + - Get the certificate by running this command: + + ```sh + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode + ``` - **Token** - GitLab authenticates against Kubernetes using service tokens, which are scoped to a particular `namespace`. @@ -102,36 +107,81 @@ To add an existing Kubernetes cluster to your project: [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) privileges.** To create this service account: - 1. Create a `gitlab` service account in the `default` namespace: + 1. Create a file called `gitlab-admin-service-account.yaml` with contents: - ```bash - kubectl create -f - <<EOF - apiVersion: v1 - kind: ServiceAccount - metadata: - name: gitlab - namespace: default - EOF + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: gitlab-admin + namespace: kube-system ``` - 1. Create a cluster role binding to give the `gitlab` service account - `cluster-admin` privileges: + + 2. Apply the service account to your cluster: ```bash - kubectl create -f - <<EOF + kubectl apply -f gitlab-admin-service-account.yaml + ``` + + Output: + + ```bash + serviceaccount "gitlab-admin" created + ``` + + 3. Create a file called `gitlab-admin-cluster-role-binding.yaml` with contents: + + ```yaml + apiVersion: rbac.authorization.k8s.io/v1beta1 kind: ClusterRoleBinding - apiVersion: rbac.authorization.k8s.io/v1 metadata: - name: gitlab-cluster-admin - subjects: - - kind: ServiceAccount - name: gitlab - namespace: default + name: gitlab-admin roleRef: + apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: cluster-admin - apiGroup: rbac.authorization.k8s.io - EOF + subjects: + - kind: ServiceAccount + name: gitlab-admin + namespace: kube-system + ``` + + 4. Apply the cluster role binding to your cluster: + + ```bash + kubectl apply -f gitlab-admin-cluster-role-binding.yaml + ``` + + Output: + + ```bash + clusterrolebinding "gitlab-admin" created + ``` + + 5. Retrieve the token for the `gitlab-admin` service account: + + ```bash + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') ``` + + Copy the `<authentication_token>` value from the output: + + ```yaml + Name: gitlab-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=gitlab-admin + kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 + + Type: kubernetes.io/service-account-token + + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` + NOTE: **Note:** For GKE clusters, you will need the `container.clusterRoleBindings.create` permission to create a cluster @@ -307,6 +357,28 @@ you should be careful as GitLab cannot detect it. In this case, installing Tiller via the applications will result in the cluster having it twice, which can lead to confusion during deployments. +### Upgrading applications + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24789) +in GitLab 11.8. + +Users can perform a one-click upgrade for the GitLab Runner application, +when there is an upgrade available. + +To upgrade the GitLab Runner application: + +1. Navigate to your project's **Operations > Kubernetes**. +1. Select your cluster. +1. Click the **Upgrade** button for the Runnner application. + +The **Upgrade** button will not be shown if there is no upgrade +available. + +NOTE: **Note:** +Upgrades will reset values back to the values built into the `runner` +chart plus the values set by +[`values.yaml`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/vendor/runner/values.yaml) + ## Getting the external IP address NOTE: **Note:** diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index e1b8dc07b50..512a4cb32f4 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -23,7 +23,7 @@ runbooks. A sample runbook is provided, showcasing common operations. **<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch this [video](https://www.youtube.com/watch?v=Q_OqHIIUPjE) -for an overview of how this is acomplished in GitLab!** +for an overview of how this is accomplished in GitLab!** ## Requirements diff --git a/doc/user/project/clusters/serverless/img/app-domain.png b/doc/user/project/clusters/serverless/img/app-domain.png Binary files differdeleted file mode 100644 index d113dfadd2e..00000000000 --- a/doc/user/project/clusters/serverless/img/app-domain.png +++ /dev/null diff --git a/doc/user/project/clusters/serverless/img/dns-entry.png b/doc/user/project/clusters/serverless/img/dns-entry.png Binary files differindex 678743f256e..351e40b77d5 100644 --- a/doc/user/project/clusters/serverless/img/dns-entry.png +++ b/doc/user/project/clusters/serverless/img/dns-entry.png diff --git a/doc/user/project/clusters/serverless/img/install-knative.png b/doc/user/project/clusters/serverless/img/install-knative.png Binary files differindex 93b1cbe602f..ecc2f8fb481 100644 --- a/doc/user/project/clusters/serverless/img/install-knative.png +++ b/doc/user/project/clusters/serverless/img/install-knative.png diff --git a/doc/user/project/clusters/serverless/img/serverless-page.png b/doc/user/project/clusters/serverless/img/serverless-page.png Binary files differindex 814b8532205..a872fda7740 100644 --- a/doc/user/project/clusters/serverless/img/serverless-page.png +++ b/doc/user/project/clusters/serverless/img/serverless-page.png diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index fc3a4a757d0..f7e72efa2ba 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -25,8 +25,12 @@ To run Knative on Gitlab, you will need: 1. **Kubernetes Cluster:** An RBAC-enabled Kubernetes cluster is required to deploy Knative. The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab). + The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. 1. **Helm Tiller:** Helm is a package manager for Kubernetes and is required to install Knative. +1. **GitLab Runner:** A runner is required to run the CI jobs that will deploy serverless + applications or functions onto your cluster. You can install the GitLab Runner + onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. 1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an external IP address for all the applications served by Knative. You will be prompted to enter a wildcard domain where your applications will be served. Configure your DNS server to use the @@ -45,9 +49,9 @@ To run Knative on Gitlab, you will need: NOTE: **Note:** The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. **RBAC must be enabled.** -1. [Add a Kubernetes cluster](../index.md) and install Helm. -1. Once Helm has been successfully installed, on the Knative app section, enter the domain to be used with - your application and click "Install". +1. [Add a Kubernetes cluster](../index.md) and [install Helm](../index.md#installing-applications). +1. Once Helm has been successfully installed, scroll down to the Knative app section. Enter the domain to be used with + your application/functions (e.g. `example.com`) and click **Install**.  @@ -66,12 +70,16 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22. 1. The ingress is now available at this address and will route incoming requests to the proper service based on the DNS name in the request. To support this, a wildcard DNS A record should be created for the desired domain name. For example, - if your Knative base domain is `knative.info` then you need to create an A record with domain `*.knative.info` + if your Knative base domain is `example.com` then you need to create an A record with domain `*.example.com` pointing the ip address of the ingress.  -## Deploying Functions +NOTE: **Note:** +You can deploy either [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications) +on a given project but not both. The current implementation makes use of a `serverless.yml` file to signal a FaaS project. + +## Deploying functions > Introduced in GitLab 11.6. @@ -84,7 +92,7 @@ Currently the following [runtimes](https://gitlab.com/triggermesh/runtimes) are - node.js - kaniko -You can find all the files referenced in this doc in the [functions example project](https://gitlab.com/knative-examples/functions). +You can find and import all the files referenced in this doc in the **[functions example project](https://gitlab.com/knative-examples/functions)**. Follow these steps to deploy a function using the Node.js runtime to your Knative instance: @@ -188,16 +196,27 @@ The function details can be retrieved directly from Knative on the cluster: kubectl -n "$KUBE_NAMESPACE" get services.serving.knative.dev ``` -The sample function can now be triggered from any HTTP client using a simple `POST` call. +The sample function can now be triggered from any HTTP client using a simple `POST` call: + + 1. Using curl - + ```bash + curl \ + --header "Content-Type: application/json" \ + --request POST \ + --data '{"GitLab":"FaaS"}' \ + http://functions-echo.functions-1.functions.example.net/ + ``` + 2. Using a web-based tool (ie. postman, restlet, etc) + +  ## Deploying Serverless applications > Introduced in GitLab 11.5. NOTE: **Note:** -You can reference the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. +You can reference and import the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. Add the following `.gitlab-ci.yml` to the root of your repository (you may skip this step if using the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) mentioned above): @@ -236,11 +255,7 @@ With all the pieces in place, the next time a CI pipeline runs, the Knative appl ### Obtain the URL for the Knative deployment -Go to the **Operations > Serverless** page to find the URL for your deployment in the **Domain** column. - - - -Alternatively, use the CI/CD deployment job output to obtain the deployment URL. Once all the stages of the pipeline finish, click the **deploy** stage. +Go to the **CI/CD > Pipelines** and click on the pipeline that deployed your app. Once all the stages of the pipeline finish, click the **deploy** stage.  @@ -262,7 +277,7 @@ registry.staging.gitlab.com/danielgruesso/knative $ tm -n "$KUBE_NAMESPACE" --config "$KUBECONFIG" deploy service "$CI_PROJECT_NAME" --from-image "$CI_REGISTRY_IMAGE" --wait Deployment started. Run "tm -n knative-4342902 describe service knative" to see the details Waiting for ready state....... -Service domain: knative.knative-4342902.knative.info +Service domain: knative.knative-4342902.example.com Job succeeded ``` diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md index 529a82ded9e..05127b274e0 100644 --- a/doc/user/project/cycle_analytics.md +++ b/doc/user/project/cycle_analytics.md @@ -80,6 +80,7 @@ Here's a little explanation of how this works behind the scenes: To sum up, anything that doesn't follow the [GitLab flow] won't be tracked at all. So, the Cycle Analytics dashboard won't present any data: + - For merge requests that do not close an issue. - For issues not labeled with a label present in the Issue Board. - For issues not assigned a milestone. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index ebf87890cfd..d51a0c0ccca 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -22,14 +22,14 @@ Import your projects from Bitbucket Server to GitLab with minimal effort. ## Limitations 1. Currently GitLab doesn't allow comments on arbitrary lines of code, so any -Bitbucket comments out of bounds will be inserted as comments in the merge -request. + Bitbucket comments out of bounds will be inserted as comments in the merge + request. 1. Bitbucket Server allows multiple levels of threading. GitLab -import will collapse this into one discussion and quote part of the original -comment. + import will collapse this into one discussion and quote part of the original + comment. 1. Declined pull requests have unreachable commits, which prevents the GitLab -importer from generating a proper diff. These pull requests will show up as -empty changes. + importer from generating a proper diff. These pull requests will show up as + empty changes. 1. Attachments in Markdown are currently not imported. 1. Task lists are not imported. 1. Emoji reactions are not imported diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 17222c53675..13409c93929 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -23,6 +23,6 @@ users to GitLab users.  1. Once the import has finished click the link to take you to the project -dashboard. Follow the directions to push your existing repository. + dashboard. Follow the directions to push your existing repository.  diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index cf99dded5e2..63b90dd76fd 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -67,7 +67,7 @@ developer documentation. Before you begin, ensure that any GitHub users who you want to map to GitLab users have either: - A GitLab account that has logged in using the GitHub icon -\- or - + \- or - - A GitLab account with an email address that matches the [public email address](https://help.github.com/articles/setting-your-commit-email-address-on-github/) of the GitHub user User-matching attempts occur in that order, and if a user is not identified either way, the activity is associated with diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 6a1aadf058e..c62de41c539 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -19,7 +19,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Issue Boards](issue_board.md): Organize and prioritize your workflow - [Multiple Issue Boards](https://docs.gitlab.com/ee/user/project/issue_board.html#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project **[STARTER]** - [Repositories](repository/index.md): Host your code in a fully -integrated platform + integrated platform - [Branches](repository/branches/index.md): use Git branching strategies to collaborate on code - [Protected branches](protected_branches.md): Prevent collaborators @@ -29,7 +29,7 @@ integrated platform - [Signing commits](gpg_signed_commits/index.md): use GPG to sign your commits - [Deploy tokens](deploy_tokens/index.md): Manage project-based deploy tokens that allow permanent access to the repository and Container Registry. - [Merge Requests](merge_requests/index.md): Apply your branching -strategy and get reviewed by your team + strategy and get reviewed by your team - [Merge Request Approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html): Ask for approval before implementing a change **[STARTER]** - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): @@ -38,13 +38,13 @@ strategy and get reviewed by your team of the changes proposed in a merge request in a per-branch basis - [Labels](labels.md): Organize issues and merge requests by labels - [Time Tracking](../../workflow/time_tracking.md): Track estimate time -and time spent on + and time spent on the conclusion of an issue or merge request - [Milestones](milestones/index.md): Work towards a target date - [Description templates](description_templates.md): Define context-specific -templates for issue and merge request description fields for your project + templates for issue and merge request description fields for your project - [Slash commands (quick actions)](quick_actions.md): Textual shortcuts for -common actions on issues or merge requests + common actions on issues or merge requests - [Web IDE](web_ide/index.md) **GitLab CI/CD:** @@ -68,7 +68,7 @@ common actions on issues or merge requests - [Kubernetes cluster integration](clusters/index.md): Connecting your GitLab project with a Kubernetes cluster - [GitLab Pages](pages/index.md): Build, test, and deploy your static -website with GitLab Pages + website with GitLab Pages **Other features:** @@ -76,11 +76,11 @@ website with GitLab Pages - [Snippets](../snippets.md): store, share and collaborate on code snippets. - [Cycle Analytics](cycle_analytics.md): review your development lifecycle. - [Syntax highlighting](highlighting.md): an alternative to customize -your code blocks, overriding GitLab's default choice of language. + your code blocks, overriding GitLab's default choice of language. - [Badges](badges.md): badges for the project overview. - [Releases](releases/index.md): a way to track deliverables in your project as snapshot in time of -the source, build output, and other metadata or artifacts -associated with a released version of your code. + the source, build output, and other metadata or artifacts + associated with a released version of your code. ### Project's integrations @@ -96,7 +96,7 @@ Learn how to [create a new project](../../gitlab-basics/create-project.md) in Gi You can [fork a project](../../gitlab-basics/fork-project.md) in order to: - Collaborate on code by forking a project and creating a merge request -from your fork to the upstream project + from your fork to the upstream project - Fork a sample project to work on the top of that ## Project settings diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index f220fa8497a..4fb753d1707 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -30,12 +30,12 @@ need to follow the firsts steps of the next section. 1. Click "Irker". 1. Select the "Active" checkbox. 1. Enter the server host address where `irkerd` runs (defaults to `localhost`) -in the `Server host` field on the Web page + in the `Server host` field on the Web page 1. Enter the server port of `irkerd` (e.g. defaults to 6659) in the -`Server port` field on the Web page. + `Server port` field on the Web page. 1. Optional: if `Default IRC URI` is set, it has to be in the format -`irc[s]://domain.name` and will be prepend to each and every channel provided -by the user which is not a full URI. + `irc[s]://domain.name` and will be prepend to each and every channel provided + by the user which is not a full URI. 1. Specify the recipients (e.g. #channel1, user1, etc.) 1. Save or optionally click "Test Settings". diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 76a2617125e..8112aa21859 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -1,9 +1,9 @@ # Redmine Service 1. To enable the Redmine integration in a project, navigate to the -[Integrations page](project_services.md#accessing-the-project-services), click -the **Redmine** service, and fill in the required details on the page as described -in the table below. + [Integrations page](project_services.md#accessing-the-project-services), click + the **Redmine** service, and fill in the required details on the page as described + in the table below. | Field | Description | | ----- | ----------- | diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index cbf08a4f30a..c3fc6d4b859 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -48,9 +48,9 @@ Navigate to the webhooks page by going to your project's ## Use-cases - You can set up a webhook in GitLab to send a notification to -[Slack](https://api.slack.com/incoming-webhooks) every time a build fails, for example + [Slack](https://api.slack.com/incoming-webhooks) every time a build fails, for example - You can [integrate with Twilio to be notified via SMS](https://www.datadoghq.com/blog/send-alerts-sms-customizable-webhooks-twilio/) -every time an issue is created for a specific project or group within GitLab + every time an issue is created for a specific project or group within GitLab - You can use them to [automatically assign labels to merge requests](https://about.gitlab.com/2016/08/19/applying-gitlab-labels-automatically/). ## Webhook endpoint tips diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 7962eeada5c..0bd565547c3 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -78,9 +78,9 @@ with labels, and from there organize and prioritize them with Issue Boards. For example, let's consider this simplified development workflow: 1. You have a repository hosting your app's codebase -and your team actively contributing to code + and your team actively contributing to code 1. Your **backend** team starts working a new -implementation, gathers feedback and approval, and pass it over to **frontend** + implementation, gathers feedback and approval, and pass it over to **frontend** 1. When frontend is complete, the new feature is deployed to **staging** to be tested 1. When successful, it is deployed to **production** @@ -88,7 +88,7 @@ If we have the labels "**backend**", "**frontend**", "**staging**", and "**production**", and an Issue Board with a list for each, we can: - Visualize the entire flow of implementations since the -beginning of the development lifecycle until deployed to production + beginning of the development lifecycle until deployed to production - Prioritize the issues in a list by moving them vertically - Move issues between lists to organize them according to the labels you've set - Add multiple issues to lists in the board by selecting one or more existing issues @@ -177,7 +177,7 @@ menu from where you can create another Issue Board and rename or delete the existing one. Using the search box at the top of the menu, you can filter the listed boards. -When you're revisiting an issue board in a project or group with multiple boards, +When you're revisiting an issue board in a project or group with multiple boards, GitLab will automatically load the last board you visited. NOTE: **Note:** @@ -234,7 +234,7 @@ 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. +one group issue board per group was made available in GitLab 10.6 Core.  diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md index afb7d9ada5f..c3e06b219ff 100644 --- a/doc/user/project/issues/automatic_issue_closing.md +++ b/doc/user/project/issues/automatic_issue_closing.md @@ -1,6 +1,7 @@ # Automatic issue closing >**Notes:** +> > - This is the user docs. In order to change the default issue closing pattern, > follow the steps in the [administration docs]. > - For performance reasons, automatic issue closing is disabled for the very diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md index 2bf4fa287e9..40040e44d64 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -79,6 +79,6 @@ in the same URL (since a description template just populates the description fie Follow these examples to form your new issue URL with prefilled fields. - For a new issue in the GitLab Community Edition project with a pre-entered title -and a pre-entered description, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` + and a pre-entered description, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` - For a new issue in the GitLab Community Edition project with a pre-entered title -and a pre-entered description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` + and a pre-entered description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 93306437c6c..7972c14c1c4 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -42,6 +42,7 @@ server's timezone. Issues with due dates can also be exported as an iCalendar feed. The URL of the feed can be added to calendar applications. The feed is accessible by clicking on the _Subscribe to calendar_ button on the following pages: + - on the **Assigned Issues** page that is linked on the right-hand side of the GitLab header - on the **Project Issues** page diff --git a/doc/user/project/issues/issues_functionalities.md b/doc/user/project/issues/issues_functionalities.md index e4a3ff52e07..27b9dc51760 100644 --- a/doc/user/project/issues/issues_functionalities.md +++ b/doc/user/project/issues/issues_functionalities.md @@ -99,16 +99,16 @@ Learn more in the [Issue Weight documentation](https://docs.gitlab.com/ee/workfl #### 10. Notifications - Subscribe: if you are not a participant of the discussion on that issue, but -want to receive notifications on each new input, subscribe to it. + want to receive notifications on each new input, subscribe to it. - Unsubscribe: if you are receiving notifications on that issue but no -longer want to receive them, unsubscribe from it. + longer want to receive them, unsubscribe from it. Read more in the [notifications documentation](../../../workflow/notifications.md#issue--merge-request-events). #### 11. Reference - A quick "copy to clipboard" button for that issue's reference, `foo/bar#xxx`, where `foo` is the `username` or `groupname`, `bar` -is the `project-name`, and `xxx` is the issue number. + is the `project-name`, and `xxx` is the issue number. #### 12. Title and description @@ -138,7 +138,7 @@ interpreted as spam. #### 14. Related Merge Requests - Any merge requests mentioned in that issue's description -or in the issue discussion thread. + or in the issue discussion thread. #### 15. Award emoji @@ -152,8 +152,8 @@ know you like it without spamming them. #### 16. Thread - Comments: collaborate to that issue by posting comments in its thread. -These text fields also fully support -[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). + These text fields also fully support + [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). #### 17. Comment, start a discussion, or comment and close @@ -166,7 +166,7 @@ Once you write a comment, you can either: #### 18. New Merge Request - Create a new merge request (with a new source branch named after the issue) in one action. -The merge request will automatically inherit the milestone and labels of the issue. The merge -request will automatically close that issue when it is merged. + The merge request will automatically inherit the milestone and labels of the issue. The merge + request will automatically close that issue when it is merged. - Optionally, you can just create a [new branch](../repository/web_editor.md#create-a-new-branch-from-an-issue) -named after that issue. + named after that issue. diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md index 90bb92d2062..41aa5b91aa7 100644 --- a/doc/user/project/operations/error_tracking.md +++ b/doc/user/project/operations/error_tracking.md @@ -21,7 +21,7 @@ GitLab provides an easy way to connect Sentry to your project: 1. Sign up to Sentry.io or [deploy your own](#deploying-sentry) Sentry instance. 1. [Find or generate](https://docs.sentry.io/api/auth/) a Sentry auth token for your Sentry project. -Make sure to give the token at least the following scopes: `event:read` and `project:read`. + Make sure to give the token at least the following scopes: `event:read` and `project:read`. 1. Navigate to your project’s **Settings > Operations** and provide the Sentry API URL and auth token. 1. Ensure that the 'Active' checkbox is set. 1. Click **Save changes** for the changes to take effect. diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index e4ee2f7cdfa..05d5a2fd99a 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -376,11 +376,11 @@ manually in the past. Read through the to understand how to go even further on your scripts. - On this blog post, understand the concept of -[using GitLab CI `environments` to deploy your -web app to staging and production](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/). + [using GitLab CI `environments` to deploy your + web app to staging and production](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/). - On this post, learn [how to run jobs sequentially, -in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/) + in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/) - On this blog post, we go through the process of -[pulling specific directories from different projects](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) -to deploy this website you're looking at, docs.gitlab.com. + [pulling specific directories from different projects](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) + to deploy this website you're looking at, docs.gitlab.com. - On this blog post, we teach you [how to use GitLab Pages to produce a code coverage report](https://about.gitlab.com/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 595241b2cba..9a95fb70964 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -77,41 +77,41 @@ Learn more about [namespaces](../../group/index.md#namespaces). #### Project Websites - You created a project called `blog` under your username `john`, -therefore your project URL is `https://gitlab.com/john/blog/`. -Once you enable GitLab Pages for this project, and build your site, -it will be available under `https://john.gitlab.io/blog/`. + therefore your project URL is `https://gitlab.com/john/blog/`. + Once you enable GitLab Pages for this project, and build your site, + it will be available under `https://john.gitlab.io/blog/`. - You created a group for all your websites called `websites`, -and a project within this group is called `blog`. Your project -URL is `https://gitlab.com/websites/blog/`. Once you enable -GitLab Pages for this project, the site will live under -`https://websites.gitlab.io/blog/`. + and a project within this group is called `blog`. Your project + URL is `https://gitlab.com/websites/blog/`. Once you enable + GitLab Pages for this project, the site will live under + `https://websites.gitlab.io/blog/`. - You created a group for your engineering department called `engineering`, -a subgroup for all your documentation websites called `docs`, -and a project within this subgroup is called `workflows`. Your project -URL is `https://gitlab.com/engineering/docs/workflows/`. Once you enable -GitLab Pages for this project, the site will live under -`https://engineering.gitlab.io/docs/workflows`. + a subgroup for all your documentation websites called `docs`, + and a project within this subgroup is called `workflows`. Your project + URL is `https://gitlab.com/engineering/docs/workflows/`. Once you enable + GitLab Pages for this project, the site will live under + `https://engineering.gitlab.io/docs/workflows`. #### User and Group Websites - Under your username, `john`, you created a project called -`john.gitlab.io`. Your project URL will be `https://gitlab.com/john/john.gitlab.io`. -Once you enable GitLab Pages for your project, your website -will be published under `https://john.gitlab.io`. + `john.gitlab.io`. Your project URL will be `https://gitlab.com/john/john.gitlab.io`. + Once you enable GitLab Pages for your project, your website + will be published under `https://john.gitlab.io`. - Under your group `websites`, you created a project called -`websites.gitlab.io`. your project's URL will be `https://gitlab.com/websites/websites.gitlab.io`. -Once you enable GitLab Pages for your project, -your website will be published under `https://websites.gitlab.io`. + `websites.gitlab.io`. your project's URL will be `https://gitlab.com/websites/websites.gitlab.io`. + Once you enable GitLab Pages for your project, + your website will be published under `https://websites.gitlab.io`. > Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) in GitLab 11.8. **General example:** - On GitLab.com, a project site will always be available under -`https://namespace.gitlab.io/project-name` + `https://namespace.gitlab.io/project-name` - On GitLab.com, a user or group website will be available under -`https://namespace.gitlab.io/` + `https://namespace.gitlab.io/` - On your GitLab instance, replace `gitlab.io` above with your -Pages server domain. Ask your sysadmin for this information. + Pages server domain. Ask your sysadmin for this information. _Read on about [Projects for GitLab Pages and URL structure](getting_started_part_two.md)._ diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index b2da1c85c62..daae2f4b5a3 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -19,7 +19,7 @@ To use one or more custom domain with your Pages site, there are two things you should consider first, which we'll cover in this guide: 1. Either if you're adding a **root domain** or a **subdomain**, for which -you'll need to set up [DNS records](#dns-records) + you'll need to set up [DNS records](#dns-records) 1. Whether you want to add an [SSL/TLS certificate](#ssl-tls-certificates) or not To finish the association, you need to [add your domain to your project's Pages settings](#add-your-custom-domain-to-gitlab-pages-settings). @@ -136,13 +136,13 @@ verify your domain's ownership with a TXT record: > **Notes**: > > - **Do not** use a CNAME record if you want to point your -`domain.com` to your GitLab Pages site. Use an `A` record instead. + `domain.com` to your GitLab Pages site. Use an `A` record instead. > - **Do not** add any special chars after the default Pages -domain. E.g., **do not** point your `subdomain.domain.com` to -`namespace.gitlab.io.` or `namespace.gitlab.io/`. + domain. E.g., **do not** point your `subdomain.domain.com` to + `namespace.gitlab.io.` or `namespace.gitlab.io/`. > - GitLab Pages IP on GitLab.com [was changed](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) in 2017 > - GitLab Pages IP on GitLab.com [has been changed](https://about.gitlab.com/2018/07/19/gcp-move-update/#gitlab-pages-and-custom-domains) -from `52.167.214.135` to `35.185.44.232` in 2018 + from `52.167.214.135` to `35.185.44.232` in 2018 ### Add your custom domain to GitLab Pages settings @@ -278,15 +278,15 @@ These fields are found under your **Project**'s **Settings** > **Pages** > **New ### What's what? - A PEM certificate is the certificate generated by the CA, -which needs to be added to the field **Certificate (PEM)**. + which needs to be added to the field **Certificate (PEM)**. - An [intermediate certificate](https://en.wikipedia.org/wiki/Intermediate_certificate_authority) (aka "root certificate") is -the part of the encryption keychain that identifies the CA. -Usually it's combined with the PEM certificate, but there are -some cases in which you need to add them manually. -[CloudFlare certs](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) -are one of these cases. + the part of the encryption keychain that identifies the CA. + Usually it's combined with the PEM certificate, but there are + some cases in which you need to add them manually. + [CloudFlare certs](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) + are one of these cases. - A private key is an encrypted key which validates -your PEM against your domain. + your PEM against your domain. ### Now what? @@ -295,9 +295,9 @@ of this, it's simple: - Your PEM certificate needs to be added to the first field - If your certificate is missing its intermediate, copy -and paste the root certificate (usually available from your CA website) -and paste it in the [same field as your PEM certificate](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/), -just jumping a line between them. + and paste the root certificate (usually available from your CA website) + and paste it in the [same field as your PEM certificate](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/), + just jumping a line between them. - Copy your private key and paste it in the last field >**Note:** diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index c9081a6d72b..644a1c951d3 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -16,7 +16,7 @@ To get started with GitLab Pages, you need: 1. A project 1. A configuration file (`.gitlab-ci.yml`) to deploy your site 1. A specific `job` called `pages` in the configuration file -that will make GitLab aware that you are deploying a GitLab Pages website + that will make GitLab aware that you are deploying a GitLab Pages website 1. A `public` directory with the content of the website Optional Features: @@ -85,16 +85,16 @@ is useful for submitting merge requests to the upstream. ### Create a project from scratch 1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**, -click **New project**, and name it considering the -[practical examples](getting_started_part_one.md#practical-examples). + click **New project**, and name it considering the + [practical examples](getting_started_part_one.md#practical-examples). 1. Clone it to your local computer, add your website -files to your project, add, commit and push to GitLab. + files to your project, add, commit and push to GitLab. 1. From the your **Project**'s page, click **Set up CI/CD**:  1. Choose one of the templates from the dropbox menu. -Pick up the template corresponding to the SSG you're using (or plain HTML). + Pick up the template corresponding to the SSG you're using (or plain HTML).  @@ -107,20 +107,20 @@ where you'll find its default URL. > **Notes:** > > - 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`. 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 -[contribute](https://gitlab.com/pages/pages.gitlab.io/blob/master/CONTRIBUTING.md) -to our examples. + if you don't find yours among the templates, you'll need + 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 + [contribute](https://gitlab.com/pages/pages.gitlab.io/blob/master/CONTRIBUTING.md) + to our examples. > > - The second step _"Clone it to your local computer"_, can be done -differently, achieving the same results: instead of cloning the bare -repository to you local computer and moving your site files into it, -you can run `git init` in your local website directory, add the -remote URL: `git remote add origin git@gitlab.com:namespace/project-name.git`, -then add, commit, and push. + differently, achieving the same results: instead of cloning the bare + repository to you local computer and moving your site files into it, + you can run `git init` in your local website directory, add the + remote URL: `git remote add origin git@gitlab.com:namespace/project-name.git`, + then add, commit, and push. ## URLs and Baseurls diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 2de3fb7e080..e0b78753e21 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -91,13 +91,13 @@ 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), +To get started with GitLab Pages, you can either [create a project from scratch](getting_started_part_two.md#create-a-project-from-scratch), use a [bundled template](getting_started_part_two.md#use-one-of-the-popular-pages-templates-bundled-with-gitlab), or copy any of our existing example projects: 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. + **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**. @@ -164,7 +164,7 @@ with Pages, read through this series: ### GitLab Pages with SSL/TLS certificates -If you're using GitLab Pages default domain (`.gitlab.io`), your website will be +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 SSL/TLS certificates. You can read the following tutorials to learn how to use these third-party certificates with GitLab Pages: diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index fa65a206273..23eb88fd305 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -151,7 +151,7 @@ Depending on how you plan to publish your website, the steps defined in the Be aware that Pages are by default branch/tag agnostic and their deployment relies solely on what you specify in `.gitlab-ci.yml`. If you don't limit the -`pages` job with the [`only` parameter](../../../ci/yaml/README.md#only-and-except), +`pages` job with the [`only` parameter](../../../ci/yaml/README.md#only-and-except-simplified), whenever a new commit is pushed to whatever branch or tag, the Pages will be overwritten. In the example below, we limit the Pages to be deployed whenever a commit is pushed only on the `master` branch: @@ -252,7 +252,7 @@ get you started. Remember that GitLab Pages are by default branch/tag agnostic and their deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit -the `pages` job with the [`only` parameter](../../../ci/yaml/README.md#only-and-except), +the `pages` job with the [`only` parameter](../../../ci/yaml/README.md#only-and-except-simplified), whenever a new commit is pushed to a branch that will be used specifically for your pages. diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index 4ab66063dcf..bf939dbdaa3 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -195,5 +195,5 @@ artifacts and the job's trace. In order to retrieve a job artifact of a different project, you might need to use a private token in order to [authenticate and download](../../../api/jobs.md#get-job-artifacts) the artifacts. -[expiry date]: ../../../ci/yaml/README.md#artifacts-expire_in +[expiry date]: ../../../ci/yaml/README.md#artifactsexpire_in [ce-14399]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14399
\ No newline at end of file diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md index ec8b8444d99..58a0fbc97cd 100644 --- a/doc/user/project/pipelines/schedules.md +++ b/doc/user/project/pipelines/schedules.md @@ -1,4 +1,4 @@ -# Pipeline Schedules +# Pipeline schedules > **Notes**: > - This feature was introduced in 9.1 as [Trigger Schedule][ce-10533]. diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index cce330aecc7..4a989afad4d 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -23,7 +23,7 @@ in `.gitlab-ci.yml`. ## Timeout Timeout defines the maximum amount of time in minutes that a job is able run. -This is configureable under your project's **Settings > CI/CD > General pipelines settings**. +This is configurable under your project's **Settings > CI/CD > General pipelines settings**. The default value is 60 minutes. Decrease the time limit if you want to impose a hard limit on your jobs' running time or increase it otherwise. In any case, if the job surpasses the threshold, it is marked as failed. @@ -134,7 +134,7 @@ Depending on the status of your job, a badge can have the following values: You can access a pipeline status badge image using the following link: ```text -https://example.gitlab.com/<namespace>/<project>/badges/<branch>/build.svg +https://example.gitlab.com/<namespace>/<project>/badges/<branch>/pipeline.svg ``` ### Test coverage report badge diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index fac5975a0dc..22d912cd9d1 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -146,9 +146,9 @@ you are introducing those changes to your branch. Via command line, you can commit multiple times before pushing. - **Commit message:** -A commit message is important to identity what is being changed and, -more importantly, why. In GitLab, you can add keywords to the commit -message that will perform one of the actions below: + A commit message is important to identity what is being changed and, + more importantly, why. In GitLab, you can add keywords to the commit + message that will perform one of the actions below: - **Trigger a GitLab CI/CD pipeline:** If you have your project configured with [GitLab CI/CD](../../../ci/README.md), you will trigger a pipeline per push, not per commit. @@ -162,14 +162,14 @@ message that will perform one of the actions below: If you mention an issue or a merge request in a commit message, they will be shown on their respective thread. - **Cherry-pick a commit:** -In GitLab, you can -[cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) -right from the UI. + In GitLab, you can + [cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) + right from the UI. - **Revert a commit:** -Easily [revert a commit](../merge_requests/revert_changes.md#reverting-a-commit) -from the UI to a selected branch. + Easily [revert a commit](../merge_requests/revert_changes.md#reverting-a-commit) + from the UI to a selected branch. - **Sign a commit:** -Use GPG to [sign your commits](gpg_signed_commits/index.md). + Use GPG to [sign your commits](gpg_signed_commits/index.md). ## Repository size diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 3e85e97d7a5..46a1b2bc3aa 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -24,21 +24,21 @@ file path fragments to start seeing results. ## Syntax highlighting -As expected from an IDE, syntax highlighting for many languages within +As expected from an IDE, syntax highlighting for many languages within the Web IDE will make your direct editing even easier. The Web IDE currently provides: -- Basic syntax colorization for a variety of programming, scripting and markup -languages such as XML, PHP, C#, C++, Markdown, Java, VB, Batch, Python, Ruby -and Objective-C. -- IntelliSense and validation support (displaying errors and warnings, providing -smart completions, formatting, and outlining) for some languages. For example: -TypeScript, JavaScript, CSS, LESS, SCSS, JSON and HTML. +- Basic syntax colorization for a variety of programming, scripting and markup + languages such as XML, PHP, C#, C++, Markdown, Java, VB, Batch, Python, Ruby + and Objective-C. +- IntelliSense and validation support (displaying errors and warnings, providing + smart completions, formatting, and outlining) for some languages. For example: +TypeScript, JavaScript, CSS, LESS, SCSS, JSON and HTML. -Because the Web IDE is based on the [Monaco Editor](https://microsoft.github.io/monaco-editor/), -you can find a more complete list of supported languages in the -[Monaco languages](https://github.com/Microsoft/monaco-languages) repository. +Because the Web IDE is based on the [Monaco Editor](https://microsoft.github.io/monaco-editor/), +you can find a more complete list of supported languages in the +[Monaco languages](https://github.com/Microsoft/monaco-languages) repository. NOTE: **Note:** Single file editing is based on the [Ace Editor](https://ace.c9.io). diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index a14df6c8402..9aa81e33fc0 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -5,6 +5,7 @@ existing routes used by GitLab. For a list of words that are not allowed to be used as group or project names, see the [`path_regex.rb` file][reserved] under the `TOP_LEVEL_ROUTES`, `PROJECT_WILDCARD_ROUTES` and `GROUP_ROUTES` lists: + - `TOP_LEVEL_ROUTES`: are names that are reserved as usernames or top level groups - `PROJECT_WILDCARD_ROUTES`: are names that are reserved for child groups or projects. - `GROUP_ROUTES`: are names that are reserved for all groups or projects. diff --git a/doc/workflow/time_tracking.md b/doc/workflow/time_tracking.md index ad43189148c..e60b6819bf1 100644 --- a/doc/workflow/time_tracking.md +++ b/doc/workflow/time_tracking.md @@ -11,7 +11,7 @@ Time Tracking lets you: - Record the time spent working on an issue or a merge request. - Add an estimate of the amount of time needed to complete an issue or a merge -request. + request. You don't have to indicate an estimate to enter the time spent, and vice versa. |
