diff options
Diffstat (limited to 'doc/integration')
| -rw-r--r-- | doc/integration/bitbucket.md | 7 | ||||
| -rw-r--r-- | doc/integration/elasticsearch.md | 41 | ||||
| -rw-r--r-- | doc/integration/github.md | 2 | ||||
| -rw-r--r-- | doc/integration/gitlab.md | 19 | ||||
| -rw-r--r-- | doc/integration/gitpod.md | 35 | ||||
| -rw-r--r-- | doc/integration/jira_development_panel.md | 11 | ||||
| -rw-r--r-- | doc/integration/vault.md | 16 |
7 files changed, 73 insertions, 58 deletions
diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index 81cbc42cf45..4bc9d39ae3f 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -104,14 +104,13 @@ you to use. url: 'https://bitbucket.org/' } ``` - --- - Where `BITBUCKET_APP_KEY` is the Key and `BITBUCKET_APP_SECRET` the Secret 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 via - Omnibus GitLab, or [restart](../administration/restart_gitlab.md#installations-from-source) if installed from source. +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. On the sign-in page there should now be a Bitbucket icon below the regular sign-in form. Click the icon to begin the authentication process. Bitbucket asks diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 52275649a67..b1fc2573bb0 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -175,7 +175,7 @@ instances](#indexing-large-instances) below. To enable Advanced Search, you need to have admin access to GitLab: -1. Navigate to **Admin Area** (wrench icon), then **Settings > General** +1. Navigate to **Admin Area**, then **Settings > General** and expand the **Advanced Search** section. NOTE: @@ -205,6 +205,12 @@ To enable Advanced Search, you need to have admin access to GitLab: **Admin Area > Settings > General > Advanced Search** and click **Save changes**. +NOTE: +When your Elasticsearch cluster is down while Elasticsearch is enabled, +you might have problems updating documents such as issues because your +instance queues a job to index the change, but cannot find a valid +Elasticsearch cluster. + ### Advanced Search configuration The following Elasticsearch settings are available: @@ -259,7 +265,7 @@ You can improve the language support for Chinese and Japanese languages by utili To enable language(s) support: 1. Install the desired plugin(s), please refer to [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/plugins/7.9/installation.html) for plugins installation instructions. The plugin(s) must be installed on every node in the cluster, and each node must be restarted after installation. For a list of plugins, see the table later in this section. -1. Navigate to the **Admin Area** (wrench icon), then **Settings > General**.. +1. Navigate to the **Admin Area**, then **Settings > General**.. 1. Expand the **Advanced Search** section and locate **Custom analyzers: language support**. 1. Enable plugin(s) support for **Indexing**. 1. Click **Save changes** for the changes to take effect. @@ -279,11 +285,11 @@ For guidance on what to install, see the following Elasticsearch language plugin To disable the Elasticsearch integration: -1. Navigate to the **Admin Area** (wrench icon), then **Settings > General**. +1. Navigate to the **Admin Area**, then **Settings > General**. 1. Expand the **Advanced Search** section and uncheck **Elasticsearch indexing** and **Search with Elasticsearch enabled**. 1. Click **Save changes** for the changes to take effect. -1. (Optional) Delete the existing index: +1. (Optional) Delete the existing indexes: ```shell # Omnibus installations @@ -311,10 +317,11 @@ used by the GitLab Advanced Search integration. In the **Admin Area > Settings > General > Advanced Search** section, select the **Pause Elasticsearch Indexing** setting, and then save your change. - With this, all updates that should happen on your Elasticsearch index will be buffered and caught up once unpaused. +The indexing will also be automatically paused when the [**Trigger cluster reindexing**](#trigger-the-reindex-via-the-advanced-search-administration) button is used, and unpaused when the reindexing completes or aborts. + ### Setup NOTE: @@ -346,7 +353,8 @@ To reclaim the `gitlab-production` index name, you need to first create a `secon To create a secondary index, run the following Rake task. The `SKIP_ALIAS` environment variable will disable the automatic creation of the Elasticsearch -alias, which would conflict with the existing index under `$PRIMARY_INDEX`: +alias, which would conflict with the existing index under `$PRIMARY_INDEX`, and will +not create a separate Issue index: ```shell # Omnibus installation @@ -506,6 +514,15 @@ This should return something similar to: In order to debug issues with the migrations you can check the [`elasticsearch.log` file](../administration/logs.md#elasticsearchlog). +### Retry a halted migration + +Some migrations are built with a retry limit. If the migration cannot finish within the retry limit, +it will be halted and a notification will be displayed in the Advanced Search integration settings. +It is recommended to check the [`elasticsearch.log` file](../administration/logs.md#elasticsearchlog) to +debug why the migration was halted and make any changes before retrying the migration. Once you believe you've +fixed the cause of the failure, click "Retry migration", and the migration will be scheduled to be retried +in the background. + ## GitLab Advanced Search Rake tasks Rake tasks are available to: @@ -522,8 +539,8 @@ The following are some available Rake tasks: | [`sudo gitlab-rake gitlab:elastic:index_projects`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Iterates over all projects and queues Sidekiq jobs to index them in the background. | | [`sudo gitlab-rake gitlab:elastic:index_projects_status`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Determines the overall status of the indexing. It is done by counting the total number of indexed projects, dividing by a count of the total number of projects, then multiplying by 100. | | [`sudo gitlab-rake gitlab:elastic:clear_index_status`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Deletes all instances of IndexStatus for all projects. Note that this command will result in a complete wipe of the index, and it should be used with caution. | -| [`sudo gitlab-rake gitlab:elastic:create_empty_index[<TARGET_NAME>]`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Generates an empty index and assigns an alias for it on the Elasticsearch side only if it doesn't already exist. | -| [`sudo gitlab-rake gitlab:elastic:delete_index[<TARGET_NAME>]`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Removes the GitLab index and alias (if exists) on the Elasticsearch instance. | +| [`sudo gitlab-rake gitlab:elastic:create_empty_index[<TARGET_NAME>]`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Generates empty indexes (the default index and a separate issues index) and assigns an alias for each on the Elasticsearch side only if it doesn't already exist. | +| [`sudo gitlab-rake gitlab:elastic:delete_index[<TARGET_NAME>]`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Removes the GitLab indexes and aliases (if they exist) on the Elasticsearch instance. | | [`sudo gitlab-rake gitlab:elastic:recreate_index[<TARGET_NAME>]`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Wrapper task for `gitlab:elastic:delete_index[<TARGET_NAME>]` and `gitlab:elastic:create_empty_index[<TARGET_NAME>]`. | | [`sudo gitlab-rake gitlab:elastic: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. | @@ -979,3 +996,11 @@ results and assuming that basic search is supported in that scope. This "basic search" will behave as though you don't have Advanced Search enabled at all for your instance and search using other data sources (ie. PostgreSQL data and Git data). + +### Data recovery: Elasticsearch is a secondary data store only + +The use of Elasticsearch in GitLab is only ever as a secondary data store. +This means that all of the data stored in Elasticsearch can always be derived +again from other data sources, specifically PostgreSQL and Gitaly. Therefore, if +the Elasticsearch data store is ever corrupted for whatever reason, you can +simply reindex everything from scratch. diff --git a/doc/integration/github.md b/doc/integration/github.md index c65027e3585..858614a0571 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -12,7 +12,7 @@ with your GitHub account. ## 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://developer.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/apps/building-oauth-apps/creating-an-oauth-app/). When you create an OAuth 2 app in GitHub, you need the following information: diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 37c91aedb15..3bd3099e390 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -75,15 +75,20 @@ GitLab.com generates an application ID and secret key for you to use. args: { scope: 'api' } } ``` -1. Change 'YOUR_APP_ID' to the Application ID from the GitLab.com application page. +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. Change `'YOUR_APP_SECRET'` to the secret from the GitLab.com application page. 1. Save the configuration file. -1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you - installed GitLab via Omnibus or from source respectively. +1. Based on how GitLab was installed, implement these changes by using + the appropriate method: -On the sign in page there should now be a GitLab.com icon below the regular sign in form. -Click 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. + - Omnibus GitLab: [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). + - Source: [Restart GitLab](../administration/restart_gitlab.md#installations-from-source). + +On the sign-in page, there should now be a GitLab.com icon following the +regular sign-in form. Select the icon to begin the authentication process. +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. diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index 04274c1c015..05f129e6049 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -8,14 +8,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated # Gitpod Integration > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228893) in GitLab 13.4. -> - It was [deployed behind a feature flag](#enable-or-disable-the-gitpod-integration), disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/258206) in GitLab 13.5. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#configure-your-gitlab-instance-with-gitpod). **(CORE ONLY)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/258206) in GitLab 13.8 With [Gitpod](https://gitpod.io/) you can describe your dev environment as code to get fully set up, compiled, and tested dev environments for any GitLab project. The dev environments are not only @@ -48,28 +41,14 @@ can follow the same steps once the integration has been enabled and configured b ## Configure your GitLab instance with Gitpod **(CORE ONLY)** -If you are new to Gitpod, head over to the [Gitpod documentation](https://www.gitpod.io/docs/self-hosted/latest/self-hosted/) -and get your instance up and running. +The integration of Gitpod with GitLab is enabled on GitLab.com and available to all users. +For GitLab self-managed instances, a GitLab administrator needs to enable it through the admin settings. + +First, you (GitLab admin) need to set up a Gitpod instance to integrate with GitLab. +Head over to the [Gitpod documentation](https://www.gitpod.io/docs/self-hosted/latest/self-hosted/) to +get your instance up and running. Once done: 1. In GitLab, go to **Admin Area > Settings > General**. 1. Expand the **Gitpod** configuration section. 1. Check **Enable Gitpod**. 1. Add your Gitpod instance URL (for example, `https://gitpod.example.com`). - -## Enable or disable the Gitpod integration **(CORE ONLY)** - -The Gitpod integration is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) -can enable or disable it. - -To disable it: - -```ruby -Feature.disable(:gitpod) -``` - -To enable it: - -```ruby -Feature.enable(:gitpod) -``` diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md index 7488df3580e..1c0b2bdc85e 100644 --- a/doc/integration/jira_development_panel.md +++ b/doc/integration/jira_development_panel.md @@ -211,7 +211,8 @@ The requested scope is invalid, unknown, or malformed. Potential resolutions: -- Verify the URL includes `scope=api` on the end of the URL. +- Verify the URL shown in the browser after being redirected from Jira in step 5 of [Jira DVCS Connector Setp](#jira-dvcs-connector-setup) includes `scope=api` within the query string. +- If `scope=api` is missing from the URL, return to [GitLab account configuration](#gitlab-account-configuration-for-dvcs) and ensure the application you created in step 1 has the `api` box checked under scopes. ##### Jira error adding account and no repositories listed @@ -272,7 +273,13 @@ The GitLab user only needs access when adding a new namespace. For syncing with  -After a namespace is added, all future commits, branches, and merge requests of all projects under that namespace are synced to Jira. Past data cannot be synced at the moment. +After a namespace is added: + +- All future commits, branches, and merge requests of all projects under that namespace + are synced to Jira. +- From GitLab 13.8, past merge request data is synced to Jira. + +Support for syncing past branch and commit data [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/263240). For more information, see [Usage](#usage). diff --git a/doc/integration/vault.md b/doc/integration/vault.md index 7f81fd3a7da..3c49cd47509 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -13,12 +13,12 @@ type: reference, howto It allows you to store and manage sensitive information such as secret environment variables, encryption keys, and authentication tokens. Vault offers Identity-based Access, which means Vault users can authenticate through several of their preferred cloud providers. -In this document, we'll explain how Vault users can authenticate themselves through GitLab by utilizing our OpenID authentication feature. +This document explains how Vault users can authenticate themselves through GitLab by utilizing our OpenID authentication feature. The following assumes you already have Vault installed and running. 1. **Get the OpenID Connect client ID and secret from GitLab:** - First you'll need to 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: + First you must create a GitLab application to obtain an application ID and secret for authenticating into Vault. To do this, sign in to GitLab and follow these steps: 1. On GitLab, click your avatar on the top-right corner, and select your user **Settings > Applications**. 1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris), @@ -71,7 +71,7 @@ The following assumes you already have Vault installed and running. Now that Vault has a GitLab application ID and secret, it needs to know the [**Redirect URIs**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris) and scopes given to GitLab during the application creation process. The redirect URIs need to match where your Vault instance is running. The `oidc_scopes` field needs to include the `openid`. Similarly to the previous step, replace `your_application_id` with the generated application ID from GitLab: - This configuration is saved under the name of the role you are creating. In this case, we are creating a `demo` role. Later, we'll show how you can access this role through the Vault CLI. + This configuration is saved under the name of the role you are creating. In this case, we are creating a `demo` role. Later, we show how you can access this role through the Vault CLI. ```shell vault write auth/oidc/role/demo \ @@ -88,11 +88,11 @@ The following assumes you already have Vault installed and running. 1. Go to your Vault UI (example: [http://127.0.0.1:8200/ui/vault/auth?with=oidc](http://127.0.0.1:8200/ui/vault/auth?with=oidc)). 1. If the `OIDC` method is not currently selected, open the dropdown and select it. - 1. Click the **Sign in With GitLab** button, which will open a modal window: + 1. Click the **Sign in With GitLab** button, which opens a modal window:  - 1. Click **Authorize** on the modal to allow Vault to sign in through GitLab. This will redirect you back to your Vault UI as a signed-in user. + 1. Click **Authorize** on the modal to allow Vault to sign in through GitLab. This redirects you back to your Vault UI as a signed-in user.  @@ -116,12 +116,12 @@ The following assumes you already have Vault installed and running. another port number that matches the port given to GitLab when listing [Redirect URIs](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). - After running the command, it will present a link in the terminal. - Click the link in the terminal and a tab will open in the browser confirming you're signed into Vault via OIDC: + After running the command, it presents a link in the terminal. + Click the link in the terminal and a browser tab opens that confirms you're signed into Vault via OIDC:  - The terminal will output: + The terminal outputs: ```plaintext Success! You are now authenticated. The token information displayed below |