diff options
Diffstat (limited to 'doc/integration')
34 files changed, 473 insertions, 289 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/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..6e27d535b63 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -5,10 +5,11 @@ 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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109 "Elasticsearch Merge Request") in GitLab 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](../subscriptions/bronze_starter.md) 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 @@ -152,7 +153,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,8 +176,7 @@ 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 @@ -186,7 +186,7 @@ To enable Advanced Search, you need to have admin access to GitLab: 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 +202,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 +218,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). | @@ -260,13 +260,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 +276,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: @@ -315,12 +314,12 @@ used by the GitLab Advanced Search integration. ### Pause the indexing -In the **Admin Area > Settings > General > Advanced Search** section, select the +In the **Admin Area > Settings > 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. +buffered and caught up after resuming. -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. +The indexing will also be automatically paused when the [**Trigger cluster reindexing**](#trigger-the-reindex-via-the-advanced-search-administration) button is used, and resumes when the reindexing completes or aborts. ### Setup @@ -332,7 +331,7 @@ 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 +# You can find this value under Admin Area > Settings > Advanced Search > URL export CLUSTER_URL="http://localhost:9200" export PRIMARY_INDEX="gitlab-production" export SECONDARY_INDEX="gitlab-production-$(date +%s)" @@ -431,16 +430,16 @@ To trigger the re-index from `primary` index: 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 +1. Resume the indexing - Under **Admin Area > Settings > General > Advanced Search**, uncheck the **Pause Elasticsearch Indexing** setting and save. + Under **Admin Area > Settings > Advanced Search**, uncheck the **Pause Elasticsearch Indexing** setting and save. ### 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. -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 +448,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 +462,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 +518,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 @@ -599,7 +598,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 @@ -823,7 +822,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: @@ -994,7 +993,7 @@ 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 +your instance and search using other data sources (such as PostgreSQL data and Git data). ### Data recovery: Elasticsearch is a secondary data store only diff --git a/doc/integration/github.md b/doc/integration/github.md index 858614a0571..8c2a48225dd 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 | |:---------------------|:---------------------------------------------|:------------| diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 3bd3099e390..94a26ee792b 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -11,7 +11,7 @@ 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. Sign in to GitLab.com. 1. On the upper right corner, click on your avatar and go to your **Settings**. diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index 05f129e6049..cc6e08259fa 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -10,45 +10,55 @@ 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. Select your avatar in the top-right corner, then select **Settings > Preferences**. +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/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..81d352cfee6 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,7 +64,7 @@ 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 @@ -166,7 +166,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 +205,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..463f8a6efaa 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. @@ -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: @@ -79,13 +78,11 @@ 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, click your profile avatar. +1. Click **Settings > Applications** to display the form to create a new application. +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,15 @@ 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 uncheck 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 +111,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 +172,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 +210,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 +229,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. @@ -252,7 +251,7 @@ resynchronize the information. To do so: 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. -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. @@ -285,7 +284,7 @@ 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." @@ -314,6 +313,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..d8297ac87b3 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,7 +109,7 @@ 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**. @@ -117,7 +117,7 @@ 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**. + **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 +291,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..8f1c625d142 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -1,83 +1,87 @@ --- -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` +GitLab supports two ways of adding a new OAuth 2 application to an instance: -## Adding an application through the profile +- As a regular user, for applications owned by an individual. +- Through the Admin Area menu for instance-wide apps. -In order to add a new application via your profile, navigate to -**Profile Settings > Applications** and select **New Application**. +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`. - +## Add an application through the profile -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. +To add a new application via your profile, select your avatar in the top right, and then select +**Settings > Applications**. You can then 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. -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. +When you 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..54fa5b0a732 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. @@ -168,10 +168,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 +198,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 +213,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 +238,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 +326,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 +346,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..1053c612782 --- /dev/null +++ b/doc/integration/security_partners/index.md @@ -0,0 +1,17 @@ +--- +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/) + +<!-- 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..80be6daa3a8 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. @@ -28,20 +28,20 @@ Taking the trigger term as `project-name`, the commands are: | `/project-name deploy <from> to <to>` | Deploy from the `<from>` environment to the `<to>` environment | | `/project-name run <job name> <arguments>` | Execute [ChatOps](../ci/chatops/README.md) job `<job name>` on `master` | -Note that if you are using the [GitLab Slack application](../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..aff0bb2f841 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -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,9 +79,9 @@ 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 @@ -95,7 +95,7 @@ If a GitLab administrator has enabled Sourcegraph, you can enable this feature i ## 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 +114,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 +122,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 +130,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/vault.md b/doc/integration/vault.md index 3c49cd47509..d3102c2616a 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -44,7 +44,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 +67,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 +108,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`. |
