diff options
Diffstat (limited to 'doc')
33 files changed, 494 insertions, 311 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/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 fff4538a7c9..a27c11c4f64 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -51,7 +51,7 @@ 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. #### Customizing GitLab's appearance 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/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/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 e44db230a7f..4c3c9920b93 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -93,6 +93,7 @@ use of advanced features: | [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 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/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/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 424be91773c..e5668c140fa 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -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/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index b5b325683a3..eb479b85083 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. +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. +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). +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. - 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). -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. +#### Reviews and merging -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). +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. -### 3. Technical Writer's role +### 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. + +#### Collaboration + +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. + +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: - 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..c97d8966b8c 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/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/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/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/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/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/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 12aa6f27444..01979f12a01 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -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/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/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..42aa6840609 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -307,6 +307,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/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 |
