diff options
Diffstat (limited to 'doc/integration')
| -rw-r--r-- | doc/integration/datadog.md | 4 | ||||
| -rw-r--r-- | doc/integration/elasticsearch.md | 122 | ||||
| -rw-r--r-- | doc/integration/github.md | 298 | ||||
| -rw-r--r-- | doc/integration/gitlab.md | 36 | ||||
| -rw-r--r-- | doc/integration/img/enable_trello_powerup.png | bin | 17791 -> 0 bytes | |||
| -rw-r--r-- | doc/integration/jenkins.md | 3 | ||||
| -rw-r--r-- | doc/integration/jenkins_deprecated.md | 2 | ||||
| -rw-r--r-- | doc/integration/jira/connect-app.md | 11 | ||||
| -rw-r--r-- | doc/integration/kerberos.md | 2 | ||||
| -rw-r--r-- | doc/integration/mattermost/index.md | 10 | ||||
| -rw-r--r-- | doc/integration/oauth_provider.md | 25 | ||||
| -rw-r--r-- | doc/integration/openid_connect_provider.md | 7 | ||||
| -rw-r--r-- | doc/integration/saml.md | 6 | ||||
| -rw-r--r-- | doc/integration/trello_power_up.md | 49 |
14 files changed, 345 insertions, 230 deletions
diff --git a/doc/integration/datadog.md b/doc/integration/datadog.md index 4be0089703a..a9be7754cb9 100644 --- a/doc/integration/datadog.md +++ b/doc/integration/datadog.md @@ -26,7 +26,7 @@ project, group, or instance level: Copy this value, as you need it in a later step. 1. *For project-level or group-level integrations:* In GitLab, go to your project or group. 1. *For instance-level integrations:* - 1. Sign in to GitLab as a user with the [Administrator role](../user/permissions.md). + 1. Sign in to GitLab as a user with administrator access. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Integrations**. 1. Scroll to **Add an integration**, and select **Datadog**. @@ -42,6 +42,8 @@ project, group, or instance level: 1. Optional. If you use groups of GitLab instances (such as staging and production environments), provide an **Env** name. This value is attached to each span the integration generates. +1. Optional. 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. Select **Save changes**. diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 7356574a33e..4976f7c2664 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -14,22 +14,30 @@ Advanced Search provides faster search response times and [improved search featu ## Version requirements -<!-- Remember to update ee/lib/system_check/app/elasticsearch_check.rb if this changes --> +> Support for Elasticsearch 6.8 was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/350275) in GitLab 14.8 and is scheduled for removal in GitLab 15.0. -| GitLab version | Elasticsearch version | -|---------------------------------------------|-------------------------------| -| GitLab Enterprise Edition 13.9 or greater | Elasticsearch 6.8 through 7.x | -| GitLab Enterprise Edition 13.3 through 13.8 | Elasticsearch 6.4 through 7.x | -| GitLab Enterprise Edition 12.7 through 13.2 | Elasticsearch 6.x through 7.x | -| GitLab Enterprise Edition 11.5 through 12.6 | Elasticsearch 5.6 through 6.x | -| GitLab Enterprise Edition 9.0 through 11.4 | Elasticsearch 5.1 through 5.5 | -| GitLab Enterprise Edition 8.4 through 8.17 | Elasticsearch 2.4 with [Delete By Query Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/2.4/plugins-delete-by-query.html) installed | +| GitLab version | Elasticsearch version | +|----------------------|--------------------------| +| GitLab 14.8 or later | Elasticsearch 7.x - 7.17 | +| GitLab 13.9 - 14.7 | Elasticsearch 6.8 - 7.x | +| GitLab 13.3 - 13.8 | Elasticsearch 6.4 - 7.x | +| GitLab 12.7 - 13.2 | Elasticsearch 6.x - 7.x | +| GitLab 11.5 - 12.6 | Elasticsearch 5.6 - 6.x | The Elasticsearch Integration works with supported versions of Elasticsearch and follows Elasticsearch's [End of Life Policy](https://www.elastic.co/support/eol). When we change Elasticsearch supported versions in GitLab, we announce them in [deprecation notes](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations) in monthly release posts before we remove them. +### Versions not supported + +GitLab does not support: + +- [Amazon's OpenSearch](https://aws.amazon.com/blogs/opensource/opensearch-1-0-launches/) +(a [fork of Elasticsearch](https://www.elastic.co/what-is/opensearch)). Use AWS Elasticsearch Service 7.10 instead. +For updates, see [issue #327560](https://gitlab.com/gitlab-org/gitlab/-/issues/327560). +- Elasticsearch 8.0. For updates, see [issue #350600](https://gitlab.com/gitlab-org/gitlab/-/issues/350600). Use Elasticsearch 7.17 instead. + ## System requirements Elasticsearch requires additional resources to those documented in the @@ -155,8 +163,7 @@ may need to set the `production -> elasticsearch -> indexer_path` setting in you ## Enable Advanced Search -For GitLab instances with more than 50GB repository data you can follow the instructions for [Indexing large -instances](#indexing-large-instances) below. +For GitLab instances with more than 50GB repository data you can follow the instructions for [how to index large instances efficiently](#how-to-index-large-instances-efficiently) below. To enable Advanced Search, you must have administrator access to GitLab: @@ -466,7 +473,7 @@ The following are some available Rake tasks: | [`sudo gitlab-rake gitlab:elastic:index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Enables Elasticsearch indexing and run `gitlab:elastic:create_empty_index`, `gitlab:elastic:clear_index_status`, `gitlab:elastic:index_projects`, and `gitlab:elastic:index_snippets`. | | [`sudo gitlab-rake gitlab:elastic:pause_indexing`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Pauses Elasticsearch indexing. Changes are still tracked. Useful for cluster/index migrations. | | [`sudo gitlab-rake gitlab:elastic:resume_indexing`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Resumes Elasticsearch indexing. | -| [`sudo gitlab-rake gitlab:elastic:index_projects`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Iterates over all projects and queues Sidekiq jobs to index them in the background. | +| [`sudo gitlab-rake gitlab:elastic:index_projects`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Iterates over all projects, and queues Sidekiq jobs to index them in the background. It can only be used after the index is created. | | [`sudo gitlab-rake gitlab:elastic:index_projects_status`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Determines the overall status of the indexing. It is done by counting the total number of indexed projects, dividing by a count of the total number of projects, then multiplying by 100. | | [`sudo gitlab-rake gitlab:elastic:clear_index_status`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Deletes all instances of IndexStatus for all projects. Note that this command results in a complete wipe of the index, and it should be used with caution. | | [`sudo gitlab-rake gitlab:elastic:create_empty_index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Generates empty indexes (the default index and a separate issues index) and assigns an alias for each on the Elasticsearch side only if it doesn't already exist. | @@ -511,7 +518,7 @@ When performing a search, the GitLab index uses the following scopes: | `projects` | Project data (default) | | `blobs` | Code | | `issues` | Issue data | -| `merge_requests` | Merge Request data | +| `merge_requests` | Merge request data | | `milestones` | Milestone data | | `notes` | Note data | | `snippets` | Snippet data | @@ -543,7 +550,7 @@ For basic guidance on choosing a cluster configuration you may refer to [Elastic - The `Number of Elasticsearch shards` setting usually corresponds with the number of CPUs available in your cluster. For example, if you have a 3-node cluster with 4 cores each, this means you benefit from having at least 3*4=12 shards in the cluster. It's only possible to change the shards number by using [Split index API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-split-index.html) or by reindexing to a different index with a changed number of shards. - The `Number of Elasticsearch replicas` setting should most of the time be equal to `1` (each shard has 1 replica). Using `0` is not recommended, because losing one node corrupts the index. -### Indexing large instances +### How to index large instances efficiently This section may be helpful in the event that the other [basic instructions](#enable-advanced-search) cause problems @@ -741,6 +748,86 @@ However, some larger installations may wish to tune the merge policy settings: - Do not do a [force merge](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-forcemerge.html "Force Merge") to remove deleted documents. A warning in the [documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-forcemerge.html "Force Merge") states that this can lead to very large segments that may never get reclaimed, and can also cause significant performance or availability issues. +## Index large instances with dedicated Sidekiq nodes or processes + +Indexing a large instance can be a lengthy and resource-intensive process that has the potential +of overwhelming Sidekiq nodes and processes. This negatively affects the GitLab performance and +availability. + +As GitLab allows you to start multiple Sidekiq processes, you can create an +additional process dedicated to indexing a set of queues (or queue group). This way, you can +ensure that indexing queues always have a dedicated worker, while the rest of the queues have +another dedicated worker to avoid contention. + +For this purpose, use the [queue selector](../administration/operations/extra_sidekiq_processes.md#queue-selector) +option that allows a more general selection of queue groups using a [worker matching query](../administration/operations/extra_sidekiq_routing.md#worker-matching-query). + +To handle these two queue groups, we generally recommend one of the following two options. You can either: + +- [Use two queue groups on one single node](#single-node-two-processes). +- [Use two queue groups, one on each node](#two-nodes-one-process-for-each). + +For the steps below, consider: + +- `feature_category=global_search` as an indexing queue group with its own Sidekiq process. +- `feature_category!=global_search` as a non-indexing queue group that has its own Sidekiq process. + +### Single node, two processes + +To create both an indexing and a non-indexing Sidekiq process in one node: + +1. On your Sidekiq node, change the `/etc/gitlab/gitlab.rb` file to: + + ```ruby + sidekiq['enable'] = true + sidekiq['queue_selector'] = true + sidekiq['queue_groups'] = [ + "feature_category=global_search", + "feature_category!=global_search" + ] + ``` + +1. Save the file and [reconfigure GitLab](../administration/restart_gitlab.md) +for the changes to take effect. + +WARNING: +When starting multiple processes, the number of processes cannot exceed the number of CPU +cores you want to dedicate to Sidekiq. Each Sidekiq process can use only one CPU core, subject +to the available workload and concurrency settings. For more details, see how to +[run multiple Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). + +### Two nodes, one process for each + +To handle these queue groups on two nodes: + +1. To set up the indexing Sidekiq process, on your indexing Sidekiq node, change the `/etc/gitlab/gitlab.rb` file to: + + ```ruby + sidekiq['enable'] = true + sidekiq['queue_selector'] = true + sidekiq['queue_groups'] = [ + "feature_category=global_search" + ] + ``` + +1. Save the file and [reconfigure GitLab](../administration/restart_gitlab.md) +for the changes to take effect. + +1. To set up the non-indexing Sidekiq process, on your non-indexing Sidekiq node, change the `/etc/gitlab/gitlab.rb` file to: + + ```ruby + sidekiq['enable'] = true + sidekiq['queue_selector'] = true + sidekiq['queue_groups'] = [ + "feature_category!=global_search" + ] + ``` + + to set up a non-indexing Sidekiq process. + +1. Save the file and [reconfigure GitLab](../administration/restart_gitlab.md) +for the changes to take effect. + ## Reverting to Basic Search Sometimes there may be issues with your Elasticsearch index data and as such @@ -983,6 +1070,13 @@ however searches will only surface results that can be viewed by the user. Advanced Search will honor all permission checks in the application by filtering out projects that a user does not have access to at search time. +### Indexing fails with `error: elastic: Error 429 (Too Many Requests)` + +If `ElasticCommitIndexerWorker` Sidekiq workers are failing with this error during indexing, it usually means that Elasticsearch is unable to keep up with the concurrency of indexing request. To address change the following settings: + +- To decrease the indexing throughput you can decrease `Bulk request concurrency` (see [Advanced Search settings](#advanced-search-configuration)). This is set to `10` by default, but you change it to as low as 1 to reduce the number of concurrent indexing operations. +- If changing `Bulk request concurrency` didn't help, you can use the [queue selector](../administration/operations/extra_sidekiq_processes.md#queue-selector) option to [limit indexing jobs only to specific Sidekiq nodes](#index-large-instances-with-dedicated-sidekiq-nodes-or-processes), which should reduce the number of indexing requests. + ### Access requirements for the self-managed AWS OpenSearch Service To use the self-managed AWS OpenSearch Service with GitLab, configure your instance's domain access policies diff --git a/doc/integration/github.md b/doc/integration/github.md index d8877e069b8..a265d5c67ed 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -4,198 +4,218 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Integrate your GitLab instance with GitHub **(FREE SELF)** +# Use GitHub as an authentication provider **(FREE SELF)** -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. +You can integrate your GitLab instance with GitHub.com and GitHub Enterprise. +You can import projects from GitHub, or sign in to GitLab +with your GitHub credentials. -## Security check +## Create an OAuth app in GitHub -Some integrations risk compromising GitLab accounts. To help mitigate this -[OAuth 2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/) -vulnerability, append `/users/auth` to the end of the authorization callback URL. +To enable the GitHub OmniAuth provider, you need an OAuth 2.0 client ID and client +secret from GitHub: + +1. Sign in to GitHub. +1. [Create an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) + and provide the following information: + - The URL of your GitLab instance, such as `https://gitlab.example.com`. + - The authorization callback URL, such as, `https://gitlab.example.com/users/auth`. + Include the port number if your GitLab instance uses a non-default port. + +### Check for security vulnerabilities + +For some integrations, the [OAuth 2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/) +vulnerability can compromise GitLab accounts. +To mitigate this vulnerability, append `/users/auth` to the authorization +callback URL. However, as far as we know, GitHub does not validate the subdomain part of the `redirect_uri`. -This means that a subdomain takeover, an XSS, or an open redirect on any subdomain of +Therefore, a subdomain takeover, an XSS, or an open redirect on any subdomain of your website could enable the covert redirect attack. -## Enabling GitHub OAuth +## Enable GitHub OAuth in GitLab -To enable the GitHub OmniAuth provider, you need an OAuth 2 Client ID and Client Secret from GitHub. To get these credentials, sign into GitHub and follow their procedure for [Creating an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app). +1. [Configure the initial settings](omniauth.md#configure-initial-settings) in GitLab. -When you create an OAuth 2 app in GitHub, you need the following information: +1. Edit the GitLab configuration file using the following information: -- The URL of your GitLab instance, such as `https://gitlab.example.com`. -- The authorization callback URL; in this case, `https://gitlab.example.com/users/auth`. Include the port number if your GitLab instance uses a non-default port. + | GitHub setting | Value in the GitLab configuration file | Description | + |----------------|----------------------------------------|-------------------------| + | Client ID | `YOUR_APP_ID` | OAuth 2.0 client ID | + | Client secret | `YOUR_APP_SECRET` | OAuth 2.0 client secret | + | URL | `https://github.example.com/` | GitHub deployment URL | -See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. + - **For Omnibus installations** -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. + 1. Open the `/etc/gitlab/gitlab.rb` file. -| Setting from GitHub | Substitute in the GitLab configuration file | Description | -|:---------------------|:---------------------------------------------|:------------| -| Client ID | `YOUR_APP_ID` | OAuth 2 Client ID | -| Client Secret | `YOUR_APP_SECRET` | OAuth 2 Client Secret | -| URL | `https://github.example.com/` | GitHub Deployment URL | + For GitHub.com, update the following section: -Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server: + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: "github", + # label: "Provider name", # optional label for login button, defaults to "GitHub" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET", + args: { scope: "user:email" } + } + ] + ``` -**For Omnibus installations** + For GitHub Enterprise, update the following section and replace + `https://github.example.com/` with your GitHub URL: -1. Edit `/etc/gitlab/gitlab.rb`: + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: "github", + # label: "Provider name", # optional label for login button, defaults to "GitHub" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET", + url: "https://github.example.com/", + args: { scope: "user:email" } + } + ] + ``` - For GitHub.com: + 1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab. - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - name: "github", - # label: "Provider name", # optional label for login button, defaults to "GitHub" - app_id: "YOUR_APP_ID", - app_secret: "YOUR_APP_SECRET", - args: { scope: "user:email" } - } - ] - ``` + - **For installations from source** - For GitHub Enterprise: + 1. Open the `config/gitlab.yml` file. - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - name: "github", - # label: "Provider name", # optional label for login button, defaults to "GitHub" - app_id: "YOUR_APP_ID", - app_secret: "YOUR_APP_SECRET", - url: "https://github.example.com/", - args: { scope: "user:email" } - } - ] - ``` + For GitHub.com, update the following section: - **Replace `https://github.example.com/` with your GitHub URL.** + ```yaml + - { name: 'github', + # label: 'Provider name', # optional label for login button, defaults to "GitHub" + app_id: 'YOUR_APP_ID', + app_secret: 'YOUR_APP_SECRET', + args: { scope: 'user:email' } } + ``` -1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect. + For GitHub Enterprise, update the following section and replace + `https://github.example.com/` with your GitHub URL: ---- - -**For installations from source** + ```yaml + - { name: 'github', + # label: 'Provider name', # optional label for login button, defaults to "GitHub" + app_id: 'YOUR_APP_ID', + app_secret: 'YOUR_APP_SECRET', + url: "https://github.example.com/", + args: { scope: 'user:email' } } + ``` -1. Navigate to your repository and edit `config/gitlab.yml`: + 1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source) + GitLab. - For GitHub.com: +1. Refresh the GitLab sign-in page. A GitHub icon should display below the + sign-in form. - ```yaml - - { name: 'github', - # label: 'Provider name', # optional label for login button, defaults to "GitHub" - app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET', - args: { scope: 'user:email' } } - ``` +1. Select the icon. Sign in to GitHub and authorize the GitLab application. - For GitHub Enterprise: +## Troubleshooting - ```yaml - - { name: 'github', - # label: 'Provider name', # optional label for login button, defaults to "GitHub" - app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET', - url: "https://github.example.com/", - args: { scope: 'user:email' } } - ``` +### Imports from GitHub Enterprise with a self-signed certificate fail - **Replace `https://github.example.com/` with your GitHub URL.** +When you import projects from GitHub Enterprise using a self-signed +certificate, the imports fail. -1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect. +To fix this issue, you must disable SSL verification: ---- +1. Set `verify_ssl` to `false` in the configuration file. -1. Refresh the GitLab sign in page. You should now see a GitHub icon below the regular sign in form. + - **For Omnibus installations** -1. Click the icon to begin the authentication process. GitHub asks the user to sign in and authorize the GitLab application. + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: "github", + # label: "Provider name", # optional label for login button, defaults to "GitHub" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET", + url: "https://github.example.com/", + verify_ssl: false, + args: { scope: "user:email" } + } + ] + ``` -## GitHub Enterprise with self-signed Certificate + - **For installations from source** -If you are attempting to import projects from GitHub Enterprise with a self-signed -certificate and the imports are failing, you must disable SSL verification. -It should be disabled by adding `verify_ssl` to `false` in the provider configuration -and changing the global Git `sslVerify` option to `false` in the GitLab server. + ```yaml + - { name: 'github', + # label: 'Provider name', # optional label for login button, defaults to "GitHub" + app_id: 'YOUR_APP_ID', + app_secret: 'YOUR_APP_SECRET', + url: "https://github.example.com/", + verify_ssl: false, + args: { scope: 'user:email' } } + ``` -For Omnibus package: +1. Change the global Git `sslVerify` option to `false` on the GitLab server. -```ruby -gitlab_rails['omniauth_providers'] = [ - { - name: "github", - # label: "Provider name", # optional label for login button, defaults to "GitHub" - app_id: "YOUR_APP_ID", - app_secret: "YOUR_APP_SECRET", - url: "https://github.example.com/", - verify_ssl: false, - args: { scope: "user:email" } - } -] -``` + - **For Omnibus installations** -You must also disable Git SSL verification on the server hosting GitLab. + ```ruby + omnibus_gitconfig['system'] = { "http" => ["sslVerify = false"] } + ``` -```ruby -omnibus_gitconfig['system'] = { "http" => ["sslVerify = false"] } -``` + - **For installations from source** -For installation from source: + ```shell + git config --global http.sslVerify false + ``` -```yaml -- { name: 'github', - # label: 'Provider name', # optional label for login button, defaults to "GitHub" - app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET', - url: "https://github.example.com/", - verify_ssl: false, - args: { scope: 'user:email' } } -``` +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. -You must also disable Git SSL verification on the server hosting GitLab. +### Signing in using GitHub Enterprise returns a 500 error -```shell -git config --global http.sslVerify false -``` +This error can occur because of a network connectivity issue between your +GitLab instance and GitHub Enterprise. -For the changes to take effect, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) if you installed -via Omnibus, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) if you installed from source. +To check for a connectivity issue: -## Troubleshooting +1. Go to the [`production.log`](../administration/logs.md#productionlog) + on your GitLab server and look for the following error: -### Error 500 when trying to sign in to GitLab via GitHub Enterprise + ``` plaintext + Faraday::ConnectionFailed (execution expired) + ``` -Check the [`production.log`](../administration/logs.md#productionlog) -on your GitLab server to obtain further details. If you are getting the error like -`Faraday::ConnectionFailed (execution expired)` in the log, there may be a connectivity issue -between your GitLab instance and GitHub Enterprise. To verify it, [start the rails console](../administration/operations/rails_console.md#starting-a-rails-console-session) -and run the commands below replacing `<github_url>` with the URL of your GitHub Enterprise instance: +1. [Start the rails console](../administration/operations/rails_console.md#starting-a-rails-console-session) + and run the following commands. Replace `<github_url>` with the URL of your + GitHub Enterprise instance: -```ruby -uri = URI.parse("https://<github_url>") # replace `GitHub-URL` with the real one here -http = Net::HTTP.new(uri.host, uri.port) -http.use_ssl = true -http.verify_mode = 1 -response = http.request(Net::HTTP::Get.new(uri.request_uri)) -``` + ```ruby + uri = URI.parse("https://<github_url>") # replace `GitHub-URL` with the real one here + http = Net::HTTP.new(uri.host, uri.port) + http.use_ssl = true + http.verify_mode = 1 + response = http.request(Net::HTTP::Get.new(uri.request_uri)) + ``` -If you are getting a similar `execution expired` error, it confirms the theory about the -network connectivity. In that case, make sure that the GitLab server is able to reach your -GitHub enterprise instance. +1. If a similar `execution expired` error is returned, this confirms the error is + caused by a connectivity issue. Make sure the GitLab server can reach + your GitHub Enterprise instance. ### Signing in using your GitHub account without a pre-existing GitLab account is not allowed -If you're getting the message `Signing in using your GitHub account without a pre-existing -GitLab account is not allowed. Create a GitLab account first, and then connect it to your -GitHub account` when signing in, in GitLab: +When you sign in to GitLab, you get the following error: + +```plaintext +Signing in using your GitHub account without a pre-existing +GitLab account is not allowed. Create a GitLab account first, +and then connect it to your GitHub account +``` + +To fix this issue, you must activate GitHub sign-in in GitLab: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Social sign-in** section, select **Connect to GitHub**. - -After that, you should be able to sign in via GitHub successfully. diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 2dd357e50a6..74ae9bb1998 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -24,7 +24,12 @@ GitLab.com generates an application ID and secret key for you to use. http://your-gitlab.example.com/users/auth/gitlab/callback ``` - The first link is required for the importer and second for the authorization. + The first link is required for the importer and second for authentication. + + If you: + + - Plan to use the importer, you can leave scopes as they are. + - Only want to use this application for authentication, we recommend using a more minimal set of scopes. `read_user` is sufficient. 1. Select **Save application**. 1. You should now see an **Application ID** and **Secret**. Keep this page open as you continue @@ -57,7 +62,9 @@ GitLab.com generates an application ID and secret key for you to use. # label: "Provider name", # optional label for login button, defaults to "GitLab.com" app_id: "YOUR_APP_ID", app_secret: "YOUR_APP_SECRET", - args: { scope: "api" } + args: { scope: "read_user" # optional: defaults to the scopes of the application + , client_options: { site: "https://gitlab.example.com/api/v4" } + } } ] ``` @@ -71,7 +78,8 @@ GitLab.com generates an application ID and secret key for you to use. label: "Provider name", # optional label for login button, defaults to "GitLab.com" app_id: "YOUR_APP_ID", app_secret: "YOUR_APP_SECRET", - args: { scope: "api", client_options: { site: "https://gitlab.example.com/api/v4" } } + args: { scope: "read_user" # optional: defaults to the scopes of the application + , client_options: { site: "https://gitlab.example.com/api/v4" } } } ] ``` @@ -83,7 +91,7 @@ GitLab.com generates an application ID and secret key for you to use. # label: 'Provider name', # optional label for login button, defaults to "GitLab.com" app_id: 'YOUR_APP_ID', app_secret: 'YOUR_APP_SECRET', - args: { scope: 'api' } } + args: { "client_options": { "site": 'https://gitlab.example.com/api/v4' } } ``` Or, for installations from source to authenticate against a different GitLab instance: @@ -93,7 +101,7 @@ GitLab.com generates an application ID and secret key for you to use. label: 'Provider name', # optional label for login button, defaults to "GitLab.com" app_id: 'YOUR_APP_ID', app_secret: 'YOUR_APP_SECRET', - args: { scope: 'api', "client_options": { "site": 'https://gitlab.example.com/api/v4' } } + args: { "client_options": { "site": 'https://gitlab.example.com/api/v4' } } ``` 1. Change `'YOUR_APP_ID'` to the Application ID from the GitLab.com application page. @@ -101,7 +109,6 @@ GitLab.com generates an application ID and secret key for you to use. 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). @@ -110,3 +117,20 @@ regular sign-in form. Select the icon to begin the authentication process. GitLab.com asks the user to sign in and authorize the GitLab application. If everything goes well, the user is returned to your GitLab instance and is signed in. + +## Reduce access privileges on sign in + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337663) in GitLab 14.8 [with a flag](../administration/feature_flags.md) named `omniauth_login_minimal_scopes`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `omniauth_login_minimal_scopes`. On GitLab.com, this feature is not available. + +If you use a GitLab instance for authentication, you can reduce access rights when an OAuth application is used for sign in. + +Any OAuth application can advertise the purpose of the application with the +authorization parameter: `gl_auth_type=login`. If the application is +configured with `api` or `read_api`, the access token is issued with +`read_user` for login, because no higher permissions are needed. + +The GitLab OAuth client is configured to pass this parameter, but other +applications can also pass it. diff --git a/doc/integration/img/enable_trello_powerup.png b/doc/integration/img/enable_trello_powerup.png Binary files differdeleted file mode 100644 index f80d0eadc0b..00000000000 --- a/doc/integration/img/enable_trello_powerup.png +++ /dev/null diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index bae52622966..b86643c7279 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -44,7 +44,7 @@ Grant a GitLab user access to the relevant GitLab projects. 1. Grant the user permission to the GitLab projects. If you're integrating Jenkins with many GitLab projects, consider granting the - user the administrator access level. Otherwise, add the user to each project + user administrator access. Otherwise, add the user to each project and grant the Developer role. ## Grant Jenkins access to the GitLab API @@ -137,6 +137,7 @@ than the [webhook integration](#configure-a-webhook). - Merge request - Tag push 1. Enter the **Jenkins server URL**. +1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](../user/project/integrations/overview.md#ssl-verification). 1. Enter the **Project name**. The project name should be URL-friendly, where spaces are replaced with underscores. To ensure diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index 8da3118cf2c..57219b18047 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -19,7 +19,7 @@ This service was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/1600) i Integration includes: - Trigger Jenkins build after push to repository -- Show build status on Merge Request page +- Show build status on Merge request page Requirements: diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index 597293ae5ca..ebe8a0f1af4 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -10,8 +10,7 @@ You can integrate GitLab and Jira Cloud using the [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app in the Atlassian Marketplace. -NOTE: -Only Jira users with the administrator role can install or configure +Only Jira users with administrator access can install or configure the GitLab.com for Jira Cloud app. ## Install the GitLab.com for Jira Cloud app **(FREE SAAS)** @@ -23,7 +22,7 @@ We recommend the GitLab.com for Jira Cloud app, because data is synchronized in real time. The DVCS connector updates data only once per hour. The user configuring the GitLab.com for Jira Cloud app must have -at least the [Maintainer](../../user/permissions.md) role in the GitLab.com namespace. +at least the Maintainer role in the GitLab.com namespace. This integration method supports [Smart Commits](dvcs.md#smart-commits). @@ -43,7 +42,7 @@ To install the GitLab.com for Jira Cloud app:  1. If not already signed in to GitLab.com, you must sign in as a user with - [Maintainer](../../user/permissions.md) permissions to add namespaces. + the Maintainer role to add namespaces.  1. To open the list of available namespaces, select **Add namespace**. @@ -91,10 +90,10 @@ self-managed GitLab instances with Jira Cloud, you can either: You can configure your Atlassian Cloud instance to allow you to install applications from outside the Marketplace, which allows you to install the application: -1. Sign in to your Jira instance as a user with an Administrator role. +1. Sign in to your Jira instance as an administrator. 1. Place your Jira instance into [development mode](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-2--enable-development-mode). -1. Sign in to your GitLab application as an [administrator](../../user/permissions.md). +1. Sign in to your GitLab application as a user with administrator access. 1. Install the GitLab application from your self-managed GitLab instance, as described in the [Atlassian developer guides](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-3--install-and-test-your-app): 1. In your Jira instance, go to **Apps > Manage Apps** and select **Upload app**: diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 04a02b8fa68..17a81419ad0 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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" --- diff --git a/doc/integration/mattermost/index.md b/doc/integration/mattermost/index.md index 02fe0f4ea71..6ac4faa5a35 100644 --- a/doc/integration/mattermost/index.md +++ b/doc/integration/mattermost/index.md @@ -372,19 +372,11 @@ For a complete list of upgrade notices and special considerations for older vers ## Upgrading GitLab Mattermost to 14.6 -GitLab 14.6 includes Mattermost 6.1, and also includes the migrations for Mattermost 6.0. For information about upgrading and for ways to reduce the downtime of those migrations, read the [Important Upgrade Notes](https://docs.mattermost.com/administration/important-upgrade-notes.html) for both versions. +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. -If you need to connect in the database to perform any manual migrations, run the following: - -```console -sudo gitlab-psql -d mattermost_production -``` - -You can then run the necessary queries that are described in the [Important Upgrade Notes](https://docs.mattermost.com/administration/important-upgrade-notes.html). - ## Upgrading GitLab Mattermost from versions prior to 11.0 With version 11.0, GitLab introduced breaking changes which affected Mattermost configuration. diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index ff144d9985b..adfb2fad941 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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 --- @@ -86,25 +86,24 @@ To create an application for your GitLab instance: When creating application in the **Admin Area** , you can mark it as _trusted_. The user authorization step is automatically skipped for this application. -## Expiring Access Tokens +## Expiring access tokens > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21745) in GitLab 14.3. -By default, all new applications expire access tokens after 2 hours. In GitLab 14.2 and -earlier, OAuth access tokens had no expiration. +WARNING: +The ability to opt-out of expiring access tokens [is deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/340848). +All existing integrations should be updated to support access token refresh. -All integrations should update to support access token refresh. +Access tokens expire in two hours which means that integrations that use them must support generating new access +tokens at least every two hours. Existing: -When creating new applications, you can opt-out of expiry for backward compatibility by clearing -**Expire access tokens** when creating them. The ability to opt-out -[is deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/340848). - -Existing: - -- Applications can have expiring access tokens. Edit the application and select - **Expire access tokens** to enable them. +- Applications can have expiring access tokens: + 1. Edit the application. + 1. Select **Expire access tokens**. - Tokens must be [revoked](../api/oauth2.md#revoke-a-token) or they don't expire. +When applications are deleted, all grants and tokens associated with the application are also deleted. + ## Authorized applications Every application you authorize with your GitLab credentials is shown diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index e85231d1c25..1254b29bfb9 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -35,12 +35,15 @@ is select the `openid` scope in the application settings. ## Settings discovery -If your client allows importing OIDC settings from a discovery URL, you can use the following URL to automatically find the correct settings: +If your client allows importing OIDC settings from a discovery URL, you can use +the following URL to automatically find the correct settings for GitLab.com: ```plaintext -https://gitlab.example.com/.well-known/openid-configuration +https://gitlab.com/.well-known/openid-configuration ``` +Similar URLs can be used for other GitLab instances. + ## Shared information The following user information is shared with clients: diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 61d09b4e173..95bf835147d 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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 type: reference --- @@ -367,7 +367,7 @@ The requirements are the same as the previous settings: - The IdP must pass Group information to GitLab. - GitLab must know where to look for the groups in the SAML response, as well as - which group(s) grant the user an administrator role. + which groups grant the user administrator access. ```yaml { name: 'saml', @@ -504,7 +504,7 @@ omniauth: Keep in mind that every sign in attempt redirects to the SAML server; you cannot sign in using local credentials. Ensure at least one of the -SAML users has an administrator role. +SAML users has administrator access. 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/trello_power_up.md b/doc/integration/trello_power_up.md index 96150440e53..8a8952cb594 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -6,44 +6,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Trello Power-Up **(FREE)** -The GitLab Trello Power-Up enables you to seamlessly attach -GitLab **merge requests** to Trello cards. +You can use the Trello Power-Up for GitLab to attach +GitLab merge requests to Trello cards.  -## Configuring the Power-Up +## Configure the Power-Up -In order to get started, you must configure your Power-Up. +To configure a Power-Up for a Trello board: -In Trello: +1. Go to your Trello board. +1. Select **Power-Ups** and find the **GitLab** row. +1. Select **Enable**. +1. Select **Settings** (the gear icon). +1. Select **Authorize Account**. +1. Enter the [GitLab API URL](#get-the-api-url) and [personal access token](../user/profile/personal_access_tokens.md#create-a-personal-access-token) with the **API** scope. +1. Select **Save**. -1. Go to your Trello board -1. Select `Power-Ups` to see a listing of all the available Power-Ups -1. Look for a row that says `GitLab` and select the `Enable` button -1. Select the `Settings` (gear) icon -1. In the popup menu, select `Authorize Account` +## Get the API URL -In this popup, fill in your `API URL` and `Personal Access Token`. After that, you can attach any merge request to any Trello card on your selected Trello board. - -## What is my API URL? - -Your API URL should be your GitLab instance URL with `/api/v4` appended in the end of the URL. -For example, if your GitLab instance URL is `https://gitlab.com`, your API URL would be `https://gitlab.com/api/v4`. -If your instance's URL is `https://example.com`, your API URL is `https://example.com/api/v4`. - - - -## What is my Personal Access Token? - -Your GitLab personal access token enables your GitLab account to be accessed -from Trello. - -To find it in GitLab: - -1. In the top-right corner, select your avatar. -1. Select **Edit profile**. -1. On the left sidebar, select **Access Tokens**. - -Learn more about generating a personal access token in the -[Personal Access Token Documentation](../user/profile/personal_access_tokens.md). -Don't forget to check the API scope checkbox! +Your API URL is your GitLab instance URL with `/api/v4` appended at the end of the URL. +For example, if your GitLab instance URL is `https://gitlab.com`, your API URL is `https://gitlab.com/api/v4`. +If your instance URL is `https://example.com`, your API URL is `https://example.com/api/v4`. |
