diff options
Diffstat (limited to 'doc/integration')
36 files changed, 958 insertions, 394 deletions
diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index a652025387e..efc293569fe 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -30,8 +30,8 @@ To use Akismet: 1. Sign in or create a new account. 1. Click **Show** to reveal the API key, and copy the API key's value. 1. Sign in to GitLab as an administrator. -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Reporting** (`/admin/application_settings/reporting`). +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Reporting** (`/admin/application_settings/reporting`). 1. Select the **Enable Akismet** checkbox. 1. Fill in the API key from step 3. 1. Save the configuration. diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index 34ee326d6d5..870da6cdb3d 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -9,8 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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. +1. Sign in to the [Auth0 Console](https://auth0.com/auth/login). You can also + create an account using the same link. 1. Select **New App/API**. diff --git a/doc/integration/azure.md b/doc/integration/azure.md index dceb135ad89..47d80ab9a66 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -4,17 +4,19 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Microsoft Azure OAuth2 OmniAuth Provider **(FREE)** +# Microsoft Azure OAuth 2.0 OmniAuth Provider **(FREE)** NOTE: Per Microsoft, this provider uses the [older Azure Active Directory v1.0 endpoint](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/v1-protocols-oauth-code). Microsoft documentation suggests that you should use the [OpenID Connect protocol to use the v2 endpoints](../administration/auth/oidc.md#microsoft-azure) for new projects. -To use v2 endpoints via OmniAuth, please follow [Microsoft Azure OAuth2 OmniAuth Provider v2 instructions](#microsoft-azure-oauth2-omniauth-provider-v2). +To use v2 endpoints via OmniAuth, please follow [Microsoft Azure OAuth 2.0 OmniAuth Provider v2 instructions](#microsoft-azure-oauth-20-omniauth-provider-v2). -To enable the Microsoft Azure OAuth2 OmniAuth provider, you must register your application with Azure. Azure generates a client ID and secret key for you to use. +To enable the Microsoft Azure OAuth 2.0 OmniAuth provider, you must register +your application with Azure. Azure generates a client ID and secret key for you +to use. -Sign in to the [Azure Portal](https://portal.azure.com), and follow the instructions in -the [Microsoft Quickstart documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app). +Sign in to the [Azure Portal](https://portal.azure.com), and follow the +instructions in the [Microsoft Quickstart documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app). As you go through the Microsoft procedure, keep the following in mind: @@ -23,9 +25,9 @@ As you go through the Microsoft procedure, keep the following in mind: - The redirect URI requires the URL of the Azure OAuth callback of your GitLab installation. For example, `https://gitlab.mycompany.com/users/auth/azure_oauth2/callback`. The type dropdown should be set to **Web**. -- The `client ID` and `client secret` are terms associated with OAuth 2. In some Microsoft documentation, +- The `client ID` and `client secret` are terms associated with OAuth 2.0. In some Microsoft documentation, the terms may be listed as `Application ID` and `Application Secret`. -- If you need to generate a new client secret, follow the Microsoft documentation +- If you have to generate a new client secret, follow the Microsoft documentation for [creating a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#create-a-new-application-secret). - Save the client ID and client secret for your new app, as the client secret is only displayed one time. @@ -89,41 +91,46 @@ As you go through the Microsoft procedure, keep the following in mind: - *If you installed from source,* [restart GitLab](../administration/restart_gitlab.md#installations-from-source). -On the sign-in page, you should now see a Microsoft icon below the regular sign-in form. -Click the icon to begin the authentication process. Microsoft then asks you to -sign in and authorize the GitLab application. If successful, you are returned to GitLab and signed in. +On the sign-in page, you should now see a Microsoft icon below the regular +sign-in form. Click the icon to begin the authentication process. Microsoft then +asks you to sign in and authorize the GitLab application. If successful, you are +returned to GitLab and signed in. Read [Enable OmniAuth for an Existing User](omniauth.md#enable-omniauth-for-an-existing-user) for information on how existing GitLab users can connect to their newly-available Azure AD accounts. -## Microsoft Azure OAuth2 OmniAuth Provider v2 +## Microsoft Azure OAuth 2.0 OmniAuth Provider v2 -In order to use v2 endpoints provided by Microsoft Azure Active Directory you must to configure it via Azure OAuth2 OmniAuth Provider v2. +To use v2 endpoints provided by Microsoft Azure Active Directory you must to +configure it via Azure OAuth 2.0 OmniAuth Provider v2. ### Registering an Azure application -To enable the Microsoft Azure OAuth2 OmniAuth provider, you must register your application with Azure. Azure generates a client ID and secret key for you to use. +To enable the Microsoft Azure OAuth 2.0 OmniAuth provider, you must register +your application with Azure. Azure generates a client ID and secret key for you +to use. -Sign in to the [Azure Portal](https://portal.azure.com), and follow the instructions in -the [Microsoft Quickstart documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app). +Sign in to the [Azure Portal](https://portal.azure.com), and follow the +instructions in the [Microsoft Quickstart documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app). As you go through the Microsoft procedure, keep the following in mind: -- If you have multiple instances of Azure Active Directory, you can switch to the desired tenant. +- If you have multiple instances of Azure Active Directory, you can switch to + the desired tenant. - You're setting up a Web application. - The redirect URI requires the URL of the Azure OAuth callback of your GitLab installation. For example, `https://gitlab.example.com/users/auth/azure_activedirectory_v2/callback`. The type dropdown should be set to **Web**. -- The `client ID` and `client secret` are terms associated with OAuth 2. In some Microsoft documentation, +- The `client ID` and `client secret` are terms associated with OAuth 2.0. In some Microsoft documentation, the terms may be listed as `Application ID` and `Application Secret`. -- If you need to generate a new client secret, follow the Microsoft documentation +- If you have to generate a new client secret, follow the Microsoft documentation for [creating a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#create-a-new-application-secret). - Save the client ID and client secret for your new app, as the client secret is only displayed one time. ### Adding API permissions (scopes) -Once you have created an application, follow the [Microsoft Quickstart documentation to expose a web API](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). Be sure to add the following delegated permissions under the Microsoft Graph API: +After you have created an application, follow the [Microsoft Quickstart documentation to expose a web API](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). Be sure to add the following delegated permissions under the Microsoft Graph API: - `email` - `openid` @@ -181,7 +188,8 @@ Once you have created an application, follow the [Microsoft Quickstart documenta The `scope` parameter is optional and can be added to `args`. Default `scope` is: `openid profile email`. -1. Replace `CLIENT ID`, `CLIENT SECRET`, and `TENANT ID` with the values you got above. +1. Replace `CLIENT ID`, `CLIENT SECRET`, and `TENANT ID` with the values you got + above. 1. Save the configuration file. diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index 44aca1ca6b1..7a3f4a7710d 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -10,8 +10,8 @@ NOTE: Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an earlier version, you must explicitly enable it. -You can set up Bitbucket.org as an OAuth2 provider to use your -Bitbucket.org account credentials to sign in to GitLab, or import your projects from +You can set up Bitbucket.org as an OAuth 2.0 provider to use your Bitbucket.org +account credentials to sign in to GitLab. You can also import your projects from Bitbucket.org. - To use Bitbucket.org as an OmniAuth provider, follow the diff --git a/doc/integration/cas.md b/doc/integration/cas.md index be54c31ec01..60ce728fa55 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -6,7 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # CAS OmniAuth Provider **(FREE)** -To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab supplies to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for back-channel logout. +To enable the CAS OmniAuth provider you must register your application with your +CAS instance. This requires the service URL GitLab supplies to CAS. It should be +something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. +Handling for Single Logout (SLO) is enabled by default, so you only have to +configure CAS for back-channel logout. 1. On your GitLab server, open the configuration file. diff --git a/doc/integration/datadog.md b/doc/integration/datadog.md index e06cca19e60..687be5adcf7 100644 --- a/doc/integration/datadog.md +++ b/doc/integration/datadog.md @@ -27,8 +27,8 @@ project, group, or instance level: 1. *For project-level or group-level integrations:* In GitLab, go to your project or group. 1. *For instance-level integrations:* 1. Sign in to GitLab as a user with the [Administrator role](../user/permissions.md). - 1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Integrations**. + 1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Integrations**. 1. Scroll to **Add an integration**, and select **Datadog**. 1. Select **Active** to enable the integration. 1. Specify the [**Datadog site**](https://docs.datadoghq.com/getting_started/site/) to send data to. diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 20b66411a7e..9514c298885 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -9,9 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Moved to GitLab Premium in 13.9. -This document describes how to enable Advanced Search. After -Advanced Search is enabled, you'll have the benefit of fast search response times -and the advantage of the [special searches](../user/search/advanced_search.md). +This page describes how to enable Advanced Search. When enabled, +Advanced Search provides faster search response times and [improved search features](../user/search/advanced_search.md). ## Version requirements @@ -26,94 +25,61 @@ and the advantage of the [special searches](../user/search/advanced_search.md). | GitLab Enterprise Edition 9.0 through 11.4 | Elasticsearch 5.1 through 5.5 | | GitLab Enterprise Edition 8.4 through 8.17 | Elasticsearch 2.4 with [Delete By Query Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/2.4/plugins-delete-by-query.html) installed | -The Elasticsearch Integration is designed to work with supported versions of -Elasticsearch and follows Elasticsearch's [End of Life Policy](https://www.elastic.co/support/eol). +The Elasticsearch Integration works with supported versions of +Elasticsearch and follows Elasticsearch's [End of Life Policy](https://www.elastic.co/support/eol). When we change Elasticsearch supported versions in GitLab, we announce them in [deprecation notes](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations) in monthly release posts -before the actual removal. +before we remove them. ## System requirements -Elasticsearch requires additional resources in excess of those documented in the +Elasticsearch requires additional resources to those documented in the [GitLab system requirements](../install/requirements.md). -The amount of resources (memory, CPU, storage) varies greatly, based on the -amount of data being indexed into the Elasticsearch cluster. According to +Memory, CPU, and storage resource amounts vary depending on the amount of data you index into the Elasticsearch cluster. Heavily used Elasticsearch clusters may require more resources. According to [Elasticsearch official guidelines](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_memory), each node should have: - [Memory](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_memory): 8 GiB (minimum). -- [CPU](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_cpus): Modern processor with multiple cores. -- [Storage](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_disks): Use SSD storage. The total storage size of all Elasticsearch nodes is about 50% of the total size of your Git repositories. It includes one primary and one replica. +- [CPU](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_cpus): Modern processor with multiple cores. GitLab.com has minimal CPU requirements for Elasticsearch. Multiple cores provide extra concurrency, which is more beneficial than faster CPUs. +- [Storage](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_disks): Use SSD storage. The total storage size of all Elasticsearch nodes is about 50% of the total size of your Git repositories. It includes one primary and one replica. The [`estimate_cluster_size`](#gitlab-advanced-search-rake-tasks) Rake task ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221177) in GitLab 13.10) uses total repository size to estimate the Advanced Search storage requirements. -A few notes on CPU and storage: - -- CPU requirements for Elasticsearch tend to be minimal. There are specific - scenarios where this isn't true, but GitLab.com isn't using Elasticsearch in - an exceptionally CPU-heavy way. More cores are more performant than faster - CPUs. Extra concurrency from multiple cores far outweighs a slightly - faster clock speed in Elasticsearch. - -- Storage requirements for Elasticsearch are important, especially for - indexing-heavy clusters. When possible use SSDs, whose speed is far superior - to any spinning media for Elasticsearch. In testing, nodes that use SSD storage - see boosts in both query and indexing performance. - -- We've introduced the [`estimate_cluster_size`](#gitlab-advanced-search-rake-tasks) - Rake task to estimate the Advanced Search storage requirements in advance, which -- The [`estimate_cluster_size`](#gitlab-advanced-search-rake-tasks) Rake task estimates the - Advanced Search storage requirements in advance. The Rake task uses total repository size - for the calculation. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221177) in GitLab 13.10. - -Keep in mind, these are **minimum requirements** for Elasticsearch. -Heavily-used Elasticsearch clusters likely require considerably more -resources. - -## Installing Elasticsearch +## Install Elasticsearch Elasticsearch is *not* included in the Omnibus packages or when you install from -source. You must [install it separately](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/install-elasticsearch.html "Elasticsearch 7.x installation documentation"). -Be sure to select your version. Providing detailed information on installing -Elasticsearch is out of the scope of this document. +source. You must [install it separately](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/install-elasticsearch.html "Elasticsearch 7.x installation documentation") and ensure you select your version. Detailed information on how to install Elasticsearch is out of the scope of this page. -Elasticsearch should be installed on a separate server, whether you install -it yourself or use a cloud hosted offering like Elastic's [Elasticsearch Service](https://www.elastic.co/elasticsearch/service) -(available on AWS, GCP, or Azure) or the [Amazon Elasticsearch](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-gsg.html) -service. Running Elasticsearch on the same server as GitLab is not recommended -and can cause a degradation in GitLab instance performance. +You can install Elasticsearch yourself, or use a cloud hosted offering such as [Elasticsearch Service](https://www.elastic.co/elasticsearch/service)(available on AWS, GCP, or Azure) or the [Amazon Elasticsearch](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-gsg.html) +service. +You should install Elasticsearch on a separate server. Running Elasticsearch on the same server as GitLab is not recommended and can cause a degradation in GitLab instance performance. -**For a single node Elasticsearch cluster the functional cluster health status -is yellow** (will never be green) because the primary shard is allocated but -replicas can not be as there is no other node to which Elasticsearch can assign a -replica. +For a single node Elasticsearch cluster, the functional cluster health status is always yellow due to the allocation of the primary shard. Elasticsearch cannot assign replica shards to the same node as primary shards. -After the data is added to the database or repository and [Elasticsearch is -enabled in the Admin Area](#enabling-advanced-search) the search index is -updated automatically. +The search index updates after you: -## Upgrading to a new Elasticsearch major version +- Add data to the database or repository. +- [Enable Elasticsearch](#enable-advanced-search) in the Admin Area. -Since Elasticsearch can read and use indices created in the previous major version, you don't need to change anything in the GitLab configuration when upgrading Elasticsearch. +## Upgrade to a new Elasticsearch major version -The only thing worth noting is that if you have created your current index before GitLab 13.0, you might want to reindex from scratch (which implicitly creates an alias) in order to use some features, for example [Zero downtime reindexing](#zero-downtime-reindexing). Once you do that, you are able to perform zero-downtime reindexing and will benefit from any future features that make use of the alias. +Elasticsearch reads and uses indices created in the previous major version. You are not required to change the GitLab configuration when you upgrade Elasticsearch. -If you are unsure when your current index was created, -you can check whether it was created after GitLab 13.0 by using the -[Elasticsearch cat aliases API](https://www.elastic.co/guide/en/elasticsearch/reference/7.11/cat-alias.html). -If the list of aliases returned contains an entry for `gitlab-production` that points to an index +If your current index was created before GitLab 13.0, you must reindex from scratch to create an alias to use features such as [zero downtime reindexing](#zero-downtime-reindexing). After you reindex, you can perform zero downtime reindexing and also benefit from future features that use the alias. + +To check if your current index was created before GitLab 13.0, use the [Elasticsearch cat aliases API](https://www.elastic.co/guide/en/elasticsearch/reference/7.11/cat-alias.html). +If the returned list of aliases does not contain a `gitlab-production` alias, you must reindex to use features such as zero downtime reindexing. +If the returned list of aliases contains an entry for `gitlab-production` that points to an index named `gitlab-production-<numerical timestamp>`, your index was created after GitLab 13.0. -If the `gitlab-production` alias is missing, you need to reindex from scratch to use -features such as Zero-downtime reindexing. ## Elasticsearch repository indexer -For indexing Git repository data, GitLab uses an [indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). +To index Git repository data, GitLab uses an [indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). -The way you install the Go indexer depends on your version of GitLab: +Depending on your GitLab version, there are different installation procedures for the Go indexer: - For Omnibus GitLab 11.8 or greater, see [Omnibus GitLab](#omnibus-gitlab). - For installations from source or older versions of Omnibus GitLab, [install the indexer from source](#from-source). -- If you are using GitLab Development Kit, see [GDK Elasticsearch how-to](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/elasticsearch.md) +- If you are using GitLab Development Kit, see [GDK Elasticsearch how-to](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/elasticsearch.md). ### Omnibus GitLab @@ -126,7 +92,7 @@ First, we need to install some dependencies, then we build and install the indexer itself. This project relies on [International Components for Unicode](http://site.icu-project.org/) (ICU) for text encoding, -therefore we need to ensure the development packages for your platform are +therefore we must ensure the development packages for your platform are installed before running `make`. #### Debian / Ubuntu @@ -154,7 +120,7 @@ brew install icu4c export PKG_CONFIG_PATH="/usr/local/opt/icu4c/lib/pkgconfig:$PKG_CONFIG_PATH" ``` -### Building and installing +### Build and install To build and install the indexer, run: @@ -166,7 +132,7 @@ sudo -u git -H bundle exec rake gitlab:indexer:install[$indexer_path] RAILS_ENV= cd $indexer_path && sudo make install ``` -The `gitlab-elasticsearch-indexer` will be installed to `/usr/local/bin`. +The `gitlab-elasticsearch-indexer` is installed to `/usr/local/bin`. You can change the installation path with the `PREFIX` environment variable. Please remember to pass the `-E` flag to `sudo` if you do so. @@ -177,21 +143,21 @@ Example: PREFIX=/usr sudo -E make install ``` -After installation, be sure to [enable Elasticsearch](#enabling-advanced-search). +After installation, be sure to [enable Elasticsearch](#enable-advanced-search). NOTE: If you see an error such as `Permission denied - /home/git/gitlab-elasticsearch-indexer/` while indexing, you may need to set the `production -> elasticsearch -> indexer_path` setting in your `gitlab.yml` file to `/usr/local/bin/gitlab-elasticsearch-indexer`, which is where the binary is installed. -## Enabling Advanced Search +## Enable Advanced Search For GitLab instances with more than 50GB repository data you can follow the instructions for [Indexing large instances](#indexing-large-instances) below. -To enable Advanced Search, you need to have admin access to GitLab: +To enable Advanced Search, you must have admin access to GitLab: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. NOTE: @@ -206,7 +172,7 @@ To enable Advanced Search, you need to have admin access to GitLab: 1. Select **Index all projects**. 1. Select **Check progress** in the confirmation message to see the status of the background jobs. -1. Personal snippets need to be indexed using another Rake task: +1. Personal snippets must be indexed using another Rake task: ```shell # Omnibus installations @@ -216,7 +182,7 @@ To enable Advanced Search, you need to have admin access to GitLab: bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production ``` -1. After the indexing has completed, enable **Search with Elasticsearch enabled** and select **Save changes**. +1. After indexing completes, enable **Search with Elasticsearch enabled** and select **Save changes**. NOTE: When your Elasticsearch cluster is down while Elasticsearch is enabled, @@ -237,8 +203,8 @@ The following Elasticsearch settings are available: | `Username` | The `username` of your Elasticsearch instance. | | `Password` | The password of your Elasticsearch instance. | | `Number of Elasticsearch shards` | Elasticsearch indexes are split into multiple shards for performance reasons. In general, you should use at least 5 shards, and indexes with tens of millions of documents need to have more shards ([see below](#guidance-on-choosing-optimal-cluster-configuration)). Changes to this value do not take effect until the index is recreated. You can read more about tradeoffs in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/scalability.html). | -| `Number of Elasticsearch replicas` | Each Elasticsearch shard can have a number of replicas. These are a complete copy of the shard, and can provide increased query performance or resilience against hardware failure. Increasing this value will greatly increase total disk space required by the index. | -| `Limit namespaces and projects that can be indexed` | Enabling this will allow you to select namespaces and projects to index. All other namespaces and projects will use database search instead. If you enable this option but do not select any namespaces or projects, none will be indexed. [Read more below](#limiting-namespaces-and-projects). +| `Number of Elasticsearch replicas` | Each Elasticsearch shard can have a number of replicas. These are a complete copy of the shard, and can provide increased query performance or resilience against hardware failure. Increasing this value increases total disk space required by the index. | +| `Limit namespaces and projects that can be indexed` | Enabling this allows you to select namespaces and projects to index. All other namespaces and projects use database search instead. If you enable this option but do not select any namespaces or projects, none will be indexed. [Read more below](#limit-namespaces-and-projects). | `Using AWS hosted Elasticsearch with IAM credentials` | Sign your Elasticsearch requests using [AWS IAM authorization](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html), [AWS EC2 Instance Profile Credentials](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-create-iam-instance-profile.html#getting-started-create-iam-instance-profile-cli), or [AWS ECS Tasks Credentials](https://docs.aws.amazon.com/AmazonECS/latest/userguide/task-iam-roles.html). Please refer to [Identity and Access Management in Amazon Elasticsearch Service](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-ac.html) for details of AWS hosted Elasticsearch domain access policy configuration. | | `AWS Region` | The AWS region in which your Elasticsearch service is located. | | `AWS Access Key` | The AWS access key. | @@ -255,38 +221,38 @@ Sidekiq performance. Return them to their default values if you see increased `s in your Sidekiq logs. For more information, see [issue 322147](https://gitlab.com/gitlab-org/gitlab/-/issues/322147). -### Limiting namespaces and projects +### Limit namespaces and projects -If you select `Limit namespaces and projects that can be indexed`, more options will become available. +If you select `Limit namespaces and projects that can be indexed`, more options become available.  -You can select namespaces and projects to index exclusively. Note that if the namespace is a group it will include +You can select namespaces and projects to index exclusively. Note that if the namespace is a group, it includes any subgroups and projects belonging to those subgroups to be indexed as well. -Advanced Search only provides cross-group code/commit search (global) if all name-spaces are indexed. In this particular scenario where only a subset of namespaces are indexed, a global search will not provide a code or commit scope. This will be possible only in the scope of an indexed namespace. Currently there is no way to code/commit search in multiple indexed namespaces (when only a subset of namespaces has been indexed). For example if two groups are indexed, there is no way to run a single code search on both. You can only run a code search on the first group and then on the second. +Advanced Search only provides cross-group code/commit search (global) if all name-spaces are indexed. In this particular scenario where only a subset of namespaces are indexed, a global search will not provide a code or commit scope. This is possible only in the scope of an indexed namespace. There is no way to code/commit search in multiple indexed namespaces (when only a subset of namespaces has been indexed). For example if two groups are indexed, there is no way to run a single code search on both. You can only run a code search on the first group and then on the second. You can filter the selection dropdown by writing part of the namespace or project name you're interested in.  NOTE: -If no namespaces or projects are selected, no Advanced Search indexing will take place. +If no namespaces or projects are selected, no Advanced Search indexing takes place. WARNING: -If you have already indexed your instance, you will have to regenerate the index in order to delete all existing data -for filtering to work correctly. To do this run the Rake tasks `gitlab:elastic:recreate_index` and -`gitlab:elastic:clear_index_status`. Afterwards, removing a namespace or a project from the list will delete the data +If you have already indexed your instance, you must regenerate the index to delete all existing data +for filtering to work correctly. To do this, run the Rake tasks `gitlab:elastic:recreate_index` and +`gitlab:elastic:clear_index_status`. Afterwards, removing a namespace or a project from the list deletes the data from the Elasticsearch index as expected. -## Enabling custom language analyzers +## Enable custom language analyzers You can improve the language support for Chinese and Japanese languages by utilizing [`smartcn`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) and/or [`kuromoji`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) analysis plugins from Elastic. To enable language(s) support: 1. Install the desired plugin(s), please refer to [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/plugins/7.9/installation.html) for plugins installation instructions. The plugin(s) must be installed on every node in the cluster, and each node must be restarted after installation. For a list of plugins, see the table later in this section. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Locate **Custom analyzers: language support**. 1. Enable plugin(s) support for **Indexing**. @@ -303,11 +269,11 @@ For guidance on what to install, see the following Elasticsearch language plugin | `Enable Japanese (kuromoji) custom analyzer: Indexing` | Enables or disables Japanese language support using [`kuromoji`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) custom analyzer for newly created indices.| | `Enable Japanese (kuromoji) custom analyzer: Search` | Enables or disables using [`kuromoji`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) fields for Advanced Search. Please only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html), enabling custom analyzer indexing and recreating the index.| -## Disabling Advanced Search +## Disable Advanced Search To disable the Elasticsearch integration: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Uncheck **Elasticsearch indexing** and **Search with Elasticsearch enabled**. 1. Click **Save changes** for the changes to take effect. @@ -327,7 +293,7 @@ The idea behind this reindexing method is to leverage the [Elasticsearch reindex and Elasticsearch index alias feature to perform the operation. We set up an index alias which connects to a `primary` index which is used by GitLab for reads/writes. When reindexing process starts, we temporarily pause the writes to the `primary` index. Then, we create another index and invoke the Reindex API which migrates the -index data onto the new index. Once the reindexing job is complete, we switch to the new index by connecting the +index data onto the new index. After the reindexing job is complete, we switch to the new index by connecting the index alias to it which becomes the new `primary` index. At the end, we resume the writes and normal operation resumes. ### Trigger the reindex via the Advanced Search administration @@ -339,7 +305,7 @@ index alias to it which becomes the new `primary` index. At the end, we resume t To trigger the reindexing process: 1. Sign in to your GitLab instance as an administrator. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Expand **Elasticsearch zero-downtime reindexing**. 1. Select **Trigger cluster reindexing**. @@ -350,13 +316,13 @@ After this process is completed, the original index is scheduled to be deleted a 14 days. You can cancel this action by pressing the **Cancel** button on the same page you triggered the reindexing process. -While the reindexing is running, you will be able to follow its progress under that same section. +While the reindexing is running, you can follow its progress under that same section. #### Elasticsearch zero-downtime reindexing > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55681) in GitLab 13.12. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Expand **Elasticsearch zero-downtime reindexing**, and you'll find the following options: @@ -404,7 +370,7 @@ Sometimes, you might want to abandon the unfinished reindex job and resume the i bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production ``` -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Expand **Elasticsearch zero-downtime reindexing**. 1. Clear the **Pause Elasticsearch indexing** checkbox. @@ -486,8 +452,8 @@ version](../update/index.md#upgrading-to-a-new-major-version). Rake tasks are available to: -- [Build and install](#building-and-installing) the indexer. -- Delete indexes when [disabling Elasticsearch](#disabling-advanced-search). +- [Build and install](#build-and-install) the indexer. +- Delete indexes when [disabling Elasticsearch](#disable-advanced-search). - Add GitLab data to an index. The following are some available Rake tasks: @@ -558,7 +524,7 @@ For basic guidance on choosing a cluster configuration you may refer to [Elastic - A good guideline is to ensure you keep the number of shards per node below 20 per GB heap it has configured. A node with a 30GB heap should therefore have a maximum of 600 shards, but the further below this limit you can keep it the better. This will generally help the cluster stay in good health. - Number of Elasticsearch shards: - Small shards result in small segments, which increases overhead. Aim to keep the average shard size between at least a few GB and a few tens of GB. - - Another consideration is the number of documents. To determine the number of shards to use, sum the numbers in the **Menu >** **{admin}** **Admin > Dashboard > Statistics** pane (the number of documents to be indexed), divide by 5 million, and add 5. For example: + - Another consideration is the number of documents. To determine the number of shards to use, sum the numbers in the **Menu > Admin > Dashboard > Statistics** pane (the number of documents to be indexed), divide by 5 million, and add 5. For example: - If you have fewer than about 2,000,000 documents, use the default of 5 shards - 10,000,000 documents: `10000000/5000000 + 5` = 7 shards - 100,000,000 documents: `100000000/5000000 + 5` = 25 shards @@ -573,7 +539,7 @@ For basic guidance on choosing a cluster configuration you may refer to [Elastic ### Indexing large instances This section may be helpful in the event that the other -[basic instructions](#enabling-advanced-search) cause problems +[basic instructions](#enable-advanced-search) cause problems due to large volumes of data being indexed. WARNING: @@ -582,7 +548,7 @@ Make sure to prepare for this task by having a [Scalable and Highly Available Setup](../administration/reference_architectures/index.md) or creating [extra Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). -1. [Configure your Elasticsearch host and port](#enabling-advanced-search). +1. [Configure your Elasticsearch host and port](#enable-advanced-search). 1. Create empty indexes: ```shell @@ -603,7 +569,7 @@ Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). bundle exec rake gitlab:elastic:clear_index_status RAILS_ENV=production ``` -1. [Enable **Elasticsearch indexing**](#enabling-advanced-search). +1. [Enable **Elasticsearch indexing**](#enable-advanced-search). 1. Indexing large Git repositories can take a while. To speed up the process, you can [tune for indexing speed](https://www.elastic.co/guide/en/elasticsearch/reference/current/tune-for-indexing-speed.html#tune-for-indexing-speed): - You can temporarily disable [`refresh`](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-refresh.html), the operation responsible for making changes to an index available to search. @@ -635,7 +601,7 @@ Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). ``` This enqueues a Sidekiq job for each project that needs to be indexed. - You can view the jobs in **Menu >** **{admin}** **Admin > Monitoring > Background Jobs > Queues Tab** + You can view the jobs in **Menu > Admin > Monitoring > Background Jobs > Queues Tab** and click `elastic_commit_indexer`, or you can query indexing status using a Rake task: ```shell @@ -734,7 +700,7 @@ Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). } }' ``` -1. After the indexing has completed, enable [**Search with Elasticsearch enabled**](#enabling-advanced-search). +1. After the indexing has completed, enable [**Search with Elasticsearch enabled**](#enable-advanced-search). ### Deleted documents @@ -836,7 +802,7 @@ be necessary for you to [reindex](#zero-downtime-reindexing) after updating GitL ### I indexed all the repositories but I can't get any hits for my search term in the UI -Make sure you indexed all the database data [as stated above](#enabling-advanced-search). +Make sure you indexed all the database data [as stated above](#enable-advanced-search). If there aren't any results (hits) in the UI search, check if you are seeing the same results via the rails console (`sudo gitlab-rails console`): @@ -857,7 +823,7 @@ More [complex Elasticsearch API calls](https://www.elastic.co/guide/en/elasticse It is important to understand at which level the problem is manifesting (UI, Rails code, Elasticsearch side) to be able to [troubleshoot further](../administration/troubleshooting/elasticsearch.md#search-results-workflow). NOTE: -The above instructions are not to be used for scenarios that only index a [subset of namespaces](#limiting-namespaces-and-projects). +The above instructions are not to be used for scenarios that only index a [subset of namespaces](#limit-namespaces-and-projects). See [Elasticsearch Index Scopes](#advanced-search-index-scopes) for more information on searching for specific types of data. @@ -906,25 +872,20 @@ Elasticsearch::Transport::Transport::Errors::BadRequest([400] { This is because we changed the index mapping in GitLab 8.12 and the old indexes should be removed and built from scratch again, see details in the [update guide](../update/upgrading_from_source.md). -- Exception `Elasticsearch::Transport::Transport::Errors::BadRequest` +### `Elasticsearch::Transport::Transport::Errors::BadRequest` - If you have this exception (just like in the case above but the actual message is different) please check if you have the correct Elasticsearch version and you met the other [requirements](#system-requirements). - There is also an easy way to check it automatically with `sudo gitlab-rake gitlab:check` command. +If you have this exception (just like in the case above but the actual message is different) please check if you have the correct Elasticsearch version and you met the other [requirements](#system-requirements). +There is also an easy way to check it automatically with `sudo gitlab-rake gitlab:check` command. -- Exception `Elasticsearch::Transport::Transport::Errors::RequestEntityTooLarge` +### `Elasticsearch::Transport::Transport::Errors::RequestEntityTooLarge` - ```plaintext - [413] {"Message":"Request size exceeded 10485760 bytes"} - ``` +```plaintext +[413] {"Message":"Request size exceeded 10485760 bytes"} +``` - This exception is seen when your Elasticsearch cluster is configured to reject - requests above a certain size (10MiB in this case). This corresponds to the - `http.max_content_length` setting in `elasticsearch.yml`. Increase it to a - larger size and restart your Elasticsearch cluster. +This exception is seen when your Elasticsearch cluster is configured to reject requests above a certain size (10MiB in this case). This corresponds to the `http.max_content_length` setting in `elasticsearch.yml`. Increase it to a larger size and restart your Elasticsearch cluster. - AWS has [fixed limits](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/aes-limits.html) - for this setting ("Maximum Size of HTTP Request Payloads"), based on the size of - the underlying instance. +AWS has [fixed limits](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/aes-limits.html) for this setting ("Maximum Size of HTTP Request Payloads"), based on the size of the underlying instance. ### My single node Elasticsearch cluster status never goes from `yellow` to `green` even though everything seems to be running properly @@ -953,7 +914,7 @@ Gitlab::Elastic::Indexer::Error: time="2020-01-23T09:13:00Z" level=fatal msg="he ``` You probably have not used either `http://` or `https://` as part of your value in the **"URL"** field of the Elasticsearch Integration Menu. Please make sure you are using either `http://` or `https://` in this field as the [Elasticsearch client for Go](https://github.com/olivere/elastic) that we are using [needs the prefix for the URL to be accepted as valid](https://github.com/olivere/elastic/commit/a80af35aa41856dc2c986204e2b64eab81ccac3a). -Once you have corrected the formatting of the URL, delete the index (via the [dedicated Rake task](#gitlab-advanced-search-rake-tasks)) and [reindex the content of your instance](#enabling-advanced-search). +Once you have corrected the formatting of the URL, delete the index (via the [dedicated Rake task](#gitlab-advanced-search-rake-tasks)) and [reindex the content of your instance](#enable-advanced-search). ### My Elasticsearch cluster has a plugin and the integration is not working diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index ded89dd93a4..58c53db7996 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -4,9 +4,10 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Facebook OAuth2 OmniAuth Provider **(FREE)** +# Facebook OAuth 2.0 OmniAuth Provider **(FREE)** -To enable the Facebook OmniAuth provider you must register your application with Facebook. Facebook generates an app ID and secret key for you to use. +To enable the Facebook OmniAuth provider you must register your application with +Facebook. Facebook generates an app ID and secret key for you to use. 1. Sign in to the [Facebook Developer Platform](https://developers.facebook.com/). @@ -14,8 +15,9 @@ 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. +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. 1. Choose "Create New Facebook App ID" @@ -49,7 +51,8 @@ To enable the Facebook OmniAuth provider you must register your application with 1. Choose "Show" next to the hidden "App Secret" -1. You should now see an app key and app secret (see screenshot). Keep this page open as you continue configuration. +1. You should now see an app key and app secret (see screenshot). Keep this page + open as you continue configuration.  @@ -101,4 +104,7 @@ To enable the Facebook OmniAuth provider you must register your application with 1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you installed GitLab via Omnibus or from source respectively. -On the sign in page there should now be a Facebook icon below the regular sign in form. Click the icon to begin the authentication process. Facebook asks the user to sign in and authorize the GitLab application. If everything goes well the user is returned to GitLab and signed in. +On the sign in page there should now be a Facebook icon below the regular sign +in form. Click the icon to begin the authentication process. Facebook asks the +user to sign in and authorize the GitLab application. If everything goes well +the user is returned to GitLab and signed in. diff --git a/doc/integration/github.md b/doc/integration/github.md index f3192e0af6c..0a96d67ac0c 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -188,7 +188,7 @@ GitHub account` when signing in, in GitLab: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Account**. +1. On the left sidebar, select **Account**. 1. In the **Social sign-in** section, select **Connect to GitHub**. After that, you should be able to sign in via GitHub successfully. diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index a0b438c9ffa..1f35faacc2e 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -14,7 +14,7 @@ GitLab.com generates an application ID and secret key for you to use. 1. Sign in to GitLab.com. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Applications**. +1. On the left sidebar, select **Applications**. 1. Provide the required details for **Add new application**. - Name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. - Redirect URI: diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index e3cd3075bc9..bafba2cdf02 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -44,11 +44,11 @@ With the Gitpod integration enabled for your GitLab instance, to enable it for y For GitLab self-managed instances, a GitLab administrator needs to: -1. Set up a Gitpod instance to integrate with GitLab. Refer to the [Gitpod documentation](https://www.gitpod.io/docs/self-hosted/latest/self-hosted/) +1. Set up a Gitpod instance to integrate with GitLab. Refer to the [Gitpod documentation](https://www.gitpod.io/docs/self-hosted/latest) to get your instance up and running. 1. Enable it in GitLab: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. - 1. In the left sidebar, select **Settings > General**. + 1. On the top bar, select **Menu > Admin**. + 1. On the left sidebar, select **Settings > General**. 1. Expand the **Gitpod** configuration section. 1. Check the **Enable Gitpod integration** checkbox. 1. Add your Gitpod instance URL (for example, `https://gitpod.example.com`). diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index f0bcc00c0fa..0468e5d0a42 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -12,10 +12,11 @@ If correctly set up, emails that require an action are marked in Gmail.  -To get this functioning, you need to be registered with Google. For instructions, see +To get this functioning, you must be registered with Google. For instructions, see [Register with Google](https://developers.google.com/gmail/markup/registering-with-google). -This process has many steps. Make sure that you fulfill all requirements set by Google to avoid your application being rejected by Google. +This process has many steps. Make sure that you fulfill all requirements set by +Google to avoid your application being rejected by Google. In particular, note: diff --git a/doc/integration/google.md b/doc/integration/google.md index a08944f65f1..4a2c61577ac 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -4,12 +4,12 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Google OAuth2 OmniAuth Provider **(FREE)** +# Google OAuth 2.0 OmniAuth Provider **(FREE)** -To enable the Google OAuth2 OmniAuth provider you must register your application +To enable the Google OAuth 2.0 OmniAuth provider you must register your application with Google. Google generates a client ID and secret key for you to use. -## Enabling Google OAuth +## Enable Google OAuth In Google's side: @@ -47,7 +47,7 @@ In Google's side: - Cloud Resource Manager API - Cloud Billing API - To do so you need to: + To do so you should: 1. Go to the [Google API Console](https://console.developers.google.com/apis/dashboard). 1. Click on **ENABLE APIS AND SERVICES** button at the top of the page. @@ -98,8 +98,8 @@ On your GitLab server: 1. Change `YOUR_APP_ID` to the client ID from the Google Developer page 1. Similarly, change `YOUR_APP_SECRET` to the client secret -1. Make sure that you configure GitLab to use a fully-qualified domain name, as Google doesn't accept - raw IP addresses. +1. Make sure that you configure GitLab to use a fully-qualified domain name, as + Google doesn't accept raw IP addresses. For Omnibus packages: @@ -115,8 +115,10 @@ On your GitLab server: ``` 1. Save the configuration file. -1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you - installed GitLab via Omnibus or from source respectively. +1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for + the changes to take effect if you installed GitLab via Omnibus or from source + respectively. On the sign in page there should now be a Google icon below the regular sign in form. Click the icon to begin the authentication process. Google asks the diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 8910e0978b0..18ae71a7059 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -74,7 +74,7 @@ Create a personal access token to authorize Jenkins' access to GitLab. 1. Sign in to GitLab as the user to be used with Jenkins. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Access Tokens**. +1. On the left sidebar, select **Access Tokens**. 1. Create a personal access token with the **API** scope checkbox checked. For more details, see [Personal access tokens](../user/profile/personal_access_tokens.md). 1. Record the personal access token's value, because it's required in [Configure the Jenkins server](#configure-the-jenkins-server) section. diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index b7e4c4f0e26..e349bb4e88f 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -40,7 +40,7 @@ In GitLab, perform the following steps. ### Read access to repository Jenkins needs read access to the GitLab repository. We already specified a -private key to use in Jenkins, now we need to add a public one to the GitLab +private key to use in Jenkins, now we must add a public one to the GitLab project. For that case we need a Deploy key. Read the documentation on [how to set up a Deploy key](../user/project/deploy_keys/index.md). @@ -50,7 +50,8 @@ Now navigate to GitLab services page and activate Jenkins  -Done! When you push to GitLab, it creates a build for Jenkins. You can view the merge request build status with a link to the Jenkins build. +Done! When you push to GitLab, it creates a build for Jenkins. You can view the +merge request build status with a link to the Jenkins build. ### Multi-project Configuration diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index b11f367258d..d4e5a1bfca1 100644 --- a/doc/integration/jira/configure.md +++ b/doc/integration/jira/configure.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Configure the Jira integration in GitLab +# Configure the Jira integration in GitLab **(FREE)** You can set up the [Jira integration](index.md#jira-integration) by configuring your project settings in GitLab. diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index e32bd4559f9..7d32c080fff 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: Only Jira users with administrator level access are able to install or configure -the GitLab app for Jira Cloud. +the GitLab.com for Jira Cloud app. ## GitLab.com for Jira Cloud app **(FREE SAAS)** @@ -60,6 +60,14 @@ After a namespace is added: Support for syncing past branch and commit data is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/263240). +## Update the GitLab.com for Jira Cloud app + +Most updates to the app are fully automated and don't require any user interaction. See the +[Atlassian Marketplace documentation](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/) +for details. + +If the app requires additional permissions, [the update must first be manually approved in Jira](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/#changes-that-require-manual-customer-approval). + ## Install the GitLab.com for Jira Cloud app for self-managed instances **(FREE SELF)** If your GitLab instance is self-managed, you must follow some @@ -78,10 +86,10 @@ self-managed GitLab instances with Jira Cloud, you can either: You can configure your Atlassian Cloud instance to allow you to install applications from outside the Marketplace, which allows you to install the application: -1. Sign in to your Jira instance as a user with administrator permissions. +1. Sign in to your Jira instance as a user with an Administrator role. 1. Place your Jira instance into [development mode](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-2--enable-development-mode). -1. Sign in to your GitLab application as a user with [Administrator](../../user/permissions.md) permissions. +1. Sign in to your GitLab application as a user with an [Administrator](../../user/permissions.md) role. 1. Install the GitLab application from your self-managed GitLab instance, as described in the [Atlassian developer guides](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-3--install-and-test-your-app): 1. In your Jira instance, go to **Apps > Manage Apps** and click **Upload app**: @@ -103,13 +111,13 @@ The **GitLab.com for Jira Cloud** app now displays under **Manage apps**. You ca click **Get started** to open the configuration page rendered from your GitLab instance. NOTE: -If you make changes to the application descriptor, you must uninstall, then reinstall, the +If a GitLab update makes changes to the application descriptor, you must uninstall, then reinstall, the application. ### Create a Marketplace listing **(FREE SELF)** If you prefer to not use development mode on your Jira instance, you can create -your own Marketplace listing for your instance, which enables your application +your own Marketplace listing for your instance. This enables your application to be installed from the Atlassian Marketplace. For full instructions, review the Atlassian [guide to creating a marketplace listing](https://developer.atlassian.com/platform/marketplace/installing-cloud-apps/#creating-the-marketplace-listing). To create a @@ -127,11 +135,15 @@ Review the for details. NOTE: -DVCS means distributed version control system. +Using this method, [updates are automated](#update-the-gitlabcom-for-jira-cloud-app) +the same way as when using our GitLab.com Marketplace listing. -## Troubleshooting GitLab.com for Jira Cloud app +## Troubleshoot GitLab.com for Jira Cloud app -The GitLab.com for Jira Cloud app uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies, which can lead to a message saying that the user needs to log in on GitLab.com even though the user is already logged in. +The GitLab.com for Jira Cloud app uses an iframe to add namespaces on the +settings page. Some browsers block cross-site cookies, which can lead to a +message saying that the user needs to log in on GitLab.com even though the user +is already logged in. > "You need to sign in or sign up before continuing." diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index c8ea224f18e..5a2ce8a0a75 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -65,11 +65,11 @@ For an overview of how to configure Jira Development panel integration, see [Agile Management - GitLab Jira Development panel integration](https://www.youtube.com/watch?v=VjVTOmMl85M). To simplify administration, we recommend that a GitLab group maintainer or group owner -(or instance administrator in the case of self-managed GitLab) set up the integration. +(or, if possible, instance administrator in the case of self-managed GitLab) set up the integration. | Jira usage | GitLab.com customers need | GitLab self-managed customers need | |------------|---------------------------|------------------------------------| -| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab and Jira. For more information, see the documentation for the [GitLab.com for Jira Cloud app](connect-app.md). | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab Jira Cloud application for self-managed instances](connect-app.md#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances) for more information. | +| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab.com and Jira. For more information, see the documentation for the [GitLab.com for Jira Cloud app](connect-app.md). | The [GitLab.com for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab.com for Jira Cloud app for self-managed instances](connect-app.md#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances) for more information. | | Your own server | The [Jira DVCS (distributed version control system) connector](dvcs.md). This syncs data hourly. | The [Jira DVCS Connector](dvcs.md). | Each GitLab project can be configured to connect to an entire Jira instance. That means after @@ -89,10 +89,6 @@ This integration is not supported on GitLab instances under a [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab). For example, `http://example.com/gitlab`. -## Related topics - -- [Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in Jira - ## Troubleshooting ### Cookies for Oracle's Access Manager diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md index 7d97312757e..664a0361da4 100644 --- a/doc/integration/jira/dvcs.md +++ b/doc/integration/jira/dvcs.md @@ -8,15 +8,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use the Jira DVCS (distributed version control system) connector if you self-host your Jira instance, and you want to sync information -between GitLab and Jira. If you use Jira Cloud and GitLab.com, you should use the -[GitLab.com for Jira Cloud app](connect-app.md) unless you specifically need the DVCS connector. +between GitLab and Jira. If you use Jira Cloud, you should use the +[GitLab.com for Jira Cloud app](connect-app.md) unless you specifically need the +DVCS connector. When you configure the Jira DVCS connector, make sure your GitLab and Jira instances are accessible. - **Self-managed GitLab**: Your GitLab instance must be accessible by Jira. -- **Jira Cloud**: Your instance must be accessible through the internet. - **Jira Server**: Your network must allow access to your instance. +- **Jira Cloud**: Your instance must be accessible through the internet. ## Smart commits @@ -61,25 +62,25 @@ you can still perform multiple actions in a single commit: ## Configure a GitLab application for DVCS -We recommend you create and use a `jira` user in GitLab, and use the account only -for integration work. A separate account ensures regular account maintenance does not affect -your integration. +We recommend you create and use a `jira` user in GitLab, and use the account +only for integration work. A separate account ensures regular account +maintenance does not affect your integration. If a `jira` user is not feasible, +you can set up this integration with your own account instead. 1. In GitLab, [create a user](../../user/profile/account/create_accounts.md) for Jira to - use to connect to GitLab. For Jira to access all projects, - a user with [administrator](../../user/permissions.md) permissions must - create the user with administrator permissions. + use to connect to GitLab. This user must be added to each project you want Jira to have access to, + or have an [Administrator](../../user/permissions.md) role to access all projects. 1. Sign in as the `jira` user. 1. In the top right corner, click the account's avatar, and select **Edit profile**. -1. In the left sidebar, select **Applications**. +1. On the left sidebar, select **Applications**. 1. In the **Name** field, enter a descriptive name for the integration, such as `Jira`. 1. In the **Redirect URI** field, enter the URI appropriate for your version of GitLab, replacing `<gitlab.example.com>` with your GitLab instance domain: - *For GitLab versions 13.0 and later* **and** *Jira versions 8.14 and later,* use the generated `Redirect URL` from [Linking GitLab accounts with Jira](https://confluence.atlassian.com/adminjiraserver/linking-gitlab-accounts-1027142272.html). - - *For GitLab versions 13.0 and later* **and** *Jira Cloud,* use `https://<gitlab.example.com>/login/oauth/callback`. - - *For GitLab versions 11.3 and later,* use `https://<gitlab.example.com>/login/oauth/callback`. + - *For GitLab versions 13.0 and later* **and** *Jira Cloud,* use `https://<gitlab.example.com>/login/oauth/callback`. + - *For GitLab versions 11.3 and later* **and** *Jira versions 8.13 and earlier,* use `https://<gitlab.example.com>/login/oauth/callback`. If you use GitLab.com, the URL is `https://gitlab.com/login/oauth/callback`. - *For GitLab versions 11.2 and earlier,* use `https://<gitlab.example.com>/-/jira/login/oauth/callback`. @@ -105,9 +106,9 @@ it completes, refreshes every 60 minutes: - *For Jira versions 8.13 and earlier:* Select **GitHub Enterprise**. 1. For **Team or User Account**, enter either: - *For Jira versions 8.14 and later:* - - The relative path of a top-level GitLab group that you have access to. + - The relative path of a top-level GitLab group that [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to. - *For Jira versions 8.13 and earlier:* - - The relative path of a top-level GitLab group that you have access to. + - The relative path of a top-level GitLab group that [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to. - The relative path of your personal namespace. 1. In the **Host URL** field, enter the URI appropriate for your version of GitLab, @@ -141,7 +142,7 @@ can refresh the data manually from the Jira interface: column, select the icon:  -## Troubleshooting your DVCS connection +## Troubleshoot your DVCS connection Refer to the items in this section if you're having problems with your DVCS connector. @@ -174,7 +175,8 @@ Error obtaining access token. Cannot access https://gitlab.example.com from Jira must have the appropriate certificate (such as your organization's root certificate) added to it . -Refer to Atlassian's documentation and Atlassian Support for assistance setting up Jira correctly: +Refer to Atlassian's documentation and Atlassian Support for assistance setting +up Jira correctly: - [Add a certificate](https://confluence.atlassian.com/kb/how-to-import-a-public-ssl-certificate-into-a-jvm-867025849.html) to the trust store. @@ -232,9 +234,17 @@ To resolve this issue: [Contact GitLab Support](https://about.gitlab.com/support/) if none of these reasons apply. +### `410 : Gone` error when connecting to Jira + +When you connect to Jira and synchronize repositories, you may receive a `410 : Gone` error. + +This issue occurs when you use the Jira DVCS connector and your integration is configured to use **GitHub Enterprise**. + +For more information and possible fixes, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340160). + ### Fix synchronization issues -If Jira displays incorrect information, such as deleted branches, you may need to +If Jira displays incorrect information, such as deleted branches, you may have to resynchronize the information. To do so: 1. In Jira, go to **Jira Administration > Applications > DVCS accounts**. diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md index febd9907028..85f99b49c41 100644 --- a/doc/integration/jira/index.md +++ b/doc/integration/jira/index.md @@ -26,9 +26,7 @@ The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be). -To set up the integration, [configure the project settings](configure.md) in GitLab. -You can also configure these settings at a [group level](../../user/admin_area/settings/project_integration_management.md#manage-group-level-default-settings-for-a-project-integration), -and for self-managed GitLab, at an [instance level](../../user/admin_area/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration). +To set up the integration, [configure the settings](configure.md) in GitLab. ### Jira development panel integration @@ -37,12 +35,9 @@ connects all GitLab projects under a group or personal namespace. When configure relevant GitLab information, including related branches, commits, and merge requests, displays in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). -To set up the Jira development panel integration: - -- *If your installation uses Jira Cloud,* use the - [GitLab for Jira app](connect-app.md). -- *If either your Jira or GitLab installation is self-managed,* use the - [Jira DVCS Connector](dvcs.md). +To set up the Jira development panel integration, use the GitLab.com for Jira Cloud app +or the Jira DVCS (distributed version control system) connector, +[depending on your installation](development_panel.md#configure-the-integration). ### Direct feature comparison diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md index e42a102e030..0cfffdb8ba4 100644 --- a/doc/integration/jira/jira_cloud_configuration.md +++ b/doc/integration/jira/jira_cloud_configuration.md @@ -11,10 +11,10 @@ on Atlassian cloud. To create the API token: 1. Sign in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) with your email address. Use an account with *write* access to Jira projects. -1. Go to **Settings > API tokens**. +1. Go to **Settings > Atlassian account settings > Security > Create and manage API tokens**. 1. Select **Create API token** to display a modal window with an API token. -1. To copy the API token, select **Copy to clipboard**, or select **View** and write - down the new API token. You need this value when you +1. In the dialog, enter a label for your token and select **Create**. +1. To copy the API token, select **Copy**, then paste the token somewhere safe. You need this value when you [configure GitLab](configure.md). You need the newly created token, and the email diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index 52e7e5e412b..32a8cd430f9 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -25,7 +25,7 @@ This process creates a user named `gitlab` and adds it to a new group named `git 1. Create a new user account (`gitlab`) with write access to projects in Jira. - **Email address**: Jira requires a valid email address, and sends a verification - email, which you need to set up the password. + email, which is required to set up the password. - **Username**: Jira creates the username by using the email prefix. You can change this username later. - **Password**: You must create a password, because the GitLab integration doesn't diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index ba3f246f5f5..48339144292 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -9,6 +9,11 @@ type: reference, how-to GitLab can integrate with [Kerberos](https://web.mit.edu/kerberos/) as an authentication mechanism. +WARNING: +GitLab CI/CD does not work with a Kerberos-enabled GitLab instance due to an unresolved +[bug in Git CLI](https://lore.kernel.org/git/YKNVop80H8xSTCjz@coredump.intra.peff.net/T/#mab47fd7dcb61fee651f7cc8710b8edc6f62983d5) +that fails to use job token authentication from the GitLab Runners. + ## Overview [Kerberos](https://web.mit.edu/kerberos/) is a secure method for authenticating a request for a service in a @@ -85,6 +90,9 @@ For source installations, make sure the `kerberos` gem group gitlab_rails['kerberos_keytab'] = "/etc/http.keytab" ``` + To avoid GitLab creating users automatically on their first sign in through Kerberos, + don't set `kerberos` for `gitlab_rails['omniauth_allow_single_sign_on']`. + 1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. GitLab now offers the `negotiate` authentication method for signing in and @@ -107,7 +115,7 @@ set up GitLab to create a new account when a Kerberos user tries to sign in. If you're an administrator, you can link a Kerberos account to an existing GitLab account. To do so: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select a user, then select the **Identities** tab. 1. Select 'Kerberos SPNEGO' in the 'Provider' dropdown box. @@ -118,7 +126,7 @@ If you're not an administrator: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Account**. +1. On the left sidebar, select **Account**. 1. In the **Social sign-in** section, select **Connect Kerberos SPNEGO**. If you don't see a **Social sign-in** Kerberos option, follow the requirements in [Enable single sign-on](#enable-single-sign-on). @@ -147,7 +155,7 @@ With that information at hand: ``` 1. As an administrator, you can confirm the new, blocked account: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users** and review the **Blocked** tab. 1. You can enable the user. 1. If `block_auto_created_users` is false, the Kerberos user is diff --git a/doc/integration/mattermost/gitlab-mattermost.msc b/doc/integration/mattermost/gitlab-mattermost.msc new file mode 100644 index 00000000000..f6d4bf7aa68 --- /dev/null +++ b/doc/integration/mattermost/gitlab-mattermost.msc @@ -0,0 +1,28 @@ +msc { + # Use https://mscgen.js.org or mscgen to convert this into PNG + hscale="1.5", + wordwraparcs=on; + + user [ label="User", textbgcolor="blue", textcolor="white" ], + mattermost [ label="Mattermost", textbgcolor="red", textcolor="white"], + gitlab [ label="GitLab", textbgcolor="indigo", textcolor="white"]; + + user=>mattermost [label="GET https://mm.domain.com"]; + mattermost note gitlab [label="Obtain access code", textcolor="green"]; + mattermost=>gitlab [label="GET https://gitlab.domain.com/oauth/authorize", textcolor="indigo"]; + gitlab rbox user [label="GitLab user logs in (if necessary)"]; + gitlab rbox gitlab [label="GitLab verifies client_id matches an OAuth application"]; + gitlab=>user [label="GitLab asks user to authorize Mattermost OAuth app"]; + user=>gitlab [label="User clicks 'Allow'"]; + gitlab rbox gitlab [label="GitLab verifies redirect_uri matches list of valid URLs"]; + gitlab=>user [label="302 Redirect: https://mm.domain.com/signup/gitlab/complete"]; + user=>mattermost [label="GET https://mm.domain.com/signup/gitlab/complete", textcolor="red"]; + mattermost note gitlab [label="Exchange access code for access token", textcolor="green"]; + mattermost=>gitlab [label="POST http://gitlab.domain.com/oauth/token", textcolor="indigo"]; + gitlab=>gitlab [label="Doorkeeper::TokensController#create"]; + gitlab=>mattermost [label="Access token", textcolor="red"]; + mattermost note gitlab [label="Mattermost looks up GitLab user", textcolor="green"]; + mattermost=>gitlab [label="GET https://gitlab.domain.com/api/v4/user", textcolor="indigo"]; + gitlab=>mattermost [label="User details", textcolor="red"]; + mattermost=>user [label="Mattermost/GitLab user ready"]; +} diff --git a/doc/integration/mattermost/img/gitlab-mattermost.png b/doc/integration/mattermost/img/gitlab-mattermost.png Binary files differnew file mode 100644 index 00000000000..1eedcb391b0 --- /dev/null +++ b/doc/integration/mattermost/img/gitlab-mattermost.png diff --git a/doc/integration/mattermost/index.md b/doc/integration/mattermost/index.md new file mode 100644 index 00000000000..4830f8ba84e --- /dev/null +++ b/doc/integration/mattermost/index.md @@ -0,0 +1,495 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# GitLab Mattermost + +NOTE: +This document applies to GitLab 11.0 and later. + +You can run a [GitLab Mattermost](https://gitlab.com/gitlab-org/gitlab-mattermost) +service on your GitLab server. Mattermost is not part of the single application that GitLab is. There is a good integration between with GitLab, and our Omnibus installer allows you to easily install it. But it is a separate application from a separate company. + +## Prerequisites + +Each release of GitLab Mattermost is compiled and manually tested on an AMD 64 chipset for Linux. ARM chipsets and operating systems, like Raspberry Pi, are not supported. + +## Getting started + +GitLab Mattermost expects to run on its own virtual host. In your DNS settings you will need +two entries pointing to the same machine, e.g., `gitlab.example.com` and +`mattermost.example.com`. + +GitLab Mattermost is disabled by default. To enable it: + +1. Edit `/etc/gitlab/gitlab.rb` and add the Mattermost external URL: + + ```ruby + mattermost_external_url 'https://mattermost.example.com' + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Confirm that GitLab Mattermost is reachable at `https://mattermost.example.com` and authorized to connect to GitLab. Authorizing Mattermost with GitLab allows users to use GitLab as an SSO provider. + +The Omnibus GitLab package attempts to automatically authorize GitLab Mattermost with GitLab if the applications are running on the same server. + +Automatic authorization requires access to the GitLab database. If the GitLab database is not available +you will need to manually authorize GitLab Mattermost for access to GitLab using the process described in the [Authorize GitLab Mattermost section](#authorize-gitlab-mattermost). + +## Configuring Mattermost + +Starting in GitLab 11.0, Mattermost can be configured using the Mattermost System Console. An extensive list of +Mattermost settings and where they can be set is available [in the Mattermost documentation](https://docs.mattermost.com/administration/config-settings.html). + +While using the System Console is recommended, you can also configure Mattermost using one of the following options: + +1. Edit the Mattermost configuration directly through `/var/opt/gitlab/mattermost/config.json`. +1. Specify environment variables used to run Mattermost by changing the `mattermost['env']` setting in `gitlab.rb`. Any settings configured in this way will be disabled from the System Console and cannot be changed without restarting Mattermost. + +## Running GitLab Mattermost with HTTPS + +Place the SSL certificate and SSL certificate key inside `/etc/gitlab/ssl`. If the directory doesn't exist, create it: + +```shell +sudo mkdir -p /etc/gitlab/ssl +sudo chmod 755 /etc/gitlab/ssl +sudo cp mattermost.gitlab.example.key mattermost.gitlab.example.crt /etc/gitlab/ssl/ +``` + +In `/etc/gitlab/gitlab.rb` specify the following configuration: + +```ruby +mattermost_external_url 'https://mattermost.gitlab.example' +mattermost_nginx['redirect_http_to_https'] = true +``` + +If you haven't named your certificate and key `mattermost.gitlab.example.crt` +and `mattermost.gitlab.example.key` then you'll need to also add the full paths +as shown below. + +```ruby +mattermost_nginx['ssl_certificate'] = "/etc/gitlab/ssl/mattermost-nginx.crt" +mattermost_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/mattermost-nginx.key" +``` + +where `mattermost-nginx.crt` and `mattermost-nginx.key` are SSL cert and key, respectively. + +Once the configuration is set, run `sudo gitlab-ctl reconfigure` to apply the changes. + +## Running GitLab Mattermost on its own server + +If you want to run GitLab and GitLab Mattermost on two separate servers the GitLab services will still be set up on your GitLab Mattermost server, but they will not accept user requests or +consume system resources. You can use the following settings and configuration details on the GitLab Mattermost server to effectively disable the GitLab service bundled into the Omnibus package. + +```ruby +mattermost_external_url 'http://mattermost.example.com' + +# Shut down GitLab services on the Mattermost server +gitlab_rails['enable'] = false +redis['enable'] = false +postgres_exporter['enable'] = false +``` + +Then follow the appropriate steps in the [Authorize GitLab Mattermost section](#authorize-gitlab-mattermost). Last, to enable +integrations with GitLab add the following on the GitLab Server: + +```ruby +gitlab_rails['mattermost_host'] = "https://mattermost.example.com" +``` + +By default GitLab Mattermost requires all users to sign up with GitLab and disables the sign-up by email option. See Mattermost [documentation on GitLab SSO](https://docs.mattermost.com/deployment/sso-gitlab.html). + +## Manually (re)authorizing GitLab Mattermost with GitLab + +### Reauthorize GitLab Mattermost + +To reauthorize GitLab Mattermost, you first need to revoke the existing +authorization. This can be done in the **Settings > Applications** area of GitLab. Then follow the steps below to complete authorization. + +### Authorize GitLab Mattermost + +Navigate to the **Settings > Applications** area in GitLab. Create a new application and for the **Redirect URI** use the following (replace `http` with `https` if you use HTTPS): + +```plaintext +http://mattermost.example.com/signup/gitlab/complete +http://mattermost.example.com/login/gitlab/complete +``` + +Note that you do not need to select any options under **Scopes**. Choose **Save application**. + +Once the application is created you will be provided with an `Application ID` and `Secret`. One other piece of information needed is the URL of GitLab instance. +Return to the server running GitLab Mattermost and edit the `/etc/gitlab/gitlab.rb` configuration file as follows using the values you received above: + +```ruby +mattermost['gitlab_enable'] = true +mattermost['gitlab_id'] = "12345656" +mattermost['gitlab_secret'] = "123456789" +mattermost['gitlab_scope'] = "" +mattermost['gitlab_auth_endpoint'] = "http://gitlab.example.com/oauth/authorize" +mattermost['gitlab_token_endpoint'] = "http://gitlab.example.com/oauth/token" +mattermost['gitlab_user_api_endpoint'] = "http://gitlab.example.com/api/v4/user" +``` + +Save the changes and then run `sudo gitlab-ctl reconfigure`. If there are no errors your GitLab and GitLab Mattermost should be configured correctly. + +### Specify numeric user and group identifiers + +Omnibus GitLab creates a user and group `mattermost`. You can specify the +numeric identifiers for these users in `/etc/gitlab/gitlab.rb` as follows: + +```ruby +mattermost['uid'] = 1234 +mattermost['gid'] = 1234 +``` + +Run `sudo gitlab-ctl reconfigure` to apply the changes. + +### Setting custom environment variables + +If necessary you can set custom environment variables to be used by Mattermost +via `/etc/gitlab/gitlab.rb`. This can be useful if the Mattermost server +is operated behind a corporate internet proxy. In `/etc/gitlab/gitlab.rb` +supply a `mattermost['env']` with a hash value. For example: + +```ruby +mattermost['env'] = {"HTTP_PROXY" => "my_proxy", "HTTPS_PROXY" => "my_proxy", "NO_PROXY" => "my_no_proxy"} +``` + +Run `sudo gitlab-ctl reconfigure` to apply the changes. + +### Connecting to the bundled PostgreSQL database + +If you need to connect to the bundled PostgreSQL database and are using the default Omnibus GitLab database configuration, you can connect as +the PostgreSQL superuser: + +```shell +sudo gitlab-psql -d mattermost_production +``` + +### Back up GitLab Mattermost + +GitLab Mattermost is not included in the regular [Omnibus GitLab backup](../../raketasks/backup_restore.md#back-up-gitlab) Rake task. + +The general Mattermost [backup and disaster recovery](https://docs.mattermost.com/deploy/backup-disaster-recovery.html) documentation can be used as a guide +on what needs to be backed up. + +#### Back up the bundled PostgreSQL database + +If you need to back up the bundled PostgreSQL database and are using the default Omnibus GitLab database configuration, you can back up using this command: + +```shell +sudo -i -u gitlab-psql -- /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/postgresql mattermost_production | gzip > mattermost_dbdump_$(date --rfc-3339=date).sql.gz +``` + +#### Back up the `data` directory and `config.json` + +Mattermost has a `data` directory and `config.json` file that will need to be backed up as well: + +```shell +sudo tar -zcvf mattermost_data_$(date --rfc-3339=date).gz -C /var/opt/gitlab/mattermost data config.json +``` + +### Restore GitLab Mattermost + +If you have previously [created a backup of GitLab Mattermost](#back-up-gitlab-mattermost), you can run the following commands to restore it: + +```shell +# Stop Mattermost so we don't have any open database connections +sudo gitlab-ctl stop mattermost + +# Drop the Mattermost database +sudo -u gitlab-psql /opt/gitlab/embedded/bin/dropdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production + +# Create the Mattermost database +sudo -u gitlab-psql /opt/gitlab/embedded/bin/createdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production + +# Perform the database restore +# Replace /tmp/mattermost_dbdump_2021-08-05.sql.gz with your backup +sudo -u mattermost sh -c "zcat /tmp/mattermost_dbdump_2021-08-05.sql.gz | /opt/gitlab/embedded/bin/psql -U gitlab_mattermost -h /var/opt/gitlab/postgresql -p 5432 mattermost_production" + +# Restore the data directory and config.json +# Replace /tmp/mattermost_data_2021-08-09.gz with your backup +sudo tar -xzvf /tmp/mattermost_data_2021-08-09.gz -C /var/opt/gitlab/mattermost + +# Fix permissions if required +sudo chown -R mattermost:mattermost /var/opt/gitlab/mattermost/data +sudo chown mattermost:mattermost /var/opt/gitlab/mattermost/config.json + +# Start Mattermost +sudo gitlab-ctl start mattermost +``` + +### Mattermost Command Line Tools (CLI) + +NOTE: +This CLI will be replaced in a future release with the new [`mmctl` Command Line Tool](https://docs.mattermost.com/administration/mmctl-cli-tool.html). + +To use the [Mattermost Command Line Tools (CLI)](https://docs.mattermost.com/administration/command-line-tools.html), ensure that you are in the `/opt/gitlab/embedded/service/mattermost` directory when you run the CLI commands and that you specify the location of the configuration file. The executable is `/opt/gitlab/embedded/bin/mattermost`. + +```shell +cd /opt/gitlab/embedded/service/mattermost + +sudo /opt/gitlab/embedded/bin/chpst -e /opt/gitlab/etc/mattermost/env -P -U mattermost:mattermost -u mattermost:mattermost /opt/gitlab/embedded/bin/mattermost --config=/var/opt/gitlab/mattermost/config.json version +``` + +Until [#4745](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4745) has been implemented, the command requires quite of bit typing and is hard to remember, so let's make a bash/zsh alias to make it a bit easier to remember. Add the following to your `~/.bashrc` or `~/.zshrc` file: + +```shell +alias mattermost-cli="cd /opt/gitlab/embedded/service/mattermost && sudo /opt/gitlab/embedded/bin/chpst -e /opt/gitlab/etc/mattermost/env -P -U mattermost:mattermost -u mattermost:mattermost /opt/gitlab/embedded/bin/mattermost --config=/var/opt/gitlab/mattermost/config.json $1" +``` + +Then source `~/.zshrc` or `~/.bashrc` with `source ~/.zshrc` or `source ~/.bashrc`. + +If successful, you can now run any Mattermost CLI command with your new shell alias `mattermost-cli`: + +```shell +$ mattermost-cli version + +[sudo] password for username: +{"level":"info","ts":1569614421.9058893,"caller":"utils/i18n.go:83","msg":"Loaded system translations for 'en' from '/opt/gitlab/embedded/service/mattermost/i18n/en.json'"} +{"level":"info","ts":1569614421.9062793,"caller":"app/server_app_adapters.go:58","msg":"Server is initializing..."} +{"level":"info","ts":1569614421.90976,"caller":"sqlstore/supplier.go:223","msg":"Pinging SQL master database"} +{"level":"info","ts":1569614422.0515099,"caller":"mlog/log.go:165","msg":"Starting up plugins"} +{"level":"info","ts":1569614422.0515954,"caller":"app/plugin.go:193","msg":"Syncing plugins from the file store"} +{"level":"info","ts":1569614422.086005,"caller":"app/plugin.go:228","msg":"Found no files in plugins file store"} +{"level":"info","ts":1569614423.9337213,"caller":"sqlstore/post_store.go:1301","msg":"Post.Message supports at most 16383 characters (65535 bytes)"} +{"level":"error","ts":1569614425.6317747,"caller":"go-plugin/stream.go:15","msg":" call to OnConfigurationChange failed, error: Must have a GitLab oauth client id","plugin_id":"com.github.manland.mattermost-plugin-gitlab","source":"plugin_stderr"} +{"level":"info","ts":1569614425.6875598,"caller":"mlog/sugar.go:19","msg":"Ensuring Surveybot exists","plugin_id":"com.mattermost.nps"} +{"level":"info","ts":1569614425.6953356,"caller":"app/server.go:216","msg":"Current version is 5.14.0 (5.14.2/Fri Aug 30 20:20:48 UTC 2019/817ee89711bf26d33f840ce7f59fba14da1ed168/none)"} +{"level":"info","ts":1569614425.6953766,"caller":"app/server.go:217","msg":"Enterprise Enabled: false"} +{"level":"info","ts":1569614425.6954057,"caller":"app/server.go:219","msg":"Current working directory is /opt/gitlab/embedded/service/mattermost/i18n"} +{"level":"info","ts":1569614425.6954265,"caller":"app/server.go:220","msg":"Loaded config","source":"file:///var/opt/gitlab/mattermost/config.json"} +Version: 5.14.0 +Build Number: 5.14.2 +Build Date: Fri Aug 30 20:20:48 UTC 2019 +Build Hash: 817ee89711bf26d33f840ce7f59fba14da1ed168 +Build Enterprise Ready: false +DB Version: 5.14.0 +``` + +For more details see [Mattermost Command Line Tools (CLI)](https://docs.mattermost.com/administration/command-line-tools.html) and the [Troubleshooting Mattermost CLI](#troubleshooting-the-mattermost-cli) below. + +## Configuring GitLab and Mattermost integrations + +As of 12.3, the Mattermost GitLab plugin is shipped with Omnibus GitLab: [Mattermost Plugin for GitLab documentation](https://github.com/mattermost/mattermost-plugin-gitlab). + +You can use the plugin to subscribe Mattermost to receive notifications about issues, merge requests, and pull requests as well as personal notifications regarding merge request reviews, unread messages, and task assignments. If you want to use slash commands to perform actions +such as creating and viewing issues, or to trigger deployments use GitLab [Mattermost slash commands](../../user/project/integrations/mattermost_slash_commands.md). + +The plugin and slash commands can be used together or individually. + +## Email Notifications + +### Setting up SMTP for GitLab Mattermost + +These settings are configured through the Mattermost System Console by the System Administrator. +On the **Environment > SMTP** tab of the **System Console**, you can enter the SMTP credentials given by your SMTP provider, or `127.0.0.1` and port `25` to use `sendmail`. More information on the specific settings +that are needed is available in the [Mattermost documentation](https://docs.mattermost.com/install/smtp-email-setup.html). + +These settings can also be configured in `/var/opt/gitlab/mattermost/config.json`. + +### Email batching + +Enabling this feature allows users to control how often they receive email notifications. + +Email batching can be enabled in the Mattermost **System Console** by going to the **Environment > SMTP** tab, and setting the **Enable Email Batching** setting to **True**. + +This setting can also be configured in `/var/opt/gitlab/mattermost/config.json`. + +## Upgrading GitLab Mattermost + +Below is a list of Mattermost versions for GitLab 11.10 and later: + +| GitLab Version | Mattermost Version | +| :------------ |:----------------| +| 11.11 | 5.10 | +| 12.0 | 5.11 | +| 12.1 | 5.12 | +| 12.2 | 5.13 | +| 12.3 | 5.14 | +| 12.4 | 5.15 | +| 12.5 | 5.16 | +| 12.6 | 5.17 | +| 12.7 | 5.17 | +| 12.8 | 5.19 | +| 12.9 | 5.20 | +| 12.10 | 5.21 | +| 13.0 | 5.22 | +| 13.1 | 5.23 | +| 13.2 | 5.24 | +| 13.3 | 5.25 | +| 13.4 | 5.26 | +| 13.5 | 5.27 | +| 13.6 | 5.28 | +| 13.7 | 5.29 | +| 13.8 | 5.30 | +| 13.9 | 5.31 | +| 13.10 | 5.32 | +| 13.11 | 5.33 | +| 13.12 | 5.34 | +| 14.0 | 5.35 | +| 14.1 | 5.36 | +| 14.2 | 5.37 | +| 14.3 | 5.38 | + +NOTE: +When upgrading the Mattermost version, it is essential to check the +[Important Upgrade Notes](https://docs.mattermost.com/administration/important-upgrade-notes.html) +for Mattermost to address any changes or migrations that need to be performed. + +Starting with GitLab 11.0, GitLab Mattermost can be upgraded through the regular Omnibus GitLab update process. When upgrading previous versions of +GitLab that process can only be used if Mattermost configuration settings have not been changed outside of GitLab (i.e., no changes to Mattermost's `config.json` +file have been made, either directly or via the Mattermost **System Console** which saves back changes to `config.json`.) + +If you are upgrading to at least GitLab 11.0 or have only configured Mattermost using `gitlab.rb`, you can upgrade GitLab using Omnibus and then run `gitlab-ctl reconfigure` to upgrade GitLab Mattermost to the latest version. + +If this is not the case, there are two options: + +1. Update [`gitlab.rb`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template#L706) + with the changes done to `config.json`. This might require adding some parameters as not all + settings in `config.json` are available in `gitlab.rb`. Once complete, Omnibus GitLab should be + able to upgrade GitLab Mattermost from one version to the next. +1. Migrate Mattermost outside of the directory controlled by Omnibus GitLab so it can be administered + and upgraded independently. Follow the [Mattermost Migration Guide](https://docs.mattermost.com/administration/migrating.html) + to move your Mattermost configuration settings and data to another directory or server independent + from Omnibus GitLab. + +For a complete list of upgrade notices and special considerations for older versions, see the [Mattermost documentation](https://docs.mattermost.com/administration/important-upgrade-notes.html). + +## Upgrading GitLab Mattermost from versions prior to 11.0 + +With version 11.0, GitLab introduced breaking changes which affected Mattermost configuration. +In versions prior to GitLab 11.0 all +Mattermost-related settings were configurable from the `gitlab.rb` file, which +generated the Mattermost `config.json` file. However, Mattermost also +permitted configuration via its System Console. This configuration ended up in +the same `config.json` file, which resulted in changes made via the System Console being +overwritten when users ran `gitlab-ctl reconfigure`. + +To resolve this problem, `gitlab.rb` includes only the +configuration necessary for GitLab<=>Mattermost integration in 11.0. GitLab no longer +generates the `config.json` file, and instead passes limited configuration settings via environment variables. + +The settings that continue to be supported in `gitlab.rb` can be found in +[`gitlab.rb.template`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template). + +From GitLab 11.0, other Mattermost settings can be configured through Mattermost's System Console, +by editing `/var/opt/gitlab/mattermost/config.json`, or by using `mattermost['env']` in `gitlab.rb`. + +If you would like to keep configuring Mattermost using `gitlab.rb`, you can take the following actions +in preparation for GitLab 11.0: + +1. Upgrade to version 10.x which supports the new `mattermost['env']` setting. +1. Configure any settings not listed above through the `mattermost['env']` setting. Mattermost requires + environment variables to be provided in `MM_<CATEGORY>SETTINGS_<ATTRIBUTE>` format. Below is an example + of how to convert the old settings syntax to the new one. + +The following settings in `gitlab.rb`: + +```ruby +mattermost['service_maximum_login_attempts'] = 10 +mattermost['team_teammate_name_display'] = "full_name" +mattermost['sql_max_idle_conns'] = 10 +mattermost['log_file_level'] = 'INFO' +mattermost['email_batching_interval'] = 30 +mattermost['file_enable_file_attachments'] = true +mattermost['ratelimit_memory_store_size'] = 10000 +mattermost['support_terms_of_service_link'] = "/static/help/terms.html" +mattermost['privacy_show_email_address'] = true +mattermost['localization_available_locales'] = "en,es,fr,ja,pt-BR" +mattermost['webrtc_enable'] = false +``` + +Would translate to: + +```ruby +mattermost['env'] = { + 'MM_SERVICESETTINGS_MAXIMUMLOGINATTEMPTS' => '10', + 'MM_TEAMSETTINGS_TEAMMATENAMEDISPLAY' => 'full_name', + 'MM_SQLSETTINGS_MAXIDLECONNS' => '10', + 'MM_LOGSETTINGS_FILELEVEL' => 'INFO', + 'MM_EMAILSETTINGS_BATCHINGINTERVAL' => '30', + 'MM_FILESETTINGS_ENABLEFILEATTACHMENTS' => 'true', + 'MM_RATELIMITSETTINGS_MEMORYSTORESIZE' => '10000', + 'MM_SUPPORTSETTINGS_TERMSOFSERVICELINK' => '/static/help/terms.html', + 'MM_PRIVACYSETTINGS_SHOWEMAILADDRESS' => 'true', + 'MM_LOCALIZATIONSETTINGS_AVAILABLELOCALES' => 'en,es,fr,ja,pt-BR', + 'MM_WEBRTCSETTINGS_ENABLE' => 'false' + } +``` + +Refer to the [Mattermost Configuration Settings +documentation](https://docs.mattermost.com/administration/config-settings.html) +for details about categories, configuration values, etc. + +There are a few exceptions to this rule: + +1. `ServiceSettings.ListenAddress` configuration of Mattermost is configured + by `mattermost['service_address']` and `mattermost['service_port']` settings. +1. Configuration settings named in an inconsistent way are given in the + following table. Use these mappings when converting them to environment + variables. + +|`gitlab.rb` configuration|Environment variable| +|---|---| +|`mattermost['service_lets_encrypt_cert_cache_file']`|`MM_SERVICESETTINGS_LETSENCRYPTCERTIFICATECACHEFILE`| +|`mattermost['service_user_access_tokens']`|`MM_SERVICESETTINGS_ENABLEUSERACCESSTOKENS`| +|`mattermost['log_console_enable']`|`MM_LOGSETTINGS_ENABLECONSOLE`| +|`mattermost['email_enable_batching']`|`MM_EMAILSETTINGS_ENABLEEMAILBATCHING`| +|`mattermost['email_batching_buffer_size']`|`MM_EMAILSETTINGS_EMAILBATCHINGBUFFERSIZE`| +|`mattermost['email_batching_interval']`|`MM_EMAILSETTINGS_EMAILBATCHINGINTERVAL`| +|`mattermost['email_smtp_auth']`|`MM_EMAILSETTINGS_ENABLESMTPAUTH`| +|`mattermost['email_notification_content_type']`|`MM_EMAILSETTINGS_NOTIFICATIONCONTENTTYPE`| +|`mattermost['ratelimit_enable_ratelimiter']`|`MM_RATELIMITSETTINGS_ENABLE`| +|`mattermost['support_email']`|`MM_SUPPORTSETTINGS_SUPPORTEMAIL`| +|`mattermost['localization_server_locale']`|`MM_LOCALIZATIONSETTINGS_DEFAULTSERVERLOCALE`| +|`mattermost['localization_client_locale']`|`MM_LOCALIZATIONSETTINGS_DEFAULTCLIENTLOCALE`| +|`mattermost['webrtc_gateway_stun_uri']`|`MM_WEBRTCSETTINGS_STUN_URI`| +|`mattermost['webrtc_gateway_turn_uri']`|`MM_WEBRTCSETTINGS_TURN_URI`| +|`mattermost['webrtc_gateway_turn_username']`|`MM_WEBRTCSETTINGS_TURN_USERNAME`| +|`mattermost['webrtc_gateway_turn_sharedkey']`|`MM_WEBRTCSETTINGS_TURN_SHAREDKEY`| + +NOTE: +GitLab 11.0 no longer generates `config.json` file from the configuration specified +in `gitlab.rb`. Users are responsible for managing this file which can be done via the +Mattermost System Console or manually. +If a configuration setting is specified via both the `gitlab.rb` (as an environment variable) +and `config.json` files, the environment variable gets precedence. + +If you encounter any issues [visit the GitLab Mattermost troubleshooting forum](https://forum.mattermost.org/t/upgrading-to-gitlab-mattermost-in-gitlab-8-9/1735) and share any relevant portions of `mattermost.log` along with the step at which you encountered issues. + +### Upgrading GitLab Mattermost outside of GitLab + +If you choose to upgrade Mattermost outside of the Omnibus GitLab automation, [follow this guide](https://docs.mattermost.com/administration/upgrade.html). + +## OAuth2 sequence diagram + +The following image is a sequence diagram for how GitLab works as an OAuth2 +provider for Mattermost. You can use this to troubleshoot errors +in getting the integration to work: + + + +## Troubleshooting the Mattermost CLI + +### Failed to ping DB retrying in 10 seconds err=dial tcp: lookup dockerhost: no such host + +As of version 11.0, majority of the Mattermost settings are now configured via environmental variables. The error is mainly due to the database connection string being commented out in `gitlab.rb` and the database connection settings being set in environmental variables. Additionally, the connection string in the `gitlab.rb` is for MySQL which is no longer supported as of 12.1. + +You can fix this by setting up a `mattermost-cli` [shell alias](#mattermost-command-line-tools-cli). + +## Community support resources + +For help and support around your GitLab Mattermost deployment please see: + +- [Troubleshooting Forum](https://forum.mattermost.org/t/how-to-use-the-troubleshooting-forum/150) for configuration questions and issues. +- [Troubleshooting FAQ](https://docs.mattermost.com/install/troubleshooting.html). +- [Mattermost GitLab Issues Support Handbook](https://docs.mattermost.com/process/support.html?highlight=omnibus#gitlab-issues). +- [GitLab Mattermost issue tracker](https://gitlab.com/gitlab-org/gitlab-mattermost/-/issues) for verified bugs with repro steps. diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 596fff47716..5df6c4f28b7 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -4,17 +4,17 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab as OAuth2 authentication service provider +# GitLab as an OAuth 2.0 authentication service provider -This document describes how you can use GitLab as an OAuth 2 +This document describes how you can use GitLab as an OAuth 2.0 authentication service provider. If you want to use: -- The [OAuth2](https://oauth.net/2/) protocol to access GitLab resources on user's behalf, - see [OAuth2 provider](../api/oauth2.md). -- Other OAuth 2 authentication service providers to sign in to - GitLab, see the [OAuth2 client documentation](omniauth.md). +- The [OAuth 2.0](https://oauth.net/2/) protocol to access GitLab resources on + a user's behalf, see [OAuth 2.0 provider](../api/oauth2.md). +- Other OAuth 2.0 authentication service providers to sign in to + GitLab, see the [OAuth 2.0 client documentation](omniauth.md). - The related API, see [Applications API](../api/applications.md). ## Introduction to OAuth @@ -48,7 +48,7 @@ To add a new application for your user: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Applications**. +1. On the left sidebar, select **Applications**. 1. Enter a **Name**, **Redirect URI** and OAuth 2 scopes as defined in [Authorized Applications](#authorized-applications). The **Redirect URI** is the URL where users are sent after they authorize with GitLab. 1. Select **Save application**. GitLab provides: @@ -81,7 +81,7 @@ To add a new application for a group: To create an application for your GitLab instance: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Applications**. 1. Select **New application**. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index bba3252fe76..7dc775c2557 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -7,8 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # OmniAuth **(FREE)** GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and -other popular services. [OmniAuth](https://rubygems.org/gems/omniauth/) is -"a generalized Rack framework for multiple-provider authentication, built on Ruby. +other popular services. [OmniAuth](https://rubygems.org/gems/omniauth/) is a +"generalized Rack framework for multiple-provider authentication" built on Ruby. Configuring OmniAuth does not prevent standard GitLab authentication or LDAP (if configured) from continuing to work. Users can choose to sign in using any @@ -22,36 +22,38 @@ of the configured mechanisms. ## Supported Providers -This is a list of the current supported OmniAuth providers. Before proceeding on each provider's documentation, -make sure to first read this document as it contains some settings that are common for all providers. - -|Provider documentation |OmniAuth provider name | -|-----------------------------------------------------------------|--------------------------| -|[Atlassian Crowd](../administration/auth/crowd.md) |`crowd` | -|[Atlassian](../administration/auth/atlassian.md) |`atlassian_oauth2` | -|[Auth0](auth0.md) |`auth0` | -|[Authentiq](../administration/auth/authentiq.md) |`authentiq` | -|[AWS Cognito](../administration/auth/cognito.md) |`cognito` | -|[Azure v2](azure.md#microsoft-azure-oauth2-omniauth-provider-v2) |`azure_activedirectory_v2`| -|[Azure v1](azure.md) |`azure_oauth2` | -|[Bitbucket Cloud](bitbucket.md) |`bitbucket` | -|[CAS](cas.md) |`cas3` | -|[Facebook](facebook.md) |`facebook` | -|[Generic OAuth2](oauth2_generic.md) |`oauth2_generic` | -|[GitHub](github.md) |`github` | -|[GitLab.com](gitlab.md) |`gitlab` | -|[Google](google.md) |`google_oauth2` | -|[JWT](../administration/auth/jwt.md) |`jwt` | -|[Kerberos](kerberos.md) |`kerberos` | -|[OpenID Connect](../administration/auth/oidc.md) |`openid_connect` | -|[Salesforce](salesforce.md) |`salesforce` | -|[SAML](saml.md) |`saml` | -|[Shibboleth](shibboleth.md) |`shibboleth` | -|[Twitter](twitter.md) |`twitter` | +This is a list of the current supported OmniAuth providers. Before proceeding on +each provider's documentation, make sure to first read this document as it +contains some settings that are common for all providers. + +| Provider documentation | OmniAuth provider name | +|---------------------------------------------------------------------|----------------------------| +| [Atlassian Crowd](../administration/auth/crowd.md) | `crowd` | +| [Atlassian](../administration/auth/atlassian.md) | `atlassian_oauth2` | +| [Auth0](auth0.md) | `auth0` | +| [Authentiq](../administration/auth/authentiq.md) | `authentiq` | +| [AWS Cognito](../administration/auth/cognito.md) | `cognito` | +| [Azure v2](azure.md#microsoft-azure-oauth-20-omniauth-provider-v2) | `azure_activedirectory_v2` | +| [Azure v1](azure.md) | `azure_oauth2` | +| [Bitbucket Cloud](bitbucket.md) | `bitbucket` | +| [CAS](cas.md) | `cas3` | +| [Facebook](facebook.md) | `facebook` | +| [Generic OAuth 2.0](oauth2_generic.md) | `oauth2_generic` | +| [GitHub](github.md) | `github` | +| [GitLab.com](gitlab.md) | `gitlab` | +| [Google](google.md) | `google_oauth2` | +| [JWT](../administration/auth/jwt.md) | `jwt` | +| [Kerberos](kerberos.md) | `kerberos` | +| [OpenID Connect](../administration/auth/oidc.md) | `openid_connect` | +| [Salesforce](salesforce.md) | `salesforce` | +| [SAML](saml.md) | `saml` | +| [Shibboleth](shibboleth.md) | `shibboleth` | +| [Twitter](twitter.md) | `twitter` | ## Initial OmniAuth Configuration -The OmniAuth provider names from the table above are needed to configure a few global settings that are in common for all providers. +The OmniAuth provider names from the table above are needed to configure a few +global settings that are in common for all providers. NOTE: Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an @@ -65,18 +67,19 @@ earlier version, you must explicitly enable it. gitlab_rails['omniauth_allow_single_sign_on'] = ['azure_activedirectory_v2', 'google_oauth2'] ``` - The value defaults to `false`. If `false` users must be created manually, or they can't sign in by using OmniAuth. + The value defaults to `false`. If `false` users must be created manually, or + they can't sign in by using OmniAuth. + - `auto_link_ldap_user` can be used if you have [LDAP / ActiveDirectory](../administration/auth/ldap/index.md) integration enabled. It defaults to `false`. When enabled, users automatically created through an OmniAuth provider have their LDAP identity created in GitLab as well. -- `block_auto_created_users` defaults to `true`. If `true` auto created users will - be blocked by default and must be unblocked by an administrator before - they are able to sign in. +- `block_auto_created_users` defaults to `true`. If `true`, auto created users will + be blocked pending approval by an administrator before they are able to sign in. NOTE: If you set `block_auto_created_users` to `false`, make sure to only define providers under `allow_single_sign_on` that you are able to control, like -SAML, Shibboleth, Crowd, or Google. Otherwise, set it to `false`, or any user on +SAML, Shibboleth, Crowd, or Google. Otherwise, set it to `true`, or any user on the Internet can successfully sign in to your GitLab without administrative approval. @@ -150,7 +153,7 @@ OmniAuth provider for an existing user. 1. Sign in normally - whether standard sign in, LDAP, or another OmniAuth provider. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Account**. +1. On the left sidebar, select **Account**. 1. In the **Connected Accounts** section, select the desired OmniAuth provider, such as Twitter. 1. The user is redirected to the provider. After the user authorizes GitLab, they are redirected back to GitLab. @@ -166,23 +169,21 @@ Automatic linking using this method works for all providers [except the SAML provider](https://gitlab.com/gitlab-org/gitlab/-/issues/338293). For automatic linking using the SAML provider, see [SAML-specific](saml.md#general-setup) instructions. -As an example, the following configuration is used to enable the auto link feature for both: - -- OpenID Connect provider. -- Twitter OAuth provider. +As an example, the following configuration is used to enable the auto link +feature for both an **OpenID Connect provider** and a **Twitter OAuth provider**. -**For Omnibus installations** +- **For Omnibus installations** -```ruby -gitlab_rails['omniauth_auto_link_user'] = ["openid_connect", "twitter"] -``` + ```ruby + gitlab_rails['omniauth_auto_link_user'] = ["openid_connect", "twitter"] + ``` -**For installations from source** +- **For installations from source** -```yaml -omniauth: - auto_link_user: ["openid_connect", "twitter"] -``` + ```yaml + omniauth: + auto_link_user: ["openid_connect", "twitter"] + ``` ## Configure OmniAuth Providers as External @@ -197,18 +198,18 @@ If you decide to remove an OmniAuth provider from the external providers list, you must manually update the users that use this method to sign in if you want their accounts to be upgraded to full internal accounts. -**For Omnibus installations** +- **For Omnibus installations** -```ruby -gitlab_rails['omniauth_external_providers'] = ['twitter', 'google_oauth2'] -``` + ```ruby + gitlab_rails['omniauth_external_providers'] = ['twitter', 'google_oauth2'] + ``` -**For installations from source** +- **For installations from source** -```yaml -omniauth: - external_providers: ['twitter', 'google_oauth2'] -``` + ```yaml + omniauth: + external_providers: ['twitter', 'google_oauth2'] + ``` ## Using Custom OmniAuth Providers @@ -217,7 +218,7 @@ The following information only applies for installations from source. GitLab uses [OmniAuth](https://github.com/omniauth/omniauth) for authentication and already ships with a few providers pre-installed, such as LDAP, GitHub, and Twitter. You may also -need to integrate with other authentication solutions. For +have to integrate with other authentication solutions. For these cases, you can use the OmniAuth provider. ### Steps @@ -268,8 +269,8 @@ By default, **Sign In** is enabled by using all the OAuth Providers that have be To enable/disable an OmniAuth provider: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, go to **Settings**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, go to **Settings**. 1. Scroll to the **Sign-in Restrictions** section, and click **Expand**. 1. Below **Enabled OAuth Sign-In sources**, select the checkbox for each provider you want to enable or disable. @@ -283,18 +284,18 @@ has an effect if providers are configured and [enabled](#enable-or-disable-sign- If OmniAuth providers are causing problems even when individually disabled, you can disable the entire OmniAuth subsystem by modifying the configuration file: -**For Omnibus installations** +- **For Omnibus installations** -```ruby -gitlab_rails['omniauth_enabled'] = false -``` + ```ruby + gitlab_rails['omniauth_enabled'] = false + ``` -**For installations from source** +- **For installations from source**: -```yaml -omniauth: - enabled: false -``` + ```yaml + omniauth: + enabled: false + ``` ## Keep OmniAuth user profiles up to date @@ -302,18 +303,20 @@ You can enable profile syncing from selected OmniAuth providers and for all or f When authenticating using LDAP, the user's name and email are always synced. -```ruby -gitlab_rails['omniauth_sync_profile_from_provider'] = ['twitter', 'google_oauth2'] -gitlab_rails['omniauth_sync_profile_attributes'] = ['name', 'email', 'location'] -``` +- **For Omnibus installations** + + ```ruby + gitlab_rails['omniauth_sync_profile_from_provider'] = ['twitter', 'google_oauth2'] + gitlab_rails['omniauth_sync_profile_attributes'] = ['name', 'email', 'location'] + ``` -**For installations from source** +- **For installations from source** -```yaml -omniauth: - sync_profile_from_provider: ['twitter', 'google_oauth2'] - sync_profile_attributes: ['email', 'location'] -``` + ```yaml + omniauth: + sync_profile_from_provider: ['twitter', 'google_oauth2'] + sync_profile_attributes: ['email', 'location'] + ``` ## Bypassing two factor authentication @@ -325,16 +328,18 @@ or as `true` or `false` to allow all providers (or none). This option should be configured only for providers which already have two factor authentication (default: false). This configuration doesn't apply to SAML. -```ruby -gitlab_rails['omniauth_allow_bypass_two_factor'] = ['twitter', 'google_oauth2'] -``` +- **For Omnibus package** -**For installations from source** + ```ruby + gitlab_rails['omniauth_allow_bypass_two_factor'] = ['twitter', 'google_oauth2'] + ``` + +- **For installations from source** -```yaml -omniauth: - allow_bypass_two_factor: ['twitter', 'google_oauth2'] -``` + ```yaml + omniauth: + allow_bypass_two_factor: ['twitter', 'google_oauth2'] + ``` ## Automatically sign in with provider @@ -342,25 +347,25 @@ You can add the `auto_sign_in_with_provider` setting to your GitLab configuration to redirect login requests to your OmniAuth provider for authentication. This removes the need to click a button before actually signing in. -For example, when using the [Azure v2 integration](azure.md#microsoft-azure-oauth2-omniauth-provider-v2), set the following to enable auto +For example, when using the [Azure v2 integration](azure.md#microsoft-azure-oauth-20-omniauth-provider-v2), set the following to enable auto sign-in: -For Omnibus package: +- **For Omnibus package** -```ruby -gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_activedirectory_v2' -``` + ```ruby + gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_activedirectory_v2' + ``` -For installations from source: +- **For installations from source** -```yaml -omniauth: - auto_sign_in_with_provider: azure_activedirectory_v2 -``` + ```yaml + omniauth: + auto_sign_in_with_provider: azure_activedirectory_v2 + ``` Keep in mind that every sign-in attempt is redirected to the OmniAuth provider; you can't sign in using local credentials. Ensure at least -one of the OmniAuth users has administrator permissions. +one of the OmniAuth users has an administrator role. You may also bypass the auto sign in feature by browsing to `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. @@ -378,18 +383,22 @@ After you ensure your image is optimized for rendering at 64 x 64 pixels, you can override this icon in one of two ways: - **Provide a custom image path**: + 1. *If you are hosting the image outside of your GitLab server domain,* ensure your [content security policies](https://docs.gitlab.com/omnibus/settings/configuration.html#content-security-policy) are configured to allow access to the image file. 1. Depending on your method of installing GitLab, add a custom `icon` parameter to your GitLab configuration file. Read [OpenID Connect OmniAuth provider](../administration/auth/oidc.md) for an example for the OpenID Connect provider. + - **Directly embed an image in a configuration file**: This example creates a Base64-encoded version of your image you can serve through a [Data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs): + 1. Encode your image file with GNU `base64` command (such as `base64 -w 0 <logo.png>`) which returns a single-line `<base64-data>` string. - 1. Add the Base64-encoded data to a custom `icon` parameter in your GitLab configuration file: + 1. Add the Base64-encoded data to a custom `icon` parameter in your GitLab + configuration file: ```yaml omniauth: diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index 84457485382..dd65fb4822a 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -49,6 +49,7 @@ The following user information is shared with clients: | `website` | `string` | URL for the user's website | `profile` | `string` | URL for the user's GitLab profile | `picture` | `string` | URL for the user's GitLab avatar -| `groups` | `array` | Names of the groups the user is a member of +| `groups` | `array` | Paths for the groups the user is a member of, either directly or through an ancestor group. +| `groups_direct` | `array` | Paths for the groups the user is a direct member of. -The claims `sub`, `sub_legacy`, `email` and `email_verified` are included in the ID token, all other claims are available from the `/oauth/userinfo` endpoint used by OIDC clients. +The claims `sub`, `sub_legacy`, `email`, `email_verified` and `groups_direct` are included in the ID token. All other claims are available from the `/oauth/userinfo` endpoint used by OIDC clients. diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 656ed8b8647..fd5170d615f 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -18,21 +18,23 @@ To use reCAPTCHA, first you must create a site and private key. 1. Fill out the form necessary to obtain reCAPTCHA v2 keys. 1. Log in to your GitLab server, with administrator credentials. 1. Go to Reporting Applications Settings in the Admin Area (`admin/application_settings/reporting`). +1. Expand the **Spam and Anti-bot Protection** section. 1. Fill all reCAPTCHA fields with keys from previous steps. -1. Check the `Enable reCAPTCHA` checkbox. +1. Select the **Enable reCAPTCHA** checkbox. +1. To enable reCAPTCHA for logins via password, select the **Enable reCAPTCHA for login** checkbox. 1. Save the configuration. 1. Change the first line of the `#execute` method in `app/services/spam/spam_verdict_service.rb` - to `return CONDITONAL_ALLOW` so that the spam check short-circuits and triggers the response to + to `return CONDITIONAL_ALLOW` so that the spam check short-circuits and triggers the response to return `recaptcha_html`. NOTE: Make sure you are viewing an issuable in a project that is public. If you're working with an issue, the issue is public. -## Enabling reCAPTCHA for user logins via passwords +## Enable reCAPTCHA for user logins using the HTTP header -By default, reCAPTCHA is only enabled for user registrations. To enable it for -user logins via passwords, the `X-GitLab-Show-Login-Captcha` HTTP header must -be set. For example, in NGINX, this can be done via the `proxy_set_header` +You can enable reCAPTCHA for user logins via password [in the user interface](#configuration) +or by setting the `X-GitLab-Show-Login-Captcha` HTTP header. +For example, in NGINX, this can be done via the `proxy_set_header` configuration variable: ```nginx diff --git a/doc/integration/saml.md b/doc/integration/saml.md index ee3e2f574c7..b89772ba2ca 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -7,9 +7,11 @@ type: reference # SAML OmniAuth Provider **(FREE SELF)** -This page describes instance-wide SAML for self-managed GitLab instances. For SAML on GitLab.com, see [SAML SSO for GitLab.com groups](../user/group/saml_sso/index.md). +This page describes instance-wide SAML for self-managed GitLab instances. For +SAML on GitLab.com, see [SAML SSO for GitLab.com groups](../user/group/saml_sso/index.md). -You should also reference the [OmniAuth documentation](omniauth.md) for general settings that apply to all OmniAuth providers. +You should also reference the [OmniAuth documentation](omniauth.md) for general +settings that apply to all OmniAuth providers. ## Glossary of common terms @@ -19,7 +21,7 @@ You should also reference the [OmniAuth documentation](omniauth.md) for general | Service provider (SP) | GitLab can be configured as a SAML 2.0 SP. | | Assertion | A piece of information about a user's identity, such as their name or role. Also known as claims or attributes. | | Single Sign-On (SSO) | Name of authentication scheme. | -| Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. | +| Assertion consumer service URL | The callback on GitLab where users are redirected after successfully authenticating with the identity provider. | | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | | Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | @@ -209,7 +211,7 @@ for a full list of supported assertions. ## SAML Groups -You can require users to be members of a certain group, or assign users [external](../user/permissions.md#external-users), admin or [auditor](../user/permissions.md#auditor-users) roles based on group membership. +You can require users to be members of a certain group, or assign users [external](../user/permissions.md#external-users), administrator or [auditor](../user/permissions.md#auditor-users) roles based on group membership. These groups are checked on each SAML login and user attributes updated as necessary. This feature **does not** allow you to automatically add users to GitLab [Groups](../user/group/index.md). @@ -221,13 +223,13 @@ and whether you've installed [GitLab Enterprise Edition (EE)](https://about.gitl |------------------------------|--------------------|--------------------------------------| | [Required](#required-groups) | **(FREE SELF)** | Yes | | [External](#external-groups) | **(FREE SELF)** | No | -| [Admin](#admin-groups) | **(FREE SELF)** | Yes | +| [Admin](#administrator-groups) | **(FREE SELF)** | Yes | | [Auditor](#auditor-groups) | **(PREMIUM SELF)** | Yes | ### Requirements -First you need to tell GitLab where to look for group information. For this you -need to make sure that your IdP server sends a specific `AttributeStatement` along +First tell GitLab where to look for group information. For this, you +must make sure that your IdP server sends a specific `AttributeStatement` along with the regular SAML response. Here is an example: ```xml @@ -242,17 +244,18 @@ with the regular SAML response. Here is an example: ``` The name of the attribute can be anything you like, but it must contain the groups -to which a user belongs. In order to tell GitLab where to find these groups, you need +to which a user belongs. To tell GitLab where to find these groups, you need to add a `groups_attribute:` element to your SAML settings. ### Required groups **(FREE SELF)** -Your IdP passes Group Information to the SP (GitLab) in the SAML Response. You need to configure GitLab to identify: +Your IdP passes Group information to the SP (GitLab) in the SAML Response. +To use this response, configure GitLab to identify: - Where to look for the groups in the SAML response via the `groups_attribute` setting - Which group membership is requisite to sign in via the `required_groups` setting -When `required_groups` is not set or it is empty, anyone with proper authentication +When `required_groups` is empty or not set, anyone with proper authentication is able to use the service. Example: @@ -273,7 +276,9 @@ Example: ### External groups **(FREE SELF)** -SAML login supports automatic identification on whether a user should be considered an [external user](../user/permissions.md#external-users). This is based on the user's group membership in the SAML identity provider. +SAML login supports the automatic identification of a user as an +[external user](../user/permissions.md#external-users). This is based on the user's group +membership in the SAML identity provider. ```yaml { name: 'saml', @@ -289,11 +294,13 @@ SAML login supports automatic identification on whether a user should be conside } } ``` -### Admin groups **(FREE SELF)** +### Administrator groups **(FREE SELF)** -The requirements are the same as the previous settings, your IdP needs to pass Group information to GitLab, you need to tell -GitLab where to look for the groups in the SAML response, and which group(s) should be -considered admin users. +The requirements are the same as the previous settings: + +- The IdP must pass Group information to GitLab. +- GitLab must know where to look for the groups in the SAML response, as well as + which group(s) grant the user an administrator role. ```yaml { name: 'saml', @@ -313,9 +320,11 @@ considered admin users. > Introduced in GitLab 11.4. -The requirements are the same as the previous settings, your IdP needs to pass Group information to GitLab, you need to tell -GitLab where to look for the groups in the SAML response, and which group(s) should be -considered [auditor users](../user/permissions.md#auditor-users). +The requirements are the same as the previous settings: + +- The IdP must pass Group information to GitLab. +- GitLab should know where to look for the groups in the SAML response, as well as which + group(s) entail that a given user is an [auditor user](../user/permissions.md#auditor-users). ```yaml { name: 'saml', @@ -333,8 +342,8 @@ considered [auditor users](../user/permissions.md#auditor-users). ## Bypass two factor authentication -If you want some SAML authentication methods to count as 2FA on a per session basis, you can register them in the -`upstream_two_factor_authn_contexts` list. +If you want some SAML authentication methods to count as 2FA on a per session +basis, you can register them in the `upstream_two_factor_authn_contexts` list. In addition to the changes in GitLab, make sure that your IdP is returning the `AuthnContext`. For example: @@ -411,7 +420,7 @@ In addition to the changes in GitLab, make sure that your IdP is returning the ### `auto_sign_in_with_provider` You can add this setting to your GitLab configuration to automatically redirect you -to your SAML server for authentication, thus removing the need to click a button +to your SAML server for authentication. This removes the requirement to click a button before actually signing in. For Omnibus package: @@ -429,7 +438,7 @@ omniauth: Keep in mind that every sign in attempt redirects to the SAML server; you cannot sign in using local credentials. Ensure at least one of the -SAML users has admin permissions. +SAML users has an administrator role. You may also bypass the auto sign-in feature by browsing to `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. @@ -464,9 +473,14 @@ args: { } ``` -#### Setting a username +#### Set a username + +By default, the email in the SAML response is used to automatically generate the +user's GitLab username. If you'd like to set another attribute as the username, +assign it to the `nickname` OmniAuth `info` hash attribute. -By default, the email in the SAML response is used to automatically generate the user's GitLab username. If you'd like to set another attribute as the username, assign it to the `nickname` OmniAuth `info` hash attribute. For example, if you wanted to set the `username` attribute in your SAML Response to the username in GitLab, use the following setting: +For example, if you want to set the `username` attribute in your SAML Response to the username +in GitLab, use the following setting: ```yaml args: { @@ -482,7 +496,7 @@ args: { ### `allowed_clock_drift` The clock of the Identity Provider may drift slightly ahead of your system clocks. -To allow for a small amount of clock drift you can use `allowed_clock_drift` within +To allow for a small amount of clock drift, you can use `allowed_clock_drift` in your settings. Its value must be given in a number (and/or fraction) of seconds. The value given is added to the current time at which the response is validated. @@ -572,7 +586,8 @@ This may be the case, for example, if you terminate TLS encryption early at a lo balancer and include sensitive details in assertions that you do not want appearing in logs. Most organizations should not need additional encryption at this layer. -The SAML integration supports EncryptedAssertion. You need to define the private key and the public certificate of your GitLab instance in the SAML settings: +The SAML integration supports EncryptedAssertion. You should define the private +key and the public certificate of your GitLab instance in the SAML settings: ```yaml args: { @@ -602,7 +617,7 @@ SAML Requests use the SAML redirect binding, so this isn't necessary (unlike the SAML POST binding, where signing is required to prevent intermediaries from tampering with the requests). -To sign, you need to create a private key and public certificate pair for your +To sign, create a private key and public certificate pair for your GitLab instance to use for SAML. The settings for signing can be set in the `security` section of the configuration. @@ -653,7 +668,7 @@ The [Generated passwords for users created through integrated authentication](.. For information on the GitLab.com implementation, please see the [SAML SSO for GitLab.com groups page](../user/group/saml_sso). -Group SAML SSO helps if you need to allow access via multiple SAML identity providers, but as a multi-tenant solution is less suited to cases where you administer your own GitLab instance. +Group SAML SSO helps if you have to allow access via multiple SAML identity providers, but as a multi-tenant solution is less suited to cases where you administer your own GitLab instance. To proceed with configuring Group SAML SSO instead, enable the `group_saml` OmniAuth provider. This can be done from: @@ -668,7 +683,7 @@ Group SAML on a self-managed instance is limited when compared to the recommende - [LDAP compatibility](../administration/auth/ldap/index.md). - [LDAP Group Sync](../user/group/index.md#manage-group-memberships-via-ldap). - [Required groups](#required-groups). -- [Admin groups](#admin-groups). +- [Administrator groups](#administrator-groups). - [Auditor groups](#auditor-groups). ### Omnibus installations @@ -750,7 +765,7 @@ Make sure you have access to a Google Workspace [Super Admin](https://support.go | First name | `first_name` | Required value to communicate with GitLab. | | Last name | `last_name` | Required value to communicate with GitLab. | -You also need to setup the following SAML attribute mappings: +You also must setup the following SAML attribute mappings: | Google Directory attributes | App attributes | |-----------------------------------|----------------| @@ -767,8 +782,9 @@ When configuring the Google Workspace SAML app, be sure to record the following | SSO URL | Depends | Google Identity Provider details. Set to the GitLab `idp_sso_target_url` setting. | | Certificate | Downloadable | Run `openssl x509 -in <your_certificate.crt> -noout -fingerprint` to generate the SHA1 fingerprint that can be used in the `idp_cert_fingerprint` setting. | -While the Google Workspace Admin provides IdP metadata, Entity ID and SHA-256 fingerprint, -GitLab does not need that information to connect to the Google Workspace SAML app. +While the Google Workspace Admin provides IdP metadata, Entity ID, and SHA-256 +fingerprint, they are not required. GitLab does not need that information to +connect to the Google Workspace SAML app. ## Troubleshooting @@ -778,9 +794,10 @@ You can find the base64-encoded SAML Response in the [`production_json.log`](../ ### GitLab+SAML Testing Environments -If you need to troubleshoot, [a complete GitLab+SAML testing environment using Docker compose](https://gitlab.com/gitlab-com/support/toolbox/replication/tree/master/compose_files) is available. +To troubleshoot, [a complete GitLab+SAML testing environment using Docker compose](https://gitlab.com/gitlab-com/support/toolbox/replication/tree/master/compose_files) +is available. -If you only need a SAML provider for testing, a [quick start guide to start a Docker container](../administration/troubleshooting/test_environments.md#saml) with a plug and play SAML 2.0 Identity Provider (IdP) is available. +If you only require a SAML provider for testing, a [quick start guide to start a Docker container](../administration/troubleshooting/test_environments.md#saml) with a plug and play SAML 2.0 Identity Provider (IdP) is available. ### 500 error after login @@ -794,8 +811,8 @@ claim name `email` or `mail`. ### 422 error after login If you see a "422 error" in GitLab when you are redirected from the SAML -sign-in page, you might have an incorrectly configured assertion consumer -service (ACS) URL on the identity provider. +sign-in page, you might have an incorrectly configured Assertion Consumer +Service (ACS) URL on the identity provider. Make sure the ACS URL points to `https://gitlab.example.com/users/auth/saml/callback`, where `gitlab.example.com` is the URL of your GitLab instance. @@ -845,14 +862,17 @@ is not providing this information, all SAML requests fail. Make sure this information is provided. -Another issue that can result in this error is when the correct information is being sent by the IdP, but the attributes don't match the names in the OmniAuth `info` hash. In this case, you need to set `attribute_statements` in the SAML configuration to [map the attribute names in your SAML Response to the corresponding OmniAuth `info` hash names](#attribute_statements). +Another issue that can result in this error is when the correct information is being sent by +the IdP, but the attributes don't match the names in the OmniAuth `info` hash. In this case, +you must set `attribute_statements` in the SAML configuration to [map the attribute names in +your SAML Response to the corresponding OmniAuth `info` hash names](#attribute_statements). ### Key validation error, Digest mismatch or Fingerprint mismatch These errors all come from a similar place, the SAML certificate. SAML requests -need to be validated using a fingerprint, a certificate or a validator. +must be validated using either a fingerprint, a certificate, or a validator. -For this you need to take the following into account: +For this requirement, be sure to take the following into account: - If a fingerprint is used, it must be the SHA1 fingerprint - If no certificate is provided in the settings, a fingerprint or fingerprint diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index b9b5f394e3c..4059aef9de3 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -4,36 +4,40 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Slash Commands **(FREE)** +# Slash commands in Mattermost and Slack **(FREE)** > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to GitLab Free 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 an [integration configuration](../user/project/integrations/slack_slash_commands.md). Type the command as a message in your chat client to activate it. +If you want to control and view GitLab content while you're +working in Slack and Mattermost, you can use slash commands. +Type the command as a message in your chat client to activate it. +For Slack, this requires an [integration configuration](../user/project/integrations/slack_slash_commands.md). -Commands are scoped to a project, with a trigger term that is specified during configuration. +Slash commands are scoped to a project +and require the trigger command specified during configuration. -We suggest you use the project name as the trigger term for simplicity and clarity. +We suggest you use the project name as the trigger command for simplicity and clarity. -Taking the trigger term as `project-name`, the commands are: +Assuming `project-name` is the trigger command, the slash commands are: | Command | Effect | | ------- | ------ | -| `/project-name help` | Shows all available slash commands | -| `/project-name issue new <title> <shift+return> <description>` | Creates a new issue with title `<title>` and description `<description>` | -| `/project-name issue show <id>` | Shows the issue with ID `<id>` | -| `/project-name issue close <id>` | Closes the issue with ID `<id>` | -| `/project-name issue search <query>` | Shows up to 5 issues matching `<query>` | -| `/project-name issue move <id> to <project>` | Moves issue ID `<id>` to `<project>` | -| `/project-name issue comment <id> <shift+return> <comment>` | Adds a new comment to an issue with ID `<id>` and comment body `<comment>` | -| `/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/index.md) job `<job name>` on the default branch | +| `/project-name help` | Shows all available slash commands. | +| `/project-name issue new <title> <shift+return> <description>` | Creates a new issue with title `<title>` and description `<description>`. | +| `/project-name issue show <id>` | Shows the issue with ID `<id>`. | +| `/project-name issue close <id>` | Closes the issue with ID `<id>`. | +| `/project-name issue search <query>` | Shows up to 5 issues matching `<query>`. | +| `/project-name issue move <id> to <project>` | Moves the issue with ID `<id>` to `<project>`. | +| `/project-name issue comment <id> <shift+return> <comment>` | Adds a new comment with comment body `<comment>` to the issue with ID `<id>`. | +| `/project-name deploy <from> to <to>` | [Deploys](#deploy-command) from the `<from>` environment to the `<to>` environment. | +| `/project-name run <job name> <arguments>` | Executes the [ChatOps](../ci/chatops/index.md) job `<job name>` on the default branch. | If you are using the [GitLab Slack application](../user/project/integrations/gitlab_slack_application.md) for your GitLab.com projects, [add the `gitlab` keyword at the beginning of the command](../user/project/integrations/gitlab_slack_application.md#usage). ## Issue commands -It's possible to create new issue, display issue details and search up to 5 issues. +You can create a new issue, display issue details, and search up to 5 issues. ## Deploy command @@ -41,7 +45,7 @@ To deploy to an environment, GitLab tries to find a deployment manual action in the pipeline. If there's only one action for a given environment, it is triggered. -If more than one action is defined, GitLab tries to find an action -which name equals the environment name we want to deploy to. +If more than one action is defined, GitLab finds an action +name that equals the environment name to deploy to. -The command returns an error when no matching action has been found. +The command returns an error if no matching action is found. diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 86ca389e9b2..6f0027aedc7 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -76,8 +76,8 @@ You can skip this step if you already have your GitLab repositories searchable i ### Configure your GitLab instance with Sourcegraph -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Sourcegraph** configuration section. 1. Check **Enable Sourcegraph**. 1. Set the Sourcegraph URL to your Sourcegraph instance, such as `https://sourcegraph.example.com`. diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md index df1d9270bd5..96150440e53 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -42,7 +42,7 @@ To find it in GitLab: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Access Tokens**. +1. On the left sidebar, select **Access Tokens**. Learn more about generating a personal access token in the [Personal Access Token Documentation](../user/profile/personal_access_tokens.md). diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index 1d711ea271e..6bc467ed7b2 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -4,9 +4,10 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Twitter OAuth2 OmniAuth Provider **(FREE)** +# Twitter OAuth 2.0 OmniAuth Provider **(FREE)** -To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter generates a client ID and secret key for you to use. +To enable the Twitter OmniAuth provider you must register your application with +Twitter. Twitter generates a client ID and secret key for you to use. 1. Sign in to [Twitter Application Management](https://developer.twitter.com/apps). diff --git a/doc/integration/vault.md b/doc/integration/vault.md index c98990bcb0e..ebfa91c7516 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -23,7 +23,7 @@ The following assumes you already have Vault installed and running. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. - 1. In the left sidebar, select **Applications**. + 1. On the left sidebar, select **Applications**. 1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). 1. Select the **OpenID** scope. 1. Select **Save application**. |
