diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-12-17 14:59:07 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-12-17 14:59:07 +0300 |
| commit | 8b573c94895dc0ac0e1d9d59cf3e8745e8b539ca (patch) | |
| tree | 544930fb309b30317ae9797a9683768705d664c4 /doc/integration | |
| parent | 4b1de649d0168371549608993deac953eb692019 (diff) | |
Add latest changes from gitlab-org/gitlab@13-7-stable-eev13.7.0-rc42
Diffstat (limited to 'doc/integration')
37 files changed, 358 insertions, 236 deletions
diff --git a/doc/integration/README.md b/doc/integration/README.md index 25e8c1a51c1..227e2eec53c 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false --- @@ -43,14 +43,15 @@ GitLab also provides features to improve the security of your own application. F GitLab can be integrated with the following external service for continuous integration: -- [Jenkins](jenkins.md) CI. **(STARTER)** +- [Jenkins](jenkins.md) CI. ## Feature enhancements GitLab can be integrated with the following enhancements: - Add GitLab actions to [Gmail actions buttons](gmail_action_buttons_for_gitlab.md). -- Configure [PlantUML](../administration/integration/plantuml.md) to use diagrams in AsciiDoc documents. +- Configure [PlantUML](../administration/integration/plantuml.md) +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), @@ -64,12 +65,12 @@ Integration with services such as Campfire, Flowdock, HipChat, Pivotal Tracker, ### SSL certificate errors -When trying to integrate GitLab with services that are using self-signed certificates, it is very likely that SSL certificate errors will occur in different parts of the application, most likely Sidekiq. +When trying to integrate GitLab with services that are using self-signed certificates, it is very likely that SSL certificate errors occur in different parts of the application, most likely Sidekiq. There are two approaches you can take to solve this: 1. Add the root certificate to the trusted chain of the OS. -1. If using Omnibus, you can add the certificate to GitLab's trusted certificates. +1. If using Omnibus, you can add the certificate to the GitLab trusted certificates. **OS main trusted chain** diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index d290ffa92b9..a2720c82fe7 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Akismet @@ -15,7 +15,7 @@ Admin page. Privacy note: GitLab submits the user's IP and user agent to Akismet. -NOTE: **Note:** +NOTE: In GitLab 8.11 and later, all issues are submitted to Akismet. In earlier GitLab versions, this only applied to API and non-project members. diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index 339d97cb00f..7e531682faf 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Auth0 OmniAuth Provider diff --git a/doc/integration/azure.md b/doc/integration/azure.md index a9660e1d716..f22a94a01c7 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Microsoft Azure OAuth2 OmniAuth Provider diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index 3dc6983355c..81cbc42cf45 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -1,12 +1,12 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Integrate your GitLab server with Bitbucket Cloud -NOTE: **Note:** +NOTE: Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an earlier version, you must explicitly enable it. diff --git a/doc/integration/cas.md b/doc/integration/cas.md index e61988c3301..5a198e85f5c 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -1,12 +1,12 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # CAS OmniAuth Provider -To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab will supply 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 backchannel logout. +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 backchannel logout. 1. On your GitLab server, open the configuration file. diff --git a/doc/integration/chat_commands.md b/doc/integration/chat_commands.md index 1a4fb46046d..a0361064d87 100644 --- a/doc/integration/chat_commands.md +++ b/doc/integration/chat_commands.md @@ -3,3 +3,6 @@ redirect_to: 'slash_commands.md' --- This document was moved to [integration/slash_commands.md](slash_commands.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/crowd.md b/doc/integration/crowd.md index 30e3e888b29..e07e3435baf 100644 --- a/doc/integration/crowd.md +++ b/doc/integration/crowd.md @@ -3,3 +3,6 @@ redirect_to: '../administration/auth/crowd.md' --- This document was moved to [`administration/auth/crowd`](../administration/auth/crowd.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 095c58f17fc..52275649a67 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -2,7 +2,7 @@ type: reference stage: Enablement group: Global Search -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 --- # Elasticsearch integration **(STARTER ONLY)** @@ -23,8 +23,8 @@ and the advantage of the following special searches: | GitLab version | Elasticsearch version | |---------------------------------------------|-------------------------------| -| GitLab Enterprise Edition 13.6 or greater | Elasticsearch 7.x (6.4 - 6.x deprecated to be removed in 13.8) | -| GitLab Enterprise Edition 13.2 through 13.5 | Elasticsearch 6.4 through 7.x | +| GitLab Enterprise Edition 13.9 or greater | Elasticsearch 6.8 through 7.x | +| GitLab Enterprise Edition 13.3 through 13.8 | Elasticsearch 6.4 through 7.x | | GitLab Enterprise Edition 12.7 through 13.2 | Elasticsearch 6.x through 7.x | | GitLab Enterprise Edition 11.5 through 12.6 | Elasticsearch 5.6 through 6.x | | GitLab Enterprise Edition 9.0 through 11.4 | Elasticsearch 5.1 through 5.5 | @@ -83,6 +83,12 @@ After the data is added to the database or repository and [Elasticsearch is enabled in the Admin Area](#enabling-advanced-search) the search index will be updated automatically. +## Upgrading to a new Elasticsearch major version + +Since Elasticsearch can read and use indices created in the previous major version, you don't need to change anything in the GitLab configuration when upgrading Elasticsearch. + +The only thing worth noting is that if you have created your current index before GitLab 13.0, you might want to [reclaim the production index name](#reclaiming-the-gitlab-production-index-name) or reindex from scratch (which will implicitly create an alias). The latter might be faster depending on the GitLab instance size. Once you do that, you'll be able to perform zero-downtime reindexing and you will benefit from any future features that will make use of the alias. + ## Elasticsearch repository indexer For indexing Git repository data, GitLab uses an [indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). @@ -157,7 +163,7 @@ PREFIX=/usr sudo -E make install After installation, be sure to [enable Elasticsearch](#enabling-advanced-search). -NOTE: **Note:** +NOTE: If you see an error such as `Permission denied - /home/git/gitlab-elasticsearch-indexer/` while indexing, you may need to set the `production -> elasticsearch -> indexer_path` setting in your `gitlab.yml` file to `/usr/local/bin/gitlab-elasticsearch-indexer`, which is where the binary is installed. @@ -172,7 +178,7 @@ To enable Advanced Search, you need to have admin access to GitLab: 1. Navigate to **Admin Area** (wrench icon), then **Settings > General** and expand the **Advanced Search** section. - NOTE: **Note:** + NOTE: To see the Advanced Search section, you need an active Starter [license](../user/admin_area/license.md). @@ -218,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 GitLab's 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 GitLab's Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | -| `Bulk request concurrency` | The Bulk request concurrency indicates how many of GitLab's 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 GitLab's 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 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. | | `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. | ### Limiting namespaces and projects @@ -237,10 +243,10 @@ You can filter the selection dropdown by writing part of the namespace or projec  -NOTE: **Note:** +NOTE: If no namespaces or projects are selected, no Advanced Search indexing will take place. -CAUTION: **Warning:** +WARNING: If you have already indexed your instance, you will have to regenerate the index in order to delete all existing data for filtering to work correctly. To do this run the Rake tasks `gitlab:elastic:recreate_index` and `gitlab:elastic:clear_index_status`. Afterwards, removing a namespace or a project from the list will delete the data @@ -297,7 +303,7 @@ feature to atomically swap between two indices. We'll refer to each index as Instead of connecting directly to the `primary` index, we'll setup an index alias such as we can change the underlying index at will. -NOTE: **Note:** +NOTE: Any index attached to the production alias is deemed a `primary` and will be used by the GitLab Advanced Search integration. @@ -311,7 +317,7 @@ buffered and caught up once unpaused. ### Setup -TIP: **Tip:** +NOTE: If your index was created with GitLab 13.0 or greater, you can directly [trigger the reindex](#trigger-the-reindex-via-the-advanced-search-administration). @@ -327,7 +333,7 @@ export SECONDARY_INDEX="gitlab-production-$(date +%s)" ### Reclaiming the `gitlab-production` index name -CAUTION: **Caution:** +WARNING: It is highly recommended that you take a snapshot of your cluster to ensure there is a recovery path if anything goes wrong. @@ -398,7 +404,7 @@ To trigger the re-index from `primary` index: curl $CLUSTER_URL/$SECONDARY_INDEX/_count => 123123 ``` - TIP: **Tip:** + NOTE: Comparing the document count is more accurate than using the index size, as improvements to the storage might cause the new index to be smaller than the original one. 1. After you are confident your `secondary` index is valid, you can process to @@ -430,11 +436,76 @@ Under **Admin Area > Settings > General > Advanced Search > Elasticsearch zero-d Reindexing can be a lengthy process depending on the size of your Elasticsearch cluster. -CAUTION: **Caution:** +WARNING: After the reindexing is completed, the original index will be scheduled to be deleted after 14 days. You can cancel this action by pressing the cancel button. While the reindexing is running, you will be able to follow its progress under that same section. +### Mark the most recent reindex job as failed and unpause the indexing + +Sometimes, you might want to abandon the unfinished reindex job and unpause the indexing. You can achieve this via the following steps: + +1. Mark the most recent reindex job as failed: + + ```shell + # Omnibus installations + sudo gitlab-rake gitlab:elastic:mark_reindex_failed + + # Installations from source + bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production + ``` + +1. Uncheck the "Pause Elasticsearch indexing" checkbox in **Admin Area > Settings > General > Advanced Search**. + +## Background migrations + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/234046) in GitLab 13.6. + +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: + +```shell +curl "$CLUSTER_URL/gitlab-production-migrations/_search?q=*" | jq . +``` + +This should return something similar to: + +```json +{ + "took": 14, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 1, + "relation": "eq" + }, + "max_score": 1, + "hits": [ + { + "_index": "gitlab-production-migrations", + "_type": "_doc", + "_id": "20201105181100", + "_score": 1, + "_source": { + "completed": true + } + } + ] + } +} +``` + +In order to debug issues with the migrations you can check the [`elasticsearch.log` file](../administration/logs.md#elasticsearchlog). + ## GitLab Advanced Search Rake tasks Rake tasks are available to: @@ -456,9 +527,10 @@ The following are some available Rake tasks: | [`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. | -| [`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: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. | -NOTE: **Note:** +NOTE: The `TARGET_NAME` parameter is optional and will use the default index/alias name from the current `RAILS_ENV` if not set. ### Environment variables @@ -506,7 +578,7 @@ For basic guidance on choosing a cluster configuration you may refer to [Elastic - Generally, you will want to use at least a 2-node cluster configuration with one replica, which will allow you to have resilience. If your storage usage is growing quickly, you may want to plan horizontal scaling (adding more nodes) beforehand. - It's not recommended to use HDD storage with the search cluster, because it will take a hit on performance. It's better to use SSD storage (NVMe or SATA SSD drives for example). - You can use the [GitLab Performance Tool](https://gitlab.com/gitlab-org/quality/performance) to benchmark search performance with different search cluster sizes and configurations. -- `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 [Setting the heap size](https://www.elastic.co/guide/en/elasticsearch/reference/current/heap-size.html#heap-size) for more details. +- `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`. @@ -524,7 +596,7 @@ This section may be helpful in the event that the other [basic instructions](#enabling-advanced-search) cause problems due to large volumes of data being indexed. -CAUTION: **Warning:** +WARNING: Indexing a large instance will generate a lot of Sidekiq jobs. Make sure to prepare for this task by having a [Scalable and Highly Available Setup](../administration/reference_architectures/index.md) or creating [extra @@ -560,7 +632,7 @@ Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). In our experience, you can expect a 20% decrease in indexing time. After completing indexing in a later step, you can return `refresh` and `number_of_replicas` to their desired settings. - NOTE: **Note:** + NOTE: This step is optional but may help significantly speed up large indexing operations. ```shell @@ -609,7 +681,7 @@ Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). Where `ID_FROM` and `ID_TO` are project IDs. Both parameters are optional. The above example will index all projects from ID `1001` up to (and including) ID `2000`. - TIP: **Troubleshooting:** + NOTE: Sometimes the project indexing jobs queued by `gitlab:elastic:index_projects` can get interrupted. This may happen for many reasons, but it's always safe to run the indexing task again. It will skip repositories that have @@ -712,6 +784,17 @@ However, some larger installations may wish to tune the merge policy settings: ## 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: + +1. [`sidekiq.log`](../administration/logs.md#sidekiqlog) - All of the + indexing happens in Sidekiq, so much of the relevant logs for the + Elasticsearch integration can be found in this file. +1. [`elasticsearch.log`](../administration/logs.md#elasticsearchlog) - There + are additional logs specific to Elasticsearch that are sent to this file + that may contain useful diagnostic information about searching, + indexing or migrations. + Here are some common pitfalls and how to overcome them. ### How can I verify that my GitLab instance is using Elasticsearch? @@ -723,7 +806,7 @@ There are a couple of ways to achieve that: This is always correctly identifying whether the current project/namespace being searched is using Elasticsearch. -- From the admin area under **Settings > General > Elasticsearch** check that the +- From the admin area under **Settings > General > Advanced Search** check that the Advanced Search settings are checked. Those same settings there can be obtained from the Rails console if necessary: @@ -771,7 +854,7 @@ More [complex Elasticsearch API calls](https://www.elastic.co/guide/en/elasticse It is important to understand at which level the problem is manifesting (UI, Rails code, Elasticsearch side) to be able to [troubleshoot further](../administration/troubleshooting/elasticsearch.md#search-results-workflow). -NOTE: **Note:** +NOTE: The above instructions are not to be used for scenarios that only index a [subset of namespaces](#limiting-namespaces-and-projects). See [Elasticsearch Index Scopes](#advanced-search-index-scopes) for more information on searching for specific types of data. @@ -790,7 +873,7 @@ You can run `sudo gitlab-rake gitlab:elastic:projects_not_indexed` to display pr ### No new data is added to the Elasticsearch index when I push code -NOTE: **Note:** +NOTE: This was [fixed in GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35936) 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: @@ -845,7 +928,7 @@ see details in the [update guide](../update/upgrading_from_source.md). **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 Elasticsearch](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/aes-handling-errors.html#aes-handling-errors-yellow-cluster-status) service. -CAUTION: **Warning:** +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). 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): @@ -869,6 +952,13 @@ 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](#enabling-advanced-search). +### My Elasticsearch cluster has a plugin and the integration is not working + +Certain 3rd party plugins may introduce bugs in your cluster or for whatever +reason may be incompatible with our integration. You should try disabling +plugins so you can rule out the possibility that the plugin is causing the +problem. + ### Low-level troubleshooting There is a [more structured, lower-level troubleshooting document](../administration/troubleshooting/elasticsearch.md) for when you experience other issues, including poor performance. diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index a4fca36b154..b1eb9d0d2fe 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # External issue tracker @@ -16,7 +16,7 @@ Once configured, you can reference external issues using the format `CODE-123`, These references in GitLab merge requests, commits, or comments are automatically converted to links to the issues. -You can keep GitLab's issue tracker enabled in parallel or disable it. When enabled, the **Issues** link in the +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 diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index bb699fa90b7..b86958726a7 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -1,12 +1,12 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Facebook OAuth2 OmniAuth Provider -To enable the Facebook OmniAuth provider you must register your application with Facebook. Facebook will generate an app ID and secret key for you to use. +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. 1. Sign in to the [Facebook Developer Platform](https://developers.facebook.com/). @@ -101,4 +101,4 @@ To enable the Facebook OmniAuth provider you must register your application with 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. -On the sign in page there should now be a Facebook icon below the regular sign in form. Click the icon to begin the authentication process. Facebook will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. +On the sign in page there should now be a Facebook icon below the regular sign in form. Click the icon to begin the authentication process. Facebook asks the user to sign in and authorize the GitLab application. If everything goes well the user is returned to GitLab and signed in. diff --git a/doc/integration/github.md b/doc/integration/github.md index 8407920c631..c65027e3585 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Integrate your GitLab instance with GitHub @@ -12,19 +12,19 @@ with your GitHub account. ## Enabling GitHub OAuth -To enable the GitHub OmniAuth provider, you'll 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://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). -When you create an OAuth 2 app in GitHub, you'll need the following information: +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: **Note:** +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. -Once you have configured the GitHub provider, you'll need the following information, which you'll need to substitute in the GitLab configuration file, in the steps shown next. +After you have configured the GitHub provider, you need the following information, which you must substitute in the GitLab configuration file, in the steps shown next. | Setting from GitHub | Substitute in the GitLab configuration file | Description | |:---------------------|:---------------------------------------------|:------------| @@ -101,12 +101,12 @@ Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server: 1. Refresh the GitLab sign in page. You should now see a GitHub icon below the regular sign in form. -1. Click the icon to begin the authentication process. GitHub will ask the user to sign in and authorize the GitLab application. +1. Click the icon to begin the authentication process. GitHub asks the user to sign in and authorize the GitLab application. ## GitHub Enterprise with self-signed Certificate If you are attempting to import projects from GitHub Enterprise with a self-signed -certificate and the imports are failing, you will need to disable SSL verification. +certificate and the imports are failing, you must disable SSL verification. It should be disabled by adding `verify_ssl` to `false` in the provider configuration and changing the global Git `sslVerify` option to `false` in the GitLab server. @@ -125,7 +125,7 @@ gitlab_rails['omniauth_providers'] = [ ] ``` -You will also need to disable Git SSL verification on the server hosting GitLab. +You must also disable Git SSL verification on the server hosting GitLab. ```ruby omnibus_gitconfig['system'] = { "http" => ["sslVerify = false"] } @@ -142,7 +142,7 @@ For installation from source: args: { scope: 'user:email' } } ``` -You will also need to disable Git SSL verification on the server hosting GitLab. +You must also disable Git SSL verification on the server hosting GitLab. ```shell git config --global http.sslVerify false diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index c618d226290..37c91aedb15 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Integrate your server with GitLab.com @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Import projects from GitLab.com and login to your GitLab instance with your GitLab.com account. To enable the GitLab.com OmniAuth provider you must register your application with GitLab.com. -GitLab.com will generate an application ID and secret key for you to use. +GitLab.com generates an application ID and secret key for you to use. 1. Sign in to GitLab.com @@ -85,5 +85,5 @@ GitLab.com will generate an application ID and secret key for you to use. installed GitLab via Omnibus or from source respectively. 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 will ask the user to sign in and authorize the GitLab application. -If everything goes well the user will be returned to your GitLab instance and will be signed in. +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. diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index b4d12b90be0..04274c1c015 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -2,7 +2,7 @@ type: reference, how-to stage: Create 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/#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" --- # Gitpod Integration @@ -14,7 +14,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated > - 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)** -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. With [Gitpod](https://gitpod.io/) you can describe your dev environment as code to get fully set diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 72196fd0f52..1158d6c9bc8 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -1,22 +1,21 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Gmail actions buttons for GitLab GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview). -If correctly set up, emails that require an action will be marked in Gmail. +If correctly set up, emails that require an action are marked in Gmail.  To get this functioning, you need to be registered with Google. For instructions, see [Register with Google](https://developers.google.com/gmail/markup/registering-with-google). -*This process has a lot of steps so make sure that you fulfill all requirements set by Google.* -*Your application will be rejected by Google if you fail to do so.* +*This process has a lot of steps so make sure that you fulfill all requirements set by Google to avoid your application being rejected by Google.* In particular, note: @@ -25,6 +24,6 @@ In particular, note: (order of hundred emails a day minimum to Gmail) for a few weeks at least". - Have a very low rate of spam complaints from users. - Emails must be authenticated via DKIM or SPF. -- Before sending the final form ("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you will have to find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there. +- Before sending the final form ("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you must find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there. You can check how it looks going through all the steps laid out in the "Registering with Google" doc in [this GitLab.com issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/1517). diff --git a/doc/integration/google.md b/doc/integration/google.md index cd40aaff30a..cd00c854fea 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -1,13 +1,13 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Google OAuth2 OmniAuth Provider To enable the Google OAuth2 OmniAuth provider you must register your application -with Google. Google will generate a client ID and secret key for you to use. +with Google. Google generates a client ID and secret key for you to use. ## Enabling Google OAuth @@ -40,7 +40,7 @@ In Google's side: ``` 1. You should now be able to see a Client ID and Client secret. Note them down - or keep this page open as you will need them later. + or keep this page open as you need them later. 1. To enable projects to access [Google Kubernetes Engine](../user/project/clusters/index.md), you must also enable these APIs: - Google Kubernetes Engine API @@ -98,7 +98,7 @@ On your GitLab server: 1. Change `YOUR_APP_ID` to the client ID from the Google Developer page 1. Similarly, change `YOUR_APP_SECRET` to the client secret -1. Make sure that you configure GitLab to use an FQDN as Google will not accept +1. Make sure that you configure GitLab to use a fully-qualified domain name, as Google doesn't accept raw IP addresses. For Omnibus packages: @@ -119,6 +119,6 @@ On your GitLab server: installed GitLab via Omnibus or from source respectively. On the sign in page there should now be a Google icon below the regular sign in -form. Click the icon to begin the authentication process. Google will ask the +form. Click the icon to begin the authentication process. Google asks the user to sign in and authorize the GitLab application. If everything goes well -the user will be returned to GitLab and will be signed in. +the user is returned to GitLab and is signed in. diff --git a/doc/integration/img/sourcegraph_admin_v12_5.png b/doc/integration/img/sourcegraph_admin_v12_5.png Binary files differindex 54511541c87..7e2df9410ce 100644 --- a/doc/integration/img/sourcegraph_admin_v12_5.png +++ b/doc/integration/img/sourcegraph_admin_v12_5.png diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 7eb147c1fe6..7be2a6efd71 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -1,23 +1,21 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Jenkins CI service **(STARTER)** +# Jenkins CI service **(CORE)** -NOTE: **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 -[Migrating from Jenkins](../ci/migration/jenkins.md) documentation. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/246756) to Core in GitLab 13.7. From GitLab, you can trigger a Jenkins build when you push code to a repository, or when a merge request is created. In return, the Jenkins pipeline status is shown on merge requests widgets and on the GitLab project's home page. -To better understand GitLab's Jenkins integration, watch the following video: +To better understand the GitLab Jenkins integration, watch the following video: - [GitLab workflow with Jira issues and Jenkins pipelines](https://youtu.be/Jn-_fyra7xQ) + Use the Jenkins integration with GitLab when: - You plan to migrate your CI from Jenkins to [GitLab CI/CD](../ci/README.md) in the future, but @@ -29,11 +27,16 @@ For a real use case, read the blog post [Continuous integration: From Jenkins to Moving from a traditional CI plug-in to a single application for the entire software development life cycle can decrease hours spent on maintaining toolchains by 10% or more. For more details, see -the ['GitLab vs. Jenkins' comparison page](https://about.gitlab.com/devops-tools/jenkins-vs-gitlab.html). +the ['GitLab vs. Jenkins' comparison page](https://about.gitlab.com/devops-tools/jenkins-vs-gitlab/). + +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 +[Migrating from Jenkins](../ci/migration/jenkins.md) documentation. ## Configure GitLab integration with Jenkins -GitLab's Jenkins integration requires installation and configuration in both GitLab and Jenkins. +The GitLab Jenkins integration requires installation and configuration in both GitLab and Jenkins. In GitLab, you need to grant Jenkins access to the relevant projects. In Jenkins, you need to install and configure several plugins. @@ -54,9 +57,9 @@ Grant a GitLab user access to the select GitLab projects. 1. Create a new GitLab user, or choose an existing GitLab user. - This account will be used by Jenkins to access the GitLab projects. We recommend creating a GitLab + This account is used by Jenkins to access the GitLab projects. We recommend creating a GitLab user for only this purpose. If you use a person's account, and their account is deactivated or - deleted, the GitLab-Jenkins integration will stop working. + deleted, the GitLab-Jenkins integration stops working. 1. Grant the user permission to the GitLab projects. @@ -72,11 +75,11 @@ Create a personal access token to authorize Jenkins' access to GitLab. 1. Click **Access Tokens** in the sidebar. 1. Create a personal access token with the **API** scope checkbox checked. For more details, see [Personal access tokens](../user/profile/personal_access_tokens.md). -1. Record the personal access token's value, because it's required in [Configure the Jenkins server](#configure-the-jenkins-server). +1. Record the personal access token's value, because it's required in [Configure the Jenkins server](#configure-the-jenkins-server) section. ## Configure the Jenkins server -Install and configure the Jenkins plugins. Both plugins must be installed and configured to +Install and configure the Jenkins plugin. The plugin must be installed and configured to authorize the connection to GitLab. 1. On the Jenkins server, go to **Manage Jenkins > Manage Plugins**. @@ -96,12 +99,12 @@ For more information, see GitLab Plugin documentation about ## Configure the Jenkins project -Set up the Jenkins project you’re going to run your build on. +Set up the Jenkins project you intend to run your build on. 1. On your Jenkins instance, go to **New Item**. 1. Enter the project's name. 1. Choose between **Freestyle** or **Pipeline** and click **OK**. - We recommend a Freestyle project, because the Jenkins plugin will update the build status on + We recommend a Freestyle project, because the Jenkins plugin updates the build status on GitLab. In a Pipeline project, you must configure a script to update the status on GitLab. 1. Choose your GitLab connection from the dropdown. 1. Check the **Build when a change is pushed to GitLab** checkbox. @@ -136,6 +139,8 @@ Set up the Jenkins project you’re going to run your build on. Configure the GitLab integration with Jenkins. +### Option 1: Jenkins integration (recommended) + 1. Create a new GitLab project or choose an existing one. 1. Go to **Settings > Integrations**, then select **Jenkins CI**. 1. Turn on the **Active** toggle. @@ -153,6 +158,17 @@ Configure the GitLab integration with Jenkins. authentication. 1. Click **Test settings and save changes**. GitLab tests the connection to Jenkins. +### Option 2: Webhook + +If you are unable to provide GitLab with your Jenkins server login, you can use this option +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 (e.g. `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 ### Error in merge requests - "Could not connect to the CI server" @@ -183,14 +199,14 @@ WebHook Error => execution expired ``` If those are present, the request is exceeding the -[webhook timeout](../user/project/integrations/webhooks.md#receiving-duplicate-or-multiple-webhook-requests-triggered-by-one-event), +[webhook timeout](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered), which is set to 10 seconds by default. -To fix this the `gitlab_rails['webhook_timeout']` value will need to be increased -in the `gitlab.rb` config file, followed by the [`gitlab-ctl reconfigure` command](../administration/restart_gitlab.md). +To fix this the `gitlab_rails['webhook_timeout']` value must be increased +in the `gitlab.rb` configuration file, followed by the [`gitlab-ctl reconfigure` command](../administration/restart_gitlab.md). If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`), this -could also indicate that [webhook requests are timing out](../user/project/integrations/webhooks.md#receiving-duplicate-or-multiple-webhook-requests-triggered-by-one-event): +could also indicate that [webhook requests are timing out](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered): ```plaintext 2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index 63d5ac48765..b5d68e3183f 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -1,30 +1,30 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Jenkins CI (deprecated) service -NOTE: **Note:** +NOTE: In GitLab 8.3, Jenkins integration using the [GitLab Hook Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin) was deprecated in favor of the [GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin). Please use documentation for the new [Jenkins CI service](jenkins.md). -NOTE: **Note:** +NOTE: This service was [removed in v13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/1600) Integration includes: -- Trigger Jenkins build after push to repo +- Trigger Jenkins build after push to repository - Show build status on Merge Request page Requirements: - [Jenkins GitLab Hook plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin) -- Git clone access for Jenkins from GitLab repo (via SSH key) +- Git clone access for Jenkins from GitLab repository (via SSH key) ## Jenkins @@ -41,7 +41,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 will need a Deploy key. Read the documentation on +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). ### Jenkins service @@ -50,14 +50,13 @@ Now navigate to GitLab services page and activate Jenkins  -Done! Now when you push to GitLab - it will create a build for Jenkins. -And also you will be able to see merge request build status with a link to the Jenkins build. +Done! Now when you push to GitLab - it creates a build for Jenkins, and you can view the merge request build status with a link to the Jenkins build. ### Multi-project Configuration The GitLab Hook plugin in Jenkins supports the automatic creation of a project -for each feature branch. After configuration GitLab will trigger feature branch -builds and a corresponding project will be created in Jenkins. +for each feature branch. After configuration GitLab triggers feature branch +builds and a corresponding project is created in Jenkins. Configure the GitLab Hook plugin in Jenkins. Go to 'Manage Jenkins' and then 'Configure System'. Find the 'GitLab Web Hook' section and configure as shown below. diff --git a/doc/integration/jira.md b/doc/integration/jira.md index 37eba25fb5a..0e22bedd1cc 100644 --- a/doc/integration/jira.md +++ b/doc/integration/jira.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/integrations/jira.md' --- This document was moved to [another location](../user/project/integrations/jira.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md index 1bd3095edce..7488df3580e 100644 --- a/doc/integration/jira_development_panel.md +++ b/doc/integration/jira_development_panel.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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 --- # GitLab Jira Development Panel integration **(CORE)** @@ -73,7 +73,7 @@ When configuring Jira DVCS Connector: #### GitLab account configuration for DVCS -TIP: **Tip:** +NOTE: To ensure that regular user account maintenance doesn't impact your integration, create and use a single-purpose `jira` user in GitLab. @@ -89,7 +89,7 @@ create and use a single-purpose `jira` user in GitLab. replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com, this would be `https://gitlab.com/login/oauth/callback`. - NOTE: **Note:** + NOTE: If using a GitLab version earlier than 11.3, the `Redirect URI` must be `https://<gitlab.example.com>/-/jira/login/oauth/callback`. If you want Jira to have access to all projects, GitLab recommends that an administrator create the @@ -100,7 +100,7 @@ create and use a single-purpose `jira` user in GitLab. - Check **API** in the Scopes section and uncheck any other checkboxes. 1. Click **Save application**. GitLab displays the generated **Application ID** - and **Secret** values. Copy these values, which you will use in Jira. + and **Secret** values. Copy these values, which you use in Jira. #### Jira DVCS Connector setup @@ -125,7 +125,7 @@ If you're using GitLab.com and Jira Cloud, we recommend you use the replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com, this would be `https://gitlab.com/`. - NOTE: **Note:** + NOTE: If using a GitLab version earlier than 11.3 the **Host URL** value should be `https://<gitlab.example.com>/-/jira` For the **Client ID** field, use the **Application ID** value from the previous section. @@ -165,7 +165,7 @@ This error message is generated in Jira, after completing the **Add New Account* form and authorizing access. It indicates a connectivity issue from Jira to GitLab. No other error messages appear in any logs. -If there was an issue with SSL/TLS, this error message will be generated. +If there was an issue with SSL/TLS, this error message is generated. - The [GitLab Jira integration](../user/project/integrations/jira.md) requires GitLab to connect to Jira. Any TLS issues that arise from a private certificate authority or self-signed @@ -232,7 +232,7 @@ Potential resolutions: - If you're using GitLab Core or GitLab Starter, be sure you're using GitLab 13.4 or later. -[Contact GitLab Support](https://about.gitlab.com/support) if none of these reasons apply. +[Contact GitLab Support](https://about.gitlab.com/support/) if none of these reasons apply. #### Fixing synchronization issues @@ -245,11 +245,11 @@ resynchronize the information. To do so: 1. For each project, there's a sync button displayed next to the **last activity** date. To perform a *soft resync*, click the button, or complete a *full sync* by shift clicking the button. For more information, see - [Atlassian's documentation](https://confluence.atlassian.com/adminjiracloud/synchronize-an-account-972332890.html). + [Atlassian's documentation](https://support.atlassian.com/jira-cloud-administration/docs/synchronize-jira-cloud-to-bitbucket/). ### GitLab for Jira app -You can integrate GitLab.com and Jira Cloud using the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-for-jira) app in the Atlassian Marketplace. +You can integrate GitLab.com and Jira Cloud using the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app in the Atlassian Marketplace. This method is recommended when using GitLab.com and Jira Cloud because data is synchronized in realtime, while the DVCS connector updates data only once per hour. If you are not using both of these environments, use the [Jira DVCS Connector](#jira-dvcs-configuration) method. @@ -257,7 +257,7 @@ This method is recommended when using GitLab.com and Jira Cloud because data is For a walkthrough of the integration with GitLab for Jira, watch [Configure GitLab Jira Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube. 1. Go to **Jira Settings > Apps > Find new apps**, then search for GitLab. -1. Click **GitLab for Jira**, then click **Get it now**. Or go the [App in the marketplace directly](https://marketplace.atlassian.com/apps/1221011/gitlab-for-jira) +1. Click **GitLab for Jira**, then click **Get it now**. Or go the [App in the marketplace directly](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud)  1. After installing, click **Get started** to go to the configurations page. This page is always available under **Jira Settings > Apps > Manage apps**. @@ -267,12 +267,12 @@ For a walkthrough of the integration with GitLab for Jira, watch [Configure GitL **Link namespace to Jira**. The user setting up *GitLab for Jira* must have *Maintainer* access to the GitLab namespace. -NOTE: **Note:** +NOTE: The GitLab user only needs access when adding a new namespace. For syncing with Jira, we do not depend on the user's token.  -After a namespace is added, all future commits, branches and merge requests of all projects under that namespace will be 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. Past data cannot be synced at the moment. For more information, see [Usage](#usage). diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 50468443769..390c3ae3e7c 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -1,7 +1,7 @@ --- stage: Manage group: Access -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: reference, how-to --- @@ -13,13 +13,13 @@ GitLab can integrate with [Kerberos](https://web.mit.edu/kerberos/) as an authen [Kerberos](https://web.mit.edu/kerberos/) is a secure method for authenticating a request for a service in a computer network. Kerberos was developed in the Athena Project at the -[Massachusetts Institute of Technology (MIT)](http://web.mit.edu/). The name is taken from Greek +[Massachusetts Institute of Technology (MIT)](https://web.mit.edu/). The name is taken from Greek mythology; Kerberos was a three-headed dog who guarded the gates of Hades. ## Use-cases - GitLab can be configured to allow your users to sign with their Kerberos credentials. -- You can use Kerberos to [prevent](http://web.mit.edu/sipb/doc/working/guide/guide/node20.html) anyone from intercepting or eavesdropping on the transmitted password. +- You can use Kerberos to [prevent](https://web.mit.edu/sipb/doc/working/guide/guide/node20.html) anyone from intercepting or eavesdropping on the transmitted password. ## Configuration @@ -49,7 +49,7 @@ sudo chmod 0600 /etc/http.keytab #### Installations from source -NOTE: **Note:** +NOTE: For source installations, make sure the `kerberos` gem group [has been installed](../install/installation.md#install-gems). @@ -150,7 +150,7 @@ With that information at hand: 1. If `block_auto_created_users` is false, the Kerberos user is authenticated and is signed in to GitLab. -CAUTION: **Warning** +WARNING: We recommend that you retain the default for `block_auto_created_users`. Kerberos users who create accounts on GitLab without administrator knowledge can be a security risk. @@ -162,7 +162,7 @@ enabled, your users will be linked to their LDAP accounts on their first sign-in For this to work, some prerequisites must be met: The Kerberos username must match the LDAP user's UID. You can choose which LDAP -attribute is used as the UID in GitLab's [LDAP configuration](../administration/auth/ldap/index.md#configuration) +attribute is used as the UID in the GitLab [LDAP configuration](../administration/auth/ldap/index.md#configuration) but for Active Directory, this should be `sAMAccountName`. The Kerberos realm must match the domain part of the LDAP user's Distinguished @@ -216,11 +216,11 @@ GitLab users with a linked Kerberos account can also `git pull` and `git push` using Kerberos tokens, i.e., without having to send their password with each operation. -DANGER: **Warning:** +WARNING: There is a [known issue](https://github.com/curl/curl/issues/1261) with `libcurl` older than version 7.64.1 wherein it won't reuse connections when negotiating. This leads to authorization issues when push is larger than `http.postBuffer` -config. Ensure that Git is using at least `libcurl` 7.64.1 to avoid this. To +configuration. Ensure that Git is using at least `libcurl` 7.64.1 to avoid this. To know the `libcurl` version installed, run `curl-config --version`. ### HTTP Git access with Kerberos token (passwordless authentication) diff --git a/doc/integration/ldap.md b/doc/integration/ldap.md index 25e4cc52375..55c169bca80 100644 --- a/doc/integration/ldap.md +++ b/doc/integration/ldap.md @@ -3,3 +3,6 @@ redirect_to: '../administration/auth/ldap/index.md' --- This document was moved to [`administration/auth/ldap`](../administration/auth/ldap/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index 5957af292ab..88e9e3ef05c 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Sign into GitLab with (almost) any OAuth2 provider @@ -20,13 +20,13 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc ## Limitations of this Strategy -- It can only be used for Single Sign on, and will not provide any other access granted by any OAuth provider +- It can only be used for Single Sign on, and doesn't provide any other access granted by any OAuth provider (importing projects or users, etc) - It only supports the Authorization Grant flow (most common for client-server applications, like GitLab) - It is not able to fetch user information from more than one URL - It has not been tested with user information formats other than JSON -## Config Instructions +## Configuration Instructions 1. Register your application in the OAuth2 provider you wish to authenticate with. @@ -37,7 +37,7 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc ``` 1. You should now be able to get a Client ID and Client Secret. - Where this shows up will differ for each provider. + Where this shows up differs for each provider. This may also be called Application ID and Secret 1. On your GitLab server, open the configuration file. @@ -64,6 +64,6 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc 1. Restart GitLab for the changes to take effect On the sign in page there should now be a new button below the regular sign in form. -Click the button to begin your provider's authentication process. This will direct +Click the button to begin your provider's authentication process. This directs the browser to your OAuth2 Provider's authentication page. If everything goes well -the user will be returned to your GitLab instance and will be signed in. +the user is returned to your GitLab instance and is signed in. diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 68d10a3135e..82cb409c560 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab as OAuth2 authentication service provider @@ -48,12 +48,12 @@ In order to add a new application via your profile, navigate to  In the application form, enter a **Name** (arbitrary), and make sure to set up -correctly the **Redirect URI** which is the URL where users will be sent after +correctly the **Redirect URI** which is the URL where users are sent after they authorize with GitLab.  -When you hit **Submit** you will be provided with the application ID and +When you click **Submit** you are provided with the application ID and the application secret which you can then use with your application that connects to GitLab. @@ -71,12 +71,12 @@ the user authorization step is automatically skipped for this application. ## Authorized applications -Every application you authorized to use your GitLab credentials will be shown +Every application you authorized to use your GitLab credentials is shown in the **Authorized applications** section under **Profile Settings > Applications**.  -GitLab's OAuth applications support scopes, which allow various actions that any given +The GitLab OAuth applications support scopes, which allow various actions that any given application can perform such as `read_user` and `api`. There are many more scopes available. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index eebafab2693..53c19ddfdb1 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # OmniAuth @@ -49,28 +49,28 @@ contains some settings that are common for all providers. Before configuring individual OmniAuth providers there are a few global settings that are in common for all providers that we need to consider. -NOTE: **Note:** +NOTE: Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an -earlier version, you'll need to explicitly enable it. +earlier version, you must explicitly enable it. - `allow_single_sign_on` allows you to specify the providers you want to allow to automatically create an account. It defaults to `false`. If `false` users must - be created manually or they will not be able to sign in via OmniAuth. + be created manually or they can't sign in via OmniAuth. - `auto_link_ldap_user` can be used if you have [LDAP / ActiveDirectory](../administration/auth/ldap/index.md) integration enabled. It defaults to `false`. When enabled, users automatically - created through an OmniAuth provider will have their LDAP identity created in GitLab as well. + created through an OmniAuth provider have their LDAP identity created in GitLab as well. - `block_auto_created_users` defaults to `true`. If `true` auto created users will - be blocked by default and will have to be unblocked by an administrator before + be blocked by default and must be unblocked by an administrator before they are able to sign in. -NOTE: **Note:** +NOTE: If you set `block_auto_created_users` to `false`, make sure to only define providers under `allow_single_sign_on` that you are able to control, like SAML, Shibboleth, Crowd or Google, or set it to `false` otherwise any user on -the Internet will be able to successfully sign in to your GitLab without +the Internet can successfully sign in to your GitLab without administrative approval. -NOTE: **Note:** +NOTE: `auto_link_ldap_user` requires the `uid` of the user to be the same in both LDAP and the OmniAuth provider. @@ -141,8 +141,8 @@ OmniAuth provider for an existing user. 1. Go to profile settings (the silhouette icon in the top right corner). 1. Select the "Account" tab. 1. Under "Connected Accounts" select the desired OmniAuth provider, such as Twitter. -1. The user will be redirected to the provider. Once the user authorized GitLab - they will be redirected back to GitLab. +1. The user is redirected to the provider. After the user authorizes GitLab, + they are redirected back to GitLab. The chosen OmniAuth provider is now active and can be used to sign in to GitLab from then on. @@ -171,12 +171,12 @@ omniauth: > Introduced in GitLab 8.7. You can define which OmniAuth providers you want to be `external` so that all users -**creating accounts, or logging in via these providers** will not be able to have -access to internal projects. You will need to use the full name of the provider, +**creating accounts, or logging in via these providers** can't have +access to internal projects. You must use the full name of the provider, like `google_oauth2` for Google. Refer to the examples for the full names of the supported providers. -NOTE: **Note:** +NOTE: If you decide to remove an OmniAuth provider from the external providers list, you must manually update the users that use this method to sign in if you want their accounts to be upgraded to full internal accounts. @@ -196,7 +196,7 @@ omniauth: ## Using Custom OmniAuth Providers -NOTE: **Note:** +NOTE: The following information only applies for installations from source. GitLab uses [OmniAuth](https://github.com/omniauth/omniauth) for authentication and already ships @@ -206,7 +206,7 @@ these cases you can use the OmniAuth provider. ### Steps -These steps are fairly general and you will need to figure out the exact details +These steps are fairly general and you must figure out the exact details from the OmniAuth provider's documentation. - Stop GitLab: @@ -253,7 +253,7 @@ we'd like to at least help those with specific needs. Administrators are able to enable or disable Sign In via some OmniAuth providers. -NOTE: **Note:** +NOTE: By default Sign In is enabled via all the OAuth Providers that have been configured in `config/gitlab.yml`. In order to enable/disable an OmniAuth provider, go to Admin Area -> Settings -> Sign-in Restrictions section -> Enabled OAuth Sign-In sources and select the providers you want to enable or disable. @@ -343,8 +343,8 @@ omniauth: auto_sign_in_with_provider: azure_oauth2 ``` -Keep in mind that every sign-in attempt will be redirected to the OmniAuth -provider; you won't be able to sign in using local credentials. Ensure at least +Keep in mind that every sign-in attempt is redirected to the OmniAuth +provider; you can't sign in using local credentials. Ensure at least one of the OmniAuth users has admin permissions. You may also bypass the auto sign in feature by browsing to diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index bf33483f949..5bf079df800 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab as OpenID Connect identity provider @@ -22,7 +22,7 @@ mobile applications. On the client side, you can use [OmniAuth::OpenIDConnect](https://github.com/jjbohn/omniauth-openid-connect/) for Rails applications, or any of the other available [client implementations](https://openid.net/developers/libraries/#connect). -GitLab's implementation uses the [doorkeeper-openid_connect](https://github.com/doorkeeper-gem/doorkeeper-openid_connect "Doorkeeper::OpenidConnect website") gem, refer +The GitLab implementation uses the [doorkeeper-openid_connect](https://github.com/doorkeeper-gem/doorkeeper-openid_connect "Doorkeeper::OpenidConnect website") gem, refer to its README for more details about which parts of the specifications are supported. diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 545f60cddbf..bb5425187c1 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # reCAPTCHA @@ -25,7 +25,7 @@ To use reCAPTCHA, first you must create a site and private key. to `return CONDITONAL_ALLOW` so that the spam check short-circuits and triggers the response to return `recaptcha_html`. -NOTE: **Note:** +NOTE: Make sure you are viewing an issuable in a project that is public, and if you're working with an issue, the issue is public. ## Enabling reCAPTCHA for user logins via passwords diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 3290f18e2cb..1aca3b04eee 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Salesforce OmniAuth Provider @@ -82,8 +82,8 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create 1. [Reconfigure GitLab]( ../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. On the sign in page, there should now be a Salesforce icon below the regular sign in form. -Click the icon to begin the authentication process. Salesforce will ask the user to sign in and authorize the GitLab application. -If everything goes well, the user will be returned to GitLab and will be signed in. +Click the icon to begin the authentication process. Salesforce asks the user to sign in and authorize the GitLab application. +If everything goes well, the user is returned to GitLab and is signed in. -NOTE: **Note:** -GitLab requires the email address of each new user. Once the user is logged in using Salesforce, GitLab will redirect the user to the profile page where they will have to provide the email and verify the email. +NOTE: +GitLab requires the email address of each new user. Once the user is logged in using Salesforce, GitLab redirects the user to the profile page where they must provide the email and verify the email. diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 16a33a86472..af0a58eab59 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Access -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 --- # SAML OmniAuth Provider **(CORE ONLY)** @@ -378,7 +378,7 @@ You may also bypass the auto sign-in feature by browsing to ### `attribute_statements` -NOTE: **Note:** +NOTE: This setting should be used only to map attributes that are part of the OmniAuth `info` hash schema. @@ -536,7 +536,7 @@ args: { Your Identity Provider will encrypt the assertion with the public certificate of GitLab. GitLab will decrypt the EncryptedAssertion with its private key. -NOTE: **Note:** +NOTE: This integration uses the `certificate` and `private_key` settings for both assertion encryption and request signing. ## Request signing (optional) diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index 59374d8ad6f..e811cac4f0b 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -1,14 +1,14 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Shibboleth OmniAuth Provider -NOTE: **Note:** +NOTE: The preferred approach for integrating a Shibboleth authentication system -with GitLab 10 or newer is to use [GitLab's SAML integration](saml.md). This documentation is for Omnibus GitLab 9.x installs or older. +with GitLab 10 or newer is to use the [GitLab SAML integration](saml.md). This documentation is for Omnibus GitLab 9.x installs or older. In order to enable Shibboleth support in GitLab we need to use Apache instead of NGINX (It may be possible to use NGINX, however this is difficult to configure using the bundled NGINX provided in the Omnibus GitLab package). Apache uses mod_shib2 module for Shibboleth authentication and can pass attributes as headers to OmniAuth Shibboleth provider. @@ -16,7 +16,7 @@ To enable the Shibboleth OmniAuth provider you must configure Apache Shibboleth The installation and configuration of the module itself is out of the scope of this document. Check <https://wiki.shibboleth.net/confluence/display/SP3/Apache> for more information. -You can find Apache config in [GitLab Recipes](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache). +You can find Apache configuration in [GitLab Recipes](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache). The following changes are needed to enable Shibboleth: @@ -40,7 +40,7 @@ The following changes are needed to enable Shibboleth: </Location> ``` -1. Exclude Shibboleth URLs from rewriting. Add `RewriteCond %{REQUEST_URI} !/Shibboleth.sso` and `RewriteCond %{REQUEST_URI} !/shibboleth-sp`. Config should look like this: +1. Exclude Shibboleth URLs from rewriting. Add `RewriteCond %{REQUEST_URI} !/Shibboleth.sso` and `RewriteCond %{REQUEST_URI} !/shibboleth-sp`. Configuration should look like this: ```apache # Apache equivalent of Nginx try files @@ -52,12 +52,12 @@ The following changes are needed to enable Shibboleth: RequestHeader set X_FORWARDED_PROTO 'https' ``` - NOTE: **Note:** + NOTE: Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an - earlier version, you'll need to explicitly enable it in `/etc/gitlab/gitlab.rb`. + earlier version, you must explicitly enable it in `/etc/gitlab/gitlab.rb`. 1. In addition, add Shibboleth to `/etc/gitlab/gitlab.rb` as an OmniAuth provider. - User attributes will be sent from the + User attributes are sent from the Apache reverse proxy to GitLab as headers with the names from the Shibboleth attribute mapping. Therefore the values of the `args` hash should be in the form of `"HTTP_ATTRIBUTE"`. The keys in the hash are arguments @@ -100,12 +100,12 @@ The following changes are needed to enable Shibboleth: 1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect if you installed GitLab via Omnibus or from source respectively. -On the sign in page, there should now be a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You will be redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user will be returned to GitLab and will be signed in. +On the sign in page, there should now be a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You are redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user is returned to GitLab and is signed in. ## Apache 2.4 / GitLab 8.6 update The order of the first 2 Location directives is important. If they are reversed, -you will not get a Shibboleth session! +requesting a Shibboleth session fails! ```plaintext <Location /> diff --git a/doc/integration/slack.md b/doc/integration/slack.md index 815032a08d5..fbea9d3035c 100644 --- a/doc/integration/slack.md +++ b/doc/integration/slack.md @@ -3,3 +3,6 @@ redirect_to: '../user/project/integrations/slack.md' --- This document was moved to [another location](../user/project/integrations/slack.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index ea2c4b3e93f..6820ff8a0aa 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Slash Commands @@ -37,11 +37,11 @@ It is possible to create new issue, display issue details and search up to 5 iss ## Deploy command -In order to deploy to an environment, GitLab will try to find a deployment +In order to deploy to an environment, GitLab tries to find a deployment manual action in the pipeline. -If there is only one action for a given environment, it is going to be triggered. -If there is more than one action defined, GitLab will try to find an action +If there is only one action for a given environment, it is triggered. +If there is more than one action defined, GitLab tries to find an action which name equals the environment name we want to deploy to. -Command will return an error when no matching action has been found. +The command returns an error when no matching action has been found. diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 47c84643a7d..8e1a6cdcfd1 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -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: reference, how-to --- @@ -19,7 +19,7 @@ For GitLab.com users, see [Sourcegraph for GitLab.com](#sourcegraph-for-gitlabco <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, watch the video [Sourcegraph's new GitLab native integration](https://www.youtube.com/watch?v=LjVxkt4_sEA). -NOTE: **Note:** +NOTE: This feature requires user opt-in. After Sourcegraph has been enabled for your GitLab instance, you can choose to enable Sourcegraph [through your user preferences](#enable-sourcegraph-in-user-preferences). @@ -32,7 +32,7 @@ Before you can enable Sourcegraph code intelligence in GitLab you will need to: ### Enable the Sourcegraph feature flag -NOTE: **Note:** +NOTE: If you are running a self-managed instance, the Sourcegraph integration will not be available unless the feature flag `sourcegraph` is enabled. This can be done from the Rails console by instance administrators. @@ -64,6 +64,8 @@ Feature.enable(:sourcegraph, Project.find_by_full_path('my_group/my_project')) If you are new to Sourcegraph, head over to the [Sourcegraph installation documentation](https://docs.sourcegraph.com/admin) and get your instance up and running. +If you are using an HTTPS connection to GitLab, you will need to [configure HTTPS](https://docs.sourcegraph.com/admin/http_https_configuration) for your Sourcegraph instance. + ### Connect your Sourcegraph instance to your GitLab instance 1. Navigate to the site admin area in Sourcegraph. diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md index 22481e14236..d30308cea7a 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -1,19 +1,19 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Trello Power-Up -GitLab's Trello Power-Up enables you to seamlessly attach +The GitLab Trello Power-Up enables you to seamlessly attach GitLab **merge requests** to Trello cards.  ## Configuring the Power-Up -In order to get started, you will need to configure your Power-Up. +In order to get started, you must configure your Power-Up. In Trello: @@ -23,19 +23,19 @@ In Trello: 1. Select the `Settings` (gear) icon 1. In the popup menu, select `Authorize Account` -In this popup, fill in your `API URL` and `Personal Access Token`. After that, you will be able to attach any merge request to any Trello card on your selected Trello board. +In this popup, fill in your `API URL` and `Personal Access Token`. After that, you can attach any merge request to any Trello card on your selected Trello board. ## What is my API URL? Your API URL should be your GitLab instance URL with `/api/v4` appended in the end of the URL. For example, if your GitLab instance URL is `https://gitlab.com`, your API URL would be `https://gitlab.com/api/v4`. -If your instance's URL is `https://example.com`, your API URL will be `https://example.com/api/v4`. +If your instance's URL is `https://example.com`, your API URL is `https://example.com/api/v4`.  ## What is my Personal Access Token? -Your GitLab's personal access token will enable your GitLab account to be accessed +Your GitLab personal access token enables your GitLab account to be accessed from Trello. > Find it in GitLab by clicking on your avatar (upright corner), from which you access diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index bfe18c43e9d..8404352d0e9 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -1,12 +1,12 @@ --- -stage: none -group: unassigned -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 +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Twitter OAuth2 OmniAuth Provider -To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter will generate a client ID and secret key for you to use. +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). @@ -85,4 +85,4 @@ To enable the Twitter OmniAuth provider you must register your application with 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. -On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the authentication process. Twitter will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. +On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the authentication process. Twitter asks the user to sign in and authorize the GitLab application. If everything goes well the user is returned to GitLab and signed in. diff --git a/doc/integration/vault.md b/doc/integration/vault.md index ea63f16c72b..7f81fd3a7da 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -1,7 +1,7 @@ --- stage: Release -group: Release Management -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 +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- |
