diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-18 10:34:06 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-18 10:34:06 +0000 |
| commit | 859a6fb938bb9ee2a317c46dfa4fcc1af49608f0 (patch) | |
| tree | d7f2700abe6b4ffcb2dcfc80631b2d87d0609239 /doc/integration | |
| parent | 446d496a6d000c73a304be52587cd9bbc7493136 (diff) | |
| download | gitlab-ce-859a6fb938bb9ee2a317c46dfa4fcc1af49608f0.tar.gz | |
Add latest changes from gitlab-org/gitlab@13-9-stable-eev13.9.0-rc42
Diffstat (limited to 'doc/integration')
39 files changed, 580 insertions, 498 deletions
diff --git a/doc/integration/README.md b/doc/integration/README.md index 227e2eec53c..7d38dd6222a 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -25,7 +25,7 @@ GitLab can be configured to authenticate access requests with the following auth - Enable sign in via [LDAP](../administration/auth/ldap/index.md). - Enable [OAuth2 provider](oauth_provider.md) application creation. - Use [OmniAuth](omniauth.md) to enable sign in via Twitter, GitHub, GitLab.com, Google, - Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure or Authentiq ID. + Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure, or Authentiq ID. - Use GitLab as an [OpenID Connect](openid_connect_provider.md) identity provider. - Authenticate to [Vault](vault.md) through GitLab OpenID Connect. - Configure GitLab as a [SAML](saml.md) 2.0 Service Provider. @@ -39,6 +39,11 @@ GitLab can be integrated with the following external services to enhance securit GitLab also provides features to improve the security of your own application. For more details see [GitLab Secure](../user/application_security/index.md). +## Security partners + +GitLab has integrated with several security partners. For more information, see +[Security partners integration](security_partners/index.md). + ## Continuous integration GitLab can be integrated with the following external service for continuous integration: @@ -65,7 +70,9 @@ Integration with services such as Campfire, Flowdock, HipChat, Pivotal Tracker, ### SSL certificate errors -When trying to integrate GitLab with services that are using self-signed certificates, it is very likely that SSL certificate errors occur in different parts of the application, most likely Sidekiq. +When trying to integrate GitLab with services using self-signed certificates, +SSL certificate errors can occur in different parts of the application. Sidekiq +is a common culprit. There are two approaches you can take to solve this: diff --git a/doc/integration/azure.md b/doc/integration/azure.md index f22a94a01c7..c83ef650f54 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -6,6 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Microsoft Azure OAuth2 OmniAuth Provider +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 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. Sign in to the [Azure Portal](https://portal.azure.com), and follow the instructions in diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index 4bc9d39ae3f..8999f4da9a2 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 so that you can use your -Bitbucket.org account credentials to sign into GitLab or import your projects from +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 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 5a198e85f5c..b444143b03e 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # CAS OmniAuth Provider -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 backchannel 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`. By default handling for SLO is enabled, you only need to configure CAS for back-channel logout. 1. On your GitLab server, open the configuration file. @@ -57,7 +57,7 @@ To enable the CAS OmniAuth provider you must register your application with your logout_url: '/CAS_PATH/logout' } } ``` -1. Change 'CAS_PATH' to the root of your CAS instance (ie. `cas`). +1. Change 'CAS_PATH' to the root of your CAS instance (such as `cas`). 1. If your CAS instance does not use default TGC lifetimes, update the `cas3.session_duration` to at least the current TGC maximum lifetime. To explicitly disable SLO, regardless of CAS settings, set this to 0. diff --git a/doc/integration/chat_commands.md b/doc/integration/chat_commands.md deleted file mode 100644 index a0361064d87..00000000000 --- a/doc/integration/chat_commands.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'slash_commands.md' ---- - -This document was moved to [integration/slash_commands.md](slash_commands.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/crowd.md b/doc/integration/crowd.md deleted file mode 100644 index e07e3435baf..00000000000 --- a/doc/integration/crowd.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../administration/auth/crowd.md' ---- - -This document was moved to [`administration/auth/crowd`](../administration/auth/crowd.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index b1fc2573bb0..389c7aabdf5 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -5,10 +5,9 @@ group: Global Search 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 --- -# Elasticsearch integration **(STARTER ONLY)** +# Elasticsearch integration **(PREMIUM SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109 "Elasticsearch Merge Request") in GitLab [Starter](https://about.gitlab.com/pricing/) 8.4. -> - Support for [Amazon Elasticsearch](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-gsg.html) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1305) in GitLab [Starter](https://about.gitlab.com/pricing/) 9.0. +> 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 @@ -87,7 +86,7 @@ updated automatically. 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. -The only thing worth noting is that if you have created your current index before GitLab 13.0, you might want to [reclaim the production index name](#reclaiming-the-gitlab-production-index-name) or reindex from scratch (which will implicitly create an alias). The latter might be faster depending on the GitLab instance size. Once you do that, you'll be able to perform zero-downtime reindexing and you will benefit from any future features that will make use of the alias. +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 will implicitly create an alias) in order to use some features, for example [Zero downtime reindexing](#zero-downtime-reindexing). Once you do that, you'll be able to perform zero-downtime reindexing and will benefit from any future features that make use of the alias. ## Elasticsearch repository indexer @@ -152,7 +151,7 @@ cd $indexer_path && sudo make install The `gitlab-elasticsearch-indexer` will be installed to `/usr/local/bin`. -You can change the installation path with the `PREFIX` env variable. +You can change the installation path with the `PREFIX` environment variable. Please remember to pass the `-E` flag to `sudo` if you do so. Example: @@ -175,18 +174,17 @@ instances](#indexing-large-instances) below. To enable Advanced Search, you need to have admin access to GitLab: -1. Navigate to **Admin Area**, then **Settings > General** - and expand the **Advanced Search** section. +1. Navigate to **Admin Area**, then **Settings > Advanced Search**. NOTE: - To see the Advanced Search section, you need an active Starter + To see the Advanced Search section, you need an active GitLab Premium [license](../user/admin_area/license.md). 1. Configure the [Advanced Search settings](#advanced-search-configuration) for your Elasticsearch cluster. Do not enable **Search with Elasticsearch enabled** yet. 1. Now enable **Elasticsearch indexing** in **Admin Area > Settings > - General > Advanced Search** and click **Save changes**. This will create + Advanced Search** and click **Save changes**. This will create an empty index if one does not already exist. 1. Click **Index all projects**. 1. Click **Check progress** in the confirmation message to see the status of @@ -202,7 +200,7 @@ To enable Advanced Search, you need to have admin access to GitLab: ``` 1. After the indexing has completed, enable **Search with Elasticsearch enabled** in - **Admin Area > Settings > General > Advanced Search** and click **Save + **Admin Area > Settings > Advanced Search** and click **Save changes**. NOTE: @@ -218,7 +216,7 @@ The following Elasticsearch settings are available: | Parameter | Description | |-------------------------------------------------------|-------------| | `Elasticsearch indexing` | Enables or disables Elasticsearch indexing and creates an empty index if one does not already exist. You may want to enable indexing but disable search in order to give the index time to be fully completed, for example. Also, keep in mind that this option doesn't have any impact on existing data, this only enables/disables the background indexer which tracks data changes and ensures new data is indexed. | -| `Pause Elasticsearch indexing` | Enables or disables temporary indexing pause. This is useful for cluster migration/reindexing. All changes are still tracked, but they are not committed to the Elasticsearch index until unpaused. | +| `Pause Elasticsearch indexing` | Enables or disables temporary indexing pause. This is useful for cluster migration/reindexing. All changes are still tracked, but they are not committed to the Elasticsearch index until resumed. | | `Search with Elasticsearch enabled` | Enables or disables using Elasticsearch in search. | | `URL` | The URL to use for connecting to Elasticsearch. Use a comma-separated list to support clustering (e.g., `http://host1, https://host2:9200`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). | | `Number of Elasticsearch shards` | Elasticsearch indexes are split into multiple shards for performance reasons. In general, larger indexes need to have more shards. 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). | @@ -241,7 +239,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 will include -any sub-groups and projects belonging to those sub-groups to be indexed as well. +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. @@ -260,13 +258,13 @@ from the Elasticsearch index as expected. ## Enabling 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. +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. Navigate to the **Admin Area**, then **Settings > General**.. -1. Expand the **Advanced Search** section and locate **Custom analyzers: language support**. +1. Navigate to the **Admin Area**, then **Settings > Advanced Search**.. +1. Locate **Custom analyzers: language support**. 1. Enable plugin(s) support for **Indexing**. 1. Click **Save changes** for the changes to take effect. 1. Trigger [Zero downtime reindexing](#zero-downtime-reindexing) or reindex everything from scratch to create a new index with updated mappings. @@ -276,18 +274,17 @@ For guidance on what to install, see the following Elasticsearch language plugin | Parameter | Description | |-------------------------------------------------------|-------------| -| `Enable Chinese (smartcn) custom analyzer: Indexing` | Enables or disables Chinese language support using [smartcn](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) custom analyzer for newly created indices.| -| `Enable Chinese (smartcn) custom analyzer: Search` | Enables or disables using [smartcn](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) fields for Advanced Search. Please only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html), enabling custom analyzer indexing and recreating the index.| -| `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.| +| `Enable Chinese (smartcn) custom analyzer: Indexing` | Enables or disables Chinese language support using [`smartcn`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) custom analyzer for newly created indices.| +| `Enable Chinese (smartcn) custom analyzer: Search` | Enables or disables using [`smartcn`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) fields for Advanced Search. Please only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html), enabling custom analyzer indexing and recreating the index.| +| `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 To disable the Elasticsearch integration: -1. Navigate to the **Admin Area**, then **Settings > General**. -1. Expand the **Advanced Search** section and uncheck **Elasticsearch indexing** - and **Search with Elasticsearch enabled**. +1. Navigate to the **Admin Area**, then **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: @@ -301,146 +298,19 @@ To disable the Elasticsearch integration: ## Zero downtime reindexing -The idea behind this reindexing method is to leverage Elasticsearch index alias -feature to atomically swap between two indices. We'll refer to each index as -`primary` (online and used by GitLab for read/writes) and `secondary` -(offline, for reindexing purpose). - -Instead of connecting directly to the `primary` index, we'll setup an index -alias such as we can change the underlying index at will. - -NOTE: -Any index attached to the production alias is deemed a `primary` and will be -used by the GitLab Advanced Search integration. - -### Pause the indexing - -In the **Admin Area > Settings > General > Advanced Search** section, select the -**Pause Elasticsearch Indexing** setting, and then save your change. -With this, all updates that should happen on your Elasticsearch index will be -buffered and caught up once unpaused. - -The indexing will also be automatically paused when the [**Trigger cluster reindexing**](#trigger-the-reindex-via-the-advanced-search-administration) button is used, and unpaused when the reindexing completes or aborts. - -### Setup - -NOTE: -If your index was created with GitLab 13.0 or greater, you can directly -[trigger the reindex](#trigger-the-reindex-via-the-advanced-search-administration). - -This process involves several shell commands and curl invocations, so a good -initial setup will help for later: - -```shell -# You can find this value under Admin Area > Settings > General > Advanced Search > URL -export CLUSTER_URL="http://localhost:9200" -export PRIMARY_INDEX="gitlab-production" -export SECONDARY_INDEX="gitlab-production-$(date +%s)" -``` - -### Reclaiming the `gitlab-production` index name - -WARNING: -It is highly recommended that you take a snapshot of your cluster to ensure -there is a recovery path if anything goes wrong. - -Due to a technical limitation, there will be a slight downtime because of the -fact that we need to reclaim the current `primary` index to be used as the alias. - -To reclaim the `gitlab-production` index name, you need to first create a `secondary` index and then trigger the re-index from `primary`. - -#### Creating a secondary index - -To create a secondary index, run the following Rake task. The `SKIP_ALIAS` -environment variable will disable the automatic creation of the Elasticsearch -alias, which would conflict with the existing index under `$PRIMARY_INDEX`, and will -not create a separate Issue index: - -```shell -# Omnibus installation -sudo SKIP_ALIAS=1 gitlab-rake "gitlab:elastic:create_empty_index[$SECONDARY_INDEX]" - -# Source installation -SKIP_ALIAS=1 bundle exec rake "gitlab:elastic:create_empty_index[$SECONDARY_INDEX]" -``` - -The index should be created successfully, with the latest index options and -mappings. - -#### Trigger the re-index from `primary` - -To trigger the re-index from `primary` index: - -1. Use the Elasticsearch [Reindex API](https://www.elastic.co/guide/en/elasticsearch/reference/7.6/docs-reindex.html): - - ```shell - curl --request POST \ - --header 'Content-Type: application/json' \ - --data "{ \"source\": { \"index\": \"$PRIMARY_INDEX\" }, \"dest\": { \"index\": \"$SECONDARY_INDEX\" } }" \ - "$CLUSTER_URL/_reindex?slices=auto&wait_for_completion=false" - ``` - - There will be an output like: - - ```plaintext - {"task":"3qw_Tr0YQLq7PF16Xek8YA:1012"} - ``` - - Note the `task` value, as it will be useful to follow the reindex progress. - -1. Wait for the reindex process to complete by checking the `completed` value. - Using the `task` value form the previous step: - - ```shell - export TASK_ID=3qw_Tr0YQLq7PF16Xek8YA:1012 - curl "$CLUSTER_URL/_tasks/$TASK_ID?pretty" - ``` - - The output will be like: - - ```plaintext - {"completed":false, …} - ``` - - After the returned value is `true`, continue to the next step. - -1. Ensure that the secondary index has data in it. You can use the - Elasticsearch API to look for the index size and compare our two indices: - - ```shell - curl $CLUSTER_URL/$PRIMARY_INDEX/_count => 123123 - curl $CLUSTER_URL/$SECONDARY_INDEX/_count => 123123 - ``` - - NOTE: - Comparing the document count is more accurate than using the index size, as improvements to the storage might cause the new index to be smaller than the original one. - -1. After you are confident your `secondary` index is valid, you can process to - the creation of the alias. - - ```shell - # Delete the original index - curl --request DELETE $CLUSTER_URL/$PRIMARY_INDEX - - # Create the alias and add the `secondary` index to it - curl --request POST \ - --header 'Content-Type: application/json' \ - --data "{\"actions\":[{\"add\":{\"index\":\"$SECONDARY_INDEX\",\"alias\":\"$PRIMARY_INDEX\"}}]}}" \ - $CLUSTER_URL/_aliases - ``` - - The reindexing is now completed. Your GitLab instance is now ready to use the [automated in-cluster reindexing](#trigger-the-reindex-via-the-advanced-search-administration) feature for future reindexing. - -1. Unpause the indexing - - Under **Admin Area > Settings > General > Advanced Search**, uncheck the **Pause Elasticsearch Indexing** setting and save. +The idea behind this reindexing method is to leverage the [Elasticsearch reindex API](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html) +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 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 -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34069) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. -> - A scheduled index deletion and the ability to cancel it was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38914) in GitLab Starter 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34069) in GitLab 13.2. +> - A scheduled index deletion and the ability to cancel it was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38914) in GitLab 13.3. -Under **Admin Area > Settings > General > Advanced Search > Elasticsearch zero-downtime reindexing**, click on **Trigger cluster reindexing**. +Under **Admin Area > Settings > Advanced Search > Elasticsearch zero-downtime reindexing**, click on **Trigger cluster reindexing**. Reindexing can be a lengthy process depending on the size of your Elasticsearch cluster. @@ -449,9 +319,9 @@ After the reindexing is completed, the original index will be scheduled to be de While the reindexing is running, you will be able to follow its progress under that same section. -### Mark the most recent reindex job as failed and unpause the indexing +### Mark the most recent reindex job as failed and resume the indexing -Sometimes, you might want to abandon the unfinished reindex job and unpause the indexing. You can achieve this via the following steps: +Sometimes, you might want to abandon the unfinished reindex job and resume the indexing. You can achieve this via the following steps: 1. Mark the most recent reindex job as failed: @@ -463,7 +333,7 @@ Sometimes, you might want to abandon the unfinished reindex job and unpause the bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production ``` -1. Uncheck the "Pause Elasticsearch indexing" checkbox in **Admin Area > Settings > General > Advanced Search**. +1. Uncheck the "Pause Elasticsearch indexing" checkbox in **Admin Area > Settings > Advanced Search**. ## Background migrations @@ -519,8 +389,8 @@ In order to debug issues with the migrations you can check the [`elasticsearch.l 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 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 +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 in the background. ## GitLab Advanced Search Rake tasks @@ -539,17 +409,14 @@ The following are some available Rake tasks: | [`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:create_empty_index[<TARGET_NAME>]`](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[<TARGET_NAME>]`](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[<TARGET_NAME>]`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Wrapper task for `gitlab:elastic:delete_index[<TARGET_NAME>]` and `gitlab:elastic:create_empty_index[<TARGET_NAME>]`. | +| [`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`. | | [`sudo gitlab-rake gitlab:elastic:index_snippets`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Performs an Elasticsearch import that indexes the snippets data. | | [`sudo gitlab-rake gitlab:elastic:projects_not_indexed`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Displays which projects are not indexed. | | [`sudo gitlab-rake gitlab:elastic:reindex_cluster`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Schedules a zero-downtime cluster reindexing task. This feature should be used with an index that was created after GitLab 13.0. | | [`sudo gitlab-rake gitlab:elastic:mark_reindex_failed`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake)`] | Mark the most recent re-index job as failed. | -NOTE: -The `TARGET_NAME` parameter is optional and will use the default index/alias name from the current `RAILS_ENV` if not set. - ### Environment variables In addition to the Rake tasks, there are some environment variables that can be used to modify the process: @@ -599,7 +466,7 @@ For basic guidance on choosing a cluster configuration you may refer to [Elastic - 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. - 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, you should aim for this simple formula for the number of shards: `number of expected documents / 5M +1`. -- `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 realtime. 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 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. - 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 @@ -799,6 +666,23 @@ However, some larger installations may wish to tune the merge policy settings: - Do not do a [force merge](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-forcemerge.html "Force Merge") to remove deleted documents. A warning in the [documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-forcemerge.html "Force Merge") states that this can lead to very large segments that may never get reclaimed, and can also cause significant performance or availability issues. +## Reverting to Basic Search + +Sometimes there may be issues with your Elasticsearch index data and as such +GitLab will allow you to revert to "basic search" when there are no search +results and assuming that basic search is supported in that scope. This "basic +search" will behave as though you don't have Advanced Search enabled at all for +your instance and search using other data sources (such as PostgreSQL data and Git +data). + +## Data recovery: Elasticsearch is a secondary data store only + +The use of Elasticsearch in GitLab is only ever as a secondary data store. +This means that all of the data stored in Elasticsearch can always be derived +again from other data sources, specifically PostgreSQL and Gitaly. Therefore, if +the Elasticsearch data store is ever corrupted for whatever reason, you can +simply reindex everything from scratch. + ## Troubleshooting One of the most valuable tools for identifying issues with the Elasticsearch @@ -823,7 +707,7 @@ There are a couple of ways to achieve that: This is always correctly identifying whether the current project/namespace being searched is using Elasticsearch. -- From the admin area under **Settings > General > Advanced Search** check that the +- From the admin area under **Settings > Advanced Search** check that the Advanced Search settings are checked. Those same settings there can be obtained from the Rails console if necessary: @@ -980,27 +864,12 @@ problem. There is a [more structured, lower-level troubleshooting document](../administration/troubleshooting/elasticsearch.md) for when you experience other issues, including poor performance. -### Known issues - -[Elasticsearch `code_analyzer` doesn't account for all code cases](https://gitlab.com/groups/gitlab-org/-/epics/3621). +### Elasticsearch `code_analyzer` doesn't account for all code cases The `code_analyzer` pattern and filter configuration is being evaluated for improvement. We have fixed [most edge cases](https://gitlab.com/groups/gitlab-org/-/epics/3621#note_363429094) that were not returning expected search results due to our pattern and filter configuration. Improvements to the `code_analyzer` pattern and filters are being discussed in [epic 3621](https://gitlab.com/groups/gitlab-org/-/epics/3621). -### Reverting to Basic Search - -Sometimes there may be issues with your Elasticsearch index data and as such -GitLab will allow you to revert to "basic search" when there are no search -results and assuming that basic search is supported in that scope. This "basic -search" will behave as though you don't have Advanced Search enabled at all for -your instance and search using other data sources (ie. PostgreSQL data and Git -data). - -### Data recovery: Elasticsearch is a secondary data store only +### Some binary files may not be searchable by name -The use of Elasticsearch in GitLab is only ever as a secondary data store. -This means that all of the data stored in Elasticsearch can always be derived -again from other data sources, specifically PostgreSQL and Gitaly. Therefore, if -the Elasticsearch data store is ever corrupted for whatever reason, you can -simply reindex everything from scratch. +In GitLab 13.9, a change was made where [binary file names are being indexed](https://gitlab.com/gitlab-org/gitlab/-/issues/301083). However, without indexing all projects' data from scratch, only binary files that are added or updated after the GitLab 13.9 release are searchable. diff --git a/doc/integration/github.md b/doc/integration/github.md index 858614a0571..0239ba0e818 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -6,9 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Integrate your GitLab instance with GitHub -You can integrate your GitLab instance with GitHub.com and GitHub Enterprise to -enable users to import projects from GitHub or sign in to your GitLab instance -with your GitHub account. +You can integrate your GitLab instance with GitHub.com and GitHub Enterprise. This integration +enables users to import projects from GitHub, or sign in to your GitLab instance +with their GitHub account. ## Enabling GitHub OAuth @@ -24,7 +24,7 @@ To prevent an [OAuth2 covert redirect](https://oauth.net/advisories/2014-1-cover See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. -After you have configured the GitHub provider, you need the following information, which you must substitute in the GitLab configuration file, in the steps shown next. +After you have configured the GitHub provider, you need the following information. You must substitute that information in the GitLab configuration file in these next steps. | Setting from GitHub | Substitute in the GitLab configuration file | Description | |:---------------------|:---------------------------------------------|:------------| @@ -179,7 +179,9 @@ If you're getting the message `Signing in using your GitHub account without a pr GitLab account is not allowed. Create a GitLab account first, and then connect it to your GitHub account` when signing in, in GitLab: -1. Go to your **Profile > Account**. -1. Under the "Social sign-in" section, click **Connect** near the GitHub icon. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In 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 3bd3099e390..97c5332c438 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -11,12 +11,10 @@ Import projects from GitLab.com and login to your GitLab instance with your GitL To enable the GitLab.com OmniAuth provider you must register your application with GitLab.com. GitLab.com generates an application ID and secret key for you to use. -1. Sign in to GitLab.com - -1. On the upper right corner, click on your avatar and go to your **Settings**. - -1. Select **Applications** in the left menu. - +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. 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: @@ -29,10 +27,8 @@ GitLab.com generates an application ID and secret key for you to use. The first link is required for the importer and second for the authorization. 1. Select **Save application**. - 1. You should now see an **Application ID** and **Secret**. Keep this page open as you continue configuration. - 1. On your GitLab server, open the configuration file. For Omnibus package: @@ -50,10 +46,9 @@ GitLab.com generates an application ID and secret key for you to use. ``` 1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - 1. Add the provider configuration: - For Omnibus package: + For Omnibus installations: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -76,16 +71,13 @@ GitLab.com generates an application ID and secret key for you to use. ``` 1. Change `'YOUR_APP_ID'` to the Application ID from the GitLab.com application page. - 1. Change `'YOUR_APP_SECRET'` to the secret from the GitLab.com application page. - 1. Save the configuration file. - 1. Based on how GitLab was installed, implement these changes by using the appropriate method: - - Omnibus GitLab: [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - - Source: [Restart GitLab](../administration/restart_gitlab.md#installations-from-source). + - Omnibus GitLab: [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). + - Source: [restart GitLab](../administration/restart_gitlab.md#installations-from-source). On the sign-in page, there should now be a GitLab.com icon following the regular sign-in form. Select the icon to begin the authentication process. diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index 05f129e6049..7dc710615fb 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -10,45 +10,57 @@ info: "To determine the technical writer assigned to the Stage/Group associated > - [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 -With [Gitpod](https://gitpod.io/) you can describe your dev environment as code to get fully set -up, compiled, and tested dev environments for any GitLab project. The dev environments are not only -automated but also prebuilt which means that Gitpod continuously builds your Git branches like a CI -server. By that you don’t have to wait for dependencies to be downloaded and builds to finish, but -you can start coding immediately. +With [Gitpod](https://gitpod.io/) you can describe your development environment as code to get fully +set up, compiled, and tested development environments for any GitLab project. The development +environments are not only automated but also prebuilt which means that Gitpod continuously builds +your Git branches like a CI/CD server. -In short: With Gitpod you can start coding instantly on any project, branch, and merge request from -any device, at any time. +This means you don't have to wait for dependencies to be downloaded and builds to finish, you can start +coding immediately. With Gitpod you can start coding instantly on any project, branch, and merge +request from any device, at any time. - +To use the GitLab Gitpod integration, it must be enabled for your GitLab instance. Users of: -You can launch Gitpod directly from GitLab by clicking the **Gitpod** button from the **Web IDE** -dropdown on the project page: - - +- GitLab.com can use it immediately after it's [enabled in their user settings](#enable-gitpod-in-your-user-settings). +- GitLab self-managed instances can use it after: + 1. It's [enabled and configured by a GitLab administrator](#configure-a-self-managed-instance). + 1. It's [enabled in their user settings](#enable-gitpod-in-your-user-settings). To learn more about Gitpod, see their [features](https://www.gitpod.io/features/) and [documentation](https://www.gitpod.io/docs/). -To use the GitLab-Gitpod integration, you need to enable it from your user preferences: +## Enable Gitpod in your user settings + +With the Gitpod integration enabled for your GitLab instance, to enable it for yourself: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Account**. +1. Under **Integrations**, locate the **Gitpod** section. +1. Check the **Enable Gitpod integration** checkbox and select the **Save changes** button. -1. From the GitLab UI, click your avatar in the top-right corner, then click **Settings**. -1. On the left-hand nav, click **Preferences**. -1. Under **Integrations**, find the **Gitpod** section. -1. Check **Enable Gitpod**. +## Configure a self-managed instance **(FREE SELF)** -Users of GitLab.com can enable it and start using straightaway. Users of GitLab self-managed instances -can follow the same steps once the integration has been enabled and configured by a GitLab administrator. +For GitLab self-managed instances, a GitLab administrator needs to: -## Configure your GitLab instance with Gitpod **(CORE ONLY)** +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/) + to get your instance up and running. +1. Enable it in GitLab: + 1. Go to **Admin Area > 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`). + 1. Select the **Save changes** button. -The integration of Gitpod with GitLab is enabled on GitLab.com and available to all users. -For GitLab self-managed instances, a GitLab administrator needs to enable it through the admin settings. +Your users then need to [enable it for themselves](#enable-gitpod-in-your-user-settings). -First, you (GitLab admin) need to set up a Gitpod instance to integrate with GitLab. -Head over to the [Gitpod documentation](https://www.gitpod.io/docs/self-hosted/latest/self-hosted/) to -get your instance up and running. Once done: +## Launch Gitpod in GitLab -1. In GitLab, go to **Admin Area > Settings > General**. -1. Expand the **Gitpod** configuration section. -1. Check **Enable Gitpod**. -1. Add your Gitpod instance URL (for example, `https://gitpod.example.com`). +You can launch Gitpod directly from GitLab by clicking the **Gitpod** button from the **Web IDE** +dropdown on the project page: + + + +A project launched in GitLab looks like: + + diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 1158d6c9bc8..af9972e825e 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -10,20 +10,29 @@ GitLab supports [Google actions in email](https://developers.google.com/gmail/ma 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 [Register with Google](https://developers.google.com/gmail/markup/registering-with-google). -*This process has a lot of steps so 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: +<!-- vale gitlab.InclusionCultural = NO --> + - The email account used by GitLab to send notification emails must: - Have a "Consistent history of sending a high volume of mail from your domain (order of hundred emails a day minimum to Gmail) for a few weeks at least". - Have a very low rate of spam complaints from users. - Emails must be authenticated via DKIM or SPF. -- Before sending the final form ("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you must find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there. +- Before sending the final form (**Gmail Schema Whitelist Request**), you must + send a real email from your production server. This means that you must find + a way to send this email from the email address you are registering. You can + do this by forwarding the real email from the email address you are + registering. You can also go into the Rails console on the GitLab server and + trigger sending the email from there. + +<!-- vale gitlab.InclusionCultural = YES --> You can check how it looks going through all the steps laid out in the "Registering with Google" doc in [this GitLab.com issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/1517). diff --git a/doc/integration/google_workspace_saml.md b/doc/integration/google_workspace_saml.md new file mode 100644 index 00000000000..7b561750b0f --- /dev/null +++ b/doc/integration/google_workspace_saml.md @@ -0,0 +1,163 @@ +--- +type: reference +stage: Manage +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 +--- + +# Google Workspace SSO provider + +Google Workspace (formerly G Suite) is a [Single Sign-on provider](https://support.google.com/a/answer/60224?hl=en) that can be used to authenticate +with GitLab. + +The following documentation enables Google Workspace as a SAML provider for GitLab. + +## Configure the Google Workspace SAML app + +The following guidance is based on this Google Workspace article, on how to [Set up your own custom SAML application](https://support.google.com/a/answer/6087519?hl=en): + +Make sure you have access to a Google Workspace [Super Admin](https://support.google.com/a/answer/2405986#super_admin) account. + Follow the instructions in the linked Google Workspace article, where you'll need the following information: + +| | Typical value | Description | +|------------------|--------------------------------------------------|----------------------------------------------------------| +| Name of SAML App | GitLab | Other names OK. | +| ACS URL | `https://<GITLAB_DOMAIN>/users/auth/saml/callback` | ACS is short for Assertion Consumer Service. | +| GITLAB_DOMAIN | `gitlab.example.com` | Set to the domain of your GitLab instance. | +| Entity ID | `https://gitlab.example.com` | A value unique to your SAML app, you'll set it to the `issuer` in your GitLab configuration. | +| Name ID format | EMAIL | Required value. Also known as `name_identifier_format` | +| Name ID | Primary email address | Make sure someone receives content sent to that address | +| First name | `first_name` | Required value to communicate with GitLab. | +| Last name | `last_name` | Required value to communicate with GitLab. | + +You will also need to setup the following SAML attribute mappings: + +| Google Directory attributes | App attributes | +|-----------------------------------|----------------| +| Basic information > Email | `email` | +| Basic Information > First name | `first_name` | +| Basic Information > Last name | `last_name` | + +You may also use some of this information when you [Configure GitLab](#configure-gitlab). + +When configuring the Google Workspace SAML app, be sure to record the following information: + +| | Value | Description | +|-------------|--------------|-----------------------------------------------------------------------------------| +| 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. + +--- + +Now that the Google Workspace SAML app is configured, it's time to enable it in GitLab. + +## Configure GitLab + +1. See [Initial OmniAuth Configuration](../integration/omniauth.md#initial-omniauth-configuration) + for initial settings. + +1. To allow people to register for GitLab, through their Google accounts, add the following + values to your configuration: + + **For Omnibus GitLab installations** + + Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_allow_single_sign_on'] = ['saml'] + gitlab_rails['omniauth_block_auto_created_users'] = false + ``` + + --- + + **For installations from source** + + Edit `config/gitlab.yml`: + + ```yaml + allow_single_sign_on: ["saml"] + block_auto_created_users: false + ``` + +1. If an existing GitLab user has the same email address as a Google Workspace user, the registration + process automatically links their accounts, if you add the following setting: + their email addresses match by adding the following setting: + + **For Omnibus GitLab installations** + + Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_auto_link_saml_user'] = true + ``` + + --- + + **For installations from source** + + Edit `config/gitlab.yml`: + + ```yaml + auto_link_saml_user: true + ``` + +1. Add the provider configuration. + +For guidance on how to set up these values, see the [SAML General Setup steps](saml.md#general-setup). +Pay particular attention to the values for: + +- `assertion_consumer_service_url` +- `idp_cert_fingerprint` +- `idp_sso_target_url` +- `issuer` +- `name_identifier_format` + + **For Omnibus GitLab installations** + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: 'saml', + args: { + assertion_consumer_service_url: 'https://<GITLAB_DOMAIN>/users/auth/saml/callback', + idp_cert_fingerprint: '00:00:00:00:00:00:0:00:00:00:00:00:00:00:00:00', + idp_sso_target_url: 'https://accounts.google.com/o/saml2/idp?idpid=00000000', + issuer: 'https://<GITLAB_DOMAIN>', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress' + }, + label: 'Google Workspace' # optional label for SAML log in button, defaults to "Saml" + } + ] + ``` + + **For installations from source** + + ```yaml + - { + name: 'saml', + args: { + assertion_consumer_service_url: 'https://<GITLAB_DOMAIN>/users/auth/saml/callback', + idp_cert_fingerprint: '00:00:00:00:00:00:0:00:00:00:00:00:00:00:00:00', + idp_sso_target_url: 'https://accounts.google.com/o/saml2/idp?idpid=00000000', + issuer: 'https://<GITLAB_DOMAIN>', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress' + }, + label: 'Google Workspace' # optional label for SAML log in button, defaults to "Saml" + } + ``` + +1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for Omnibus and installations + from source respectively for the changes to take effect. + +To avoid caching issues, test the result on an incognito or private browser window. + +## Troubleshooting + +The Google Workspace documentation on [SAML app error messages](https://support.google.com/a/answer/6301076?hl=en) is helpful for debugging if you are seeing an error from Google while signing in. +Pay particular attention to the following 403 errors: + +- `app_not_configured` +- `app_not_configured_for_user` diff --git a/doc/integration/img/jira_dev_panel_setup_com_3.png b/doc/integration/img/jira_dev_panel_setup_com_3.png Binary files differdeleted file mode 100644 index eb3c573a4bb..00000000000 --- a/doc/integration/img/jira_dev_panel_setup_com_3.png +++ /dev/null diff --git a/doc/integration/img/jira_dev_panel_setup_com_3_v13_9.png b/doc/integration/img/jira_dev_panel_setup_com_3_v13_9.png Binary files differnew file mode 100644 index 00000000000..fe791637d31 --- /dev/null +++ b/doc/integration/img/jira_dev_panel_setup_com_3_v13_9.png diff --git a/doc/integration/img/jira_dev_panel_setup_com_4_v13_9.png b/doc/integration/img/jira_dev_panel_setup_com_4_v13_9.png Binary files differnew file mode 100644 index 00000000000..08787f12b67 --- /dev/null +++ b/doc/integration/img/jira_dev_panel_setup_com_4_v13_9.png diff --git a/doc/integration/img/oauth_provider_application_form.png b/doc/integration/img/oauth_provider_application_form.png Binary files differdeleted file mode 100644 index c4546d8b3f5..00000000000 --- a/doc/integration/img/oauth_provider_application_form.png +++ /dev/null diff --git a/doc/integration/img/oauth_provider_application_id_secret.png b/doc/integration/img/oauth_provider_application_id_secret.png Binary files differdeleted file mode 100644 index 21e442b5d04..00000000000 --- a/doc/integration/img/oauth_provider_application_id_secret.png +++ /dev/null diff --git a/doc/integration/img/oauth_provider_authorized_application.png b/doc/integration/img/oauth_provider_authorized_application.png Binary files differdeleted file mode 100644 index ebff8529b4e..00000000000 --- a/doc/integration/img/oauth_provider_authorized_application.png +++ /dev/null diff --git a/doc/integration/img/oauth_provider_user_wide_applications.png b/doc/integration/img/oauth_provider_user_wide_applications.png Binary files differdeleted file mode 100644 index 9cc12555574..00000000000 --- a/doc/integration/img/oauth_provider_user_wide_applications.png +++ /dev/null diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 7be2a6efd71..b51ce5de8d7 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -4,9 +4,9 @@ group: Ecosystem 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 --- -# Jenkins CI service **(CORE)** +# Jenkins CI service **(FREE)** -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/246756) to Core in GitLab 13.7. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/246756) to GitLab Free in 13.7. From GitLab, you can trigger a Jenkins build when you push code to a repository, or when a merge request is created. In return, the Jenkins pipeline status is shown on merge requests widgets and @@ -64,15 +64,16 @@ Grant a GitLab user access to the select GitLab projects. 1. Grant the user permission to the GitLab projects. If you're integrating Jenkins with many GitLab projects, consider granting the user global - Admin permission. Otherwise, add the user to each project, and grant Developer permission. + Administrator permission. Otherwise, add the user to each project, and grant Developer permission. ## Configure GitLab API access Create a personal access token to authorize Jenkins' access to GitLab. -1. Log in to GitLab as the user to be used with Jenkins. -1. Click your avatar, then **Settings**. -1. Click **Access Tokens** in the sidebar. +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. 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. @@ -166,7 +167,7 @@ to integrate GitLab and Jenkins. 1. In the configuration of your Jenkins job, in the GitLab configuration section, click **Advanced**. 1. Click the **Generate** button under the **Secret Token** field. 1. Copy the resulting token, and save the job configuration. -1. In GitLab, create a webhook for your project, enter the trigger URL (e.g. `https://JENKINS_URL/project/YOUR_JOB`) and paste the token in the **Secret Token** field. +1. In GitLab, create a webhook for your project, enter the trigger URL (such as `https://JENKINS_URL/project/YOUR_JOB`) and paste the token in the **Secret Token** field. 1. After you add the webhook, click the **Test** button, and it should succeed. ## Troubleshooting @@ -205,8 +206,8 @@ which is set to 10 seconds by default. To fix this the `gitlab_rails['webhook_timeout']` value must be increased in the `gitlab.rb` configuration file, followed by the [`gitlab-ctl reconfigure` command](../administration/restart_gitlab.md). -If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`), this -could also indicate that [webhook requests are timing out](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered): +If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`), +[webhook requests may be timing out](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered): ```plaintext 2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index b5d68e3183f..2ed87456ea1 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -50,7 +50,7 @@ Now navigate to GitLab services page and activate Jenkins  -Done! Now when you push to GitLab - it creates a build for Jenkins, and 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.md b/doc/integration/jira.md deleted file mode 100644 index 0e22bedd1cc..00000000000 --- a/doc/integration/jira.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/project/integrations/jira.md' ---- - -This document was moved to [another location](../user/project/integrations/jira.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md index 1c0b2bdc85e..59a96970d75 100644 --- a/doc/integration/jira_development_panel.md +++ b/doc/integration/jira_development_panel.md @@ -4,12 +4,11 @@ group: Ecosystem 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 Jira Development Panel integration **(CORE)** +# GitLab Jira Development Panel integration **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2381) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/233149) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/233149) to GitLab Free in 13.4. -The Jira Development Panel integration allows you to reference Jira issues within GitLab, displaying +The Jira Development Panel integration allows you to reference Jira issues in GitLab, displaying activity in the [Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) in the issue. @@ -19,8 +18,8 @@ to configure both integrations to take advantage of both sets of features. See a Depending on your environment, you can enable this integration by either: -- Configuring the Jira DVCS connector. -- Using the GitLab for Jira app in the Atlassian Marketplace. +- Configuring [the Jira DVCS connector](#jira-dvcs-configuration). +- Using the [GitLab for Jira app](#gitlab-for-jira-app) in the Atlassian Marketplace. See the [Configuration](#configuration) section for details. @@ -35,7 +34,7 @@ See the [Configuration](#configuration) section for details. With this integration, you can access related GitLab merge requests, branches, and commits directly from a Jira issue, reflecting your work in GitLab. From the Development panel, you can open a detailed view and take actions including creating a new merge request from a branch. For more information, see [Usage](#usage). -This integration connects all GitLab projects to projects in the Jira instance within either: +This integration connects all GitLab projects to projects in the Jira instance in either: - A top-level group. A top-level GitLab group is one that does not have any parent group itself. All the projects of that top-level group, as well as projects of the top-level group's subgroups nesting @@ -57,13 +56,13 @@ If you're using: - Self-managed GitLab, self-managed Jira, or both, configure the integration using [Jira's DVCS Connector](#jira-dvcs-configuration), which syncs data hourly. -We recommend that a GitLab group administrator or instance administrator (in the case of +We recommend that a GitLab group maintainer or group owner, or instance administrator (in the case of self-managed GitLab) set up the integration to simplify administration. ### Jira DVCS configuration -If you're using GitLab.com and Jira Cloud, we recommend you use the -[GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector. +If you're using GitLab.com and Jira Cloud, use the +[GitLab for Jira app](#gitlab-for-jira-app) unless you have a specific need for the DVCS Connector. When configuring Jira DVCS Connector: @@ -78,14 +77,12 @@ To ensure that regular user account maintenance doesn't impact your integration, create and use a single-purpose `jira` user in GitLab. 1. In GitLab, create a new application to allow Jira to connect with your GitLab account. - - While signed in to the GitLab account that you want Jira to use to connect to GitLab, - click your profile avatar at the top right, and then click **Settings > Applications**. - Use the form to create a new application. - - In the **Name** field, enter a descriptive name for the integration, such as `Jira`. - - For the **Redirect URI** field, enter `https://<gitlab.example.com>/login/oauth/callback`, +1. Sign in to the GitLab account that you want Jira to use to connect to GitLab. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In 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 `https://<gitlab.example.com>/login/oauth/callback`, replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com, this would be `https://gitlab.com/login/oauth/callback`. @@ -97,15 +94,14 @@ create and use a single-purpose `jira` user in GitLab.  - - Check **API** in the Scopes section and uncheck any other checkboxes. - +1. Check **API** in the **Scopes** section, and clear any other checkboxes. 1. Click **Save application**. GitLab displays the generated **Application ID** and **Secret** values. Copy these values, which you use in Jira. #### Jira DVCS Connector setup -If you're using GitLab.com and Jira Cloud, we recommend you use the -[GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector. +If you're using GitLab.com and Jira Cloud, use the +[GitLab for Jira app](#gitlab-for-jira-app) unless you have a specific need for the DVCS Connector. 1. Ensure you have completed the [GitLab configuration](#gitlab-account-configuration-for-dvcs). 1. If you're using Jira Server, go to **Settings (gear) > Applications > DVCS accounts**. @@ -114,37 +110,39 @@ If you're using GitLab.com and Jira Cloud, we recommend you use the (We're pretending to be GitHub in this integration, until there's additional platform support in Jira.) 1. Complete the form: - Select **GitHub Enterprise** for the **Host** field. +1. Select **GitHub Enterprise** for the **Host** field. + +1. In the **Team or User Account** field, enter either: - In the **Team or User Account** field, enter the relative path of a top-level GitLab group that you have access to, - or the relative path of your personal namespace. + - The relative path of a top-level GitLab group that you have access to. + - The relative path of your personal namespace.  - In the **Host URL** field, enter `https://<gitlab.example.com>/`, +1. In the **Host URL** field, enter `https://<gitlab.example.com>/`, replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com, this would be `https://gitlab.com/`. NOTE: If using a GitLab version earlier than 11.3 the **Host URL** value should be `https://<gitlab.example.com>/-/jira` - For the **Client ID** field, use the **Application ID** value from the previous section. +1. For the **Client ID** field, use the **Application ID** value from the previous section. - For the **Client Secret** field, use the **Secret** value from the previous section. +1. For the **Client Secret** field, use the **Secret** value from the previous section. - Ensure that the rest of the checkboxes are checked. +1. Ensure that the rest of the checkboxes are checked. 1. Click **Add** to complete and create the integration. - Jira takes up to a few minutes to know about (import behind the scenes) all the commits and branches - for all the projects in the GitLab group you specified in the previous step. These are refreshed - every 60 minutes. + Jira takes up to a few minutes to know about (import behind the scenes) all the commits and branches + for all the projects in the GitLab group you specified in the previous step. These are refreshed + every 60 minutes. - In the future, we plan on implementing real-time integration. If you need - to refresh the data manually, you can do this from the `Applications -> DVCS - accounts` screen where you initially set up the integration: + In the future, we plan on implementing real-time integration. If you need + to refresh the data manually, you can do this from the `Applications -> DVCS + accounts` screen where you initially set up the integration: -  +  To connect additional GitLab projects from other GitLab top-level groups (or personal namespaces), repeat the previous steps with additional Jira DVCS accounts. @@ -173,26 +171,26 @@ If there was an issue with SSL/TLS, this error message is generated. as GitLab is the TLS client. - The Jira Development Panel integration requires Jira to connect to GitLab, which causes Jira to be the TLS client. If your GitLab server's certificate is not - issued by a public certificate authority, the Java truststore on Jira's server + issued by a public certificate authority, the Java Truststore on Jira's server needs to have the appropriate certificate added to it (such as your organization's root certificate). Refer to Atlassian's documentation and Atlassian Support for assistance setting up Jira correctly: - [Adding a certificate to the trust store](https://confluence.atlassian.com/kb/how-to-import-a-public-ssl-certificate-into-a-jvm-867025849.html). - - Simplest approach is to use [keytool](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html). - - Add additional roots to Java's default truststore (`cacerts`) to allow Jira to + - Simplest approach is to use [`keytool`](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html). + - Add additional roots to Java's default Truststore (`cacerts`) to allow Jira to also trust public certificate authorities. - If the integration stops working after upgrading Jira's Java runtime, this - might be because the `cacerts` truststore got replaced. + might be because the `cacerts` Truststore got replaced. - [Troubleshooting connectivity up to and including TLS handshaking](https://confluence.atlassian.com/kb/unable-to-connect-to-ssl-services-due-to-pkix-path-building-failed-error-779355358.html), using the a java class called `SSLPoke`. -- Download the class from Atlassian's knowledgebase to Jira's server, for example to `/tmp`. +- Download the class from Atlassian's knowledge base to Jira's server, for example to `/tmp`. - Use the same Java runtime as Jira. - Pass all networking-related parameters that Jira is called with, such as proxy - settings or an alternative root truststore (`-Djavax.net.ssl.trustStore`): + settings or an alternative root Truststore (`-Djavax.net.ssl.trustStore`): ```shell ${JAVA_HOME}/bin/java -Djavax.net.ssl.trustStore=/var/atlassian/application-data/jira/cacerts -classpath /tmp SSLPoke gitlab.example.com 443 @@ -211,7 +209,7 @@ The requested scope is invalid, unknown, or malformed. Potential resolutions: -- Verify the URL shown in the browser after being redirected from Jira in step 5 of [Jira DVCS Connector Setp](#jira-dvcs-connector-setup) includes `scope=api` within the query string. +- Verify the URL shown in the browser after being redirected from Jira in step 5 of [Jira DVCS Connector Setup](#jira-dvcs-connector-setup) includes `scope=api` in the query string. - If `scope=api` is missing from the URL, return to [GitLab account configuration](#gitlab-account-configuration-for-dvcs) and ensure the application you created in step 1 has the `api` box checked under scopes. ##### Jira error adding account and no repositories listed @@ -230,7 +228,7 @@ Potential resolutions: - If you're using GitLab versions 11.10-12.7, upgrade to GitLab 12.8.10 or later to resolve an identified [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/37012). -- If you're using GitLab Core or GitLab Starter, be sure you're using +- If you're using GitLab Free or GitLab Starter, be sure you're using GitLab 13.4 or later. [Contact GitLab Support](https://about.gitlab.com/support/) if none of these reasons apply. @@ -248,30 +246,40 @@ resynchronize the information. To do so: the button. For more information, see [Atlassian's documentation](https://support.atlassian.com/jira-cloud-administration/docs/synchronize-jira-cloud-to-bitbucket/). -### GitLab for Jira app +### GitLab for Jira app **(FREE SAAS)** -You can integrate GitLab.com and Jira Cloud using the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app in the Atlassian Marketplace. +You can integrate GitLab.com and Jira Cloud using the +[GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) +app in the Atlassian Marketplace. The user configuring GitLab for Jira must have +[Maintainer](../user/permissions.md) permissions in the GitLab namespace. -This method is recommended when using GitLab.com and Jira Cloud because data is synchronized in realtime, while the DVCS connector updates data only once per hour. If you are not using both of these environments, use the [Jira DVCS Connector](#jira-dvcs-configuration) method. +This method is recommended when using GitLab.com and Jira Cloud because data is synchronized in real-time. The DVCS connector updates data only once per hour. If you are not using both of these environments, use the [Jira DVCS Connector](#jira-dvcs-configuration) method. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a walkthrough of the integration with GitLab for Jira, watch [Configure GitLab Jira Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube. 1. Go to **Jira Settings > Apps > Find new apps**, then search for GitLab. -1. Click **GitLab for Jira**, then click **Get it now**. Or go the [App in the marketplace directly](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) +1. Click **GitLab for Jira**, then click **Get it now**, or go to the + [App in the marketplace directly](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud).  -1. After installing, click **Get started** to go to the configurations page. This page is always available under **Jira Settings > Apps > Manage apps**. +1. After installing, click **Get started** to go to the configurations page. + This page is always available under **Jira Settings > Apps > Manage apps**.  -1. In **Namespace**, enter the group or personal namespace, and then click - **Link namespace to Jira**. The user setting up *GitLab for Jira* must have - *Maintainer* access to the GitLab namespace. +1. If not already signed in to GitLab.com, you must sign in as a user with + [Maintainer](../user/permissions.md) permissions to add namespaces. -NOTE: -The GitLab user only needs access when adding a new namespace. For syncing with Jira, we do not depend on the user's token. +  +1. Select **Add namespace** to open the list of available namespaces. + +1. Identify the namespace you want to link, and select **Link**. -  +  + +NOTE: +The GitLab user only needs access when adding a new namespace. For syncing with +Jira, we do not depend on the user's token. After a namespace is added: @@ -285,11 +293,11 @@ For more information, see [Usage](#usage). #### Troubleshooting GitLab for Jira -The GitLab for Jira 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 for Jira App uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies. This 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." -In this case, use [Firefox](https://www.mozilla.org/en-US/firefox/), [Google Chrome](https://www.google.com/chrome/index.html) or enable cross-site cookies in your browser. +In this case, use [Firefox](https://www.mozilla.org/en-US/firefox/) or enable cross-site cookies in your browser. ## Usage @@ -314,6 +322,6 @@ For more information on using Jira Smart Commits to track time against an issue, ## Limitations -This integration is currently not supported on GitLab instances under a +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`. diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 390c3ae3e7c..5be076464d8 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, how-to --- -# Kerberos integration **(STARTER ONLY)** +# Kerberos integration **(PREMIUM SELF)** GitLab can integrate with [Kerberos](https://web.mit.edu/kerberos/) as an authentication mechanism. @@ -109,15 +109,16 @@ existing GitLab account. To do so: 1. Navigate to **Admin Area > Overview > Users > Example User**. 1. Select the Identities tab. -1. Select 'Kerberos Spnego' in the 'Provider' dropdown box. +1. Select 'Kerberos SPNEGO' in the 'Provider' dropdown box. 1. Make sure the **Identifier** corresponds to the Kerberos username. 1. Select **Save changes**. If you're not an administrator: -1. Select your avatar in the upper-right corner, and select **Settings**. -1. Select Account. In the **Social sign-in** section, select - **Connect Kerberos Spnego**. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In 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). @@ -291,10 +292,10 @@ remove support for password-based Kerberos sign-ins in a future release, so we recommend that you upgrade to ticket-based sign-ins. Depending on your existing GitLab configuration, the 'Sign in with: -Kerberos Spnego' button may already be visible on your GitLab sign-in +Kerberos SPNEGO' button may already be visible on your GitLab sign-in page. If not, then add the settings [described above](#configuration). -Once you have verified that the 'Kerberos Spnego' button works +Once you have verified that the 'Kerberos SPNEGO' button works without entering any passwords, you can proceed to disable password-based Kerberos sign-ins. To do this you need only need to remove the OmniAuth provider named `kerberos` from your `gitlab.yml` / diff --git a/doc/integration/ldap.md b/doc/integration/ldap.md deleted file mode 100644 index 55c169bca80..00000000000 --- a/doc/integration/ldap.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../administration/auth/ldap/index.md' ---- - -This document was moved to [`administration/auth/ldap`](../administration/auth/ldap/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index 88e9e3ef05c..41656bd2216 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Sign into GitLab with (almost) any OAuth2 provider -The `omniauth-oauth2-generic` gem allows Single Sign On between GitLab and your own OAuth2 provider +The `omniauth-oauth2-generic` gem allows Single Sign-On between GitLab and your own 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: diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 82cb409c560..377c8ec82d0 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -1,83 +1,88 @@ --- -stage: Create -group: Ecosystem +stage: Manage +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 -This document is about using GitLab as an OAuth authentication service provider -to sign in to other services. +This document describes how you can use GitLab as an OAuth 2 +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 authentication service providers to sign in to + 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 related API, see [Applications API](../api/applications.md). ## Introduction to OAuth -[OAuth](https://oauth.net/2/) provides to client applications a 'secure delegated access' to server -resources on behalf of a resource owner. In fact, OAuth allows an authorization -server to issue access tokens to third-party clients with the approval of the -resource owner, or the end-user. +[OAuth 2](https://oauth.net/2/) provides to client applications a 'secure delegated +access' to server resources on behalf of a resource owner. OAuth 2 allows +authorization servers to issue access tokens to third-party clients with the approval +of the resource owner or the end-user. -OAuth is mostly used as a Single Sign-On service (SSO), but you can find a -lot of different uses for this functionality. For example, you can allow users -to sign in to your application with their GitLab.com account, or GitLab.com -can be used for authentication to your GitLab instance +OAuth 2 can be used: + +- To allow users to sign in to your application with their GitLab.com account. +- To set up GitLab.com for authentication to your GitLab instance. (see [GitLab OmniAuth](gitlab.md)). -The 'GitLab Importer' feature is also using the OAuth protocol to give access +The 'GitLab Importer' feature also uses OAuth 2 to give access to repositories without sharing user credentials to your GitLab.com account. -GitLab supports two ways of adding a new OAuth2 application to an instance. You -can either add an application as a regular user or add it in the Admin Area. -What this means is that GitLab can actually have instance-wide and a user-wide -applications. There is no difference between them except for the different -permission levels they are set (user/admin). The default callback URL is -`http://your-gitlab.example.com/users/auth/gitlab/callback` - -## Adding an application through the profile +GitLab supports two ways of adding a new OAuth 2 application to an instance: -In order to add a new application via your profile, navigate to -**Profile Settings > Applications** and select **New Application**. +- As a regular user, for applications owned by an individual. +- Through the Admin Area menu for instance-wide apps. - +The only difference between these two methods is the [permission](../user/permissions.md) +levels. The default callback URL is `http://your-gitlab.example.com/users/auth/gitlab/callback`. -In the application form, enter a **Name** (arbitrary), and make sure to set up -correctly the **Redirect URI** which is the URL where users are sent after -they authorize with GitLab. +## Add an application through the profile - +To add a new application via your profile: -When you click **Submit** you are provided with the application ID and -the application secret which you can then use with your application that -connects to GitLab. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In 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 displays: - + - Application ID: OAuth 2 Client ID. + - Secret: OAuth 2 Client Secret. ## OAuth applications in the Admin Area -To create an application that does not belong to a certain user, you can create -it from the Admin Area. - - +To create an application for your GitLab instance, select +**Admin Area > Applications > New application**. -You're also able to mark an application as _trusted_ when creating it through the Admin Area. By doing that, -the user authorization step is automatically skipped for this application. +When creating an **Admin Area** application, you can mark it as _trusted_. +The user authorization step is automatically skipped for this application. ## Authorized applications -Every application you authorized to use your GitLab credentials is shown -in the **Authorized applications** section under **Profile Settings > Applications**. - - - -The GitLab OAuth applications support scopes, which allow various actions that any given -application can perform such as `read_user` and `api`. There are many more scopes -available. - -At any time you can revoke any access by just clicking **Revoke**. +Every application you authorize with your GitLab credentials is shown +in the **Authorized applications** section under **Settings > Applications**. + +The GitLab OAuth 2 applications support scopes, which allow various actions that any given +application can perform. Available scopes are depicted in the following table. + +| Scope | Description | +| ------------------ | ----------- | +| `api` | Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry. | +| `read_user` | Grants read-only access to the authenticated user's profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users. | +| `read_api` | Grants read access to the API, including all groups and projects, the container registry, and the package registry. | +| `read_repository` | Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API. | +| `write_repository` | Grants read-write access to repositories on private projects using Git-over-HTTP (not using the API). | +| `read_registry` | Grants read-only access to container registry images on private projects. | +| `write_registry` | Grants read-only access to container registry images on private projects. | +| `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an administrator user. | +| `openid` | Grants permission to authenticate with GitLab using [OpenID Connect](openid_connect_provider.md). Also gives read-only access to the user's profile and group memberships. | +| `profile` | Grants read-only access to the user's profile data using [OpenID Connect](openid_connect_provider.md). | +| `email` | Grants read-only access to the user's primary email address using [OpenID Connect](openid_connect_provider.md). | + +At any time you can revoke any access by clicking **Revoke**. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 53c19ddfdb1..cf033018e17 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -55,7 +55,7 @@ earlier version, you must explicitly enable it. - `allow_single_sign_on` allows you to specify the providers you want to allow to automatically create an account. It defaults to `false`. If `false` users must - be created manually or they can't sign in via OmniAuth. + 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. @@ -66,7 +66,7 @@ earlier version, you must explicitly enable it. NOTE: If you set `block_auto_created_users` to `false`, make sure to only define providers under `allow_single_sign_on` that you are able to control, like -SAML, Shibboleth, Crowd or Google, or set it to `false` otherwise any user on +SAML, Shibboleth, Crowd, or Google. Otherwise, set it to `false`, or any user on the Internet can successfully sign in to your GitLab without administrative approval. @@ -138,9 +138,10 @@ provider such as Twitter can be enabled. Follow the steps below to enable an OmniAuth provider for an existing user. 1. Sign in normally - whether standard sign in, LDAP, or another OmniAuth provider. -1. Go to profile settings (the silhouette icon in the top right corner). -1. Select the "Account" tab. -1. Under "Connected Accounts" select the desired OmniAuth provider, such as Twitter. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In 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. @@ -168,10 +169,8 @@ omniauth: ## Configure OmniAuth Providers as External -> Introduced in GitLab 8.7. - -You can define which OmniAuth providers you want to be `external` so that all users -**creating accounts, or logging in via these providers** can't have +You can define which OmniAuth providers you want to be `external`. Users +creating accounts, or logging in by using these `external` providers cannot have access to internal projects. You must use the full name of the provider, like `google_oauth2` for Google. Refer to the examples for the full names of the supported providers. @@ -200,9 +199,9 @@ NOTE: 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 (e.g. LDAP, GitHub, Twitter). But sometimes that -is not enough and you need to integrate with other authentication solutions. For -these cases you can use the OmniAuth provider. +with a few providers pre-installed, such as LDAP, GitHub, and Twitter. You may also +need to integrate with other authentication solutions. For +these cases, you can use the OmniAuth provider. ### Steps @@ -215,7 +214,7 @@ from the OmniAuth provider's documentation. sudo service gitlab stop ``` -- Add the gem to your [Gemfile](https://gitlab.com/gitlab-org/gitlab/blob/master/Gemfile): +- Add the gem to your [`Gemfile`](https://gitlab.com/gitlab-org/gitlab/blob/master/Gemfile): ```shell gem "omniauth-your-auth-provider" @@ -240,25 +239,28 @@ from the OmniAuth provider's documentation. If you have successfully set up a provider that is not shipped with GitLab itself, please let us know. +Share your experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations). You can help others by reporting successful configurations and probably share a -few insights or provide warnings for common errors or pitfalls by sharing your -experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations). +few insights or provide warnings for common errors or pitfalls. While we can't officially support every possible authentication mechanism out there, we'd like to at least help those with specific needs. ## Enable or disable Sign In with an OmniAuth provider without disabling import sources -> Introduced in GitLab 8.8. - -Administrators are able to enable or disable Sign In via some OmniAuth providers. +Administrators are able to enable or disable **Sign In** by using some OmniAuth providers. NOTE: -By default Sign In is enabled via all the OAuth Providers that have been configured in `config/gitlab.yml`. +By default, **Sign In** is enabled by using all the OAuth Providers that have been configured in `config/gitlab.yml`. + +To enable/disable an OmniAuth provider: -In order to enable/disable an OmniAuth provider, go to Admin Area -> Settings -> Sign-in Restrictions section -> Enabled OAuth Sign-In sources and select the providers you want to enable or disable. +1. In the top navigation bar, go to **Admin Area**. +1. In the left sidebar, go to **Settings**. +1. Scroll to the **Sign-in Restrictions** section, and click **Expand**. +1. Next to **Enabled OAuth Sign-In sources**, select the check box for each provider you want to enable or disable. - +  ## Disabling OmniAuth @@ -325,7 +327,7 @@ omniauth: You can add the `auto_sign_in_with_provider` setting to your GitLab configuration to redirect login requests to your OmniAuth provider for -authentication, removing the need to click a button before actually signing in. +authentication. This removes the need to click a button before actually signing in. For example, when using the Azure integration, set the following to enable auto sign-in: @@ -345,7 +347,7 @@ omniauth: 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 admin permissions. +one of the OmniAuth users has administrator permissions. You may also bypass the auto sign in feature by browsing to `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index 5bf079df800..4455ace3e1f 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -12,11 +12,12 @@ to sign in to other services. ## Introduction to OpenID Connect [OpenID Connect](https://openid.net/connect/) \(OIDC) is a simple identity layer on top of the -OAuth 2.0 protocol. It allows clients to verify the identity of the end-user -based on the authentication performed by GitLab, as well as to obtain -basic profile information about the end-user in an interoperable and -REST-like manner. OIDC performs many of the same tasks as OpenID 2.0, -but does so in a way that is API-friendly, and usable by native and +OAuth 2.0 protocol. It allows clients to: + +- Verify the identity of the end-user based on the authentication performed by GitLab. +- Obtain basic profile information about the end-user in an interoperable and REST-like manner. + +OIDC performs many of the same tasks as OpenID 2.0, but is API-friendly and usable by native and mobile applications. On the client side, you can use [OmniAuth::OpenIDConnect](https://github.com/jjbohn/omniauth-openid-connect/) for Rails @@ -34,7 +35,7 @@ is select the `openid` scope in the application settings. ## Shared information -Currently the following user information is shared with clients: +The following user information is shared with clients: | Claim | Type | Description | |:-----------------|:----------|:------------| diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index bb5425187c1..8f090dfc588 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -14,7 +14,7 @@ to confirm that a real user, not a bot, is attempting to create an account. To use reCAPTCHA, first you must create a site and private key. -1. Go to the URL: <https://www.google.com/recaptcha/admin>. +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`). @@ -26,7 +26,7 @@ To use reCAPTCHA, first you must create a site and private key. return `recaptcha_html`. NOTE: -Make sure you are viewing an issuable in a project that is public, and if you're working with an issue, the issue is public. +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 diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 1aca3b04eee..156109518a6 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -86,4 +86,6 @@ Click the icon to begin the authentication process. Salesforce asks the user to If everything goes well, the user is returned to GitLab and is signed in. NOTE: -GitLab requires the email address of each new user. Once the user is logged in using Salesforce, GitLab redirects the user to the profile page where they must provide the email and verify the email. +GitLab requires the email address of each new user. After the user is signed in +using Salesforce, GitLab redirects the user to the profile page where they must +provide the email and verify the email. diff --git a/doc/integration/saml.md b/doc/integration/saml.md index af0a58eab59..9b6ad3f2755 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -5,7 +5,7 @@ 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 --- -# SAML OmniAuth Provider **(CORE ONLY)** +# 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). @@ -17,7 +17,7 @@ You should also reference the [OmniAuth documentation](omniauth.md) for general |------|-------------| | Identity Provider (IdP) | The service which manages your user identities such as ADFS, Okta, Onelogin, or Ping Identity. | | Service Provider (SP) | SAML considers GitLab to be a service provider. | -| Assertion | A piece of information about a user's identity, such as their name or role. Also know as claims or attributes. | +| Assertion | A piece of information about a user's identity, such as their name or role. Also known as claims or attributes. | | SSO | Single Sign-On. | | Assertion consumer service URL | The callback on GitLab where users will be 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". | @@ -163,9 +163,21 @@ will be returned to GitLab and will be signed in. ## SAML Groups -You can require users to be members of a certain group, or assign users `external`, `admin` or `auditor` roles based on group membership. This feature **does not** allow you to +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. +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). +Support for these groups depends on your [subscription](https://about.gitlab.com/pricing/) +and whether you've installed [GitLab Enterprise Edition (EE)](https://about.gitlab.com/install/). + +| Group | Tier | GitLab Enterprise Edition (EE) Only? | +|------------------------------|--------------------|--------------------------------------| +| [Required](#required-groups) | **(FREE SELF)** | Yes | +| [External](#external-groups) | **(FREE SELF)** | No | +| [Admin](#admin-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 @@ -187,7 +199,7 @@ The name of the attribute can be anything you like, but it must contain the grou to which a user belongs. In order to tell GitLab where to find these groups, you need to add a `groups_attribute:` element to your SAML settings. -### Required groups **(STARTER ONLY)** +### Required groups **(FREE SELF)** Your IdP passes Group Information to the SP (GitLab) in the SAML Response. You need to configure GitLab to identify: @@ -213,9 +225,9 @@ Example: } } ``` -### External Groups **(STARTER ONLY)** +### External groups **(FREE SELF)** -SAML login supports automatic identification on whether a user should be considered an [external](../user/permissions.md) user. This is based on the user's group membership in the SAML identity provider. +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. ```yaml { name: 'saml', @@ -231,7 +243,7 @@ SAML login supports automatic identification on whether a user should be conside } } ``` -### Admin Groups **(STARTER ONLY)** +### Admin 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 @@ -251,13 +263,13 @@ considered admin users. } } ``` -### Auditor Groups **(STARTER ONLY)** +### Auditor groups **(PREMIUM SELF)** > Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 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. +considered [auditor users](../user/permissions.md#auditor-users). ```yaml { name: 'saml', @@ -385,7 +397,7 @@ This setting should be used only to map attributes that are part of the OmniAuth `attribute_statements` is used to map Attribute Names in a SAMLResponse to entries in the OmniAuth [`info` hash](https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema#schema-10-and-later). -For example, if your SAMLResponse contains an Attribute called 'EmailAddress', +For example, if your SAMLResponse contains an Attribute called `EmailAddress`, specify `{ email: ['EmailAddress'] }` to map the Attribute to the corresponding key in the `info` hash. URI-named Attributes are also supported, e.g. `{ email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }`. @@ -582,8 +594,8 @@ GitLab will sign the request with the provided private key. GitLab will include Avoid user control of the following attributes: -- [`*NameID*`](../user/group/saml_sso/index.md#nameid) -- *Email* when used with `omniauth_auto_link_saml_user` +- [`NameID`](../user/group/saml_sso/index.md#nameid) +- `Email` when used with `omniauth_auto_link_saml_user` These attributes define the SAML user. If users can change these attributes, they can impersonate others. @@ -593,7 +605,7 @@ Refer to the documentation for your SAML Identity Provider for information on ho The [Generated passwords for users created through integrated authentication](../security/passwords_for_integrated_authentication_methods.md) guide provides an overview of how GitLab generates and sets passwords for users created via SAML. -## Configuring Group SAML on a self-managed GitLab instance **(PREMIUM ONLY)** +## Configuring Group SAML on a self-managed GitLab instance **(PREMIUM SELF)** For information on the GitLab.com implementation, please see the [SAML SSO for GitLab.com groups page](../user/group/saml_sso). diff --git a/doc/integration/security_partners/index.md b/doc/integration/security_partners/index.md new file mode 100644 index 00000000000..1cd14947e74 --- /dev/null +++ b/doc/integration/security_partners/index.md @@ -0,0 +1,23 @@ +--- +stage: Protect +group: Container Security +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 +type: index +--- + +# Security partner integrations + +You can integrate GitLab with its security partners. This page has information on how do this with +each security partner: + +<!-- vale gitlab.Spelling = NO --> + +- [Anchore](https://docs.anchore.com/current/docs/using/integration/ci_cd/gitlab/) +- [Bridgecrew](https://docs.bridgecrew.io/docs/integrate-with-gitlab-self-managed) +- [Checkmarx](https://checkmarx.atlassian.net/wiki/spaces/SD/pages/1929937052/GitLab+Integration) +- [Indeni](https://indeni.com/doc-indeni-cloudrail/integrate-with-ci-cd/gitlab-instructions/) +- [JScrambler](https://docs.jscrambler.com/code-integrity/documentation/gitlab-ci-integration) +- [StackHawk](https://docs.stackhawk.com/continuous-integration/gitlab.html) +- [WhiteSource](https://www.whitesourcesoftware.com/gitlab/) + +<!-- vale gitlab.Spelling = YES --> diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index e811cac4f0b..3b92f2858ac 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -10,17 +10,17 @@ NOTE: The preferred approach for integrating a Shibboleth authentication system with GitLab 10 or newer is to use the [GitLab SAML integration](saml.md). This documentation is for Omnibus GitLab 9.x installs or older. -In order to enable Shibboleth support in GitLab we need to use Apache instead of NGINX (It may be possible to use NGINX, however this is difficult to configure using the bundled NGINX provided in the Omnibus GitLab package). Apache uses mod_shib2 module for Shibboleth authentication and can pass attributes as headers to OmniAuth Shibboleth provider. +To enable Shibboleth support in GitLab we need to use Apache instead of NGINX. (It may be possible to use NGINX, however this is difficult to configure using the bundled NGINX provided in the Omnibus GitLab package.) Apache uses `mod_shib2` module for Shibboleth authentication and can pass attributes as headers to OmniAuth Shibboleth provider. To enable the Shibboleth OmniAuth provider you must configure Apache Shibboleth module. The installation and configuration of the module itself is out of the scope of this document. -Check <https://wiki.shibboleth.net/confluence/display/SP3/Apache> for more information. +Check [the Shibboleth documentation](https://wiki.shibboleth.net/confluence/display/SP3/Apache) for more information. You can find Apache configuration in [GitLab Recipes](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache). The following changes are needed to enable Shibboleth: -1. Protect OmniAuth Shibboleth callback URL: +1. Protect the OmniAuth Shibboleth callback URL: ```apache <Location /users/auth/shibboleth/callback> @@ -53,7 +53,7 @@ The following changes are needed to enable Shibboleth: ``` NOTE: - Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an + In GitLab versions 11.4 and later, OmniAuth is enabled by default. If you're using an earlier version, you must explicitly enable it in `/etc/gitlab/gitlab.rb`. 1. In addition, add Shibboleth to `/etc/gitlab/gitlab.rb` as an OmniAuth provider. @@ -100,7 +100,7 @@ The following changes are needed to enable Shibboleth: 1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab 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 "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You are redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user is returned to GitLab and is signed in. +On the sign in page, there should now be a **Sign in with: Shibboleth** icon below the regular sign in form. Click the icon to begin the authentication process. You are redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user is returned to GitLab and is signed in. ## Apache 2.4 / GitLab 8.6 update diff --git a/doc/integration/slack.md b/doc/integration/slack.md deleted file mode 100644 index fbea9d3035c..00000000000 --- a/doc/integration/slack.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../user/project/integrations/slack.md' ---- - -This document was moved to [another location](../user/project/integrations/slack.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index 6820ff8a0aa..0dcf86cc46d 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -6,9 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Slash Commands -> The `run` command was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. +> - [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). Simply type the command as a message in your chat client to activate it. +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. Commands are scoped to a project, with a trigger term that is specified during configuration. @@ -26,22 +26,22 @@ Taking the trigger term as `project-name`, the commands are: | `/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/README.md) job `<job name>` on `master` | +| `/project-name run <job name> <arguments>` | Execute [ChatOps](../ci/chatops/index.md) job `<job name>` on `master` | -Note that if you are using the [GitLab Slack application](../user/project/integrations/gitlab_slack_application.md) for -your GitLab.com projects, you need to [add the `gitlab` keyword at the beginning of the command](../user/project/integrations/gitlab_slack_application.md#usage). +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 is possible to create new issue, display issue details and search up to 5 issues. +It's possible to create new issue, display issue details and search up to 5 issues. ## Deploy command -In order to deploy to an environment, GitLab tries to find a deployment +To deploy to an environment, GitLab tries to find a deployment manual action in the pipeline. -If there is only one action for a given environment, it is triggered. -If there is more than one action defined, GitLab tries to find an action +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. The command returns an error when no matching action has been found. diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 8e1a6cdcfd1..d068aabed41 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, how-to --- -# Sourcegraph integration +# Sourcegraph integration **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16556) in GitLab 12.5. > - Note that this integration is in BETA and deployed [behind a feature flag](#enable-the-sourcegraph-feature-flag) disabled by default. Self-managed instances can opt to enable it. @@ -23,9 +23,9 @@ NOTE: This feature requires user opt-in. After Sourcegraph has been enabled for your GitLab instance, you can choose to enable Sourcegraph [through your user preferences](#enable-sourcegraph-in-user-preferences). -## Set up for self-managed GitLab instances **(CORE ONLY)** +## Set up for self-managed GitLab instances **(FREE SELF)** -Before you can enable Sourcegraph code intelligence in GitLab you will need to: +Before you can enable Sourcegraph code intelligence in GitLab you must: - Enable the `sourcegraph` feature flag for your GitLab instance. - Configure a Sourcegraph instance with your GitLab instance as an external service. @@ -33,7 +33,7 @@ Before you can enable Sourcegraph code intelligence in GitLab you will need to: ### Enable the Sourcegraph feature flag NOTE: -If you are running a self-managed instance, the Sourcegraph integration will not be available +If you are running a self-managed instance, the Sourcegraph integration is unavailable unless the feature flag `sourcegraph` is enabled. This can be done from the Rails console by instance administrators. @@ -64,7 +64,7 @@ Feature.enable(:sourcegraph, Project.find_by_full_path('my_group/my_project')) If you are new to Sourcegraph, head over to the [Sourcegraph installation documentation](https://docs.sourcegraph.com/admin) and get your instance up and running. -If you are using an HTTPS connection to GitLab, you will need to [configure HTTPS](https://docs.sourcegraph.com/admin/http_https_configuration) for your Sourcegraph instance. +If you are using an HTTPS connection to GitLab, you must [configure HTTPS](https://docs.sourcegraph.com/admin/http_https_configuration) for your Sourcegraph instance. ### Connect your Sourcegraph instance to your GitLab instance @@ -79,23 +79,26 @@ You can skip this step if you already have your GitLab repositories searchable i 1. In GitLab, go to **Admin Area > Settings > General**. 1. Expand the **Sourcegraph** configuration section. 1. Check **Enable Sourcegraph**. -1. Set the Sourcegraph URL to your Sourcegraph instance, e.g., `https://sourcegraph.example.com`. +1. Set the Sourcegraph URL to your Sourcegraph instance, such as `https://sourcegraph.example.com`. - + ## Enable Sourcegraph in user preferences If a GitLab administrator has enabled Sourcegraph, you can enable this feature in your user preferences. -1. In GitLab, click your avatar in the top-right corner, then click **Settings**. On the left-hand nav, click **Preferences**. -1. Under **Integrations**, find the **Sourcegraph** section. -1. Check **Enable Sourcegraph**. +In GitLab: + +1. In the top-right corner, select your avatar. +1. Select **Preferences**. +1. In the **Integrations** section, select the checkbox under **Sourcegraph**. +1. Select **Save changes**.  ## Using Sourcegraph code intelligence -Once enabled, participating projects will have a code intelligence popover available in +Once enabled, participating projects display a code intelligence popover available in the following code views: - Merge request diffs @@ -114,7 +117,7 @@ When visiting one of these views, you can now hover over a code reference to see Sourcegraph powered code intelligence is available for all public projects on GitLab.com. -Support for private projects is currently not available for GitLab.com; +Support for private projects is not yet available for GitLab.com; follow the epic [&2201](https://gitlab.com/groups/gitlab-org/-/epics/2201) for updates. @@ -122,7 +125,7 @@ for updates. ### Sourcegraph isn't working -If you enabled Sourcegraph for your project but still it doesn't look like it's working, it might be because Sourcegraph has not indexed the project yet. You can check for Sourcegraph's availability of your project by visiting `https://sourcegraph.com/gitlab.com/<project-path>`replacing `<project-path>` with the path to your GitLab project. +If you enabled Sourcegraph for your project but it isn't working, Sourcegraph may not have indexed the project yet. You can check for Sourcegraph's availability of your project by visiting `https://sourcegraph.com/gitlab.com/<project-path>`replacing `<project-path>` with the path to your GitLab project. ## Sourcegraph and Privacy @@ -130,5 +133,5 @@ From Sourcegraph's [extension documentation](https://docs.sourcegraph.com/integr engine behind the native GitLab integration: > Sourcegraph integrations never send any logs, pings, usage statistics, or telemetry to Sourcegraph.com. -> They will only connect to Sourcegraph.com as required to provide code intelligence or other functionality on public code. +> They connect only to Sourcegraph.com as required to provide code intelligence or other functionality on public code. > As a result, no private code, private repository names, usernames, or any other specific data is sent to Sourcegraph.com. diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md index d30308cea7a..1a1b6cd101f 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -38,8 +38,11 @@ If your instance's URL is `https://example.com`, your API URL is `https://exampl Your GitLab personal access token enables your GitLab account to be accessed from Trello. -> Find it in GitLab by clicking on your avatar (upright corner), from which you access -your user **Settings** > **Access Tokens**. +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**. 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/vault.md b/doc/integration/vault.md index 3c49cd47509..362ae36389b 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -18,12 +18,15 @@ The following assumes you already have Vault installed and running. 1. **Get the OpenID Connect client ID and secret from GitLab:** - First you must create a GitLab application to obtain an application ID and secret for authenticating into Vault. To do this, sign in to GitLab and follow these steps: - - 1. On GitLab, click your avatar on the top-right corner, and select your user **Settings > Applications**. - 1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris), - making sure to select the **OpenID** scope. - 1. Save application. + First you must create a GitLab application to obtain an application ID and secret for authenticating into Vault. + To do this, sign in to GitLab and follow these steps: + + 1. In the top-right corner, select your avatar. + 1. Select **Edit profile**. + 1. In 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**. 1. Copy client ID and secret, or keep the page open for reference.  @@ -44,7 +47,7 @@ The following assumes you already have Vault installed and running. Success! Enabled oidc auth method at: oidc/ ``` -1. **Write the OIDC config:** +1. **Write the OIDC configuration:** Next, Vault needs to be given the application ID and secret generated by GitLab. @@ -67,7 +70,7 @@ The following assumes you already have Vault installed and running. Success! Data written to: auth/oidc/config ``` -1. **Write the OIDC Role Config:** +1. **Write the OIDC Role Configuration:** Now that Vault has a GitLab application ID and secret, it needs to know the [**Redirect URIs**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris) and scopes given to GitLab during the application creation process. The redirect URIs need to match where your Vault instance is running. The `oidc_scopes` field needs to include the `openid`. Similarly to the previous step, replace `your_application_id` with the generated application ID from GitLab: @@ -108,7 +111,7 @@ The following assumes you already have Vault installed and running. Here's a short explanation of what this command does: - 1. In the **Write the OIDC Role Config** (step 4), we created a role called + 1. In the **Write the OIDC Role Configuration** (step 4), we created a role called `demo`. We set `role=demo` so Vault knows which configuration we'd like to sign in with. 1. To set Vault to use the `OIDC` sign-in method, we set `-method=oidc`. |
