diff options
Diffstat (limited to 'doc/integration')
| -rw-r--r-- | doc/integration/azure.md | 271 | ||||
| -rw-r--r-- | doc/integration/elasticsearch.md | 53 | ||||
| -rw-r--r-- | doc/integration/external-issue-tracker.md | 20 | ||||
| -rw-r--r-- | doc/integration/gitlab.md | 7 | ||||
| -rw-r--r-- | doc/integration/jenkins.md | 4 | ||||
| -rw-r--r-- | doc/integration/jira/configure.md | 2 | ||||
| -rw-r--r-- | doc/integration/jira/connect-app.md | 2 | ||||
| -rw-r--r-- | doc/integration/jira/development_panel.md | 2 | ||||
| -rw-r--r-- | doc/integration/omniauth.md | 4 | ||||
| -rw-r--r-- | doc/integration/security_partners/index.md | 6 | ||||
| -rw-r--r-- | doc/integration/twitter.md | 4 |
11 files changed, 155 insertions, 220 deletions
diff --git a/doc/integration/azure.md b/doc/integration/azure.md index 8d69881699b..5749e638164 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -4,135 +4,45 @@ 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 --- -# Microsoft Azure OAuth 2.0 OmniAuth Provider **(FREE SELF)** +# Use Microsoft Azure as an authentication provider **(FREE SELF)** -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 OAuth 2.0 OmniAuth Provider v2 instructions](#microsoft-azure-oauth-20-omniauth-provider-v2). - -To enable the Microsoft Azure OAuth 2.0 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.mycompany.com/users/auth/azure_oauth2/callback`. - The type dropdown should be set to **Web**. -- The `client ID` and `client secret` are terms associated with OAuth 2.0. In some Microsoft documentation, - the terms may be listed as `Application ID` and `Application Secret`. -- If you have 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. - -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 [Configure initial settings](omniauth.md#configure-initial-settings) - for initial settings. - -1. Add the provider configuration: - - For Omnibus GitLab: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - name: "azure_oauth2", - # label: "Provider name", # optional label for login button, defaults to "Azure AD" - args: { - client_id: "CLIENT ID", - client_secret: "CLIENT SECRET", - tenant_id: "TENANT ID", - } - } - ] - ``` - - For installations from source: +You can enable the Microsoft Azure OAuth 2.0 OmniAuth provider and sign in to +GitLab with your Microsoft Azure credentials. You can configure the provider that uses +[the earlier Azure Active Directory v1.0 endpoint](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/v1-protocols-oauth-code), +or the provider that uses the v2.0 endpoint. - ```yaml - - { name: 'azure_oauth2', - # label: 'Provider name', # optional label for login button, defaults to "Azure AD" - 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"`. - -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. Click 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. - -## Microsoft Azure OAuth 2.0 OmniAuth Provider v2 - -To use v2 endpoints provided by Microsoft Azure Active Directory you must to -configure it via Azure OAuth 2.0 OmniAuth Provider v2. +NOTE: +For new projects, Microsoft suggests you use the +[OpenID Connect protocol](../administration/auth/oidc.md#microsoft-azure), +which uses the Microsoft identity platform (v2.0) endpoint. -### Registering an Azure application +## Register an Azure application To enable the Microsoft Azure OAuth 2.0 OmniAuth provider, you must register -your application with Azure. Azure generates a client ID and secret key for you -to use. +an Azure application and get a client ID and secret key. -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). +1. Sign in to the [Azure portal](https://portal.azure.com). +1. If you have multiple Azure Active Directory tenants, switch to the desired tenant. +1. [Register an application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) + and provide the following information: + - The redirect URI, which requires the URL of the Azure OAuth callback of your GitLab + installation. For example: + - For the v1.0 endpoint: `https://gitlab.example.com/users/auth/azure_oauth2/callback`. + - For the v2.0 endpoint: `https://gitlab.example.com/users/auth/azure_activedirectory_v2/callback`. + - The application type, which must be set to **Web**. +1. Save the client ID and client secret. The client secret is only + displayed once. -As you go through the Microsoft procedure, keep the following in mind: + If required, you can [create a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret). -- 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.0. In some Microsoft documentation, - the terms may be listed as `Application ID` and `Application Secret`. -- If you have 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. +`client ID` and `client secret` are terms associated with OAuth 2.0. +In some Microsoft documentation, the terms are named `Application ID` and +`Application Secret`. -### Adding API permissions (scopes) +## Add API permissions (scopes) -After 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: +If you're using the v2.0 endpoint, after you create the application, [configure it to expose a web API](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). +Add the following delegated permissions under the Microsoft Graph API: - `email` - `openid` @@ -140,75 +50,100 @@ After you have created an application, follow the [Microsoft Quickstart document Alternatively, add the `User.Read.All` application permission. -### Configuring GitLab +## Enable Microsoft OAuth in GitLab 1. On your GitLab server, open the configuration file. - For Omnibus GitLab: + - **For Omnibus installations** + + ```shell + sudo editor /etc/gitlab/gitlab.rb + ``` - ```shell - sudo editor /etc/gitlab/gitlab.rb - ``` + - **For installations from source** - For installations from source: + ```shell + cd /home/git/gitlab - ```shell - cd /home/git/gitlab + sudo -u git -H editor config/gitlab.yml + ``` - sudo -u git -H editor config/gitlab.yml - ``` +1. [Configure the initial settings](omniauth.md#configure-initial-settings). -1. Refer to [Configure initial settings](omniauth.md#configure-initial-settings) - for initial settings. +1. Add the provider configuration. Replace `CLIENT ID`, `CLIENT SECRET`, and `TENANT ID` + with the values you got when you registered the Azure application. -1. Add the provider configuration: + - **For Omnibus installations** - For Omnibus GitLab: + For the v1.0 endpoint: - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "azure_activedirectory_v2", - "label" => "Provider name", # optional label for login button, defaults to "Azure AD v2" - "args" => { - "client_id" => "CLIENT ID", - "client_secret" => "CLIENT SECRET", - "tenant_id" => "TENANT ID", + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: "azure_oauth2", + # label: "Provider name", # optional label for login button, defaults to "Azure AD" + args: { + client_id: "CLIENT ID", + client_secret: "CLIENT SECRET", + tenant_id: "TENANT ID", + } } - } - ] - ``` + ] + ``` + + For the v2.0 endpoint: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "azure_activedirectory_v2", + "label" => "Provider name", # optional label for login button, defaults to "Azure AD v2" + "args" => { + "client_id" => "CLIENT ID", + "client_secret" => "CLIENT SECRET", + "tenant_id" => "TENANT ID", + } + } + ] + ``` + + - **For installations from source** - For installations from source: + For the v1.0 endpoint: - ```yaml - - { name: 'azure_activedirectory_v2', - label: 'Provider name', # optional label for login button, defaults to "Azure AD v2" - args: { client_id: "CLIENT ID", - client_secret: "CLIENT SECRET", - tenant_id: "TENANT ID" } } - ``` + ```yaml + - { name: 'azure_oauth2', + # label: 'Provider name', # optional label for login button, defaults to "Azure AD" + 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"`. + For the v2.0 endpoint: + + ```yaml + - { name: 'azure_activedirectory_v2', + label: 'Provider name', # optional label for login button, defaults to "Azure AD v2" + args: { client_id: "CLIENT ID", + client_secret: "CLIENT SECRET", + tenant_id: "TENANT ID" } } + ``` - The `scope` parameter is optional and can be added to `args`. Default `scope` is: `openid profile email`. + You can optionally add the following parameters: -1. Replace `CLIENT ID`, `CLIENT SECRET`, and `TENANT ID` with the values you got - above. + - `base_azure_url` for different locales. For example, `base_azure_url: "https://login.microsoftonline.de"`. + - `scope`, which you add to `args`. The default is `openid profile email`. 1. Save the configuration file. -1. Reconfigure or restart GitLab, depending on your installation method: +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. - - *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). +1. Refresh the GitLab sign-in page. A Microsoft icon should display below the + sign-in form. -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. +1. Select the icon. Sign in to Microsoft and authorize the GitLab application. -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. +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 new Azure AD accounts. diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 4976f7c2664..5265a24d299 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -58,6 +58,9 @@ source. You must [install it separately](https://www.elastic.co/guide/en/elastic You can install Elasticsearch yourself, or use a cloud hosted offering such as [Elasticsearch Service](https://www.elastic.co/elasticsearch/service) (available on AWS, GCP, or Azure) or the [Amazon OpenSearch](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/gsg.html) service. + +If using the Amazon OpenSearch service, ensure that you select `Elasticsearch 7.10` when configuring Deployment type. As noted in [Versions not supported](#versions-not-supported), Amazon's non-Elasticsearch versions are not yet supported. + You should install Elasticsearch on a separate server. Running Elasticsearch on the same server as GitLab is not recommended and can cause a degradation in GitLab instance performance. For a single node Elasticsearch cluster, the functional cluster health status is always yellow due to the allocation of the primary shard. Elasticsearch cannot assign replica shards to the same node as primary shards. @@ -206,7 +209,7 @@ The following Elasticsearch settings are available: | Parameter | Description | |-------------------------------------------------------|-------------| -| `Elasticsearch indexing` | Enables or disables Elasticsearch indexing and creates an empty index if one does not already exist. You may want to enable indexing but disable search in order to give the index time to be fully completed, for example. Also, keep in mind that this option doesn't have any impact on existing data, this only enables/disables the background indexer which tracks data changes and ensures new data is indexed. | +| `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 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 of your Elasticsearch instance. Use a comma-separated list to support clustering (for example, `http://host1, https://host2:9200`). If your Elasticsearch instance is password-protected, use the `Username` and `Password` fields described below. Alternatively, use inline credentials such as `http://<username>:<password>@<elastic_host>:9200/`. | @@ -221,8 +224,8 @@ The following Elasticsearch settings are available: | `AWS Secret Access Key` | The AWS secret access key. | | `Maximum file size indexed` | See [the explanation in instance limits.](../administration/instance_limits.md#maximum-file-size-indexed). | | `Maximum field length` | See [the explanation in instance limits.](../administration/instance_limits.md#maximum-field-length). | -| `Maximum bulk request size (MiB)` | The Maximum Bulk Request size is used by the GitLab Golang-based indexer processes and indicates how much data it ought to collect (and store in memory) in a given indexing process before submitting the payload to Elasticsearch's Bulk API. This setting should be used with the Bulk request concurrency setting (see below) 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. | -| `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. | +| `Maximum bulk request size (MiB)` | The Maximum Bulk Request size is used by the GitLab Golang-based indexer processes and indicates how much data it ought to collect (and store in memory) in a given indexing process before submitting the payload to Elasticsearch's Bulk API. This setting should be used with the Bulk request concurrency setting (see below) and needs to accommodate the resource constraints of both the Elasticsearch hosts and the hosts running the GitLab Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | +| `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 hosts and the hosts 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: @@ -259,16 +262,16 @@ from the Elasticsearch index as expected. You can improve the language support for Chinese and Japanese languages by utilizing [`smartcn`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) and/or [`kuromoji`](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) analysis plugins from Elastic. -To enable language(s) support: +To enable languages 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. Install the desired plugins, please refer to [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/plugins/7.9/installation.html) for plugins installation instructions. The plugins must be installed on every node in the cluster, and each node must be restarted after installation. For a list of plugins, see the table later in this section. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Locate **Custom analyzers: language support**. -1. Enable plugin(s) support for **Indexing**. +1. Enable plugins support for **Indexing**. 1. Click **Save changes** for the changes to take effect. 1. Trigger [Zero downtime reindexing](#zero-downtime-reindexing) or reindex everything from scratch to create a new index with updated mappings. -1. Enable plugin(s) support for **Searching** after the previous step is completed. +1. Enable plugins support for **Searching** after the previous step is completed. For guidance on what to install, see the following Elasticsearch language plugin options: @@ -662,7 +665,7 @@ Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). ``` You can also use the `gitlab:elastic:clear_index_status` Rake task to force the - indexer to "forget" all progress, so it will retry the indexing process from the + indexer to "forget" all progress, so it retries the indexing process from the start. 1. Personal snippets are not associated with a project and need to be indexed separately: @@ -831,9 +834,9 @@ for the changes to take effect. ## Reverting to Basic Search Sometimes there may be issues with your Elasticsearch index data and as such -GitLab will allow you to revert to "basic search" when there are no search +GitLab allows you to revert to "basic search" when there are no search results and assuming that basic search is supported in that scope. This "basic -search" will behave as though you don't have Advanced Search enabled at all for +search" behaves as though you don't have Advanced Search enabled at all for your instance and search using other data sources (such as PostgreSQL data and Git data). @@ -847,7 +850,7 @@ the Elasticsearch data store is ever corrupted for whatever reason, you can rein ## Troubleshooting One of the most valuable tools for identifying issues with the Elasticsearch -integration will be logs. The most relevant logs for this integration are: +integration are logs. The most relevant logs for this integration are: 1. [`sidekiq.log`](../administration/logs.md#sidekiqlog) - All of the indexing happens in Sidekiq, so much of the relevant logs for the @@ -863,7 +866,7 @@ Here are some common pitfalls and how to overcome them. There are a couple of ways to achieve that: -- Whenever you perform a search there will be a link on the search results page +- Whenever you perform a search there is a link on the search results page in the top right hand corner saying "Advanced search functionality is enabled". This is always correctly identifying whether the current project/namespace being searched is using Elasticsearch. @@ -923,7 +926,7 @@ See [Elasticsearch Index Scopes](#advanced-search-index-scopes) for more informa ### I indexed all the repositories but then switched Elasticsearch servers and now I can't find anything -You will need to re-run all the Rake tasks to reindex the database, repositories, and wikis. +You must re-run all the Rake tasks to reindex the database, repositories, and wikis. ### The indexing process is taking a very long time @@ -938,7 +941,7 @@ You can run `sudo gitlab-rake gitlab:elastic:projects_not_indexed` to display pr NOTE: This was [fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35936) in GitLab 13.2 and the Rake task is not available for versions greater than that. -When performing the initial indexing of blobs, we lock all projects until the project finishes indexing. It could happen that an error during the process causes one or multiple projects to remain locked. In order to unlock them, run: +When performing the initial indexing of blobs, we lock all projects until the project finishes indexing. It could happen that an error during the process causes one or multiple projects to remain locked. To unlock them, run: ```shell sudo gitlab-rake gitlab:elastic:clear_locked_projects @@ -946,8 +949,8 @@ sudo gitlab-rake gitlab:elastic:clear_locked_projects ### `Can't specify parent if no parent field has been configured` error -If you enabled Elasticsearch before GitLab 8.12 and have not rebuilt indexes you will get -exception in lots of different cases: +If you enabled Elasticsearch before GitLab 8.12 and have not rebuilt indexes, you get +exceptions in lots of different cases: ```plaintext Elasticsearch::Transport::Transport::Errors::BadRequest([400] { @@ -983,12 +986,12 @@ AWS has [fixed limits](https://docs.aws.amazon.com/opensearch-service/latest/dev ### My single node Elasticsearch cluster status never goes from `yellow` to `green` even though everything seems to be running properly -**For a single node Elasticsearch cluster the functional cluster health status will be yellow** (never green) because the primary shard is allocated but replicas cannot be as there is no other node to which Elasticsearch can assign a replica. This also applies if you are using the [Amazon OpenSearch](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/aes-handling-errors.html#aes-handling-errors-yellow-cluster-status) service. +**For a single node Elasticsearch cluster the functional cluster health status is yellow** (never green) because the primary shard is allocated but replicas cannot be as there is no other node to which Elasticsearch can assign a replica. This also applies if you are using the [Amazon OpenSearch](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/aes-handling-errors.html#aes-handling-errors-yellow-cluster-status) service. WARNING: -Setting the number of replicas to `0` is discouraged (this is not allowed in the GitLab Elasticsearch Integration menu). If you are planning to add more Elasticsearch nodes (for a total of more than 1 Elasticsearch) the number of replicas will need to be set to an integer value larger than `0`. Failure to do so will result in lack of redundancy (losing one node will corrupt the index). +Setting the number of replicas to `0` is discouraged (this is not allowed in the GitLab Elasticsearch Integration menu). If you are planning to add more Elasticsearch nodes (for a total of more than 1 Elasticsearch) the number of replicas needs to be set to an integer value larger than `0`. Failure to do so results in lack of redundancy (losing one node corrupts the index). -If you have a **hard requirement to have a green status for your single node Elasticsearch cluster**, please make sure you understand the risks outlined in the previous paragraph and then run the following query to set the number of replicas to `0`(the cluster will no longer try to create any shard replicas): +If you have a **hard requirement to have a green status for your single node Elasticsearch cluster**, please make sure you understand the risks outlined in the previous paragraph and then run the following query to set the number of replicas to `0`(the cluster no longer tries to create any shard replicas): ```shell curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \ @@ -1008,7 +1011,7 @@ Gitlab::Elastic::Indexer::Error: time="2020-01-23T09:13:00Z" level=fatal msg="he ``` You probably have not used either `http://` or `https://` as part of your value in the **"URL"** field of the Elasticsearch Integration Menu. Please make sure you are using either `http://` or `https://` in this field as the [Elasticsearch client for Go](https://github.com/olivere/elastic) that we are using [needs the prefix for the URL to be accepted as valid](https://github.com/olivere/elastic/commit/a80af35aa41856dc2c986204e2b64eab81ccac3a). -Once you have corrected the formatting of the URL, delete the index (via the [dedicated Rake task](#gitlab-advanced-search-rake-tasks)) and [reindex the content of your instance](#enable-advanced-search). +After you have corrected the formatting of the URL, delete the index (via the [dedicated Rake task](#gitlab-advanced-search-rake-tasks)) and [reindex the content of your instance](#enable-advanced-search). ### My Elasticsearch cluster has a plugin and the integration is not working @@ -1041,8 +1044,8 @@ 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, +installation, then this might take a very long time to complete. Until the +index is fully recreated, your index does not serve 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 @@ -1065,9 +1068,9 @@ sudo -u git -H bundle exec rake gitlab:elastic:index ### How does Advanced Search handle private projects? -Advanced Search will store all the projects in the same Elasticsearch indexes, -however searches will only surface results that can be viewed by the user. -Advanced Search will honor all permission checks in the application by +Advanced Search stores all the projects in the same Elasticsearch indexes, +however, searches only surface results that can be viewed by the user. +Advanced Search honors 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)` diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index 19f789832b9..ac470291c27 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -6,27 +6,26 @@ info: To determine the technical writer assigned to the Stage/Group associated w # 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. +GitLab has an [issue tracker](../user/project/issues/index.md), but you can +configure an external issue tracker per GitLab project. -Once configured, you can reference external issues using the format `CODE-123`, where: +After you configure the external tracker, you can reference external issues +in GitLab merge requests, commits, and comments +using the format `CODE-123`, where: - `CODE` is a unique code for the tracker. - `123` is the issue number in the tracker. -These references in GitLab merge requests, commits, or comments are automatically converted to links to the issues. +The references are automatically converted to links to the issues. You can keep the GitLab issue tracker enabled in parallel or disable it. When enabled, the **Issues** link in the GitLab menu always opens the internal issue tracker. When disabled, the link is not visible in the menu. -## Configuration +## Configure an external issue tracker -The configuration is done via a project's **Settings > Integrations**. +To enable an external issue tracker, you must configure the appropriate [integration](../user/project/integrations/index.md). -### Integration - -To enable an external issue tracker you must configure the appropriate **Integration**. -Visit the links below for details: +The following external issue tracker integrations are available: - [Bugzilla](../user/project/integrations/bugzilla.md) - [Custom Issue Tracker](../user/project/integrations/custom_issue_tracker.md) @@ -34,3 +33,4 @@ Visit the links below for details: - [Jira](../integration/jira/index.md) - [Redmine](../user/project/integrations/redmine.md) - [YouTrack](../user/project/integrations/youtrack.md) +- [ZenTao](../user/project/integrations/zentao.md) diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 74ae9bb1998..132006ab996 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -62,9 +62,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: "read_user" # optional: defaults to the scopes of the application - , client_options: { site: "https://gitlab.example.com/api/v4" } - } + args: { scope: "read_user" } # optional: defaults to the scopes of the application } ] ``` @@ -91,7 +89,6 @@ 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: { "client_options": { "site": 'https://gitlab.example.com/api/v4' } } ``` Or, for installations from source to authenticate against a different GitLab instance: @@ -125,7 +122,7 @@ signed in. 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. +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 diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index b86643c7279..54d235b5357 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -45,7 +45,7 @@ Grant a GitLab user access to the relevant GitLab projects. If you're integrating Jenkins with many GitLab projects, consider granting the user administrator access. Otherwise, add the user to each project - and grant the Developer role. + and grant the Maintainer role. ## Grant Jenkins access to the GitLab API @@ -242,7 +242,7 @@ To enable job logs in Jenkins: 1. Go to **Dashboard > Manage Jenkins > System Log**. 1. Select **Add new log recorder**. 1. Enter a name for the log recorder. -1. On the next screen, select **Add** and enter `org.jenkinsci.plugins.workflow.job`. +1. On the next screen, select **Add** and enter `com.dabsquared.gitlabjenkins`. 1. Make sure that the Log Level is **All** and select **Save**. To view your logs: diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index 979d8a52fb8..2033ddbad6f 100644 --- a/doc/integration/jira/configure.md +++ b/doc/integration/jira/configure.md @@ -50,7 +50,7 @@ To configure your project: If you enable Jira issues with this setting, all users with access to this GitLab project can view all issues from the specified Jira project. -1. To enable [issue creation for vulnerabilities](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability), select **Enable Jira issues creation from vulnerabilities**. +1. To enable [issue creation for vulnerabilities](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability), select **Enable Jira issue creation from vulnerabilities**. 1. Select the **Jira issue type**. If the dropdown is empty, select refresh (**{retry}**) and try again. 1. To verify the Jira connection is working, select **Test settings**. 1. Select **Save changes**. diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index ebe8a0f1af4..59cdba93543 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -101,7 +101,7 @@ from outside the Marketplace, which allows you to install the application:  1. For **App descriptor URL**, provide the full URL to your manifest file, based - on your instance configuration. For example: `https://your.domain/your-path/-/jira_connect/app_descriptor.json`. + on your instance configuration. By default, your manifest file is located at `/-/jira_connect/app_descriptor.json`. For example, if your GitLab self-managed instance domain is `app.pet-store.cloud`, your manifest file is located at `https://app.pet-store.cloud/-/jira_connect/app_descriptor.json`. 1. Select **Upload**. Jira fetches the content of your `app_descriptor` file and installs it. 1. If the upload is successful, Jira displays a modal panel: **Installed and ready to go!** diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index 8f66edcffa8..66810945d19 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -20,7 +20,7 @@ The information displayed in the Jira Development panel depends on where you men | Your mention of Jira issue ID in GitLab context | Automated effect in Jira issue | |---------------------------------------------------|--------------------------------------------------------------------------------------------------------| -| In a merge request | Link to the MR is displayed in Development panel. | +| In a merge request title or description | Link to the MR is displayed in Development panel. | | In a branch name | Link to the branch is displayed in Development panel. | | In a commit message | Link to the commit is displayed in Development panel. | | In a commit message with Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) | Displays your custom comment or logged time spent and/or performs specified issue transition on merge. | diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 4c05f94148c..7a4bcba25e4 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -26,7 +26,7 @@ GitLab supports the following OmniAuth providers. | [Auth0](auth0.md) | `auth0` | | [Authentiq](../administration/auth/authentiq.md) | `authentiq` | | [AWS Cognito](../administration/auth/cognito.md) | `cognito` | -| [Azure v2](azure.md#microsoft-azure-oauth-20-omniauth-provider-v2) | `azure_activedirectory_v2` | +| [Azure v2](azure.md) | `azure_activedirectory_v2` | | [Azure v1](azure.md) | `azure_oauth2` | | [Bitbucket Cloud](bitbucket.md) | `bitbucket` | | [CAS](cas.md) | `cas3` | @@ -326,7 +326,7 @@ configuration to redirect login requests to your OmniAuth provider for authentication. This removes the need to select the provider before signing in. For example, to enable automatic sign-in for the -[Azure v2 integration](azure.md#microsoft-azure-oauth-20-omniauth-provider-v2): +[Azure v2 integration](azure.md): - **For Omnibus package** diff --git a/doc/integration/security_partners/index.md b/doc/integration/security_partners/index.md index 2c7641124a0..50a7b3b717b 100644 --- a/doc/integration/security_partners/index.md +++ b/doc/integration/security_partners/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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: index --- @@ -12,16 +12,16 @@ each security partner: <!-- vale gitlab.Spelling = NO --> -- [Accurics](https://readme.accurics.com/1409/) - [Anchore](https://docs.anchore.com/current/docs/using/integration/ci_cd/gitlab/) - [Bridgecrew](https://docs.bridgecrew.io/docs/integrate-with-gitlab-self-managed) - [Checkmarx](https://checkmarx.atlassian.net/wiki/spaces/SD/pages/1929937052/GitLab+Integration) - [Deepfactor](https://docs.deepfactor.io/hc/en-us/articles/1500008981941) - [GrammaTech](https://www.grammatech.com/codesonar-gitlab-integration) -- [Indeni](https://cloudrail.app/doc/integrate-with-ci-cd/gitlab-instructions/) +- [Indeni](https://docs.cloudrail.app/#/integrations/gitlab) - [JScrambler](https://docs.jscrambler.com/code-integrity/documentation/gitlab-ci-integration) - [Semgrep](https://semgrep.dev/for/gitlab) - [StackHawk](https://docs.stackhawk.com/continuous-integration/gitlab.html) +- [Tenable](https://docs.tenable.com/tenableio/Content/ContainerSecurity/GetStarted.htm) - [Venafi](https://marketplace.venafi.com/details/gitlab-ci-cd/) - [Veracode](https://community.veracode.com/s/knowledgeitem/gitlab-ci-MCEKSYPRWL35BRTGOVI55SK5RI4A) - [WhiteSource](https://www.whitesourcesoftware.com/gitlab/) diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index e1f67df76c3..3aba6b70b94 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -9,9 +9,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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. -1. Sign in to [Twitter Application Management](https://developer.twitter.com/apps). +1. Sign in to [Twitter Application Management](https://apps.twitter.com). -1. Select "Create new app" +1. Select "Create new app". 1. Fill in the application details. - Name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or |