diff options
Diffstat (limited to 'doc/integration')
27 files changed, 240 insertions, 64 deletions
diff --git a/doc/integration/README.md b/doc/integration/README.md index 7d38dd6222a..9c3d39327f8 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w comments: false --- -# GitLab integrations +# GitLab integrations **(FREE)** GitLab can be integrated with external services for enhanced functionality. @@ -59,8 +59,7 @@ GitLab can be integrated with the following enhancements: or [Kroki](../administration/integration/kroki.md) to use diagrams in AsciiDoc and Markdown documents. - Attach merge requests to [Trello](trello_power_up.md) cards. - Enable integrated code intelligence powered by [Sourcegraph](sourcegraph.md). -- Add [Elasticsearch](elasticsearch.md) for [Advanced Search](../user/search/advanced_global_search.md), - [Advanced System Search](../user/search/advanced_search_syntax.md), and faster searching. +- Add [Elasticsearch](elasticsearch.md) for [Advanced Search](../user/search/advanced_search.md). ## Integrations diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index a2720c82fe7..d2e20b225cc 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -4,7 +4,7 @@ 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 --- -# Akismet +# Akismet **(FREE)** GitLab leverages [Akismet](https://akismet.com/) to protect against spam. GitLab uses Akismet to prevent the creation of spam issues on public projects. Issues diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index 7e531682faf..6b8b07c3707 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -4,7 +4,7 @@ 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 --- -# Auth0 OmniAuth Provider +# Auth0 OmniAuth Provider **(FREE SELF)** To enable the Auth0 OmniAuth provider, you must create an Auth0 account, and an application. diff --git a/doc/integration/azure.md b/doc/integration/azure.md index c83ef650f54..61a8290e664 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -4,11 +4,12 @@ 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 --- -# Microsoft Azure OAuth2 OmniAuth Provider +# Microsoft Azure OAuth2 OmniAuth Provider **(FREE)** NOTE: Per Microsoft, this provider uses the [older Azure Active Directory v1.0 endpoint](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/v1-protocols-oauth-code). Microsoft documentation suggests that you should use the [OpenID Connect protocol to use the v2 endpoints](../administration/auth/oidc.md#microsoft-azure) for new projects. +To use v2 endpoints via OmniAuth, please follow [Microsoft Azure OAuth2 OmniAuth Provider v2 instructions](#microsoft-azure-oauth2-omniauth-provider-v2). To enable the Microsoft Azure OAuth2 OmniAuth provider, you must register your application with Azure. Azure generates a client ID and secret key for you to use. @@ -94,3 +95,106 @@ sign in and authorize the GitLab application. If successful, you are returned to Read [Enable OmniAuth for an Existing User](omniauth.md#enable-omniauth-for-an-existing-user) for information on how existing GitLab users can connect to their newly-available Azure AD accounts. + +## Microsoft Azure OAuth2 OmniAuth Provider v2 + +In order to use v2 endpoints provided by Microsoft Azure Active Directory you must to configure it via Azure OAuth2 OmniAuth Provider v2. + +### Registering an Azure application + +To enable the Microsoft Azure OAuth2 OmniAuth provider, you must register your application with Azure. Azure generates a client ID and secret key for you to use. + +Sign in to the [Azure Portal](https://portal.azure.com), and follow the instructions in +the [Microsoft Quickstart documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app). + +As you go through the Microsoft procedure, keep the following in mind: + +- If you have multiple instances of Azure Active Directory, you can switch to the desired tenant. +- You're setting up a Web application. +- The redirect URI requires the URL of the Azure OAuth callback of your GitLab + installation. For example, `https://gitlab.example.com/users/auth/azure_activedirectory_v2/callback`. + The type dropdown should be set to **Web**. +- The `client ID` and `client secret` are terms associated with OAuth 2. In some Microsoft documentation, + the terms may be listed as `Application ID` and `Application Secret`. +- If you need to generate a new client secret, follow the Microsoft documentation + for [creating a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#create-a-new-application-secret). +- Save the client ID and client secret for your new app, as the client secret is only + displayed one time. + +### Adding API permissions (scopes) + +Once you have created an application, follow the [Microsoft Quickstart documentation to expose a web API](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). Be sure to add the following delegated permissions under the Microsoft Graph API: + +- `email` +- `openid` +- `profile` + +### Configuring GitLab + +1. On your GitLab server, open the configuration file. + + For Omnibus GitLab: + + ```shell + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```shell + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. Refer to [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) + for initial settings. + +1. Add the provider configuration: + + For Omnibus GitLab: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "azure_activedirectory_v2", + "args" => { + "client_id" => "CLIENT ID", + "client_secret" => "CLIENT SECRET", + "tenant_id" => "TENANT ID", + } + } + ] + ``` + + For installations from source: + + ```yaml + - { name: 'azure_activedirectory_v2', + args: { client_id: "CLIENT ID", + client_secret: "CLIENT SECRET", + tenant_id: "TENANT ID" } } + ``` + + The `base_azure_url` is optional and can be added for different locales; + such as `base_azure_url: "https://login.microsoftonline.de"`. + + The `scope` parameter is optional and can be added to `args`. Default `scope` is: `openid profile email`. + +1. Replace `CLIENT ID`, `CLIENT SECRET`, and `TENANT ID` with the values you got above. + +1. Save the configuration file. + +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,* + [restart GitLab](../administration/restart_gitlab.md#installations-from-source). + +On the sign-in page, you should now see a Microsoft icon below the regular sign-in form. +Select the icon to begin the authentication process. Microsoft then asks you to +sign in and authorize the GitLab application. If successful, you are returned to GitLab and signed in. + +Read [Enable OmniAuth for an Existing User](omniauth.md#enable-omniauth-for-an-existing-user) +for information on how existing GitLab users can connect to their newly available Azure AD accounts. diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index 8999f4da9a2..a492b891248 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -4,7 +4,7 @@ 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 --- -# Integrate your GitLab server with Bitbucket Cloud +# Integrate your GitLab server with Bitbucket Cloud **(FREE)** NOTE: Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an @@ -26,6 +26,11 @@ To enable the Bitbucket OmniAuth provider you must register your application with Bitbucket.org. Bitbucket generates an application ID and secret key for you to use. +WARNING: +To help prevent an [OAuth 2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/) +vulnerability in which users' GitLab accounts could be compromised, append `/users/auth` +to the end of the Bitbucket authorization callback URL. + 1. Sign in to [Bitbucket.org](https://bitbucket.org). 1. Navigate to your individual user settings (**Bitbucket settings**) or a team's settings (**Manage team**), depending on how you want the application registered. @@ -40,9 +45,7 @@ you to use. - **Application description:** *(Optional)* Fill this in if you wish. - **Callback URL:** (Required in GitLab versions 8.15 and greater) The URL to your GitLab installation, such as - `https://gitlab.example.com/users/auth`. Be sure to append `/users/auth` to - the end of the callback URL to prevent an - [OAuth2 convert redirect](http://tetraph.com/covert_redirect/) vulnerability. + `https://gitlab.example.com/users/auth`. Leaving this field empty [results in an `Invalid redirect_uri` message](https://confluence.atlassian.com/bitbucket/oauth-faq-338365710.html). - **URL:** The URL to your GitLab installation, such as `https://gitlab.example.com`. diff --git a/doc/integration/cas.md b/doc/integration/cas.md index b444143b03e..59f41ab4368 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -4,7 +4,7 @@ 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 --- -# CAS OmniAuth Provider +# CAS OmniAuth Provider **(FREE)** To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab supplies to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for back-channel logout. diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 389c7aabdf5..5c9149ef49b 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -11,10 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w This document describes how to enable Advanced Search. After Advanced Search is enabled, you'll have the benefit of fast search response times -and the advantage of the following special searches: - -- [Advanced Search](../user/search/advanced_global_search.md) -- [Advanced Search Syntax](../user/search/advanced_search_syntax.md) +and the advantage of the [special searches](../user/search/advanced_search.md). ## Version requirements @@ -41,7 +38,7 @@ each node should have: - [Memory](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_memory): 8 GiB (minimum). - [CPU](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_cpus): Modern processor with multiple cores. -- [Storage](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_disks): Use SSD storage. You will need enough storage for 50% of the total size of your Git repositories. +- [Storage](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_disks): Use SSD storage. The total storage size of all Elasticsearch nodes is about 50% of the total size of your Git repositories. It includes one primary and one replica. A few notes on CPU and storage: @@ -56,6 +53,12 @@ A few notes on CPU and storage: to any spinning media for Elasticsearch. In testing, nodes that use SSD storage see boosts in both query and indexing performance. +- We've introduced the [`estimate_cluster_size`](#gitlab-advanced-search-rake-tasks) + Rake task to estimate the Advanced Search storage requirements in advance, which +- The [`estimate_cluster_size`](#gitlab-advanced-search-rake-tasks) Rake task estimates the + Advanced Search storage requirements in advance. The Rake task uses total repository size + for the calculation. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221177) in GitLab 13.10. + Keep in mind, these are **minimum requirements** for Elasticsearch. Heavily-used Elasticsearch clusters will likely require considerably more resources. @@ -218,8 +221,8 @@ The following Elasticsearch settings are available: | `Elasticsearch indexing` | Enables or disables Elasticsearch indexing and creates an empty index if one does not already exist. You may want to enable indexing but disable search in order to give the index time to be fully completed, for example. Also, keep in mind that this option doesn't have any impact on existing data, this only enables/disables the background indexer which tracks data changes and ensures new data is indexed. | | `Pause Elasticsearch indexing` | Enables or disables temporary indexing pause. This is useful for cluster migration/reindexing. All changes are still tracked, but they are not committed to the Elasticsearch index until resumed. | | `Search with Elasticsearch enabled` | Enables or disables using Elasticsearch in search. | -| `URL` | The URL to use for connecting to Elasticsearch. Use a comma-separated list to support clustering (e.g., `http://host1, https://host2:9200`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). | -| `Number of Elasticsearch shards` | Elasticsearch indexes are split into multiple shards for performance reasons. In general, larger indexes need to have more shards. Changes to this value do not take effect until the index is recreated. You can read more about tradeoffs in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/scalability.html). | +| `URL` | The URL to use for connecting to Elasticsearch. Use a comma-separated list to support clustering (e.g., `http://host1, https://host2:9200`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). Special characters in the username or password should use [percentage encoding](https://en.wikipedia.org/wiki/Percent-encoding). | +| `Number of Elasticsearch shards` | Elasticsearch indexes are split into multiple shards for performance reasons. In general, you should use at least 5 shards, and indexes with tens of millions of documents need to have more shards ([see below](#guidance-on-choosing-optimal-cluster-configuration)). Changes to this value do not take effect until the index is recreated. You can read more about tradeoffs in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/scalability.html). | | `Number of Elasticsearch replicas` | Each Elasticsearch shard can have a number of replicas. These are a complete copy of the shard, and can provide increased query performance or resilience against hardware failure. Increasing this value will greatly increase total disk space required by the index. | | `Limit namespaces and projects that can be indexed` | Enabling this will allow you to select namespaces and projects to index. All other namespaces and projects will use database search instead. Please note that if you enable this option but do not select any namespaces or projects, none will be indexed. [Read more below](#limiting-namespaces-and-projects). | `Using AWS hosted Elasticsearch with IAM credentials` | Sign your Elasticsearch requests using [AWS IAM authorization](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html), [AWS EC2 Instance Profile Credentials](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-create-iam-instance-profile.html#getting-started-create-iam-instance-profile-cli), or [AWS ECS Tasks Credentials](https://docs.aws.amazon.com/AmazonECS/latest/userguide/task-iam-roles.html). Please refer to [Identity and Access Management in Amazon Elasticsearch Service](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-ac.html) for details of AWS hosted Elasticsearch domain access policy configuration. | @@ -232,6 +235,12 @@ The following Elasticsearch settings are available: | `Bulk request concurrency` | The Bulk request concurrency indicates how many of the GitLab Golang-based indexer processes (or threads) can run in parallel to collect data to subsequently submit to Elasticsearch’s Bulk API. This increases indexing performance, but fills the Elasticsearch bulk requests queue faster. This setting should be used together with the Maximum bulk request size setting (see above) and needs to accommodate the resource constraints of both the Elasticsearch host(s) and the host(s) running the GitLab Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | | `Client request timeout` | Elasticsearch HTTP client request timeout value in seconds. `0` means using the system default timeout value, which depends on the libraries that GitLab application is built upon. | +WARNING: +Increasing the values of `Maximum bulk request size (MiB)` and `Bulk request concurrency` can negatively impact +Sidekiq performance. Return them to their default values if you see increased `scheduling_latency_s` durations +in your Sidekiq logs. For more information, see +[issue 322147](https://gitlab.com/gitlab-org/gitlab/-/issues/322147). + ### Limiting namespaces and projects If you select `Limit namespaces and projects that can be indexed`, more options will become available. @@ -335,7 +344,7 @@ Sometimes, you might want to abandon the unfinished reindex job and resume the i 1. Uncheck the "Pause Elasticsearch indexing" checkbox in **Admin Area > Settings > Advanced Search**. -## Background migrations +## Advanced Search migrations > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/234046) in GitLab 13.6. @@ -343,7 +352,7 @@ With reindex migrations running in the background, there's no need for a manual intervention. This usually happens in situations where new features are added to Advanced Search, which means adding or changing the way content is indexed. -To confirm that the background migrations ran, you can check with: +To confirm that the Advanced Search migrations ran, you can check with: ```shell curl "$CLUSTER_URL/gitlab-production-migrations/_search?q=*" | jq . @@ -393,6 +402,21 @@ debug why the migration was halted and make any changes before retrying the migr fixed the cause of the failure, click "Retry migration", and the migration will be scheduled to be retried in the background. +If you cannot get the migration to succeed, you may +consider the [last resort to recreate the index from +scratch](#last-resort-to-recreate-an-index). This may allow you to skip over +the problem because a newly created index will skip all migrations as the index +will be recreated with the correct up-to-date schema. + +### All migrations must be finished before doing a major upgrade + +Before doing a major version GitLab upgrade, you should have completed all +migrations that exist up until the latest minor version before that major +version. If you have halted migrations, these will need to be resolved and +[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). + ## GitLab Advanced Search Rake tasks Rake tasks are available to: @@ -415,7 +439,9 @@ The following are some available Rake tasks: | [`sudo gitlab-rake gitlab:elastic:index_snippets`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Performs an Elasticsearch import that indexes the snippets data. | | [`sudo gitlab-rake gitlab:elastic:projects_not_indexed`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Displays which projects are not indexed. | | [`sudo gitlab-rake gitlab:elastic:reindex_cluster`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Schedules a zero-downtime cluster reindexing task. This feature should be used with an index that was created after GitLab 13.0. | -| [`sudo gitlab-rake gitlab:elastic:mark_reindex_failed`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake)`] | Mark the most recent re-index job as failed. | +| [`sudo gitlab-rake gitlab:elastic:mark_reindex_failed`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Mark the most recent re-index job as failed. | +| [`sudo gitlab-rake gitlab:elastic:list_pending_migrations`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | List pending migrations. Pending migrations include those that have not yet started, have started but not finished, and those that are halted. | +| [`sudo gitlab-rake gitlab:elastic:estimate_cluster_size`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Get an estimate of cluster size based on the total repository size. | ### Environment variables @@ -465,7 +491,12 @@ For basic guidance on choosing a cluster configuration you may refer to [Elastic - `Heap size` should be set to no more than 50% of your physical RAM. Additionally, it shouldn't be set to more than the threshold for zero-based compressed oops. The exact threshold varies, but 26 GB is safe on most systems, but can also be as large as 30 GB on some systems. See [Heap size settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/important-settings.html#heap-size-settings) and [Setting JVM options](https://www.elastic.co/guide/en/elasticsearch/reference/current/jvm-options.html) for more details. - Number of CPUs (CPU cores) per node usually corresponds to the `Number of Elasticsearch shards` setting described below. - A good guideline is to ensure you keep the number of shards per node below 20 per GB heap it has configured. A node with a 30GB heap should therefore have a maximum of 600 shards, but the further below this limit you can keep it the better. This will generally help the cluster stay in good health. -- Small shards result in small segments, which increases overhead. Aim to keep the average shard size between at least a few GB and a few tens of GB. Another consideration is the number of documents, you should aim for this simple formula for the number of shards: `number of expected documents / 5M +1`. +- Number of Elasticsearch shards: + - Small shards result in small segments, which increases overhead. Aim to keep the average shard size between at least a few GB and a few tens of GB. + - Another consideration is the number of documents. To determine the number of shards to use, sum the numbers in the **Admin Area > Dashboard > Statistics** pane (the number of documents to be indexed), divide by 5 million, and add 5. For example: + - If you have fewer than about 2,000,000 documents, use the default of 5 shards + - 10,000,000 documents: `10000000/5000000 + 5` = 7 shards + - 100,000,000 documents: `100000000/5000000 + 5` = 25 shards - `refresh_interval` is a per index setting. You may want to adjust that from default `1s` to a bigger value if you don't need data in real-time. This will change how soon you will see fresh results. If that's important for you, you should leave it as close as possible to the default value. - You might want to raise [`indices.memory.index_buffer_size`](https://www.elastic.co/guide/en/elasticsearch/reference/current/indexing-buffer.html) to 30% or 40% if you have a lot of heavy indexing operations. @@ -873,3 +904,35 @@ Improvements to the `code_analyzer` pattern and filters are being discussed in [ ### Some binary files may not be searchable by name In GitLab 13.9, a change was made where [binary file names are being indexed](https://gitlab.com/gitlab-org/gitlab/-/issues/301083). However, without indexing all projects' data from scratch, only binary files that are added or updated after the GitLab 13.9 release are searchable. + +### Last resort to recreate an index + +There may be cases where somehow data never got indexed and it's not in the +queue, or the index is somehow in a state where migrations just simply cannot +proceed. It is always best to try to troubleshoot the root cause of the problem +using the above [troubleshooting](#troubleshooting) steps. + +If there are no other options, then you always have the option of recreating the +entire index from scratch. If you have a small GitLab installation, this can +sometimes be a quick way to resolve a problem, but if you have a large GitLab +installation, then this will likely take a very long time to complete. Until the +index is fully recreated, your index will not be serving correct search results, +so you may want to disable **Search with Elasticsearch** while it is running. + +If you are sure you've read the above caveats and want to proceed, then you +should run the following Rake task to recreate the entire index from scratch: + +**For Omnibus installations** + +```shell +# WARNING: DO NOT RUN THIS UNTIL YOU READ THE DESCRIPTION ABOVE +sudo gitlab-rake gitlab:elastic:index +``` + +**For installations from source** + +```shell +# WARNING: DO NOT RUN THIS UNTIL YOU READ THE DESCRIPTION ABOVE +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:elastic:index +``` diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index b1eb9d0d2fe..4e00057c4b7 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -4,7 +4,7 @@ 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 --- -# External issue tracker +# External issue tracker **(FREE)** GitLab has a great [issue tracker](../user/project/issues/index.md) but you can also use an external one. External issue trackers are configurable per GitLab project. diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index b86958726a7..c901fdfdd10 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -4,7 +4,7 @@ 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 --- -# Facebook OAuth2 OmniAuth Provider +# Facebook OAuth2 OmniAuth Provider **(FREE)** To enable the Facebook OmniAuth provider you must register your application with Facebook. Facebook generates an app ID and secret key for you to use. diff --git a/doc/integration/github.md b/doc/integration/github.md index 0239ba0e818..4d8adfe42f1 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -4,24 +4,31 @@ 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 --- -# Integrate your GitLab instance with GitHub +# Integrate your GitLab instance with GitHub **(FREE)** 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. +## Security check + +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. + +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 +your website could enable the covert redirect attack. + ## Enabling GitHub OAuth -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/apps/building-oauth-apps/creating-an-oauth-app/). +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/creating-an-oauth-app). When you create an OAuth 2 app in GitHub, you need 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. -NOTE: -To prevent an [OAuth2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/) vulnerability, append `/users/auth` to the end of the GitHub authorization callback URL. - See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. 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. diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 97c5332c438..7e21685fd54 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -4,7 +4,7 @@ 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 --- -# Integrate your server with GitLab.com +# Integrate your server with GitLab.com **(FREE)** Import projects from GitLab.com and login to your GitLab instance with your GitLab.com account. diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index 7dc710615fb..e62e3de29c2 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -5,7 +5,7 @@ group: Editor info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" --- -# Gitpod Integration +# Gitpod Integration **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228893) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/258206) in GitLab 13.8 @@ -34,9 +34,8 @@ To learn more about Gitpod, see their [features](https://www.gitpod.io/features/ With the Gitpod integration enabled for your GitLab instance, to enable it for yourself: 1. In the top-right corner, select your avatar. -1. Select **Edit profile**. -1. In the left sidebar, select **Account**. -1. Under **Integrations**, locate the **Gitpod** section. +1. Select **Preferences**. +1. Under **Preferences**, locate the **Integrations** section. 1. Check the **Enable Gitpod integration** checkbox and select the **Save changes** button. ## Configure a self-managed instance **(FREE SELF)** diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index af9972e825e..fa0e79d4c0b 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -4,7 +4,7 @@ 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 --- -# Gmail actions buttons for GitLab +# Gmail actions buttons for GitLab **(FREE)** GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview). diff --git a/doc/integration/google.md b/doc/integration/google.md index cd00c854fea..0e4c9b78b5f 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -4,7 +4,7 @@ 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 --- -# Google OAuth2 OmniAuth Provider +# Google OAuth2 OmniAuth Provider **(FREE)** To enable the Google OAuth2 OmniAuth provider you must register your application with Google. Google generates a client ID and secret key for you to use. diff --git a/doc/integration/img/oauth_provider_admin_application.png b/doc/integration/img/oauth_provider_admin_application.png Binary files differdeleted file mode 100644 index 353114fea30..00000000000 --- a/doc/integration/img/oauth_provider_admin_application.png +++ /dev/null diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index b51ce5de8d7..1250ddee584 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -31,7 +31,8 @@ the ['GitLab vs. Jenkins' comparison page](https://about.gitlab.com/devops-tools NOTE: This documentation focuses only on how to **configure** a Jenkins *integration* with -GitLab. Learn how to **migrate** from Jenkins to GitLab CI/CD in our +GitLab. Learn how to set up Jenkins [on your local machine](../development/integrations/jenkins.md) +in our developer documentation, and how to **migrate** from Jenkins to GitLab CI/CD in our [Migrating from Jenkins](../ci/migration/jenkins.md) documentation. ## Configure GitLab integration with Jenkins @@ -138,9 +139,11 @@ Set up the Jenkins project you intend to run your build on. ## Configure the GitLab project -Configure the GitLab integration with Jenkins. +Configure the GitLab integration with Jenkins in one of the following ways. -### Option 1: Jenkins integration (recommended) +### Recommended Jenkins integration + +GitLab recommends this approach for Jenkins integrations. 1. Create a new GitLab project or choose an existing one. 1. Go to **Settings > Integrations**, then select **Jenkins CI**. @@ -159,7 +162,7 @@ Configure the GitLab integration with Jenkins. authentication. 1. Click **Test settings and save changes**. GitLab tests the connection to Jenkins. -### Option 2: Webhook +### Webhook integration If you are unable to provide GitLab with your Jenkins server login, you can use this option to integrate GitLab and Jenkins. @@ -167,7 +170,8 @@ to integrate GitLab and Jenkins. 1. In the configuration of your Jenkins job, in the GitLab configuration section, click **Advanced**. 1. Click the **Generate** button under the **Secret Token** field. 1. Copy the resulting token, and save the job configuration. -1. In GitLab, create a webhook for your project, enter the trigger URL (such as `https://JENKINS_URL/project/YOUR_JOB`) and paste the token in the **Secret Token** field. +1. In GitLab, create a webhook for your project, enter the trigger URL + (such as `https://JENKINS_URL/project/YOUR_JOB`) and paste the token in the **Secret Token** field. 1. After you add the webhook, click the **Test** button, and it should succeed. ## Troubleshooting diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index 2ed87456ea1..61d1deace4f 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Jenkins CI (deprecated) service +# Jenkins CI (deprecated) service **(FREE)** NOTE: In GitLab 8.3, Jenkins integration using the @@ -42,7 +42,7 @@ In GitLab, perform the following steps. Jenkins needs read access to the GitLab repository. We already specified a private key to use in Jenkins, now we need to add a public one to the GitLab project. For that case we need a Deploy key. Read the documentation on -[how to set up a Deploy key](../ssh/README.md#deploy-keys). +[how to set up a Deploy key](../user/project/deploy_keys/index.md). ### Jenkins service diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index 41656bd2216..84490757c16 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -4,7 +4,7 @@ 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 --- -# Sign into GitLab with (almost) any OAuth2 provider +# Sign into GitLab with (almost) any OAuth2 provider **(FREE)** The `omniauth-oauth2-generic` gem allows Single Sign-On between GitLab and your own OAuth2 provider (or any OAuth2 provider compatible with this gem) diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index cf033018e17..e3b18c0b82b 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -4,7 +4,7 @@ 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 --- -# OmniAuth +# OmniAuth **(FREE)** GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and other popular services. [OmniAuth](https://rubygems.org/gems/omniauth/) is @@ -239,7 +239,6 @@ from the OmniAuth provider's documentation. If you have successfully set up a provider that is not shipped with GitLab itself, please let us know. -Share your experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations). You can help others by reporting successful configurations and probably share a few insights or provide warnings for common errors or pitfalls. diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index 4455ace3e1f..b37c5064063 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab as OpenID Connect identity provider +# GitLab as OpenID Connect identity provider **(FREE)** This document is about using GitLab as an OpenID Connect identity provider to sign in to other services. diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 8f090dfc588..9ffc89e2c13 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -4,7 +4,7 @@ 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 --- -# reCAPTCHA +# reCAPTCHA **(FREE)** GitLab leverages [Google's reCAPTCHA](https://www.google.com/recaptcha/about/) to protect against spam and abuse. GitLab displays the CAPTCHA form on the sign-up page diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 156109518a6..102b89298a1 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -4,7 +4,7 @@ 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 --- -# Salesforce OmniAuth Provider +# Salesforce OmniAuth Provider **(FREE)** You can integrate your GitLab instance with [Salesforce](https://www.salesforce.com/) to enable users to log in to your GitLab instance with their Salesforce account. diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 9b6ad3f2755..d68cf8e2f34 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -13,15 +13,15 @@ You should also reference the [OmniAuth documentation](omniauth.md) for general ## Common SAML Terms -| Term | Description | -|------|-------------| -| Identity Provider (IdP) | The service which manages your user identities such as ADFS, Okta, Onelogin, or Ping Identity. | -| Service Provider (SP) | SAML considers GitLab to be a service provider. | -| Assertion | A piece of information about a user's identity, such as their name or role. Also known as claims or attributes. | -| SSO | Single Sign-On. | +| Term | Description | +|--------------------------------|-------------| +| Identity Provider (IdP) | The service which manages your user identities, such as ADFS, Okta, OneLogin, or Ping Identity. | +| Service Provider (SP) | SAML considers GitLab to be a service provider. | +| Assertion | A piece of information about a user's identity, such as their name or role. Also known as claims or attributes. | +| SSO | Single Sign-On. | | Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. | -| Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | -| Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | +| Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | +| Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | ## General Setup @@ -265,7 +265,7 @@ considered admin users. ### Auditor groups **(PREMIUM SELF)** -> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 11.4. +> Introduced in GitLab 11.4. The requirements are the same as the previous settings, your IdP needs to pass Group information to GitLab, you need to tell GitLab where to look for the groups in the SAML response, and which group(s) should be @@ -454,8 +454,6 @@ args: { ### `uid_attribute` -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17734) in GitLab 10.7. - By default, the `uid` is set as the `name_id` in the SAML response. If you'd like to designate a unique attribute for the `uid`, you can set the `uid_attribute`. In the example below, the value of `uid` attribute in the SAML response is set as the `uid_attribute`. ```yaml diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index 3b92f2858ac..c4cf19747be 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -4,7 +4,7 @@ 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 +# Shibboleth OmniAuth Provider **(FREE)** NOTE: The preferred approach for integrating a Shibboleth authentication system diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index 0dcf86cc46d..2c133c1de76 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -4,7 +4,7 @@ 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 --- -# Slash Commands +# Slash Commands **(FREE)** > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to GitLab Free in 11.9. diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md index 1a1b6cd101f..e8956271508 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -4,7 +4,7 @@ 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 --- -# Trello Power-Up +# Trello Power-Up **(FREE)** The GitLab Trello Power-Up enables you to seamlessly attach GitLab **merge requests** to Trello cards. diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index 8404352d0e9..58e111be73c 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -4,7 +4,7 @@ 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 --- -# Twitter OAuth2 OmniAuth Provider +# Twitter OAuth2 OmniAuth Provider **(FREE)** To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter generates a client ID and secret key for you to use. |
