diff options
Diffstat (limited to 'doc/integration')
33 files changed, 458 insertions, 293 deletions
diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index d5e39a59dff..5541c5914d5 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -20,15 +20,15 @@ NOTE: GitLab submits all issues to Akismet. Akismet configuration is available to users on self-managed GitLab. Akismet is already enabled on -GitLab SaaS (GitLab.com), where it's configuration and management are handled by GitLab Inc. +GitLab SaaS (GitLab.com), where its configuration and management are handled by GitLab Inc. -## Configuration **(FREE SELF)** +## Configure Akismet **(FREE SELF)** To use Akismet: 1. Go to the [Akismet sign-in page](https://akismet.com/account/). 1. Sign in or create a new account. -1. Click **Show** to reveal the API key, and copy the API key's value. +1. Select **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**. 1. On the left sidebar, select **Settings > Reporting** (`/admin/application_settings/reporting`). @@ -38,7 +38,7 @@ To use Akismet: ![Screenshot of Akismet settings](img/akismet_settings.png) -## Training **(FREE SELF)** +## Train the Akismet filter **(FREE SELF)** To better differentiate between spam and ham, you can train the Akismet filter whenever there is a false positive or false negative. diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index e243e1defe8..8bac95c5f04 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -58,12 +58,14 @@ application. ```ruby gitlab_rails['omniauth_providers'] = [ { - "name" => "auth0", - "args" => { client_id: 'YOUR_AUTH0_CLIENT_ID', - client_secret: 'YOUR_AUTH0_CLIENT_SECRET', - domain: 'YOUR_AUTH0_DOMAIN', - scope: 'openid profile email' - } + name: "auth0", + # label: "Provider name", # optional label for login button, defaults to "Auth0" + args: { + client_id: "YOUR_AUTH0_CLIENT_ID", + client_secret: "YOUR_AUTH0_CLIENT_SECRET", + domain: "YOUR_AUTH0_DOMAIN", + scope: "openid profile email" + } } ] ``` @@ -72,6 +74,7 @@ application. ```yaml - { name: 'auth0', + # label: 'Provider name', # optional label for login button, defaults to "Auth0" args: { client_id: 'YOUR_AUTH0_CLIENT_ID', client_secret: 'YOUR_AUTH0_CLIENT_SECRET', diff --git a/doc/integration/azure.md b/doc/integration/azure.md index bd16c8c0069..8d69881699b 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -58,11 +58,12 @@ As you go through the Microsoft procedure, keep the following in mind: ```ruby gitlab_rails['omniauth_providers'] = [ { - "name" => "azure_oauth2", - "args" => { - "client_id" => "CLIENT ID", - "client_secret" => "CLIENT SECRET", - "tenant_id" => "TENANT ID", + name: "azure_oauth2", + # label: "Provider name", # optional label for login button, defaults to "Azure AD" + args: { + client_id: "CLIENT ID", + client_secret: "CLIENT SECRET", + tenant_id: "TENANT ID", } } ] @@ -72,9 +73,10 @@ As you go through the Microsoft procedure, keep the following in mind: ```yaml - { name: 'azure_oauth2', - args: { client_id: "CLIENT ID", - client_secret: "CLIENT SECRET", - tenant_id: "TENANT ID" } } + # label: 'Provider name', # optional label for login button, defaults to "Azure AD" + args: { client_id: 'CLIENT ID', + client_secret: 'CLIENT SECRET', + tenant_id: 'TENANT ID' } } ``` The `base_azure_url` is optional and can be added for different locales; @@ -167,6 +169,7 @@ Alternatively, add the `User.Read.All` application permission. gitlab_rails['omniauth_providers'] = [ { "name" => "azure_activedirectory_v2", + "label" => "Provider name", # optional label for login button, defaults to "Azure AD v2" "args" => { "client_id" => "CLIENT ID", "client_secret" => "CLIENT SECRET", @@ -180,9 +183,10 @@ Alternatively, add the `User.Read.All` application permission. ```yaml - { name: 'azure_activedirectory_v2', - args: { client_id: "CLIENT ID", - client_secret: "CLIENT SECRET", - tenant_id: "TENANT ID" } } + label: 'Provider name', # optional label for login button, defaults to "Azure AD v2" + args: { client_id: "CLIENT ID", + client_secret: "CLIENT SECRET", + tenant_id: "TENANT ID" } } ``` The `base_azure_url` is optional and can be added for different locales; diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index fa3b62ba7af..db7e7d74efe 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -42,7 +42,7 @@ to the end of the Bitbucket authorization callback URL. - **Name:** This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. - - **Application description:** *(Optional)* Fill this in if you wish. + - **Application description:** Optional. Fill this in if you wish. - **Callback URL:** (Required in GitLab versions 8.15 and greater) The URL to your GitLab installation, such as `https://gitlab.example.com/users/auth`. @@ -87,10 +87,11 @@ to the end of the Bitbucket authorization callback URL. ```ruby gitlab_rails['omniauth_providers'] = [ { - "name" => "bitbucket", - "app_id" => "BITBUCKET_APP_KEY", - "app_secret" => "BITBUCKET_APP_SECRET", - "url" => "https://bitbucket.org/" + name: "bitbucket", + # label: "Provider name", # optional label for login button, defaults to "Bitbucket" + app_id: "BITBUCKET_APP_KEY", + app_secret: "BITBUCKET_APP_SECRET", + url: "https://bitbucket.org/" } ] ``` @@ -102,6 +103,7 @@ to the end of the Bitbucket authorization callback URL. enabled: true providers: - { name: 'bitbucket', + # label: 'Provider name', # optional label for login button, defaults to "Bitbucket" app_id: 'BITBUCKET_APP_KEY', app_secret: 'BITBUCKET_APP_SECRET', url: 'https://bitbucket.org/' } diff --git a/doc/integration/cas.md b/doc/integration/cas.md index 4699f7147aa..9594836164a 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -37,14 +37,14 @@ configure CAS for back-channel logout. ```ruby gitlab_rails['omniauth_providers'] = [ { - "name"=> "cas3", - "label"=> "cas", - "args"=> { - "url"=> 'CAS_SERVER', - "login_url"=> '/CAS_PATH/login', - "service_validate_url"=> '/CAS_PATH/p3/serviceValidate', - "logout_url"=> '/CAS_PATH/logout' - } + name: "cas3", + label: "Provider name", # optional label for login button, defaults to "Cas3" + args: { + url: "CAS_SERVER", + login_url: "/CAS_PATH/login", + service_validate_url: "/CAS_PATH/p3/serviceValidate", + logout_url: "/CAS_PATH/logout" + } } ] ``` @@ -53,7 +53,7 @@ configure CAS for back-channel logout. ```yaml - { name: 'cas3', - label: 'cas', + label: 'Provider name', # optional label for login button, defaults to "Cas3" args: { url: 'CAS_SERVER', login_url: '/CAS_PATH/login', diff --git a/doc/integration/datadog.md b/doc/integration/datadog.md index 687be5adcf7..89e08d330e8 100644 --- a/doc/integration/datadog.md +++ b/doc/integration/datadog.md @@ -32,20 +32,20 @@ project, group, or instance level: 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. -1. (Optional) To override the API URL used to send data directly, provide an **API URL**. +1. Optional. To override the API URL used to send data directly, provide an **API URL**. Used only in advanced scenarios. 1. Provide your Datadog **API key**. -1. (Optional) If you use more than one GitLab instance, provide a unique **Service** name +1. Optional. If you use more than one GitLab instance, provide a unique **Service** name to differentiate between your GitLab instances. -1. (Optional) If you use groups of GitLab instances (such as staging and production +1. Optional. If you use groups of GitLab instances (such as staging and production environments), provide an **Env** name. This value is attached to each span the integration generates. -1. (Optional) Select **Test settings** to test your integration. +1. Optional. Select **Test settings** to test your integration. 1. Select **Save changes**. When the integration sends data, you can view it in the [CI Visibility](https://app.datadoghq.com/ci) section of your Datadog account. -## Related links +## Related topics - [Datadog's CI Visibility](https://docs.datadoghq.com/continuous_integration/) documentation. diff --git a/doc/integration/ding_talk.md b/doc/integration/ding_talk.md index 55d51a5ebff..2bc4f29298a 100644 --- a/doc/integration/ding_talk.md +++ b/doc/integration/ding_talk.md @@ -60,9 +60,10 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene ```ruby gitlab_rails['omniauth_providers'] = [ { - "name" => "ding_talk", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET" + name: "dingtalk", + # label: "Provider name", # optional label for login button, defaults to "Ding Talk" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET" } ] ``` @@ -70,7 +71,8 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene For installations from source: ```yaml - - { name: 'ding_talk', + - { name: 'dingtalk', + # label: 'Provider name', # optional label for login button, defaults to "Ding Talk" app_id: 'YOUR_APP_ID', app_secret: 'YOUR_APP_SECRET' } ``` diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 20f8fdc55f2..8461aca8c8d 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -48,7 +48,7 @@ each node should have: 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") and ensure you select your version. Detailed information on how to install Elasticsearch is out of the scope of this page. -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) +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 OpenSearch](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/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. @@ -93,7 +93,7 @@ the indexer itself. This project relies on [International Components for Unicode](https://icu.unicode.org/) (ICU) for text encoding, therefore we must ensure the development packages for your platform are -installed before running `make`. +installed before running `make`. #### Debian / Ubuntu @@ -207,9 +207,9 @@ The following Elasticsearch settings are available: | `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 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. | +| `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 are 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 OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html) for details of AWS hosted OpenSearch domain access policy configuration. | +| `AWS Region` | The AWS region in which your OpenSearch Service is located. | | `AWS Access Key` | The AWS access key. | | `AWS Secret Access Key` | The AWS secret access key. | | `Maximum file size indexed` | See [the explanation in instance limits.](../administration/instance_limits.md#maximum-file-size-indexed). | @@ -233,7 +233,7 @@ If you select `Limit namespaces and projects that can be indexed`, more options 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 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. +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 does 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. @@ -279,8 +279,8 @@ To disable the Elasticsearch integration: 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. -1. (Optional) Delete the existing indexes: +1. Select **Save changes**. +1. Optional. Delete the existing indexes: ```shell # Omnibus installations @@ -355,7 +355,7 @@ Setting this value too high can have adverse performance impacts as your cluster may become heavily saturated with searches and writes. Setting this value too low may lead the reindexing process to take a very long time to complete. -The best value for this will depend on your cluster size, whether you're willing +The best value for this depends on your cluster size, whether you're willing to accept some degraded search performance during reindexing, and how important it is for the reindex to finish quickly and resume indexing. @@ -375,7 +375,7 @@ Sometimes, you might want to abandon the unfinished reindex job and resume the i 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. -1. Expand **Elasticsearch zero-downtime reindexing**. +1. Expand **Advanced Search**. 1. Clear the **Pause Elasticsearch indexing** checkbox. ## Advanced Search migrations @@ -430,23 +430,23 @@ In order to debug issues with the migrations you can check the [`elasticsearch.l ### Retry a halted migration Some migrations are built with a retry limit. If the migration cannot finish within the retry limit, -it will be halted and a notification will be displayed in the Advanced Search integration settings. +it is halted and a notification is displayed in the Advanced Search integration settings. It is recommended to check the [`elasticsearch.log` file](../administration/logs.md#elasticsearchlog) to debug why the migration was halted and make any changes before retrying the migration. Once you believe you've -fixed the cause of the failure, click "Retry migration", and the migration will be scheduled to be retried +fixed the cause of the failure, click "Retry migration", and the migration is scheduled to be retried in the background. If you cannot get the migration to succeed, you may consider the [last resort to recreate the index from scratch](#last-resort-to-recreate-an-index). This may allow you to skip over -the problem because a newly created index will skip all migrations as the index -will be recreated with the correct up-to-date schema. +the problem because a newly created index skips all migrations as the index +is recreated with the correct up-to-date schema. ### All migrations must be finished before doing a major upgrade Before doing a major version GitLab upgrade, you should have completed all migrations that exist up until the latest minor version before that major -version. If you have halted migrations, these will need to be resolved and +version. If you have halted migrations, these need to be resolved and [retried](#retry-a-halted-migration) before proceeding with a major version upgrade. Read more about [upgrading to a new major version](../update/index.md#upgrading-to-a-new-major-version). @@ -468,7 +468,7 @@ The following are some available Rake tasks: | [`sudo gitlab-rake gitlab:elastic:resume_indexing`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Resumes Elasticsearch indexing. | | [`sudo gitlab-rake gitlab:elastic:index_projects`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Iterates over all projects and queues Sidekiq jobs to index them in the background. | | [`sudo gitlab-rake gitlab:elastic:index_projects_status`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Determines the overall status of the indexing. It is done by counting the total number of indexed projects, dividing by a count of the total number of projects, then multiplying by 100. | -| [`sudo gitlab-rake gitlab:elastic:clear_index_status`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Deletes all instances of IndexStatus for all projects. Note that this command will result in a complete wipe of the index, and it should be used with caution. | +| [`sudo gitlab-rake gitlab:elastic:clear_index_status`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Deletes all instances of IndexStatus for all projects. Note that this command results in a complete wipe of the index, and it should be used with caution. | | [`sudo gitlab-rake gitlab:elastic:create_empty_index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Generates empty indexes (the default index and a separate issues index) and assigns an alias for each on the Elasticsearch side only if it doesn't already exist. | | [`sudo gitlab-rake gitlab:elastic:delete_index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Removes the GitLab indexes and aliases (if they exist) on the Elasticsearch instance. | | [`sudo gitlab-rake gitlab:elastic:recreate_index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Wrapper task for `gitlab:elastic:delete_index` and `gitlab:elastic:create_empty_index`. | @@ -501,7 +501,7 @@ I, [2019-03-04T21:27:05.215266 #3384] INFO -- : Indexing GitLab User / test (ID ## Advanced Search index scopes -When performing a search, the GitLab index will use the following scopes: +When performing a search, the GitLab index uses the following scopes: | Scope Name | What it searches | | ---------------- | ---------------------- | @@ -521,25 +521,25 @@ When performing a search, the GitLab index will use the following scopes: For basic guidance on choosing a cluster configuration you may refer to [Elastic Cloud Calculator](https://cloud.elastic.co/pricing). You can find more information below. -- Generally, you will want to use at least a 2-node cluster configuration with one replica, which will allow you to have resilience. If your storage usage is growing quickly, you may want to plan horizontal scaling (adding more nodes) beforehand. -- It's not recommended to use HDD storage with the search cluster, because it will take a hit on performance. It's better to use SSD storage (NVMe or SATA SSD drives for example). +- Generally, you want to use at least a 2-node cluster configuration with one replica, which allows you to have resilience. If your storage usage is growing quickly, you may want to plan horizontal scaling (adding more nodes) beforehand. +- It's not recommended to use HDD storage with the search cluster, because it takes a hit on performance. It's better to use SSD storage (NVMe or SATA SSD drives for example). - You can use the [GitLab Performance Tool](https://gitlab.com/gitlab-org/quality/performance) to benchmark search performance with different search cluster sizes and configurations. - `Heap size` should be set to no more than 50% of your physical RAM. Additionally, it shouldn't be set to more than the threshold for zero-based compressed oops. The exact threshold varies, but 26 GB is safe on most systems, but can also be as large as 30 GB on some systems. See [Heap size settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/important-settings.html#heap-size-settings) and [Setting JVM options](https://www.elastic.co/guide/en/elasticsearch/reference/current/jvm-options.html) for more details. - Number of CPUs (CPU cores) per node usually corresponds to the `Number of Elasticsearch shards` setting described below. -- 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. +- 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 generally helps 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 > 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 -- `refresh_interval` is a per index setting. You may want to adjust that from default `1s` to a bigger value if you don't need data in real-time. This will change how soon you will see fresh results. If that's important for you, you should leave it as close as possible to the default value. +- `refresh_interval` is a per index setting. You may want to adjust that from default `1s` to a bigger value if you don't need data in real-time. This changes how soon you see fresh results. If that's important for you, you should leave it as close as possible to the default value. - You might want to raise [`indices.memory.index_buffer_size`](https://www.elastic.co/guide/en/elasticsearch/reference/current/indexing-buffer.html) to 30% or 40% if you have a lot of heavy indexing operations. ### Advanced Search integration settings guidance -- The `Number of Elasticsearch shards` setting usually corresponds with the number of CPUs available in your cluster. For example, if you have a 3-node cluster with 4 cores each, this means you will benefit from having at least 3*4=12 shards in the cluster. It's only possible to change the shards number by using [Split index API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-split-index.html) or by reindexing to a different index with a changed number of shards. -- The `Number of Elasticsearch replicas` setting should most of the time be equal to `1` (each shard will have 1 replica). Using `0` is not recommended, because losing one node will corrupt the index. +- The `Number of Elasticsearch shards` setting usually corresponds with the number of CPUs available in your cluster. For example, if you have a 3-node cluster with 4 cores each, this means you benefit from having at least 3*4=12 shards in the cluster. It's only possible to change the shards number by using [Split index API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-split-index.html) or by reindexing to a different index with a changed number of shards. +- The `Number of Elasticsearch replicas` setting should most of the time be equal to `1` (each shard has 1 replica). Using `0` is not recommended, because losing one node corrupts the index. ### Indexing large instances @@ -548,7 +548,7 @@ This section may be helpful in the event that the other due to large volumes of data being indexed. WARNING: -Indexing a large instance will generate a lot of Sidekiq jobs. +Indexing a large instance generates a lot of Sidekiq jobs. 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). @@ -890,11 +890,11 @@ There is also an easy way to check it automatically with `sudo gitlab-rake gitla 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/opensearch-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 -**For a single node Elasticsearch cluster the functional cluster health status will be yellow** (never green) because the primary shard is allocated but replicas cannot be as there is no other node to which Elasticsearch can assign a replica. This also applies if you are using the [Amazon Elasticsearch](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/aes-handling-errors.html#aes-handling-errors-yellow-cluster-status) service. +**For a single node Elasticsearch cluster the functional cluster health status will be yellow** (never green) because the primary shard is allocated but replicas cannot be as there is no other node to which Elasticsearch can assign a replica. This also applies if you are using the [Amazon OpenSearch](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/aes-handling-errors.html#aes-handling-errors-yellow-cluster-status) service. WARNING: Setting the number of replicas to `0` is discouraged (this is not allowed in the GitLab Elasticsearch Integration menu). If you are planning to add more Elasticsearch nodes (for a total of more than 1 Elasticsearch) the number of replicas will need to be set to an integer value larger than `0`. Failure to do so will result in lack of redundancy (losing one node will corrupt the index). @@ -981,11 +981,11 @@ however searches will only surface results that can be viewed by the user. Advanced Search will honor all permission checks in the application by filtering out projects that a user does not have access to at search time. -### Access requirements for the self-managed AWS Elasticsearch Service +### Access requirements for the self-managed AWS OpenSearch Service -To use the self-managed AWS Elasticsearch Service with GitLab, configure your instance's domain access policies +To use the self-managed AWS OpenSearch Service with GitLab, configure your instance's domain access policies to contain the actions below. -See [Identity and Access Management in Amazon Elasticsearch Service](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-ac.html) for details. +See [Identity and Access Management in Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html) for details. ```plaintext es:ESHttpDelete diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index 1a3360aa470..b94fa24d290 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -81,9 +81,10 @@ Facebook. Facebook generates an app ID and secret key for you to use. ```ruby gitlab_rails['omniauth_providers'] = [ { - "name" => "facebook", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET" + name: "facebook", + # label: "Provider name", # optional label for login button, defaults to "Facebook" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET" } ] ``` @@ -91,7 +92,9 @@ Facebook. Facebook generates an app ID and secret key for you to use. For installations from source: ```yaml - - { name: 'facebook', app_id: 'YOUR_APP_ID', + - { name: 'facebook', + # label: 'Provider name', # optional label for login button, defaults to "Facebook" + app_id: 'YOUR_APP_ID', app_secret: 'YOUR_APP_SECRET' } ``` diff --git a/doc/integration/github.md b/doc/integration/github.md index 11a9a5ea64d..d8877e069b8 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -50,10 +50,11 @@ Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server: ```ruby gitlab_rails['omniauth_providers'] = [ { - "name" => "github", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET", - "args" => { "scope" => "user:email" } + name: "github", + # label: "Provider name", # optional label for login button, defaults to "GitHub" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET", + args: { scope: "user:email" } } ] ``` @@ -63,11 +64,12 @@ Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server: ```ruby gitlab_rails['omniauth_providers'] = [ { - "name" => "github", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET", - "url" => "https://github.example.com/", - "args" => { "scope" => "user:email" } + name: "github", + # label: "Provider name", # optional label for login button, defaults to "GitHub" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET", + url: "https://github.example.com/", + args: { scope: "user:email" } } ] ``` @@ -85,7 +87,9 @@ Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server: For GitHub.com: ```yaml - - { name: 'github', app_id: 'YOUR_APP_ID', + - { name: 'github', + # label: 'Provider name', # optional label for login button, defaults to "GitHub" + app_id: 'YOUR_APP_ID', app_secret: 'YOUR_APP_SECRET', args: { scope: 'user:email' } } ``` @@ -94,6 +98,7 @@ Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server: ```yaml - { name: 'github', + # label: 'Provider name', # optional label for login button, defaults to "GitHub" app_id: 'YOUR_APP_ID', app_secret: 'YOUR_APP_SECRET', url: "https://github.example.com/", @@ -122,12 +127,13 @@ For Omnibus package: ```ruby gitlab_rails['omniauth_providers'] = [ { - "name" => "github", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET", - "url" => "https://github.example.com/", - "verify_ssl" => false, - "args" => { "scope" => "user:email" } + name: "github", + # label: "Provider name", # optional label for login button, defaults to "GitHub" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET", + url: "https://github.example.com/", + verify_ssl: false, + args: { scope: "user:email" } } ] ``` @@ -142,6 +148,7 @@ For installation from source: ```yaml - { name: 'github', + # label: 'Provider name', # optional label for login button, defaults to "GitHub" app_id: 'YOUR_APP_ID', app_secret: 'YOUR_APP_SECRET', url: "https://github.example.com/", diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index b69147b3829..2dd357e50a6 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -53,10 +53,11 @@ GitLab.com generates an application ID and secret key for you to use. ```ruby gitlab_rails['omniauth_providers'] = [ { - "name" => "gitlab", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET", - "args" => { "scope" => "api" } + name: "gitlab", + # label: "Provider name", # optional label for login button, defaults to "GitLab.com" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET", + args: { scope: "api" } } ] ``` @@ -66,10 +67,11 @@ GitLab.com generates an application ID and secret key for you to use. ```ruby gitlab_rails['omniauth_providers'] = [ { - "name" => "gitlab", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET", - "args" => { "scope" => "api", "client_options" => { "site" => "https://gitlab.example.com/api/v4" } } + name: "gitlab", + label: "Provider name", # optional label for login button, defaults to "GitLab.com" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET", + args: { scope: "api", client_options: { site: "https://gitlab.example.com/api/v4" } } } ] ``` @@ -78,6 +80,7 @@ GitLab.com generates an application ID and secret key for you to use. ```yaml - { name: 'gitlab', + # label: 'Provider name', # optional label for login button, defaults to "GitLab.com" app_id: 'YOUR_APP_ID', app_secret: 'YOUR_APP_SECRET', args: { scope: 'api' } } @@ -87,6 +90,7 @@ GitLab.com generates an application ID and secret key for you to use. ```yaml - { name: 'gitlab', + label: 'Provider name', # optional label for login button, defaults to "GitLab.com" app_id: 'YOUR_APP_ID', app_secret: 'YOUR_APP_SECRET', args: { scope: 'api', "client_options": { "site": 'https://gitlab.example.com/api/v4' } } diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index 26520df18fa..977e794396e 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -5,7 +5,7 @@ group: Editor 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" --- -# Gitpod Integration **(FREE)** +# Gitpod integration **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228893) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/258206) in GitLab 13.8 @@ -38,7 +38,7 @@ With the Gitpod integration enabled for your GitLab instance, to enable it for y 1. In the top-right corner, select your avatar. 1. Select **Preferences**. 1. Under **Preferences**, locate the **Integrations** section. -1. Check the **Enable Gitpod integration** checkbox and select the **Save changes** button. +1. Select the **Enable Gitpod integration** checkbox and select **Save changes**. ## Configure a self-managed instance **(FREE SELF)** @@ -50,9 +50,9 @@ For GitLab self-managed instances, a GitLab administrator needs to: 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. Select the **Enable Gitpod integration** checkbox. 1. Add your Gitpod instance URL (for example, `https://gitpod.example.com`). - 1. Select the **Save changes** button. + 1. Select **Save changes**. Your users can then [enable it for themselves](#enable-gitpod-in-your-user-settings). diff --git a/doc/integration/google.md b/doc/integration/google.md index 5df76ebb3d1..d6a37dbf30f 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -79,10 +79,11 @@ On your GitLab server: ```ruby gitlab_rails['omniauth_providers'] = [ { - "name" => "google_oauth2", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET", - "args" => { "access_type" => "offline", "approval_prompt" => '' } + name: "google_oauth2", + # label: "Provider name", # optional label for login button, defaults to "Google" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET", + args: { access_type: "offline", approval_prompt: "" } } ] ``` @@ -91,6 +92,7 @@ On your GitLab server: ```yaml - { name: 'google_oauth2', + # label: 'Provider name', # optional label for login button, defaults to "Google" app_id: 'YOUR_APP_ID', app_secret: 'YOUR_APP_SECRET', args: { access_type: 'offline', approval_prompt: '' } } diff --git a/doc/integration/img/ding_talk_menu.png b/doc/integration/img/ding_talk_menu.png Binary files differindex 2c5a23435fa..fe020cab397 100644 --- a/doc/integration/img/ding_talk_menu.png +++ b/doc/integration/img/ding_talk_menu.png diff --git a/doc/integration/img/omniauth_providers_v_14_6.png b/doc/integration/img/omniauth_providers_v_14_6.png Binary files differnew file mode 100644 index 00000000000..b434e9a210b --- /dev/null +++ b/doc/integration/img/omniauth_providers_v_14_6.png diff --git a/doc/integration/index.md b/doc/integration/index.md index 0b2bf6fde94..61d8547aaf7 100644 --- a/doc/integration/index.md +++ b/doc/integration/index.md @@ -46,7 +46,7 @@ GitLab has integrated with several security partners. For more information, see ## Continuous integration -GitLab can be integrated with the following external service for continuous integration: +GitLab can be integrated with the following external services for continuous integration: - [Jenkins](jenkins.md) CI. - [Datadog](datadog.md), to monitor for CI/CD job failures and performance issues. diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 2bbda74533f..822530775e5 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -179,6 +179,17 @@ to integrate GitLab and Jenkins. ## Troubleshooting +### Error during GitLab configuration - "Connection failed. Please check your settings" + +If you get this error message while configuring GitLab, the following are possible causes: + +- GitLab is unable to reach your Jenkins instance at the address. If your GitLab instance is self-managed, try pinging the + Jenkins instance at the domain provided on the GitLab instance. +- The Jenkins instance is at a local address and is not included in the + [GitLab installation's allowlist](../security/webhooks.md#allowlist-for-local-requests). +- The credentials for the Jenkins instance do not have sufficient access or are invalid. +- The **Enable authentication for ‘/project’ end-point checkbox** is not selected in your [Jenkin's plugin configuration](#configure-the-jenkins-server). + ### Error in merge requests - "Could not connect to the CI server" This integration relies on Jenkins reporting the build status back to GitLab via diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index 27f482ee2ba..597293ae5ca 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -76,7 +76,7 @@ If the app requires additional permissions, [the update must first be manually a ## 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 -extra steps to install the GitLab.com for Jira Cloud app. +extra steps to install the GitLab.com for Jira Cloud app, and your GitLab instance must be accessible by Jira. Each Jira Cloud application must be installed from a single location. Jira fetches a [manifest file](https://developer.atlassian.com/cloud/jira/platform/connect-app-descriptor/) diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md index 2b7cc5ff0a6..e69b7675a59 100644 --- a/doc/integration/jira/dvcs.md +++ b/doc/integration/jira/dvcs.md @@ -265,3 +265,22 @@ resynchronize the information: For more information, read [Atlassian's documentation](https://support.atlassian.com/jira-cloud-administration/docs/synchronize-jira-cloud-to-bitbucket/). + +### `Sync Failed` error when refreshing repository data + +If you get a `Sync Failed` error in Jira when [refreshing repository data](#refresh-data-imported-to-jira) for specific projects, check your DVCS connector logs. Look for errors that occur when executing requests to API resources in GitLab. For example: + +```plaintext +Failed to execute request [https://gitlab.com/api/v4/projects/:id/merge_requests?page=1&per_page=100 GET https://gitlab.com/api/v4/projects/:id/merge_requests?page=1&per_page=100 returned a response status of 403 Forbidden] errors: +{"message":"403 Forbidden"} +``` + +If you find a `{"message":"403 Forbidden"}` error, it is possible that this specific project has some [GitLab features disabled](../../user/project/settings/index.md#sharing-and-permissions). +In the example above, the merge requests feature is disabled. + +To resolve the issue, enable the relevant feature: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Use the toggles to enable the features as needed. diff --git a/doc/integration/jira/img/open_jira_issues_list_v13.2.png b/doc/integration/jira/img/open_jira_issues_list_v13.2.png Binary files differdeleted file mode 100644 index 0cf58433b25..00000000000 --- a/doc/integration/jira/img/open_jira_issues_list_v13.2.png +++ /dev/null diff --git a/doc/integration/jira/img/open_jira_issues_list_v14_6.png b/doc/integration/jira/img/open_jira_issues_list_v14_6.png Binary files differnew file mode 100644 index 00000000000..6f06b7fec9a --- /dev/null +++ b/doc/integration/jira/img/open_jira_issues_list_v14_6.png diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md index 70e938a24d4..e24862242e1 100644 --- a/doc/integration/jira/issues.md +++ b/doc/integration/jira/issues.md @@ -101,10 +101,10 @@ Consider this example: You can browse, search, and view issues from a selected Jira project directly in GitLab, if your GitLab administrator [has configured it](configure.md). -To do this, in GitLab, go to your project and select **Jira > Issues list**. The issue list +To do this, in GitLab, go to your project and select **Issues > Jira issues**. The issue list sorts by **Created date** by default, with the newest issues listed at the top: -![Jira issues integration enabled](img/open_jira_issues_list_v13.2.png) +![Jira issues integration enabled](img/open_jira_issues_list_v14_6.png) - To display the most recently updated issues first, select **Last updated**. - You can [search and filter](#search-and-filter-the-issues-list) the issues list. @@ -140,7 +140,7 @@ Enhancements to use these filters through the user interface ## Automatic issue transitions -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/...) in GitLab 13.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55773) in GitLab 13.11. When you configure automatic issue transitions, you can transition a referenced Jira issue to the next available status with a category of **Done**. To configure diff --git a/doc/integration/mattermost/gitlab-mattermost.msc b/doc/integration/mattermost/gitlab-mattermost.msc deleted file mode 100644 index f6d4bf7aa68..00000000000 --- a/doc/integration/mattermost/gitlab-mattermost.msc +++ /dev/null @@ -1,28 +0,0 @@ -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 differdeleted file mode 100644 index c3b019988d0..00000000000 --- a/doc/integration/mattermost/img/gitlab-mattermost.png +++ /dev/null diff --git a/doc/integration/mattermost/index.md b/doc/integration/mattermost/index.md index 0489ccd431c..97da971dd75 100644 --- a/doc/integration/mattermost/index.md +++ b/doc/integration/mattermost/index.md @@ -18,8 +18,8 @@ Each release of GitLab Mattermost is compiled and manually tested on an AMD 64 c ## 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 +GitLab Mattermost expects to run on its own virtual host. In your DNS settings, you need +two entries pointing to the same machine. For example, `gitlab.example.com` and `mattermost.example.com`. GitLab Mattermost is disabled by default. To enable it: @@ -41,7 +41,7 @@ GitLab Mattermost is disabled by default. To enable it: 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). +you 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 @@ -51,7 +51,7 @@ Mattermost settings and where they can be set is available [in the Mattermost do 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. +1. Specify environment variables used to run Mattermost by changing the `mattermost['env']` setting in `gitlab.rb`. Any settings configured in this way are disabled from the System Console and cannot be changed without restarting Mattermost. ## Running GitLab Mattermost with HTTPS @@ -71,7 +71,7 @@ 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 +and `mattermost.gitlab.example.key` then you need to also add the full paths as shown below. ```ruby @@ -85,7 +85,7 @@ Once the configuration is set, run `sudo gitlab-ctl reconfigure` to apply the ch ## 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 +If you want to run GitLab and GitLab Mattermost on two separate servers the GitLab services are still set up on your GitLab Mattermost server, but they do 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 @@ -124,7 +124,7 @@ 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. +Once the application is created you are 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 @@ -190,7 +190,7 @@ sudo -i -u gitlab-psql -- /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/po #### 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: +Mattermost has a `data` directory and `config.json` file that 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 @@ -339,6 +339,11 @@ Below is a list of Mattermost versions for GitLab 11.10 and later: | 14.2 | 5.37 | | 14.3 | 5.38 | | 14.4 | 5.39 | +| 14.5 | 5.39 | +| 14.6 | 6.1 | + +- GitLab 14.5 remained on Mattermost 5.39 +- GitLab 14.6 updates to Mattermost 6.1 instead of 6.0 NOTE: When upgrading the Mattermost version, it is essential to check the @@ -346,8 +351,8 @@ When upgrading the Mattermost version, it is essential to check the 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`.) +GitLab, the update process can only be used if Mattermost configuration settings have not been changed outside of GitLab. That is, no changes to Mattermost's `config.json` +file have been made - either directly or via the Mattermost **System Console**, which saves 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. @@ -364,6 +369,21 @@ If this is not the case, there are two options: 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 to 14.6 + +GitLab 14.6 includes Mattermost 6.1, and also includes the migrations for Mattermost 6.0. For information about upgrading and for ways to reduce the downtime of those migrations, read the [Important Upgrade Notes](https://docs.mattermost.com/administration/important-upgrade-notes.html) for both versions. + +NOTE: +The Mattermost upgrade notes refer to different impacts when used with a PostgreSQL versus a MySQL database. The GitLab Mattermost included with the GitLab Linux packages uses a PostgreSQL database. + +If you need to connect in the database to perform any manual migrations, run the following: + +```console +sudo gitlab-psql -d mattermost_production +``` + +You can then run the necessary queries that are described in the [Important Upgrade Notes](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. @@ -476,7 +496,27 @@ 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: -![sequence diagram](img/gitlab-mattermost.png) +```mermaid +sequenceDiagram + User->>Mattermost: GET https://mm.domain.com + Note over Mattermost, GitLab: Obtain access code + Mattermost->>GitLab: GET https://gitlab.domain.com/oauth/authorize + Note over User, GitLab: GitLab user signs in (if necessary) + Note over GitLab: GitLab verifies client_id matches an OAuth application + GitLab->>User: GitLab asks user to authorize Mattermost OAuth app + User->>GitLab: User selects 'Allow' + Note over GitLab: GitLab verifies redirect_uri matches list of valid URLs + GitLab->>User: 302 redirect: https://mm.domain.com/signup/gitlab/complete + User->>Mattermost: GET https://mm.domain.com/signup/gitlab/complete + Note over Mattermost, GitLab: Exchange access code for access token + Mattermost->>GitLab: POST http://gitlab.domain.com/oauth/token + GitLab->>GitLab: Doorkeeper::TokensController#35;create + GitLab->>Mattermost: Access token + Note over Mattermost, GitLab: Mattermost looks up GitLab user + Mattermost->>GitLab: GET https://gitlab.domain.com/api/v4/user + GitLab->>Mattermost: User details + Mattermost->>User: Mattermost/GitLab user ready +``` ## Troubleshooting the Mattermost CLI diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index cdc7e6db61c..3d44da8b4c8 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -4,31 +4,39 @@ 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 --- -# Sign into GitLab with (almost) any OAuth2 provider **(FREE SELF)** +# Generic OAuth2 provider **(FREE SELF)** -The `omniauth-oauth2-generic` gem allows Single Sign-On between GitLab and your own OAuth2 provider -(or any OAuth2 provider compatible with this gem) +The `omniauth-oauth2-generic` gem allows single sign-on (SSO) between GitLab +and your OAuth2 provider (or any OAuth2 provider compatible with this gem). -This strategy is designed to allow configuration of the simple OmniAuth SSO process outlined below: +This strategy allows for the configuration of this OmniAuth SSO process: -1. Strategy directs client to your authorization URL (**configurable**), with specified ID and key -1. OAuth provider handles authentication of request, user, and (optionally) authorization to access user's profile -1. OAuth provider directs client back to GitLab where Strategy handles retrieval of access token -1. Strategy requests user information from a **configurable** "user profile" URL (using the access token) -1. Strategy parses user information from the response, using a **configurable** format -1. GitLab finds or creates the returned user and logs them in +1. Strategy directs the client to your authorization URL (**configurable**), with + the specified ID and key. +1. The OAuth2 provider handles authentication of the request, user, and (optionally) + authorization to access user's profile. +1. The OAuth2 provider directs the client back to GitLab where Strategy handles + the retrieval of the access token. +1. Strategy requests user information from a **configurable** "user profile" + URL (using the access token). +1. Strategy parses user information from the response, using a **configurable** + format. +1. GitLab finds or creates the returned user and signs them in. -## Limitations of this Strategy +## Limitations of this strategy -- It can only be used for Single Sign on, and doesn't provide any other access granted by any OAuth provider - (importing projects or users, etc) -- It only supports the Authorization Grant flow (most common for client-server applications, like GitLab) -- It is not able to fetch user information from more than one URL -- It has not been tested with user information formats other than JSON +- It can only be used for single sign-on, and doesn't provide any other access + granted by any OAuth2 provider (like importing projects or users). +- It supports only the Authorization Grant flow (most common for client-server + applications, like GitLab). +- It can't fetch user information from more than one URL. +- It hasn't been tested with user information formats, other than JSON. -## Configuration Instructions +## Configure the OAuth2 provider -1. Register your application in the OAuth2 provider you wish to authenticate with. +To configure the provider: + +1. Register your application in the OAuth2 provider you want to authenticate with. The redirect URI you provide when registering the application should be: @@ -36,13 +44,13 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc http://your-gitlab.host.com/users/auth/oauth2_generic/callback ``` -1. You should now be able to get a Client ID and Client Secret. - Where this shows up differs for each provider. - This may also be called Application ID and Secret + You should now be able to get a Client ID and Client Secret. Where this + appears differs for each provider. This may also be called Application ID + and Secret. -1. On your GitLab server, open the configuration file. +1. On your GitLab server, open the appropriate configuration file. - For Omnibus package: + For Omnibus GitLab: ```shell sudo editor /etc/gitlab/gitlab.rb @@ -55,36 +63,37 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc sudo -u git -H editor config/gitlab.yml ``` -1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings +1. See [Configure initial settings](omniauth.md#configure-initial-settings) for + initial settings. -1. Add the provider-specific configuration for your provider, for example: +1. Add the provider-specific configuration for your provider. For example: ```ruby gitlab_rails['omniauth_providers'] = [ - { 'name' => 'oauth2_generic', - 'label' => '<your_oauth2_label>', - 'app_id' => '<your_app_client_id>', - 'app_secret' => '<your_app_client_secret>', - 'args' => { + { + name: "oauth2_generic", + label: "Provider name", # optional label for login button, defaults to "Oauth2 Generic" + app_id: "<your_app_client_id>", + app_secret: "<your_app_client_secret>", + args: { client_options: { - 'site' => '<your_auth_server_url>', - 'user_info_url' => '/oauth2/v1/userinfo', - 'authorize_url' => '/oauth2/v1/authorize', - 'token_url' => '/oauth2/v1/token' - }, - user_response_structure: { - root_path: [], - id_path: ['sub'], - attributes: { - email: 'email', - name: 'name' - } - }, - authorize_params: { - scope: 'openid profile email' - }, - strategy_class: "OmniAuth::Strategies::OAuth2Generic" - } + site: "<your_auth_server_url>", + user_info_url: "/oauth2/v1/userinfo", + authorize_url: "/oauth2/v1/authorize", + token_url: "/oauth2/v1/token" + }, + user_response_structure: { + root_path: [], + id_path: ["sub"], + attributes: { + email: "email", + name: "name" + } + }, + authorize_params: { + scope: "openid profile email" + }, + strategy_class: "OmniAuth::Strategies::OAuth2Generic" } } ] @@ -92,11 +101,13 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc For more information about these settings, see [the gem's README](https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example). -1. Save the configuration file +1. Save the configuration file. -1. Restart GitLab for the changes to take effect +1. [Restart](../administration/restart_gitlab.md#installations-from-source) + GitLab for the changes to take effect. -On the sign in page there should now be a new button below the regular sign in form. -Click the button to begin your provider's authentication process. This directs -the browser to your OAuth2 Provider's authentication page. If everything goes well -the user is returned to your GitLab instance and is signed in. +On the sign-in page there should now be a new button below the regular sign-in +form. Select the button to begin your provider's authentication process. This +directs the browser to your OAuth2 provider's authentication page. If +everything goes well, you are returned to your GitLab instance and are +signed in. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 5e96a1e7c65..dd51d823109 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -10,6 +10,8 @@ Users can sign in to GitLab by using their credentials from Twitter, GitHub, and [OmniAuth](https://rubygems.org/gems/omniauth/) is the Rack framework that GitLab uses to provide this authentication. +![OmniAuth providers on sign-in page](img/omniauth_providers_v_14_6.png) + If you configure OmniAuth, users can continue to sign in using other mechanisms, including standard GitLab authentication or LDAP (if configured). @@ -28,7 +30,7 @@ GitLab supports the following OmniAuth providers. | [Azure v1](azure.md) | `azure_oauth2` | | [Bitbucket Cloud](bitbucket.md) | `bitbucket` | | [CAS](cas.md) | `cas3` | -| [DingTalk](ding_talk.md) | `ding_talk` | +| [DingTalk](ding_talk.md) | `dingtalk` | | [Facebook](facebook.md) | `facebook` | | [Generic OAuth 2.0](oauth2_generic.md) | `oauth2_generic` | | [GitHub](github.md) | `github` | @@ -113,6 +115,12 @@ To change these settings: After configuring these settings, you can configure your chosen [provider](#supported-providers). +### Passwords for users created via OmniAuth + +The [Generated passwords for users created through integrated authentication](../security/passwords_for_integrated_authentication_methods.md) +guide provides an overview about how GitLab generates and sets passwords for +users created with OmniAuth. + ## Enable OmniAuth for an existing user If you're an existing user, after your GitLab account is @@ -129,6 +137,41 @@ provider like Twitter. You can now use your chosen OmniAuth provider to sign in to GitLab. +## Enable or disable sign-in with an OmniAuth provider without disabling import sources + +Administrators can enable or disable sign-in for some OmniAuth providers. + +NOTE: +By default, sign-in is enabled for all the OAuth providers configured in `config/gitlab.yml`. + +To enable or disable an OmniAuth provider: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings**. +1. Expand **Sign-in restrictions**. +1. In the **Enabled OAuth authentication sources** section, select or clear the checkbox for each provider you want to enable or disable. + +## Disable OmniAuth + +In GitLab 11.4 and later, OmniAuth is enabled by default. However, OmniAuth only works +if providers are configured and [enabled](#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources). + +If OmniAuth providers are causing problems even when individually disabled, you +can disable the entire OmniAuth subsystem by modifying the configuration file: + +- **For Omnibus installations** + + ```ruby + gitlab_rails['omniauth_enabled'] = false + ``` + +- **For installations from source** + + ```yaml + omniauth: + enabled: false + ``` + ## Link existing users to OmniAuth users > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36664) in GitLab 13.4. @@ -228,41 +271,6 @@ let us know. We can't officially support every possible authentication mechanism available, but we'd like to at least help those with specific needs. -## Enable or disable sign-in with an OmniAuth provider without disabling import sources - -Administrators can enable or disable sign-in for some OmniAuth providers. - -NOTE: -By default, sign-in is enabled for all the OAuth providers configured in `config/gitlab.yml`. - -To enable or disable an OmniAuth provider: - -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings**. -1. Expand **Sign-in restrictions**. -1. In the **Enabled OAuth authentication sources** section, select or clear the checkbox for each provider you want to enable or disable. - -## Disable OmniAuth - -In GitLab 11.4 and later, OmniAuth is enabled by default. However, OmniAuth only works -if providers are configured and [enabled](#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources). - -If OmniAuth providers are causing problems even when individually disabled, you -can disable the entire OmniAuth subsystem by modifying the configuration file: - -- **For Omnibus installations** - - ```ruby - gitlab_rails['omniauth_enabled'] = false - ``` - -- **For installations from source**: - - ```yaml - omniauth: - enabled: false - ``` - ## Keep OmniAuth user profiles up to date You can enable profile syncing from selected OmniAuth providers. You can sync @@ -344,12 +352,6 @@ one of the OmniAuth users is an administrator. You can also bypass automatic sign-in by browsing to `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. -## Passwords for users created via OmniAuth - -The [Generated passwords for users created through integrated authentication](../security/passwords_for_integrated_authentication_methods.md) -guide provides an overview about how GitLab generates and sets passwords for -users created with OmniAuth. - ## Use a custom OmniAuth provider icon Most supported providers include a built-in icon for the rendered sign-in button. @@ -359,7 +361,7 @@ then override the 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 + 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 diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index dd65fb4822a..54d4a5b6bb7 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -33,6 +33,14 @@ Refer to the [OAuth guide](oauth_provider.md) for basic information on how to se applications in GitLab. To enable OIDC for an application, all you have to do is select the `openid` scope in the application settings. +## Settings discovery + +If your client allows importing OIDC settings from a discovery URL, you can use the following URL to automatically find the correct settings: + +```plaintext +https://gitlab.example.com/.well-known/openid-configuration +``` + ## Shared information The following user information is shared with clients: @@ -51,5 +59,8 @@ The following user information is shared with clients: | `picture` | `string` | URL for the user's GitLab avatar | `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. +| `https://gitlab.org/claims/groups/owner` | `array` | Names of the groups the user is a direct member of with Owner role +| `https://gitlab.org/claims/groups/maintainer` | `array` | Names of the groups the user is a direct member of with Maintainer role +| `https://gitlab.org/claims/groups/developer` | `array` | Names of the groups the user is a direct member of with Developer role 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 60e2d70ce32..4963dea19a4 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -12,20 +12,21 @@ to confirm that a real user, not a bot, is attempting to create an account. ## Configuration -To use reCAPTCHA, first you must create a site and private key. +To use reCAPTCHA, first create a site and private key. 1. Go to the [Google reCAPTCHA page](https://www.google.com/recaptcha/admin). -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. To get reCAPTCHA v2 keys, fill in the form and select **Submit**. +1. Sign in to your GitLab server as an administrator. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Reporting** (`admin/application_settings/reporting`). +1. Expand **Spam and Anti-bot Protection**. +1. In the reCAPTCHA fields, enter the keys you obtained in the previous steps. 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 CONDITIONAL_ALLOW` so that the spam check short-circuits and triggers the response to - return `recaptcha_html`. +1. Select **Save changes**. +1. To short-circuit the spam check and trigger the response to return `recaptcha_html`: + 1. Open `app/services/spam/spam_verdict_service.rb`. + 1. Change the first line of the `#execute` method to `return CONDITIONAL_ALLOW`. 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. diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 68daced3521..ebd936424d3 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -57,9 +57,10 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create ```ruby gitlab_rails['omniauth_providers'] = [ { - "name" => "salesforce", - "app_id" => "SALESFORCE_CLIENT_ID", - "app_secret" => "SALESFORCE_CLIENT_SECRET" + name: "salesforce", + # label: "Provider name", # optional label for login button, defaults to "Salesforce" + app_id: "SALESFORCE_CLIENT_ID", + app_secret: "SALESFORCE_CLIENT_SECRET" } ] ``` @@ -68,6 +69,7 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create ```yaml - { name: 'salesforce', + # label: 'Provider name', # optional label for login button, defaults to "Salesforce" app_id: 'SALESFORCE_CLIENT_ID', app_secret: 'SALESFORCE_CLIENT_SECRET' } diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 47a35cf21a8..70d6932b9eb 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -98,15 +98,15 @@ as described in the section on [Security](#security). Otherwise, your users are ```ruby gitlab_rails['omniauth_providers'] = [ { - name: 'saml', + name: "saml", + label: "Provider name", # optional label for login button, defaults to "Saml" args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' - }, - label: 'Provider name' # optional label for SAML login button, defaults to "Saml" + assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback", + idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8", + idp_sso_target_url: "https://login.example.com/idp", + issuer: "https://gitlab.example.com", + name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" + } } ] ``` @@ -118,14 +118,14 @@ as described in the section on [Security](#security). Otherwise, your users are providers: - { name: 'saml', + label: 'Provider name', # optional label for login button, defaults to "Saml" args: { assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', idp_sso_target_url: 'https://login.example.com/idp', issuer: 'https://gitlab.example.com', name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' - }, - label: 'Company Login' # optional label for SAML login button, defaults to "Saml" + } } ``` @@ -163,6 +163,74 @@ On the sign in page there should now be a SAML button below the regular sign in Click the icon to begin the authentication process. If everything goes well the user is returned to GitLab and signed in. +### Use multiple SAML identity providers + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14361) in GitLab 14.6. + +You can configure GitLab to use multiple SAML identity providers if: + +- Each provider has a unique name set that matches a name set in `args`. +- The providers' names are: + - Used in OmniAuth configuration for properties based on the provider name. For example, `allowBypassTwoFactor`, `allowSingleSignOn`, and + `syncProfileFromProvider`. + - Used for association to each existing user as an additional identity. +- The `assertion_consumer_service_url` matches the provider name. +- The `strategy_class` is explicitly set because it cannot be inferred from provider name. + +Example multiple providers configuration for Omnibus GitLab: + +```ruby +gitlab_rails['omniauth_providers'] = [ + { + name: 'saml_1', + args: { + name: 'saml_1', # This is mandatory and must match the provider name + strategy_class: 'OmniAuth::Strategies::SAML' + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_1/callback', # URL must match the name of the provider + ... # Put here all the required arguments similar to a single provider + }, + label: 'Provider 1' # Differentiate the two buttons and providers in the UI + }, + { + name: 'saml_2', + args: { + name: 'saml_2', # This is mandatory and must match the provider name + strategy_class: 'OmniAuth::Strategies::SAML' + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider + ... # Put here all the required arguments similar to a single provider + }, + label: 'Provider 2' # Differentiate the two buttons and providers in the UI + } +] +``` + +Example providers configuration for installations from source: + +```yaml +omniauth: + providers: + - { + name: 'saml_1', + args: { + name: 'saml_1', # This is mandatory and must match the provider name + strategy_class: 'OmniAuth::Strategies::SAML', + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_1/callback', # URL must match the name of the provider + ... # Put here all the required arguments similar to a single provider + }, + label: 'Provider 1' # Differentiate the two buttons and providers in the UI + } + - { + name: 'saml_2', + args: { + name: 'saml_2', # This is mandatory and must match the provider name + strategy_class: 'OmniAuth::Strategies::SAML', + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider + ... # Put here all the required arguments similar to a single provider + }, + label: 'Provider 2' # Differentiate the two buttons and providers in the UI + } +``` + ### Notes on configuring your identity provider When configuring a SAML app on the IdP, you need at least: @@ -362,22 +430,21 @@ In addition to the changes in GitLab, make sure that your IdP is returning the ```ruby gitlab_rails['omniauth_providers'] = [ { - name: 'saml', + name: "saml", args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - upstream_two_factor_authn_contexts: - %w( - urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport - urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS - urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN - ) - - }, - label: 'Company Login' # optional label for SAML login button, defaults to "Saml" + assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback", + idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8", + idp_sso_target_url: "https://login.example.com/idp", + issuer: "https://gitlab.example.com", + name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent", + upstream_two_factor_authn_contexts: + %w( + urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport + urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS + urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN + ) + }, + label: "Company Login" # optional label for SAML login button, defaults to "Saml" } ] ``` diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index 50ef04681f0..e1f67df76c3 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -62,9 +62,10 @@ Twitter. Twitter generates a client ID and secret key for you to use. ```ruby gitlab_rails['omniauth_providers'] = [ { - "name" => "twitter", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET" + name: "twitter", + # label: "Provider name", # optional label for login button, defaults to "Twitter" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET" } ] ``` @@ -73,6 +74,7 @@ Twitter. Twitter generates a client ID and secret key for you to use. ```yaml - { name: 'twitter', + # label: 'Provider name', # optional label for login button, defaults to "Twitter" app_id: 'YOUR_APP_ID', app_secret: 'YOUR_APP_SECRET' } ``` diff --git a/doc/integration/vault.md b/doc/integration/vault.md index 3bca3767785..9e738f8493d 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Configure +group: Configure 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 --- |