diff options
Diffstat (limited to 'doc/integration')
35 files changed, 460 insertions, 274 deletions
diff --git a/doc/integration/advanced_search/elasticsearch.md b/doc/integration/advanced_search/elasticsearch.md index e886f2a4b37..7b23eaa278a 100644 --- a/doc/integration/advanced_search/elasticsearch.md +++ b/doc/integration/advanced_search/elasticsearch.md @@ -172,7 +172,8 @@ Prerequisite: To enable advanced search: -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Advanced Search**. NOTE: @@ -219,8 +220,7 @@ The following Elasticsearch settings are available: | `URL` | The URL of your Elasticsearch instance. Use a comma-separated list to support clustering (for example, `http://host1, https://host2:9200`). If your Elasticsearch instance is password-protected, use the `Username` and `Password` fields described below. Alternatively, use inline credentials such as `http://<username>:<password>@<elastic_host>:9200/`. | | `Username` | The `username` of your Elasticsearch instance. | | `Password` | The password of your Elasticsearch instance. | -| `Number of Elasticsearch shards` | Elasticsearch indices are split into multiple shards for performance reasons. In general, you should use at least 5 shards, and indices with tens of millions of documents need to have more shards ([see below](#guidance-on-choosing-optimal-cluster-configuration)). Changes to this value do not take effect until the index is recreated. You can read more about tradeoffs in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/scalability.html). | -| `Number of Elasticsearch replicas` | Each Elasticsearch shard can have a number of replicas. These are a complete copy of the shard, and can provide increased query performance or resilience against hardware failure. Increasing this value increases total disk space required by the index. | +| `Number of Elasticsearch shards and replicas per index` | Elasticsearch indices are split into multiple shards for performance reasons. In general, you should use at least five shards. Indices with tens of millions of documents should have more shards ([see the guidance](#guidance-on-choosing-optimal-cluster-configuration)). Changes to this value do not take effect until you re-create the index. For more information about scalability and resilience, see the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/scalability.html). Each Elasticsearch shard can have a number of replicas. These replicas are a complete copy of the shard and can provide increased query performance or resilience against hardware failure. Increasing this value increases the total disk space required by the index. You can set the number of shards and replicas for each of the indices. | | `Limit the number of namespaces and projects that can be indexed` | Enabling this allows you to select namespaces and projects to index. All other namespaces and projects use database search instead. If you enable this option but do not select any namespaces or projects, none are indexed. [Read more below](#limit-the-number-of-namespaces-and-projects-that-can-be-indexed).| | `Using AWS OpenSearch Service with IAM credentials` | Sign your OpenSearch requests using [AWS IAM authorization](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html), [AWS EC2 Instance Profile Credentials](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-create-iam-instance-profile.html#getting-started-create-iam-instance-profile-cli), or [AWS ECS Tasks Credentials](https://docs.aws.amazon.com/AmazonECS/latest/userguide/task-iam-roles.html). Refer to [Identity and Access Management in Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html) for details of AWS hosted OpenSearch domain access policy configuration. | | `AWS Region` | The AWS region in which your OpenSearch Service is located. | @@ -377,7 +377,8 @@ You can improve the language support for Chinese and Japanese languages by utili To enable languages support: 1. Install the desired plugins, refer to [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/plugins/7.9/installation.html) for plugins installation instructions. The plugins must be installed on every node in the cluster, and each node must be restarted after installation. For a list of plugins, see the table later in this section. -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Locate **Custom analyzers: language support**. 1. Enable plugins support for **Indexing**. @@ -398,7 +399,8 @@ For guidance on what to install, see the following Elasticsearch language plugin To disable the Elasticsearch integration: -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Clear the **Elasticsearch indexing** and **Search with Elasticsearch enabled** checkboxes. 1. Select **Save changes**. @@ -414,7 +416,8 @@ To disable the Elasticsearch integration: ## Unpause Indexing -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Expand **Advanced Search**. 1. Clear the **Pause Elasticsearch indexing** checkbox. @@ -441,7 +444,8 @@ You can use zero-downtime reindexing to configure index settings or mappings tha To trigger the reindexing process: 1. Sign in to your GitLab instance as an administrator. -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Expand **Elasticsearch zero-downtime reindexing**. 1. Select **Trigger cluster reindexing**. @@ -458,7 +462,8 @@ While the reindexing is running, you can follow its progress under that same sec > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55681) in GitLab 13.12. -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Expand **Elasticsearch zero-downtime reindexing**, and you'll find the following options: @@ -506,7 +511,8 @@ Sometimes, you might want to abandon the unfinished reindex job and resume the i bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production ``` -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Expand **Advanced Search**. 1. Clear the **Pause Elasticsearch indexing** checkbox. @@ -578,11 +584,17 @@ is recreated with the correct up-to-date schema. ### All migrations must be finished before doing a major upgrade -Before doing a major version GitLab upgrade, you should have completed all +Before upgrading to a major GitLab version, you must complete all migrations that exist up until the latest minor version before that major -version. If you have halted migrations, these need to be resolved and -[retried](#retry-a-halted-migration) before proceeding with a major version -upgrade. Read more about [upgrading to a new major version](../../update/index.md#upgrading-to-a-new-major-version). +version. You must also resolve and [retry any halted migrations](#retry-a-halted-migration) +before proceeding with a major version upgrade. For more information, see [Upgrading to a new major version](../../update/index.md#upgrading-to-a-new-major-version). + +Migrations that have been removed are +[marked as obsolete](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63001). +If you upgrade GitLab before all pending advanced search migrations are completed, +any pending migrations that have been removed in the new version cannot be executed or retried. +In this case, you must +[re-create your index from scratch](elasticsearch_troubleshooting.md#last-resort-to-recreate-an-index). ## GitLab advanced search Rake tasks diff --git a/doc/integration/advanced_search/elasticsearch_troubleshooting.md b/doc/integration/advanced_search/elasticsearch_troubleshooting.md index 0c4895f34fa..e8eace7bd16 100644 --- a/doc/integration/advanced_search/elasticsearch_troubleshooting.md +++ b/doc/integration/advanced_search/elasticsearch_troubleshooting.md @@ -17,7 +17,7 @@ See [Starting a Rails console session](../../administration/operations/rails_con To list all available attributes: -1. Open the Rails console (`gitlab rails c`). +1. Open the Rails console (`sudo gitlab-rails console`). 1. Run the following command: ```ruby @@ -453,3 +453,41 @@ When using fine-grained access control with an IAM role or a role created using ``` To fix this, you need to [map the roles to users](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html#fgac-mapping) in Kibana. + +## Elasticsearch workers overload Sidekiq + +In some cases, Elasticsearch cannot connect to GitLab anymore because: + +- The Elasticsearch password has been updated on one side only (`Unauthorized [401] ... unable to authenticate user` errors). +- A firewall or network issue impairs connectivity (`Failed to open TCP connection to <ip>:9200` errors). + +These errors are logged in [`gitlab-rails/elasticsearch.log`](../../administration/logs/index.md#elasticsearchlog). To retrieve the errors, use [`jq`](../../administration/logs/log_parsing.md): + +```shell +$ jq --raw-output 'select(.severity == "ERROR") | [.error_class, .error_message] | @tsv' \ + gitlab-rails/elasticsearch.log | + sort | uniq -c +``` + +`Elastic` workers and [Sidekiq jobs](../../user/admin_area/index.md#background-jobs) could also appear much more often +because Elasticsearch frequently attempts to reindex if a previous job fails. +You can use [`fast-stats`](https://gitlab.com/gitlab-com/support/toolbox/fast-stats#usage) +or `jq` to count workers in the [Sidekiq logs](../../administration/logs/index.md#sidekiq-logs): + +```shell +$ fast-stats --print-fields=count,score sidekiq/current +WORKER COUNT SCORE +ElasticIndexBulkCronWorker 234 123456 +ElasticIndexInitialBulkCronWorker 345 12345 +Some::OtherWorker 12 123 +... + +$ jq '.class' sidekiq/current | sort | uniq -c | sort -nr + 234 "ElasticIndexInitialBulkCronWorker" + 345 "ElasticIndexBulkCronWorker" + 12 "Some::OtherWorker" +... +``` + +In this case, `free -m` on the overloaded GitLab node would also show +unexpectedly high `buff/cache` usage. diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index 09f16c76765..a7ab4ec5a84 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -30,8 +30,10 @@ To use Akismet: 1. Sign in or create a new account. 1. Select **Show** to reveal the API key, and copy the API key's value. 1. Sign in to GitLab as an administrator. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Reporting** (`/admin/application_settings/reporting`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > Reporting**. +1. Expand **Spam and Anti-bot Protection**. 1. Select the **Enable Akismet** checkbox. 1. Fill in the API key from step 3. 1. Save the configuration. diff --git a/doc/integration/alicloud.md b/doc/integration/alicloud.md index 4270444f0bb..db27cb78173 100644 --- a/doc/integration/alicloud.md +++ b/doc/integration/alicloud.md @@ -88,6 +88,6 @@ Sign in to the AliCloud platform and create an application on it. AliCloud gener 1. Save the configuration file. -1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - if you installed using Omnibus, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) +1. [Reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) + if you installed using the Linux package, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) if you installed from source. diff --git a/doc/integration/arkose.md b/doc/integration/arkose.md index 8f6cec0ac0a..cd0b80e5a66 100644 --- a/doc/integration/arkose.md +++ b/doc/integration/arkose.md @@ -48,6 +48,10 @@ sequenceDiagram end ``` +## How do we treat malicious sign-up attempts? + +Depending on the risk score received, a user might be required to perform up to three stages of [identity verification](../security/identity_verification.md) to register an account. + ## How do we treat malicious sign-in attempts? Users are not denied access if Arkose Protect considers they are malicious. However, diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index 07a750143d6..03b4980ad66 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -48,7 +48,7 @@ application. 1. Add the provider configuration: - For Omnibus GitLab: + For Linux package installations: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -65,7 +65,7 @@ application. ] ``` - For installations from source: + For self-compiled installations: ```yaml - { name: 'auth0', @@ -82,9 +82,9 @@ application. 1. Replace `<your_auth0_client_secret>` with the client secret from the Auth0 Console page. 1. Replace `<your_auth0_client_secret>` with the domain from the Auth0 Console page. 1. Reconfigure or restart GitLab, depending on your installation method: - - *If you installed from Omnibus GitLab,* - [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab. - - *If you installed from source,* + - If you installed using the Linux package, + [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). + - If you self-compiled your installation, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). On the sign-in page there should now be an Auth0 icon below the regular sign-in diff --git a/doc/integration/azure.md b/doc/integration/azure.md index 0d8c830c016..d49fa8f53f7 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -29,9 +29,13 @@ You must set the `uid_field`, which differs across the providers: | [`omniauth_openid_connect`](https://github.com/omniauth/omniauth_openid_connect/) | `sub` | Specify `uid_field` to use another field | To migrate from `omniauth-azure-oauth2` to `omniauth_openid_connect` you -must change the configuration: +must change the configuration. -- **For Omnibus installations** +::Tabs + +:::TabTitle Linux package (Omnibus) + +Remove some of the existing configuration and add new configuration as shown. ```diff gitlab_rails['omniauth_providers'] = [ @@ -60,7 +64,9 @@ gitlab_rails['omniauth_providers'] = [ ] ``` -- **For installations from source** +:::TabTitle Self-compiled (source) + +Remove some of the existing configuration and add new configuration as shown. ```diff - { name: 'azure_oauth2', @@ -88,10 +94,16 @@ gitlab_rails['omniauth_providers'] = [ } ``` +::EndTabs + To migrate for example from `omniauth-azure-activedirectory-v2` to `omniauth_openid_connect` you -must change the configuration: +must change the configuration. -- **For Omnibus installations** +::Tabs + +:::TabTitle Linux package (Omnibus) + +Remove some of the existing configuration and add new configuration as shown. ```diff gitlab_rails['omniauth_providers'] = [ @@ -120,7 +132,9 @@ gitlab_rails['omniauth_providers'] = [ ] ``` -- **For installations from source** +:::TabTitle Self-compiled (source) + +Remove some of the existing configuration and add new configuration as shown. ```diff - { name: 'azure_activedirectory_v2', @@ -148,6 +162,8 @@ gitlab_rails['omniauth_providers'] = [ } ``` +::EndTabs + For more information on other customizations, see [`gitlab_username_claim`](index.md#authentication-sources). ## Register an Azure application @@ -299,9 +315,9 @@ Alternatively, add the `User.Read.All` application permission. 1. Save the configuration file. -1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - if you installed using Omnibus, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) - if you installed from source. +1. [Reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) + if you installed using the Linux package, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) + if you self-compiled your installation. 1. Refresh the GitLab sign-in page. A Microsoft icon should display below the sign-in form. diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index 8019eccc421..81564e6eaae 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -110,9 +110,9 @@ you to use. from the Bitbucket application page. 1. Save the configuration file. -1. For the changes to take effect, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - if you installed using Omnibus GitLab, or [restart](../administration/restart_gitlab.md#installations-from-source) - if you installed from source. +1. For the changes to take effect, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) + if you installed using the Linux package, or [restart](../administration/restart_gitlab.md#installations-from-source) + if you self-compiled your installation. On the sign-in page there should now be a Bitbucket icon below the regular sign-in form. Select the icon to begin the authentication process. Bitbucket asks diff --git a/doc/integration/datadog.md b/doc/integration/datadog.md index edae3d0f9bd..affc707f504 100644 --- a/doc/integration/datadog.md +++ b/doc/integration/datadog.md @@ -27,7 +27,8 @@ project, group, or instance level: 1. *For project-level or group-level integrations:* In GitLab, go to your project or group. 1. *For instance-level integrations:* 1. Sign in to GitLab as a user with administrator access. - 1. On the top bar, select **Main menu > Admin**. + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Integrations**. 1. Scroll to **Add an integration**, and select **Datadog**. 1. Select **Active** to enable the integration. @@ -45,7 +46,7 @@ project, group, or instance level: <!-- vale gitlab.Spelling = YES --> 1. Optional. To define any custom tags for all spans at which the integration is being configured, enter one tag per line in **Tags**. Each line must be in the format `key:value`. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79665) in GitLab 14.8.) -1. Optional. Select **Test settings** to test your integration. +1. Optional. Select **Test settings**. 1. Select **Save changes**. When the integration sends data, you can view it in the [CI Visibility](https://app.datadoghq.com/ci) diff --git a/doc/integration/ding_talk.md b/doc/integration/ding_talk.md index 97ffab146a0..fd836b80208 100644 --- a/doc/integration/ding_talk.md +++ b/doc/integration/ding_talk.md @@ -86,6 +86,6 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene 1. Save the configuration file. -1. For the changes to take effect, if you installed: - - Using Omnibus, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - - From source, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). +1. For the changes to take effect, if you: + - Installed using the Linux package, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). + - Self-compiled your installation, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index c63c2e3fd24..b8cffc449ec 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -21,6 +21,16 @@ The references are automatically converted to links to the issues. You can keep the GitLab issue tracker enabled in parallel or disable it. When enabled, the **Issues** link in the GitLab menu always opens the internal issue tracker. When disabled, the link is not visible in the menu. +## Disable the GitLab issue tracker + +To disable the GitLab issue tracker: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Under **Issues**, turn off the toggle. +1. Select **Save changes**. + ## Configure an external issue tracker To enable an external issue tracker, you must configure the appropriate [integration](../user/project/integrations/index.md). @@ -28,6 +38,7 @@ To enable an external issue tracker, you must configure the appropriate [integra The following external issue tracker integrations are available: - [Bugzilla](../user/project/integrations/bugzilla.md) +- [ClickUp](../user/project/integrations/clickup.md) - [Custom Issue Tracker](../user/project/integrations/custom_issue_tracker.md) - [Engineering Workflow Management](../user/project/integrations/ewm.md) - [Jira](../integration/jira/index.md) diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index aeea798715f..4dd17d71602 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -107,8 +107,8 @@ Facebook. Facebook generates an app ID and secret key for you to use. 1. Save the configuration file. 1. For the changes to take effect: - - If you installed via Omnibus, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - - If you installed from source, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). + - If you installed using the Linux package, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). + - If you self-compiled your installation, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). On the sign in page there should now be a Facebook icon below the regular sign in form. Select the icon to begin the authentication process. Facebook asks the diff --git a/doc/integration/github.md b/doc/integration/github.md index 00303754d85..1f7b4f26476 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -81,7 +81,7 @@ your website could enable the covert redirect attack. ] ``` - 1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + 1. Save the file and [reconfigure](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) GitLab. - **For installations from source** @@ -187,9 +187,9 @@ To fix this issue, you must disable SSL verification: git config --global http.sslVerify false ``` -1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - if you installed using Omnibus, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) - if you installed from source. +1. [Reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) + if you installed using the Linux package, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) + if you self-compiled your installation. ### Signing in using GitHub Enterprise returns a 500 error @@ -233,7 +233,7 @@ and then connect it to your GitHub account To fix this issue, you must activate GitHub sign-in in GitLab: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Service sign-in** section, select **Connect to GitHub**. diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 59f122a5110..8767d1398ac 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -12,7 +12,7 @@ To enable the GitLab.com OmniAuth provider you must register your application wi GitLab.com generates an application ID and secret key for you to use. 1. Sign in to GitLab.com. -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Applications**. 1. Provide the required details for **Add new application**. @@ -111,10 +111,9 @@ GitLab.com generates an application ID and secret key for you to use. 1. Change `'YOUR_APP_ID'` to the Application ID from the GitLab.com application page. 1. Change `'YOUR_APP_SECRET'` to the secret from the GitLab.com application page. 1. Save the configuration file. -1. Based on how GitLab was installed, implement these changes by using - the appropriate method: - - Omnibus GitLab: [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - - Source: [restart GitLab](../administration/restart_gitlab.md#installations-from-source). +1. Implement these changes by using the appropriate method: + - For Linux package installations, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). + - For self-compiled installations, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). On the sign-in page, there should now be a GitLab.com icon following the regular sign-in form. Select the icon to begin the authentication process. diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index 0ba227c2a85..f43f4cb4f40 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -35,7 +35,7 @@ For more information about Gitpod, see the Gitpod [features](https://www.gitpod. With the Gitpod integration enabled for your GitLab instance, to enable it for yourself: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Preferences**. 1. Under **Preferences**, locate the **Integrations** section. 1. Select the **Enable Gitpod integration** checkbox and select **Save changes**. @@ -45,7 +45,8 @@ With the Gitpod integration enabled for your GitLab instance, to enable it for y For self-managed GitLab instances, a GitLab administrator must: 1. Enable the Gitpod integration in GitLab: - 1. On the top bar, select **Main menu > Admin**. + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Gitpod** configuration section. 1. Select the **Enable Gitpod integration** checkbox. @@ -59,16 +60,12 @@ GitLab users can then [enable the Gitpod integration for themselves](#enable-git You can launch Gitpod directly from GitLab in one of these ways: -- *From your project's page:* - 1. Go to your project, then go to the page you want to edit. - 1. Select the caret (**{chevron-lg-down}**) next to **Web IDE**, and select **Gitpod** - from the list: +- **From a project repository:** + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. In the upper right, select **Edit > Gitpod**. -  - - 1. Select **Open in Gitpod**. -- *From a merge request:* +- **From a merge request:** 1. Go to your merge request. - 1. In the upper-right corner, select **Code**, then select **Open in Gitpod**. + 1. In the upper-right corner, select **Code > Open in Gitpod**. Gitpod builds your development environment for your branch. diff --git a/doc/integration/google.md b/doc/integration/google.md index d60c1b43ed6..211c86b557a 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -9,29 +9,34 @@ info: To determine the technical writer assigned to the Stage/Group associated w To enable the Google OAuth 2.0 OmniAuth provider you must register your application with Google. Google generates a client ID and secret key for you to use. -## Enable Google OAuth - -In Google's side: - -1. Navigate to the [cloud resource manager](https://console.cloud.google.com/cloud-resource-manager) page -1. Select **Create Project** -1. Provide the project information: - - **Project name** - "GitLab" works just fine here. - - **Project ID** - Must be unique to all Google Developer registered applications. - Google provides a randomly generated Project ID by default. You can use - the randomly generated ID or choose a new one. -1. Refresh the page and you should see your new project in the list -1. Go to the [Google API Console](https://console.developers.google.com/apis/dashboard) -1. In the upper-left corner, select the previously created project -1. Select **Credentials** from the sidebar -1. Select **OAuth consent screen** and fill the form with the required information -1. In the **Credentials** tab, select **Create credentials > OAuth client ID** -1. Fill in the required information - - **Application type** - Choose "Web Application" - - **Name** - Use the default one or provide your own - - **Authorized JavaScript origins** -This isn't really used by GitLab but go - ahead and put `https://gitlab.example.com` - - **Authorized redirect URIs** - Enter your domain name followed by the +To enable Google OAuth, you must configure the: + +- Google Cloud Resource Manager +- Google API Console +- GitLab server + +## Configure the Google Cloud Resource Manager + +1. Go to the [Google Cloud Resource Manager](https://console.cloud.google.com/cloud-resource-manager). +1. Select **CREATE PROJECT**. +1. In **Project name**, enter `GitLab`. +1. In **Project ID**, Google provides a randomly generated project ID by default. + You can use this randomly generated ID or create a new one. If you create a new + ID, it must be unique to all Google Developer registered applications. + +To see your new project in the list, refresh the page. + +## Configure the Google API Console + +1. Go to the [Google API Console](https://console.developers.google.com/apis/dashboard). +1. In the upper-left corner, select your previously created project. +1. Select **OAuth consent screen** and complete the fields. +1. Select **Credentials > Create credentials > OAuth client ID**. +1. Complete the fields: + - **Application type**: Select **Web application**. + - **Name**: Use the default name or enter your own. + - **Authorized JavaScript origins**: Enter `https://gitlab.example.com`. + - **Authorized redirect URIs**: Enter your domain name followed by the callback URIs one at a time: ```plaintext @@ -39,22 +44,22 @@ In Google's side: https://gitlab.example.com/-/google_api/auth/callback ``` -1. You should now be able to see a Client ID and Client secret. Note them down +1. You should see a client ID and client secret. Note them down or keep this page open as you need them later. -1. To enable projects to access [Google Kubernetes Engine](../user/infrastructure/clusters/index.md), you must also - enable these APIs: +1. To enable projects to access [Google Kubernetes Engine](../user/infrastructure/clusters/index.md), + you must also enable the: - Google Kubernetes Engine API - Cloud Resource Manager API - Cloud Billing API - To do so you should: + To do so: 1. Go to the [Google API Console](https://console.developers.google.com/apis/dashboard). 1. Select **ENABLE APIS AND SERVICES** at the top of the page. 1. Find each of the above APIs. On the page for the API, select **ENABLE**. It may take a few minutes for the API to be fully functional. -On your GitLab server: +## Configure the GitLab server 1. Open the configuration file. @@ -83,8 +88,8 @@ On your GitLab server: { name: "google_oauth2", # label: "Provider name", # optional label for login button, defaults to "Google" - app_id: "YOUR_APP_ID", - app_secret: "YOUR_APP_SECRET", + app_id: "<YOUR_APP_ID>", + app_secret: "<YOUR_APP_SECRET>", args: { access_type: "offline", approval_prompt: "" } } ] @@ -100,8 +105,8 @@ On your GitLab server: args: { access_type: 'offline', approval_prompt: '' } } ``` -1. Change `YOUR_APP_ID` to the client ID from the Google Developer page -1. Similarly, change `YOUR_APP_SECRET` to the client secret +1. Replace `<YOUR_APP_ID>` with the client ID from the Google Developer page. +1. Replace `<YOUR_APP_SECRET>` with the client secret from the Google Developer page. 1. Make sure that you configure GitLab to use a fully-qualified domain name, as Google doesn't accept raw IP addresses. @@ -120,8 +125,8 @@ On your GitLab server: 1. Save the configuration file. 1. For the changes to take effect: - - If you installed via Omnibus, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - - If you installed from source, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). + - If you installed using the Linux package, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). + - If you self-compiled your installation, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). On the sign in page there should now be a Google icon below the regular sign in form. Select the icon to begin the authentication process. Google asks the diff --git a/doc/integration/img/gitpod_button_project_page_v13_4.png b/doc/integration/img/gitpod_button_project_page_v13_4.png Binary files differdeleted file mode 100644 index 55a70d89169..00000000000 --- a/doc/integration/img/gitpod_button_project_page_v13_4.png +++ /dev/null diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 3db02ed1221..760488b895f 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -117,8 +117,8 @@ Configure the GitLab integration with Jenkins in one of the following ways. GitLab recommends this approach for Jenkins integrations because it is easier to configure than the [webhook integration](#configure-a-webhook). -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Jenkins**. 1. Select the **Active** checkbox. 1. Select the events you want GitLab to trigger a Jenkins build for: @@ -134,7 +134,7 @@ than the [webhook integration](#configure-a-webhook). project. 1. If your Jenkins server requires authentication, enter the **Username** and **Password**. -1. To test the connection to Jenkins, select **Test settings**. +1. Optional. Select **Test settings**. 1. Select **Save changes**. ### Configure a webhook diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index 3f3511c3838..89afa998431 100644 --- a/doc/integration/jira/configure.md +++ b/doc/integration/jira/configure.md @@ -10,6 +10,8 @@ The Jira issue integration connects one or more GitLab projects to a Jira instan ## Configure the integration +> Authentication with Jira personal access tokens was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/8222) in GitLab 16.0. + Prerequisites: - Your GitLab installation must not use a [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configure-a-relative-url-for-gitlab). @@ -17,55 +19,51 @@ Prerequisites: the email address you used to create the token. - **For Jira Data Center or Jira Server**, you must have one of the following: - [Jira username and password](jira_server_configuration.md). - - Jira personal access token. + - Jira personal access token (GitLab 16.0 and later). You can enable the Jira issue integration by configuring your project settings in GitLab. -You can also configure these settings at the: - -- [Group level](../../user/admin_area/settings/project_integration_management.md#manage-group-level-default-settings-for-a-project-integration) -- [Instance level](../../user/admin_area/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration) for self-managed GitLab +You can configure these settings at the [group level](../../user/admin_area/settings/project_integration_management.md#manage-group-level-default-settings-for-a-project-integration) or at the [instance level](../../user/admin_area/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration) for self-managed GitLab. To configure your project settings in GitLab: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Jira**. -1. Select **Enable integration**. -1. Select **Trigger** actions. Your choice determines whether a mention of Jira issue - (in a GitLab commit, merge request, or both) creates a cross-link in Jira back to GitLab. -1. To comment in the Jira issue when a **Trigger** action is made in GitLab, select - **Enable comments**. -1. To transition Jira issues when a - [closing reference](../../user/project/issues/managing_issues.md#closing-issues-automatically) - is made in GitLab, select **Enable Jira transitions**. -1. Provide Jira configuration information: +1. In **Enable integration**, select the **Active** checkbox. +1. Provide connection details: - **Web URL**: Base URL for the Jira instance web interface you're linking to this GitLab project (for example, `https://jira.example.com`). - **Jira API URL**: Base URL for the Jira instance API (for example, `https://jira-api.example.com`). If this URL is not set, the **Web URL** value is used by default. For Jira Cloud, leave **Jira API URL** blank. - - **Authentication type**: From the dropdown list, select: - - **Basic** - - **Jira personal access token (Jira Data Center and Jira Server only)** - - **Email or username** (relevant to **Basic** authentication only): - - For Jira Cloud, enter an email. - - For Jira Data Center or Jira Server, enter a username. - - **New API token, password, or Jira personal access token**: - - For **Basic** authentication: - - For Jira Cloud, enter an API token. - - For Jira Data Center or Jira Server, enter a password. - - For **Jira personal access token** authentication, enter a personal access token. -1. To enable users to [view Jira issues](issues.md#view-jira-issues) inside the GitLab project, select **Enable Jira issues** and - enter a Jira project key. - - You can display issues only from a single Jira project in a given GitLab project. + - **Authentication method**: + - **Basic**: + - **Email or username**: + - For Jira Cloud, enter an email. + - For Jira Data Center or Jira Server, enter a username. + - **API token or password**: + - For Jira Cloud, enter an API token. + - For Jira Data Center or Jira Server, enter a password. + - **Jira personal access token** (only available for Jira Data Center and Jira Server): Enter a personal access token. +1. Provide trigger settings: + - Select **Commit**, **Merge request**, or both as triggers. When you mention a Jira issue ID in GitLab, + GitLab links to that issue. + - To add a comment to the Jira issue that links back to GitLab, select the + **Enable comments** checkbox and the information that the comment displays. + - To [transition Jira issues automatically](../../user/project/issues/managing_issues.md#closing-issues-automatically) in GitLab, + select the **Enable Jira transitions** checkbox. +1. In the **Jira issue matching** section: + - For **Jira issue regex**, [enter a regex pattern](issues.md#use-regular-expression). + - For **Jira issue prefix**, [enter a prefix](issues.md#use-a-prefix). +1. In the **Issues** section: + - To [view Jira issues](issues.md#view-jira-issues) in a GitLab project, select the **Enable Jira issues** checkbox and + enter a Jira project key. You can only view issues from a single Jira project in a GitLab project. WARNING: - If you enable Jira issues with this setting, all users with access to this GitLab project - can view all issues from the specified Jira project. + When you enable this setting, all users with access to that GitLab project + can view all issues from the Jira project you've specified. -1. To enable [issue creation for vulnerabilities](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability), select **Enable Jira issue creation from vulnerabilities**. -1. Select the **Jira issue type**. If the dropdown list is empty, select **Refresh** (**{retry}**) and try again. -1. To verify the Jira connection is working, select **Test settings**. + - To [create Jira issues for vulnerabilities](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability), select the **Enable Jira issue creation from vulnerabilities** checkbox. +1. Optional. Select **Test settings**. 1. Select **Save changes**. Your GitLab project can now interact with all Jira projects in your instance, and the project @@ -77,7 +75,7 @@ To configure the Jira issue integration for Jira Cloud, you must have a Jira Clo To create a Jira Cloud API token: 1. Sign in to [Atlassian](https://id.atlassian.com/manage-profile/security/api-tokens) - from an account with **write** access to Jira projects. + from an account with write access to Jira projects. The link opens the **API tokens** page. Alternatively, from your Atlassian profile, select **Account Settings > Security > Create and manage API tokens**. @@ -85,20 +83,20 @@ To create a Jira Cloud API token: 1. Select **Create API token**. 1. In the dialog, enter a label for your token and select **Create**. -To copy the API token, select **Copy** and paste the token somewhere safe. +To copy the API token, select **Copy**. ## Migrate from Jira Server to Jira Cloud in GitLab To migrate from Jira Server to Jira Cloud in GitLab and maintain your Jira integration: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Jira**. 1. In **Web URL**, enter the new Jira site URL (for example, `https://myjirasite.atlassian.net`). -1. In **Username or Email**, enter the username or email registered on your Jira profile. +1. In **Email or username**, enter the email registered on your Jira profile. 1. [Create a Jira Cloud API token](#create-a-jira-cloud-api-token), and copy the token value. -1. In **Password or API token**, paste the API token value. -1. Optional. Select **Test settings** to check if the connection is working. +1. In **API token or password**, paste the API token value. +1. Optional. Select **Test settings**. 1. Select **Save changes**. To update existing Jira issue references in GitLab to use the new Jira site URL, you must [invalidate the Markdown cache](../../administration/invalidate_markdown_cache.md#invalidate-the-cache). diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index e60eeb8fba1..67f51a6f472 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -20,6 +20,8 @@ If you use Jira Data Center or Jira Server, use the [Jira DVCS connector](dvcs/i ## Install the GitLab for Jira Cloud app **(FREE SAAS)** +> Link groups feature [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/331432) from Add namespace in GitLab 16.1. + Prerequisites: - You must have at least the Maintainer role for the GitLab group. @@ -35,7 +37,7 @@ To install the GitLab for Jira Cloud app: 1. To go to the configurations page, select **Get started**. You can always access this page in **Jira Settings > Apps > Manage apps**. -1. For a list of groups to link, select **Add namespace**. +1. For a list of groups to link, select **Link groups**. 1. To link to a group, select **Link**. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -50,11 +52,9 @@ After you add a group, the following data is synced to Jira for all projects in ## Update the GitLab for Jira Cloud app -Most updates to the app are fully automated and don't require any user interaction. See the -[Atlassian Marketplace documentation](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/) -for details. - -If the app requires additional permissions, [the update must first be manually approved in Jira](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/#changes-that-require-manual-customer-approval). +Most updates to the app are automatic. For more information, see the +[Atlassian documentation](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/). +If the app requires additional permissions, [you must manually approve the update in Jira](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/#changes-that-require-manual-customer-approval). ## Set up OAuth authentication for self-managed instances **(FREE SELF)** @@ -68,8 +68,9 @@ You must enable OAuth authentication to: To create an OAuth application: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Applications** (`/admin/applications`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Applications**. 1. Select **New application**. 1. In **Redirect URI**: - If you're installing the app from the official marketplace listing, enter `https://gitlab.com/-/jira_connect/oauth_callbacks`. @@ -78,7 +79,7 @@ To create an OAuth application: 1. In **Scopes**, select the `api` checkbox only. 1. Select **Save application**. 1. Copy the **Application ID** value. -1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). +1. On the left sidebar, select **Settings > General**. 1. Expand **GitLab for Jira App**. 1. Paste the **Application ID** value into **Jira Connect Application ID**. 1. Select **Save changes**. @@ -105,7 +106,11 @@ To create branches from Jira Cloud, [install the app manually](#install-the-gitl - The instance must be publicly available. - The instance must be on GitLab version 15.7 or later. - You must set up [OAuth authentication](#set-up-oauth-authentication-for-self-managed-instances). -- Your network must allow inbound and outbound connections between GitLab and Jira. +- Your network must allow inbound and outbound connections between GitLab and Jira. For self-managed instances that are behind a + firewall and cannot be directly accessed from the internet, you can: + - Open your firewall and only allow inbound traffic from [Atlassian IP addresses](https://support.atlassian.com/organization-administration/docs/ip-addresses-and-domains-for-atlassian-cloud-products/#Outgoing-Connections). + - Set up an internet-facing reverse proxy in front of your self-managed instance. To secure this proxy further, only allow inbound + traffic from [Atlassian IP addresses](https://support.atlassian.com/organization-administration/docs/ip-addresses-and-domains-for-atlassian-cloud-products/#Outgoing-Connections). ### Set up your instance @@ -113,8 +118,9 @@ To create branches from Jira Cloud, [install the app manually](#install-the-gitl To set up your self-managed instance for the GitLab for Jira Cloud app in GitLab 15.7 and later: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. 1. Expand **GitLab for Jira App**. 1. In **Jira Connect Proxy URL**, enter `https://gitlab.com`. 1. Select **Save changes**. @@ -207,8 +213,9 @@ You might want to use a proxy if you're managing multiple GitLab instances but o To configure your GitLab instance to serve as a proxy: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. 1. Expand **GitLab for Jira App**. 1. Select **Enable public key storage**. 1. Select **Save changes**. @@ -276,8 +283,9 @@ To resolve this issue, disable the **Jira Connect Proxy URL** setting. - In GitLab 15.8 and later: - 1. On the top bar, select **Main menu > Admin**. - 1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. On the left sidebar, select **Settings > General**. 1. Expand **GitLab for Jira App**. 1. Clear the **Jira Connect Proxy URL** text box. 1. Select **Save changes**. @@ -306,14 +314,9 @@ To resolve this issue on GitLab self-managed, follow one of the solutions below, - In all GitLab versions: - Re-install the GitLab for Jira Cloud app. This method might remove all synced data from the Jira development panel. -### `Failed to update GitLab version` error when setting up the GitLab for Jira Cloud app for self-managed instances +### `Failed to update the GitLab instance` for self-managed instances -When you set up the GitLab for Jira Cloud app, you might get the following message after you enter your -self-managed instance URL: - -```plaintext -Failed to update GitLab version. Please try again. -``` +When you set up the GitLab for Jira Cloud app, you might get a `Failed to update the GitLab instance` error after you enter your self-managed instance URL. To resolve this issue, ensure all prerequisites for your installation method have been met: diff --git a/doc/integration/jira/dvcs/index.md b/doc/integration/jira/dvcs/index.md index 0406fef3f1e..3ebbc9a921d 100644 --- a/doc/integration/jira/dvcs/index.md +++ b/doc/integration/jira/dvcs/index.md @@ -49,16 +49,14 @@ To create a GitLab application for DVCS: To configure Jira for DVCS: -1. Go to your DVCS account. **For Jira Server**, select **Settings (gear) > Applications > DVCS accounts**. -1. To create a new integration, for **Host**, select **GitLab** or **GitLab Self-Managed**. -1. For **Team or User Account**, enter the relative path of a top-level GitLab group that [the GitLab user](#create-a-gitlab-application-for-dvcs) can access. -1. In the **Host URL** text box, enter the appropriate URL. - Replace `<gitlab.example.com>` with your GitLab instance domain. - Use `https://<gitlab.example.com>`. -1. For **Client ID**, use the [**Application ID** value](#create-a-gitlab-application-for-dvcs). -1. For **Client Secret**, use the [**Secret** value](#create-a-gitlab-application-for-dvcs). -1. Ensure that all other checkboxes are selected. -1. To create the DVCS account, select **Add**, then **Continue**. +1. On the top bar, in the upper-right corner, select **Administration** (**{settings}**) > **Applications**. +1. On the left sidebar, select **DVCS accounts**. +1. From the **Host** dropdown list, select **GitLab** or **GitLab Self-Managed**. +1. For **Team or User Account**, enter the relative path of a [top-level GitLab group](#create-a-gitlab-application-for-dvcs) the GitLab user can access. +1. For **Host URL**, enter the domain of your GitLab instance. +1. From the **Client Configuration** dropdown list, select the [application link](#create-a-gitlab-application-for-dvcs) you've created. +1. Optional. Select or clear the **Auto Link New Repositories** and **Enable Smart Commits** checkboxes. +1. Select **Add**, then **Continue**. Jira redirects to GitLab where you have to confirm the authorization. GitLab then redirects back to Jira where the synced projects are displayed in the new account. The initial sync takes a few minutes. @@ -72,6 +70,10 @@ personal namespaces, repeat the previous steps with additional Jira DVCS account Jira imports commits and branches for GitLab projects every 60 minutes. To refresh the data manually in Jira: 1. Sign in to your Jira instance as the user you configured the integration with. -1. Go to **Settings (gear) > Applications**. -1. Select **DVCS accounts**. -1. In the **Last activity** column, next to the repository you want to refresh, select **Refresh** (**{retry}**). +1. On the top bar, in the upper-right corner, select **Administration** (**{settings}**) > **Applications**. +1. On the left sidebar, select **DVCS accounts**. +1. To refresh one or more repositories in a DVCS account: + - **For all repositories**, next to the account, select the ellipsis (**{ellipsis_h}**) > **Refresh repositories**. + - **For a single repository**: + 1. Select the account. + 1. Hover over the repository you want to refresh, and in the **Last activity** column, select **Click to sync repository** (**{retry}**). diff --git a/doc/integration/jira/dvcs/troubleshooting.md b/doc/integration/jira/dvcs/troubleshooting.md index 541c743b609..31038526d63 100644 --- a/doc/integration/jira/dvcs/troubleshooting.md +++ b/doc/integration/jira/dvcs/troubleshooting.md @@ -137,7 +137,7 @@ In the example above, the merge requests feature is disabled. To resolve the issue, enable the relevant feature: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Use the toggles to enable the features as needed. @@ -146,7 +146,7 @@ To resolve the issue, enable the relevant feature: To find webhook logs in a DVCS-linked project: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. On the left sidebar, select **Settings > Webhooks**. 1. Scroll down to **Project Hooks**. 1. Next to the log that points to your Jira instance, select **Edit**. diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md index 086d478ac15..7ed9d3ab329 100644 --- a/doc/integration/jira/issues.md +++ b/doc/integration/jira/issues.md @@ -27,7 +27,7 @@ git commit -m "GIT-1 this is a test commit" GitLab adds to that Jira issue: -- A reference in the **Web links** section +- A reference in the **Web links** section. - A comment in the **Activity** section that follows this format: ```plaintext @@ -41,9 +41,9 @@ GitLab adds to that Jira issue: - `COMMENTLINK`: Link to where the Jira issue is mentioned. - `ENTITY_TITLE`: Title of the GitLab commit (first line), issue, or merge request. -Only a single cross-reference comment appears in Jira per GitLab issue, merge request, or commit. +Only a single cross-reference appears in Jira per GitLab issue, merge request, or commit. For example, multiple comments on a GitLab merge request that reference a Jira issue -create only a single cross-reference comment back to that merge request in Jira. +create only a single cross-reference back to that merge request in Jira. You can [disable comments](#disable-comments-on-jira-issues) on issues. @@ -55,8 +55,8 @@ You can [disable comments](#disable-comments-on-jira-issues) on issues. With this integration, you can prevent merge requests from being merged if they do not refer to a Jira issue. To enable this feature: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. In the **Merge checks** section, select **Require an associated issue from Jira**. 1. Select **Save**. @@ -79,8 +79,8 @@ When you don't configure custom rules, the [default behavior](https://gitlab.com To define a regex pattern for Jira issue keys: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Jira**. 1. Go to the **Jira issue matching** section. 1. In the **Jira issue regex** text box, enter a regex pattern. @@ -92,8 +92,8 @@ For more information, see the [Atlassian documentation](https://confluence.atlas To define a prefix for Jira issue keys: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Jira**. 1. Go to the **Jira issue matching** section. 1. In the **Jira issue prefix** text box, enter a prefix. @@ -138,8 +138,8 @@ provided your GitLab administrator [has configured the integration](configure.md To view Jira issues: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues > Jira issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Plan > Jira issues**. The issues are sorted by **Created date** by default, with the most recently created issues listed at the top. @@ -173,10 +173,6 @@ of these filters: Enhancements to use these filters through the user interface [are planned](https://gitlab.com/groups/gitlab-org/-/epics/3622). -## Create a Jira issue for a vulnerability **(ULTIMATE)** - -You can create a Jira issue for a vulnerability from a [Vulnerability Page](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability). - ## Automatic issue transitions > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55773) in GitLab 13.11. @@ -217,3 +213,7 @@ adding a comment to the Jira issue: 1. Refer to the [Configure GitLab](configure.md) instructions. 1. Clear the **Enable comments** checkbox. + +## Related topics + +- [Create a Jira issue for a vulnerability](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability) diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index c840e1ebde5..672df5d615f 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -4,55 +4,55 @@ group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Jira Server credentials **(FREE)** +# Tutorial: Create Jira credentials **(FREE)** -To [integrate Jira with GitLab](configure.md), you should create a separate Jira user account for your Jira projects -to access projects in GitLab. This Jira user account must have write access to your Jira projects. -To create the credentials: +This tutorial shows you how to create Jira credentials. You can use your new Jira credentials to +configure the [Jira issue integration](configure.md) in GitLab for Jira Data Center or Jira Server. -1. [Create a Jira Server user](#create-a-jira-server-user). -1. [Create a Jira Server group for the user](#create-a-jira-server-group-for-the-user). +To create Jira credentials, here's what we're going to do: + +1. [Create a Jira user](#create-a-jira-user). +1. [Create a Jira group for the user](#create-a-jira-group-for-the-user). 1. [Create a permission scheme for the group](#create-a-permission-scheme-for-the-group). -Alternatively, you can use an existing Jira user account, provided the user belongs to a Jira group that -has been granted the **Administer Projects** [permission scheme](#create-a-permission-scheme-for-the-group). +Prerequisite: + +- You must have administrator access to the Jira instance. + +## Create a Jira user -After you select a Jira user account, [configure the integration](configure.md#configure-the-integration) in GitLab to use the account. +To create a Jira user: -## Create a Jira Server user +1. Sign in to your Jira instance as an administrator. +1. On the top bar, in the upper-right corner, select **Administration** (**{settings}**) > **User management**. +1. [Create a new user account](https://confluence.atlassian.com/adminjiraserver/create-edit-or-remove-a-user-938847025.html#Create,edit,orremoveauser-CreateusersmanuallyinJira) with write access to your Jira projects. -To create a Jira Server user: + Alternatively, you can use an existing user account, provided the user belongs to a Jira group that has been granted + the **Administer Projects** [permission scheme](#create-a-permission-scheme-for-the-group). -1. Sign in to your Jira instance as a Jira administrator. -1. On the top bar, in the upper-right corner, select the gear icon, then - select **User Management**. -1. [Create a new user account manually](https://confluence.atlassian.com/adminjiraserver/create-edit-or-remove-a-user-938847025.html#Create,edit,orremoveauser-CreateusersmanuallyinJira) with write access to - projects in Jira. - - **Email address**: You should use a valid email address. - - **Username**: Set the username to `gitlab`. - - **Password**: You must set a password because the Jira issue integration does not - support SSO such as SAML. + - In **Email address**, enter a valid email address. + - In **Username**, enter `gitlab`. + - In **Password**, enter a password (the Jira issue integration does not support SSO such as SAML). 1. Select **Create user**. Now that you've created a user named `gitlab`, it's time to create a group for the user. -## Create a Jira Server group for the user +## Create a Jira group for the user -To create a Jira Server group for the user: +To create a Jira group for the user: -1. Sign in to your Jira instance as a Jira administrator. -1. On the top bar, in the upper-right corner, select the gear icon, then - select **User Management**. +1. Sign in to your Jira instance as an administrator. +1. On the top bar, in the upper-right corner, select **Administration** (**{settings}**) > **User management**. 1. On the left sidebar, select **Groups**. -1. In the **Add group** section, enter a **Name** for the group (for example, +1. In the **Add group** section, enter a name for the group (for example, `gitlab-developers`), then select **Add group**. -1. To add the `gitlab` user to the `gitlab-developers` group, select **Edit members**. +1. To add the `gitlab` user to the new `gitlab-developers` group, select **Edit members**. The `gitlab-developers` group appears as a selected group. <!-- vale gitlab.BadPlurals = NO --> 1. In the **Add members to selected group(s)** section, enter `gitlab`. +<!-- vale gitlab.BadPlurals = YES --> 1. Select **Add selected users**. The `gitlab` user appears as a group member. -<!-- vale gitlab.BadPlurals = YES --> Now that you've added the `gitlab` user to a new group named `gitlab-developers`, it's time to create a permission scheme for the group. @@ -61,15 +61,18 @@ it's time to create a permission scheme for the group. To create a permission scheme for the group: -1. Sign in to your Jira instance as a Jira administrator. -1. On the top bar, in the upper-right corner, select the gear icon, then - select **Issues**. -1. On the left sidebar, select **Permission Schemes**. -1. Select **Add Permission Scheme**, enter a **Name** and (optionally) a - **Description**, then select **Add**. -1. In the permissions scheme list, locate your new permissions scheme, and - select **Permissions**. +1. Sign in to your Jira instance as an administrator. +1. On the top bar, in the upper-right corner, select **Administration** (**{settings}**) > **Issues**. +1. On the left sidebar, select **Permission schemes**. +1. Select **Add permission scheme**. +1. In the **Add permission scheme** dialog: + - Enter a name for the scheme. + - Optional. Enter a description for the scheme. +1. Select **Add**. +1. On the **Permission schemes** page, in the **Actions** column, select **Permissions** for the new scheme. 1. Next to **Administer Projects**, select **Edit**. +1. In the **Grant permission** dialog, for **Granted to**, select **Group**. 1. From the **Group** dropdown list, select `gitlab-developers`, then select **Grant**. -You need the new Jira username and password when you [configure the integration](configure.md#configure-the-integration) in GitLab. +You've done it! You can now use your new Jira username and password to configure the +[Jira issue integration](configure.md) in GitLab for Jira Data Center or Jira Server. diff --git a/doc/integration/jira/troubleshooting.md b/doc/integration/jira/troubleshooting.md index 586f09be751..d592455788d 100644 --- a/doc/integration/jira/troubleshooting.md +++ b/doc/integration/jira/troubleshooting.md @@ -16,7 +16,7 @@ set up for the [Jira integration](configure.md) has permission to: - Post comments on a Jira issue. - Transition the Jira issue. -Jira issue references and update comments do not work if the GitLab issue tracker is disabled. +Jira issue references and update comments do not work if the [GitLab issue tracker](../../integration/external-issue-tracker.md) is disabled. If you [restrict IP addresses for Jira access](https://support.atlassian.com/security-and-access-policies/docs/specify-ip-addresses-for-product-access/), make sure you add your self-managed IP addresses or [GitLab.com IP range](../../user/gitlab_com/index.md#ip-range) to the allowlist in Jira. diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index c2be5a5a91c..62441f6de8f 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -82,7 +82,7 @@ For source installations, make sure the `kerberos` gem group To avoid GitLab creating users automatically on their first sign in through Kerberos, don't set `kerberos` for `gitlab_rails['omniauth_allow_single_sign_on']`. -1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. [Reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. GitLab now offers the `negotiate` authentication method for signing in and HTTP Git access, enabling Git clients that support this authentication protocol @@ -106,7 +106,8 @@ set up GitLab to create a new account when a Kerberos user tries to sign in. If you're an administrator, you can link a Kerberos account to an existing GitLab account. To do so: -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Overview > Users**. 1. Select a user, then select the **Identities** tab. 1. From the **Provider** dropdown list, select **Kerberos**. @@ -115,7 +116,7 @@ existing GitLab account. To do so: If you're not an administrator: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Service sign-in** section, select **Connect Kerberos**. @@ -147,7 +148,8 @@ With that information at hand: ``` 1. As an administrator, you can confirm the new, blocked account: - 1. On the top bar, select **Main menu > Admin**. + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. 1. On the left sidebar, select **Overview > Users** and review the **Blocked** tab. 1. You can enable the user. 1. If `block_auto_created_users` is false, the Kerberos user is @@ -193,7 +195,7 @@ ignored and an LDAP identity is not linked. gitlab_rails['kerberos_simple_ldap_linking_allowed_realms'] = ['example.com','kerberos.example.com'] ``` -1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) +1. Save the file and [reconfigure](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) GitLab for the changes to take effect. --- @@ -284,7 +286,7 @@ this can happen in GitLab CI/CD jobs that [authenticate with the CI/CD job token gitlab_rails['kerberos_https'] = true ``` -1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. [Reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. After this change, Git remote URLs have to be updated to `https://gitlab.example.com:8443/mygroup/myproject.git` to use @@ -332,7 +334,7 @@ To disable password-based Kerberos sign-ins, remove the OmniAuth provider ] ``` -1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. [Reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. NOTE: Removing the `kerberos` OmniAuth provider can also resolve a rare diff --git a/doc/integration/mattermost/index.md b/doc/integration/mattermost/index.md index e1183f62225..0f9192f9a84 100644 --- a/doc/integration/mattermost/index.md +++ b/doc/integration/mattermost/index.md @@ -10,7 +10,7 @@ NOTE: This document applies to GitLab 11.0 and later. You can run a [GitLab Mattermost](https://gitlab.com/gitlab-org/gitlab-mattermost) -service on your GitLab server. Mattermost is not part of the single application that GitLab is. There is a good integration between [Mattermost and GitLab](https://mattermost.com/solutions/mattermost-gitlab/), and our Omnibus installer allows you to easily install it. But it is a separate application from a separate company. +service on your GitLab server. Mattermost is not part of the single application that GitLab is. There is a good integration between [Mattermost and GitLab](https://mattermost.com/solutions/mattermost-gitlab/), and our Linux package allows you to easily install it. But it is a separate application from a separate company. ## Prerequisites @@ -38,7 +38,7 @@ GitLab Mattermost is disabled by default. To enable it: 1. Confirm that GitLab Mattermost is reachable at `https://mattermost.example.com` and authorized to connect to GitLab. Authorizing Mattermost with GitLab allows users to use GitLab as an SSO provider. -The Omnibus GitLab package attempts to automatically authorize GitLab Mattermost with GitLab if the applications are running on the same server. +The Linux package attempts to automatically authorize GitLab Mattermost with GitLab if the applications are running on the same server. Automatic authorization requires access to the GitLab database. If the GitLab database is not available you need to manually authorize GitLab Mattermost for access to GitLab using the process described in the [Authorize GitLab Mattermost section](#authorize-gitlab-mattermost). @@ -86,7 +86,7 @@ Once the configuration is set, run `sudo gitlab-ctl reconfigure` to apply the ch ## Running GitLab Mattermost on its own server If you want to run GitLab and GitLab Mattermost on two separate servers the GitLab services are still set up on your GitLab Mattermost server, but they do not accept user requests or -consume system resources. You can use the following settings and configuration details on the GitLab Mattermost server to effectively disable the GitLab service bundled into the Omnibus package. +consume system resources. You can use the following settings and configuration details on the GitLab Mattermost server to effectively disable the GitLab service bundled into the Linux package. ```ruby mattermost_external_url 'http://mattermost.example.com' @@ -142,7 +142,7 @@ Save the changes and then run `sudo gitlab-ctl reconfigure`. If there are no err ## Specify numeric user and group identifiers -Omnibus GitLab creates a user and group `mattermost`. You can specify the +The Linux pacakage creates a user and group `mattermost`. You can specify the numeric identifiers for these users in `/etc/gitlab/gitlab.rb` as follows: ```ruby @@ -167,7 +167,7 @@ Run `sudo gitlab-ctl reconfigure` to apply the changes. ## Connecting to the bundled PostgreSQL database -If you need to connect to the bundled PostgreSQL database and are using the default Omnibus GitLab database configuration, you can connect as +If you need to connect to the bundled PostgreSQL database and are using the default Linux package database configuration, you can connect as the PostgreSQL superuser: ```shell @@ -176,14 +176,14 @@ sudo gitlab-psql -d mattermost_production ## Back up GitLab Mattermost -GitLab Mattermost is not included in the regular [Omnibus GitLab backup](../../raketasks/backup_restore.md) Rake task. +GitLab Mattermost is not included in the regular [Linux package backup](../../raketasks/backup_restore.md) Rake task. The general Mattermost [backup and disaster recovery](https://docs.mattermost.com/deploy/backup-disaster-recovery.html) documentation can be used as a guide on what needs to be backed up. ### Back up the bundled PostgreSQL database -If you need to back up the bundled PostgreSQL database and are using the default Omnibus GitLab database configuration, you can back up using this command: +If you need to back up the bundled PostgreSQL database and are using the default Linux package database configuration, you can back up using this command: ```shell sudo -i -u gitlab-psql -- /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/postgresql mattermost_production | gzip > mattermost_dbdump_$(date --rfc-3339=date).sql.gz @@ -286,8 +286,6 @@ Password: ## Configuring GitLab and Mattermost integrations -As of 12.3, the Mattermost GitLab plugin is shipped with Omnibus GitLab: [Mattermost Plugin for GitLab documentation](https://github.com/mattermost/mattermost-plugin-gitlab). - You can use the plugin to subscribe Mattermost to receive notifications about issues, merge requests, and pull requests as well as personal notifications regarding merge request reviews, unread messages, and task assignments. If you want to use slash commands to perform actions such as creating and viewing issues, or to trigger deployments use GitLab [Mattermost slash commands](../../user/project/integrations/mattermost_slash_commands.md). @@ -359,22 +357,22 @@ When upgrading the Mattermost version, it is essential to check the [Important Upgrade Notes](https://docs.mattermost.com/administration/important-upgrade-notes.html) for Mattermost to address any changes or migrations that need to be performed. -Starting with GitLab 11.0, GitLab Mattermost can be upgraded through the regular Omnibus GitLab update process. When upgrading previous versions of +Starting with GitLab 11.0, GitLab Mattermost can be upgraded through the regular Linux package update process. When upgrading previous versions of GitLab, the update process can only be used if Mattermost configuration settings have not been changed outside of GitLab. That is, no changes to the Mattermost `config.json` file have been made - either directly or via the Mattermost **System Console**, which saves changes to `config.json`. -If you are upgrading to at least GitLab 11.0 or have only configured Mattermost using `gitlab.rb`, you can upgrade GitLab using Omnibus and then run `gitlab-ctl reconfigure` to upgrade GitLab Mattermost to the latest version. +If you are upgrading to at least GitLab 11.0 or have only configured Mattermost using `gitlab.rb`, you can upgrade GitLab using the Linux package and then run `gitlab-ctl reconfigure` to upgrade GitLab Mattermost to the latest version. If this is not the case, there are two options: 1. Update [`gitlab.rb`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template#L706) with the changes done to `config.json`. This might require adding some parameters as not all - settings in `config.json` are available in `gitlab.rb`. Once complete, Omnibus GitLab should be + settings in `config.json` are available in `gitlab.rb`. Once complete, the Linux package should be able to upgrade GitLab Mattermost from one version to the next. -1. Migrate Mattermost outside of the directory controlled by Omnibus GitLab so it can be administered +1. Migrate Mattermost outside of the directory controlled by the Linux package so it can be administered and upgraded independently. Follow the [Mattermost Migration Guide](https://docs.mattermost.com/administration/migrating.html) to move your Mattermost configuration settings and data to another directory or server independent - from Omnibus GitLab. + from the Linux package. For a complete list of upgrade notices and special considerations for older versions, see the [Mattermost documentation](https://docs.mattermost.com/administration/important-upgrade-notes.html). @@ -387,7 +385,7 @@ GitLab 15.10 ships with Mattermost 7.8. Before upgrading, [connect to the bundle GitLab 14.6 ships with Mattermost 6.1 including potentially long running database migrations for Mattermost 6.0. For information about upgrading and for ways to reduce the downtime caused by those migrations, read the [Important Upgrade Notes](https://docs.mattermost.com/administration/important-upgrade-notes.html) for both versions. If you need to perform any manual migrations, [connect to the bundled PostgreSQL database](#connecting-to-the-bundled-postgresql-database). NOTE: -The Mattermost upgrade notes refer to different impacts when used with a PostgreSQL versus a MySQL database. The GitLab Mattermost included with the GitLab Linux packages uses a PostgreSQL database. +The Mattermost upgrade notes refer to different impacts when used with a PostgreSQL versus a MySQL database. The GitLab Mattermost included with the Linux package uses a PostgreSQL database. ## Upgrading GitLab Mattermost from versions prior to 11.0 @@ -492,7 +490,7 @@ If you encounter any issues [visit the GitLab Mattermost troubleshooting forum]( ### Upgrading GitLab Mattermost outside of GitLab -If you choose to upgrade Mattermost outside of the Omnibus GitLab automation, [follow this guide](https://docs.mattermost.com/administration/upgrade.html). +If you choose to upgrade Mattermost outside of the Linux package automation, [follow this guide](https://docs.mattermost.com/administration/upgrade.html). ## OAuth 2.0 sequence diagram diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 3e8c892cf38..6d08af225db 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -35,7 +35,7 @@ After adding an OAuth 2 application to an instance, you can use OAuth 2 to: To create a new application for your user: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Applications**. 1. Enter a **Name** and **Redirect URI**. @@ -74,7 +74,8 @@ To create a new application for a group: To create an application for your GitLab instance: -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Applications**. 1. Select **New application**. @@ -85,7 +86,7 @@ The user authorization step is automatically skipped for this application. To see all the application you've authorized with your GitLab credentials: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile** and then select **Applications**. 1. See the **Authorized applications** section. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index cd287d70ca3..2a871b97a28 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -35,6 +35,7 @@ GitLab supports the following OmniAuth providers. | [OpenID Connect](../administration/auth/oidc.md) | `openid_connect` | | [Salesforce](salesforce.md) | `salesforce` | | [SAML](saml.md) | `saml` | +| [Shibboleth](shibboleth.md) | `shibboleth` | | [Twitter](twitter.md) | `twitter` | ## Configure common settings @@ -234,7 +235,7 @@ created, you can activate an OmniAuth provider. For example, if you originally s provider like Twitter. 1. Sign in to GitLab with your GitLab credentials, LDAP, or another OmniAuth provider. -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Connected Accounts** section, select the OmniAuth provider, such as Twitter. @@ -252,8 +253,9 @@ By default, sign-in is enabled for all the OAuth providers configured in `config To enable or disable an OmniAuth provider: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. 1. Expand **Sign-in restrictions**. 1. In the **Enabled OAuth authentication sources** section, select or clear the checkbox for each provider you want to enable or disable. diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 3cdbc5303f8..9e44efc3e60 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -17,8 +17,9 @@ To use reCAPTCHA, first create a site and private key. 1. Go to the [Google reCAPTCHA page](https://www.google.com/recaptcha/admin). 1. To get reCAPTCHA v2 keys, fill in the form and select **Submit**. 1. Sign in to your GitLab server as an administrator. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Reporting** (`admin/application_settings/reporting`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > Reporting**. 1. Expand **Spam and Anti-bot Protection**. 1. In the reCAPTCHA fields, enter the keys you obtained in the previous steps. 1. Select the **Enable reCAPTCHA** checkbox. diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 8c43f038f86..40e1c4616a5 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -85,8 +85,8 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create 1. Save the configuration file. 1. For the changes to take effect: - - If you installed via Omnibus, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - - If you installed from source, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). + - If you installed using the Linux package, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). + - If you self-compiled your installation, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). On the sign in page, there should now be a Salesforce icon below the regular sign in form. Select the icon to begin the authentication process. Salesforce asks the user to sign in and authorize the GitLab application. diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md new file mode 100644 index 00000000000..db49b30fa21 --- /dev/null +++ b/doc/integration/shibboleth.md @@ -0,0 +1,91 @@ +--- +stage: Create +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 +--- + +# Shibboleth OmniAuth Provider **(FREE)** + +NOTE: +Use the [GitLab SAML integration](saml.md) to integrate specific Shibboleth identity providers (IdPs). For Shibboleth federation support (Discovery Service), use this document. + +To enable Shibboleth support in GitLab, use Apache instead of NGINX. Apache uses the `mod_shib2` module for Shibboleth authentication, and can pass attributes as headers to the OmniAuth Shibboleth provider. + +You can use the bundled NGINX provided in the Omnibus GitLab package to run a Shibboleth service provider on a different instance using a reverse proxy setup. However if you are not doing this, the bundled NGINX is difficult to configure. + +To enable the Shibboleth OmniAuth provider, you must: + +- [Install the Apache module](https://wiki.shibboleth.net/confluence/display/SP3/Apache). +- [Configure the Apache module](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache). + +To enable Shibboleth: + +1. Protect the OmniAuth Shibboleth callback URL: + + ```apache + <Location /users/auth/shibboleth/callback> + AuthType shibboleth + ShibRequestSetting requireSession 1 + ShibUseHeaders On + require valid-user + </Location> + + Alias /shibboleth-sp /usr/share/shibboleth + <Location /shibboleth-sp> + Satisfy any + </Location> + + <Location /Shibboleth.sso> + SetHandler shib + </Location> + ``` + +1. Exclude Shibboleth URLs from rewriting. Add `RewriteCond %{REQUEST_URI} !/Shibboleth.sso` and `RewriteCond %{REQUEST_URI} !/shibboleth-sp`. An example configuration: + + ```apache + # Apache equivalent of Nginx try files + RewriteEngine on + RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_URI} !/Shibboleth.sso + RewriteCond %{REQUEST_URI} !/shibboleth-sp + RewriteRule .* http://127.0.0.1:8080%{REQUEST_URI} [P,QSA] + RequestHeader set X_FORWARDED_PROTO 'https' + ``` + +1. Add Shibboleth to `/etc/gitlab/gitlab.rb` as an OmniAuth provider. + User attributes are sent from the Apache reverse proxy to GitLab as headers with the names from the Shibboleth attribute mapping. + Therefore the values of the `args` hash should be in the form of `"HTTP_ATTRIBUTE"`. + The keys in the hash are arguments to the [OmniAuth::Strategies::Shibboleth class](https://github.com/omniauth/omniauth-shibboleth-redux/blob/master/lib/omniauth/strategies/shibboleth.rb) and are documented by the [`omniauth-shibboleth-redux`](https://github.com/omniauth/omniauth-shibboleth-redux) gem (take care to note the version of the gem packaged with GitLab). + + The file should look like this: + + ```ruby + external_url 'https://gitlab.example.com' + gitlab_rails['internal_api_url'] = 'https://gitlab.example.com' + + # disable Nginx + nginx['enable'] = false + + gitlab_rails['omniauth_allow_single_sign_on'] = true + gitlab_rails['omniauth_block_auto_created_users'] = false + gitlab_rails['omniauth_providers'] = [ + { + "name" => "shibboleth", + "label" => "Text for Login Button", + "args" => { + "shib_session_id_field" => "HTTP_SHIB_SESSION_ID", + "shib_application_id_field" => "HTTP_SHIB_APPLICATION_ID", + "uid_field" => 'HTTP_EPPN', + "name_field" => 'HTTP_CN', + "info_fields" => { "email" => 'HTTP_MAIL'} + } + } + ] + ``` + + If some of your users appear to be authenticated by Shibboleth and Apache, but GitLab rejects their account with a URI that contains "e-mail is invalid" then your Shibboleth Identity Provider or Attribute Authority may be asserting multiple email addresses. In this instance, consider setting the `multi_values` argument to `first`. +1. For the changes to take effect: + - For Linux package installations, [reconfigure](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) GitLab. + - For self-compiled installations, [restart](../administration/restart_gitlab.md#installations-from-source) GitLab. + +On the sign in page, there should now be a **Sign in with: Shibboleth** icon below the regular sign-in form. Select the icon to begin the authentication process. You are redirected to the appropriate IdP server for your Shibboleth module configuration. If everything goes well, you are returned to GitLab and signed in. diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index d90a1fa2cca..366a862a9fb 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -49,7 +49,8 @@ You can skip this step if you already have your GitLab repositories searchable i ### Configure your GitLab instance with Sourcegraph -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Sourcegraph** configuration section. 1. Check **Enable Sourcegraph**. @@ -63,7 +64,7 @@ If a GitLab administrator has enabled Sourcegraph, you can enable this feature i In GitLab: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Preferences**. 1. In the **Integrations** section, select the checkbox under **Sourcegraph**. 1. Select **Save changes**. diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index 0ccda59f9b3..3edb0f25938 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -96,10 +96,9 @@ Twitter. Twitter generates a client ID and secret key for you to use. 1. Save the configuration file. -1. For the changes to take effect, if you installed: - - - Using Omnibus, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - - From source, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). +1. For the changes to take effect: + - For Linux package installations, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). + - For self-compiled installations, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). On the sign-in page, find the Twitter option below the regular sign-in form. Select the option to begin the authentication process. Twitter asks you to sign in and authorize the GitLab application. After authorization, you are returned to GitLab and signed in. diff --git a/doc/integration/vault.md b/doc/integration/vault.md index c505097d65c..c93e3e53949 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -26,7 +26,7 @@ GitLab by using our OpenID authentication feature. First you must create a GitLab application to obtain an application ID and secret for authenticating into Vault. To do this, sign in to GitLab and follow these steps: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Applications**. 1. Fill out the application **Name** and [**Redirect URI**](https://developer.hashicorp.com/vault/docs/auth/jwt#redirect-uris). |
