diff options
Diffstat (limited to 'doc/integration')
| -rw-r--r-- | doc/integration/README.md | 105 | ||||
| -rw-r--r-- | doc/integration/elasticsearch.md | 85 | ||||
| -rw-r--r-- | doc/integration/external-issue-tracker.md | 2 | ||||
| -rw-r--r-- | doc/integration/index.md | 105 | ||||
| -rw-r--r-- | doc/integration/jira/connect-app.md | 34 | ||||
| -rw-r--r-- | doc/integration/jira/development_panel.md | 177 | ||||
| -rw-r--r-- | doc/integration/jira/dvcs.md | 46 | ||||
| -rw-r--r-- | doc/integration/jira/img/jira_dev_panel_jira_setup_5.png | bin | 11002 -> 10336 bytes | |||
| -rw-r--r-- | doc/integration/jira/img/jira_merge_request_close.png | bin | 21130 -> 0 bytes | |||
| -rw-r--r-- | doc/integration/jira/index.md | 7 | ||||
| -rw-r--r-- | doc/integration/jira/issues.md | 238 | ||||
| -rw-r--r-- | doc/integration/jira/jira_cloud_configuration.md | 2 | ||||
| -rw-r--r-- | doc/integration/jira/jira_server_configuration.md | 2 | ||||
| -rw-r--r-- | doc/integration/kerberos.md | 28 | ||||
| -rw-r--r-- | doc/integration/saml.md | 48 |
15 files changed, 504 insertions, 375 deletions
diff --git a/doc/integration/README.md b/doc/integration/README.md index c725cc08556..c5274535d98 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -1,105 +1,8 @@ --- -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 +redirect_to: 'index.md' --- -# GitLab integrations **(FREE)** +This document was moved to [another location](index.md). -GitLab can be integrated with external services for enhanced functionality. - -## Issue trackers - -You can use an [external issue tracker](external-issue-tracker.md) at the same time as the GitLab -issue tracker, or use only the external issue tracker. - -## Authentication sources - -GitLab can be configured to authenticate access requests with the following authentication sources: - -- Enable the [Auth0 OmniAuth](auth0.md) provider. -- Enable sign in with [Bitbucket](bitbucket.md) accounts. -- Configure GitLab to sign in using [CAS](cas.md). -- Integrate with [Kerberos](kerberos.md). -- Enable sign in via [LDAP](../administration/auth/ldap/index.md). -- Enable [OAuth2 provider](oauth_provider.md) application creation. -- Use [OmniAuth](omniauth.md) to enable sign in via Twitter, GitHub, GitLab.com, Google, - Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure, or Authentiq ID. -- Use GitLab as an [OpenID Connect](openid_connect_provider.md) identity provider. -- Authenticate to [Vault](vault.md) through GitLab OpenID Connect. -- Configure GitLab as a [SAML](saml.md) 2.0 Service Provider. - -## Security enhancements - -GitLab can be integrated with the following external services to enhance security: - -- [Akismet](akismet.md) helps reduce spam. -- Google [reCAPTCHA](recaptcha.md) helps verify new users. - -GitLab also provides features to improve the security of your own application. For more details see [GitLab Secure](../user/application_security/index.md). - -## Security partners - -GitLab has integrated with several security partners. For more information, see -[Security partners integration](security_partners/index.md). - -## Continuous integration - -GitLab can be integrated with the following external service for continuous integration: - -- [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) -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_search.md). - -## Integrations - -Integration with services such as Campfire, Flowdock, Jira, Pivotal Tracker, and Slack are available as [Integrations](../user/project/integrations/overview.md). - -## Troubleshooting - -### SSL certificate errors - -When trying to integrate GitLab with services using self-signed certificates, -SSL certificate errors can occur in different parts of the application. Sidekiq -is a common culprit. - -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 the GitLab trusted certificates. - -**OS main trusted chain** - -This [resource](https://manuals.gfi.com/en/kerio/connect/content/server-configuration/ssl-certificates/adding-trusted-root-certificates-to-the-server-1605.html) -has all the information you need to add a certificate to the main trusted chain. - -This [answer](https://superuser.com/questions/437330/how-do-you-add-a-certificate-authority-ca-to-ubuntu) -at Super User also has relevant information. - -**Omnibus Trusted Chain** - -[Install the self signed certificate or custom certificate authorities](https://docs.gitlab.com/omnibus/common_installation_problems/README.html#using-self-signed-certificate-or-custom-certificate-authorities) -in to Omnibus GitLab. - -It is enough to concatenate the certificate to the main trusted certificate -however it may be overwritten during upgrades: - -```shell -cat jira.pem >> /opt/gitlab/embedded/ssl/certs/cacert.pem -``` - -After that restart GitLab with: - -```shell -sudo gitlab-ctl restart -``` +<!-- This redirect file can be deleted after <2021-07-30>. --> +<!-- 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 a6c3afceeea..68e3f6c76c3 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -31,7 +31,7 @@ and the advantage of the [special searches](../user/search/advanced_search.md). Elasticsearch requires additional resources in excess of those documented in the [GitLab system requirements](../install/requirements.md). -The amount of resources (memory, CPU, storage) will vary greatly, based on the +The amount of resources (memory, CPU, storage) varies greatly, based on the amount of data being indexed into the Elasticsearch cluster. According to [Elasticsearch official guidelines](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_memory), each node should have: @@ -44,8 +44,8 @@ A few notes on CPU and storage: - CPU requirements for Elasticsearch tend to be minimal. There are specific scenarios where this isn't true, but GitLab.com isn't using Elasticsearch in - an exceptionally CPU-heavy way. More cores will be more performant than faster - CPUs. Extra concurrency from multiple cores will far outweigh a slightly + an exceptionally CPU-heavy way. More cores are more performant than faster + CPUs. Extra concurrency from multiple cores far outweighs a slightly faster clock speed in Elasticsearch. - Storage requirements for Elasticsearch are important, especially for @@ -60,7 +60,7 @@ A few notes on CPU and storage: for the calculation. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221177) in GitLab 13.10. Keep in mind, these are **minimum requirements** for Elasticsearch. -Heavily-used Elasticsearch clusters will likely require considerably more +Heavily-used Elasticsearch clusters likely require considerably more resources. ## Installing Elasticsearch @@ -77,26 +77,26 @@ service. Running Elasticsearch on the same server as GitLab is not recommended and can cause a degradation in GitLab instance performance. **For a single node Elasticsearch cluster the functional cluster health status -will be yellow** (will never be green) because the primary shard is allocated but +is yellow** (will never be green) because the primary shard is allocated but replicas can not be as there is no other node to which Elasticsearch can assign a replica. 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 +enabled in the Admin Area](#enabling-advanced-search) the search index is 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 reindex from scratch (which will implicitly create an alias) in order to use some features, for example [Zero downtime reindexing](#zero-downtime-reindexing). Once you do that, you'll be able to perform zero-downtime reindexing and will benefit from any future features that make use of the alias. +The only thing worth noting is that if you have created your current index before GitLab 13.0, you might want to reindex from scratch (which implicitly creates an alias) in order to use some features, for example [Zero downtime reindexing](#zero-downtime-reindexing). Once you do that, you are able to perform zero-downtime reindexing and will benefit from any future features that make use of the alias. If you are unsure when your current index was created, you can check whether it was created after GitLab 13.0 by using the [Elasticsearch cat aliases API](https://www.elastic.co/guide/en/elasticsearch/reference/7.11/cat-alias.html). If the list of aliases returned contains an entry for `gitlab-production` that points to an index named `gitlab-production-<numerical timestamp>`, your index was created after GitLab 13.0. -If the `gitlab-production` alias is missing, you'll need to reindex from scratch to use +If the `gitlab-production` alias is missing, you need to reindex from scratch to use features such as Zero-downtime reindexing. ## Elasticsearch repository indexer @@ -108,6 +108,7 @@ The way you install the Go indexer depends on your version of GitLab: - For Omnibus GitLab 11.8 or greater, see [Omnibus GitLab](#omnibus-gitlab). - For installations from source or older versions of Omnibus GitLab, [install the indexer from source](#from-source). +- If you are using GitLab Development Kit, see [GDK Elasticsearch how-to](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/elasticsearch.md) ### Omnibus GitLab @@ -116,7 +117,7 @@ The former Ruby-based indexer was removed in [GitLab 12.3](https://gitlab.com/gi ### From source -First, we need to install some dependencies, then we'll build and install +First, we need to install some dependencies, then we build and install the indexer itself. This project relies on [ICU](http://site.icu-project.org/) for text encoding, @@ -229,7 +230,9 @@ The following Elasticsearch settings are available: | `Elasticsearch indexing` | Enables or disables Elasticsearch indexing and creates an empty index if one does not already exist. You may want to enable indexing but disable search in order to give the index time to be fully completed, for example. Also, keep in mind that this option doesn't have any impact on existing data, this only enables/disables the background indexer which tracks data changes and ensures new data is indexed. | | `Pause Elasticsearch indexing` | Enables or disables temporary indexing pause. This is useful for cluster migration/reindexing. All changes are still tracked, but they are not committed to the Elasticsearch index until resumed. | | `Search with Elasticsearch enabled` | Enables or disables using Elasticsearch in search. | -| `URL` | The URL to use for connecting to Elasticsearch. Use a comma-separated list to support clustering (e.g., `http://host1, https://host2:9200`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). Special characters in the username or password should use [percentage encoding](https://en.wikipedia.org/wiki/Percent-encoding). | +| `URL` | The URL of your Elasticsearch instance. Use a comma-separated list to support clustering (for example, `http://host1, https://host2:9200`). If your Elasticsearch instance is password-protected, use the `Username` and `Password` fields described below. Alternatively, use inline credentials such as `http://<username>:<password>@<elastic_host>:9200/`. | +| `Username` | The `username` of your Elasticsearch instance. | +| `Password` | The password of your Elasticsearch instance. | | `Number of Elasticsearch shards` | Elasticsearch indexes are split into multiple shards for performance reasons. In general, you should use at least 5 shards, and indexes with tens of millions of documents need to have more shards ([see below](#guidance-on-choosing-optimal-cluster-configuration)). Changes to this value do not take effect until the index is recreated. You can read more about tradeoffs in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/scalability.html). | | `Number of Elasticsearch replicas` | Each Elasticsearch shard can have a number of replicas. These are a complete copy of the shard, and can provide increased query performance or resilience against hardware failure. Increasing this value will greatly increase total disk space required by the index. | | `Limit namespaces and projects that can be indexed` | Enabling this will allow you to select namespaces and projects to index. All other namespaces and projects will use database search instead. Please note that if you enable this option but do not select any namespaces or projects, none will be indexed. [Read more below](#limiting-namespaces-and-projects). @@ -326,16 +329,57 @@ index alias to it which becomes the new `primary` index. At the end, we resume t > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34069) in GitLab 13.2. > - A scheduled index deletion and the ability to cancel it was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38914) in GitLab 13.3. +> - Support for retries during reindexing was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55681) in GitLab 13.12. -Under **Admin Area > Settings > Advanced Search > Elasticsearch zero-downtime reindexing**, click on **Trigger cluster reindexing**. +To trigger the reindexing process: + +1. Sign in to your GitLab instance as an administrator. +1. Go to **Admin Area > Settings > Advanced Search > Elasticsearch zero-downtime reindexing**. +1. Select **Trigger cluster reindexing**. Reindexing can be a lengthy process depending on the size of your Elasticsearch cluster. -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. +After this process is completed, the original index is scheduled to be deleted after +14 days. You can cancel this action by pressing the **Cancel** button on the same +page you triggered the reindexing process. While the reindexing is running, you will be able to follow its progress under that same section. +#### Elasticsearch zero-downtime reindexing + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55681) in GitLab 13.12. + +The following reindex settings are available in **Admin Area > Settings > Advanced Search > Elasticsearch zero-downtime reindexing**: + +- [Slice multiplier](#slice-multiplier) +- [Maximum running slices](#maximum-running-slices) + +##### Slice multiplier + +The slice multiplier calculates the [number of slices during reindexing](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html#docs-reindex-slice). + +GitLab uses [manual slicing](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html#docs-reindex-manual-slice) +to control the reindex efficiently and safely, which enables users to retry only +failed slices. + +The multiplier defaults to `2` and applies to the number of shards per index. +For example, if this value is `2` and your index has 20 shards, then the +reindex task is split into 40 slices. + +##### Maximum running slices + +The maximum running slices parameter defaults to `60` and corresponds to the +maximum number of slices allowed to run concurrently during Elasticsearch +reindexing. + +Setting this value too high can have adverse performance impacts as your cluster +may become heavily saturated with searches and writes. Setting this value too +low may lead the reindexing process to take a very long time to complete. + +The best value for this will depend on your cluster size, whether you're willing +to accept some degraded search performance during reindexing, and how important +it is for the reindex to finish quickly and resume indexing. + ### Mark the most recent reindex job as failed and resume the indexing Sometimes, you might want to abandon the unfinished reindex job and resume the indexing. You can achieve this via the following steps: @@ -950,3 +994,18 @@ Advanced Search will store all the projects in the same Elasticsearch indexes, however searches will only surface results that can be viewed by the user. Advanced Search will honor all permission checks in the application by filtering out projects that a user does not have access to at search time. + +### Access requirements for the self-managed AWS Elasticsearch Service + +To use the self-managed AWS Elasticsearch Service with GitLab, configure your instance's domain access policies +to contain the actions below. +See [Identity and Access Management in Amazon Elasticsearch Service](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-ac.html) for details. + +```plaintext +es:ESHttpDelete +es:ESHttpGet +es:ESHttpHead +es:ESHttpPost +es:ESHttpPut +es:ESHttpPatch +``` diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index 4e00057c4b7..e82c21947e2 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -31,7 +31,7 @@ Visit the links below for details: - [Bugzilla](../user/project/integrations/bugzilla.md) - [Custom Issue Tracker](../user/project/integrations/custom_issue_tracker.md) - [Engineering Workflow Management](../user/project/integrations/ewm.md) -- [Jira](../user/project/integrations/jira.md) +- [Jira](../integration/jira/index.md) - [Redmine](../user/project/integrations/redmine.md) - [YouTrack](../user/project/integrations/youtrack.md) diff --git a/doc/integration/index.md b/doc/integration/index.md new file mode 100644 index 00000000000..c725cc08556 --- /dev/null +++ b/doc/integration/index.md @@ -0,0 +1,105 @@ +--- +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 +--- + +# GitLab integrations **(FREE)** + +GitLab can be integrated with external services for enhanced functionality. + +## Issue trackers + +You can use an [external issue tracker](external-issue-tracker.md) at the same time as the GitLab +issue tracker, or use only the external issue tracker. + +## Authentication sources + +GitLab can be configured to authenticate access requests with the following authentication sources: + +- Enable the [Auth0 OmniAuth](auth0.md) provider. +- Enable sign in with [Bitbucket](bitbucket.md) accounts. +- Configure GitLab to sign in using [CAS](cas.md). +- Integrate with [Kerberos](kerberos.md). +- Enable sign in via [LDAP](../administration/auth/ldap/index.md). +- Enable [OAuth2 provider](oauth_provider.md) application creation. +- Use [OmniAuth](omniauth.md) to enable sign in via Twitter, GitHub, GitLab.com, Google, + Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure, or Authentiq ID. +- Use GitLab as an [OpenID Connect](openid_connect_provider.md) identity provider. +- Authenticate to [Vault](vault.md) through GitLab OpenID Connect. +- Configure GitLab as a [SAML](saml.md) 2.0 Service Provider. + +## Security enhancements + +GitLab can be integrated with the following external services to enhance security: + +- [Akismet](akismet.md) helps reduce spam. +- Google [reCAPTCHA](recaptcha.md) helps verify new users. + +GitLab also provides features to improve the security of your own application. For more details see [GitLab Secure](../user/application_security/index.md). + +## Security partners + +GitLab has integrated with several security partners. For more information, see +[Security partners integration](security_partners/index.md). + +## Continuous integration + +GitLab can be integrated with the following external service for continuous integration: + +- [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) +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_search.md). + +## Integrations + +Integration with services such as Campfire, Flowdock, Jira, Pivotal Tracker, and Slack are available as [Integrations](../user/project/integrations/overview.md). + +## Troubleshooting + +### SSL certificate errors + +When trying to integrate GitLab with services using self-signed certificates, +SSL certificate errors can occur in different parts of the application. Sidekiq +is a common culprit. + +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 the GitLab trusted certificates. + +**OS main trusted chain** + +This [resource](https://manuals.gfi.com/en/kerio/connect/content/server-configuration/ssl-certificates/adding-trusted-root-certificates-to-the-server-1605.html) +has all the information you need to add a certificate to the main trusted chain. + +This [answer](https://superuser.com/questions/437330/how-do-you-add-a-certificate-authority-ca-to-ubuntu) +at Super User also has relevant information. + +**Omnibus Trusted Chain** + +[Install the self signed certificate or custom certificate authorities](https://docs.gitlab.com/omnibus/common_installation_problems/README.html#using-self-signed-certificate-or-custom-certificate-authorities) +in to Omnibus GitLab. + +It is enough to concatenate the certificate to the main trusted certificate +however it may be overwritten during upgrades: + +```shell +cat jira.pem >> /opt/gitlab/embedded/ssl/certs/cacert.pem +``` + +After that restart GitLab with: + +```shell +sudo gitlab-ctl restart +``` diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index b096d5bff61..a080d513afa 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -4,12 +4,12 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab for Jira app **(FREE SAAS)** +# GitLab.com for Jira Cloud app **(FREE SAAS)** 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. The user configuring GitLab for Jira must have -[Maintainer](../../user/permissions.md) permissions in the GitLab namespace. +[GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) +app in the Atlassian Marketplace. The user configuring GitLab.com for Jira Cloud must have +[Maintainer](../../user/permissions.md) permissions in the GitLab.com namespace. This integration method supports [smart commits](dvcs.md#smart-commits). @@ -18,30 +18,30 @@ synchronized in real-time. The DVCS connector updates data only once per hour. If you are not using both of these environments, use the [Jira DVCS Connector](dvcs.md) method. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -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. +For a walkthrough of the integration with GitLab.com for Jira Cloud, watch +[Configure GitLab.com Jira Could 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 to the +1. Click **GitLab.com for Jira Cloud**, then click **Get it now**, or go to 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**. -  +  1. If not already signed in to GitLab.com, you must sign in as a user with [Maintainer](../../user/permissions.md) permissions to add namespaces. -  +  1. Select **Add namespace** to open the list of available namespaces. 1. Identify the namespace you want to link, and select **Link**. -  +  NOTE: -The GitLab user only needs access when adding a new namespace. For syncing with +The GitLab.com 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: @@ -52,10 +52,10 @@ After a namespace is added: Support for syncing past branch and commit data [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/263240). -## Install the GitLab Jira Cloud application for self-managed instances **(FREE SELF)** +## Install the GitLab.com for Jira Cloud application for self-managed instances **(FREE SELF)** If your GitLab instance is self-managed, you must follow some -extra steps to install the GitLab Jira Cloud application. +extra steps to install the GitLab.com for Jira Cloud application. Each Jira Cloud application must be installed from a single location. Jira fetches a [manifest file](https://developer.atlassian.com/cloud/jira/platform/connect-app-descriptor/) @@ -91,7 +91,7 @@ from outside the Marketplace, which allows you to install the application: 1. Disable [development mode](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-2--enable-development-mode) on your Jira instance. -The **GitLab for Jira** app now displays under **Manage apps**. You can also +The **GitLab.com for Jira Cloud** app now displays under **Manage apps**. You can also click **Get started** to open the configuration page rendered from your GitLab instance. NOTE: @@ -121,9 +121,9 @@ for details. NOTE: DVCS means distributed version control system. -## Troubleshooting GitLab for Jira +## Troubleshooting GitLab.com for Jira Cloud -The GitLab for Jira App uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies. This can lead to a message saying that the user needs to log in on GitLab.com even though the user is already logged in. +The GitLab.com for Jira Cloud app uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies. This can lead to a message saying that the user needs to log in on GitLab.com even though the user is already logged in. > "You need to sign in or sign up before continuing." diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index 1617e950104..3aba2e3b3a0 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -8,55 +8,75 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/233149) to GitLab Free in 13.4. -The Jira Development panel integration allows you to reference Jira issues in GitLab, displaying -activity in the [Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) -in the issue. +With the Jira Development panel integration, you can reference Jira issues in GitLab. +When configured, activity (such as pipeline, deployment, and feature flags) displays in the Jira issue's +[Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). +From the Development panel, you can open a detailed view and +[take various actions](#use-the-integration), including creating a new merge request from a branch: -It complements the [GitLab Jira integration](../../user/project/integrations/jira.md). You may choose -to configure both integrations to take advantage of both sets of features. See a -[feature comparison](index.md#direct-feature-comparison). + -## Features +The information displayed in the Jira Development panel depends on where you mention the Jira issue ID: | Your mention of Jira issue ID in GitLab context | Automated effect in Jira issue | |---------------------------------------------------|--------------------------------------------------------------------------------------------------------| | In a merge request | Link to the MR is displayed in Development panel. | | In a branch name | Link to the branch is displayed in Development panel. | | In a commit message | Link to the commit is displayed in Development panel. | -| In a commit message with Jira Smart Commit format | Displays your custom comment or logged time spent and/or performs specified issue transition on merge. | - -With this integration, you can access related GitLab merge requests, branches, and commits directly from a Jira issue, reflecting your work in GitLab. From the Development panel, you can open a detailed view and take actions including creating a new merge request from a branch. For more information, see [Usage](#usage). +| In a commit message with Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) | Displays your custom comment or logged time spent and/or performs specified issue transition on merge. | This integration connects all GitLab projects to projects in the Jira instance in either: -- A top-level group. A top-level GitLab group is one that does not have any parent group itself. All - the projects of that top-level group, as well as projects of the top-level group's subgroups nesting - down, are connected. -- A personal namespace, which then connects the projects in that personal namespace to Jira. +- A top-level GitLab group: Connects the projects in a group with no parent group, + including the projects in its subgroups. +- A personal namespace: Connects the projects in that personal namespace to Jira. + +This differs from the [Jira integration](index.md), +where the mapping is between one GitLab project and the entire Jira instance. +You can install both integrations to take advantage of both sets of features. +A [feature comparison](index.md#direct-feature-comparison) is available. + +## Use the integration + +After the integration is [set up on GitLab and Jira](#configure-the-integration), you can: -This differs from the [Jira integration](../../user/project/integrations/jira.md), where the mapping is between one GitLab project and the entire Jira instance. +- Refer to any Jira issue by its ID (in uppercase) in GitLab branch names, + commit messages, and merge request titles. +- See the linked branches, commits, and merge requests in Jira issues: -Additional features provided by the Jira Development Panel integration include: +Merge requests are called "pull requests" in Jira issues. + +Select the links to see your GitLab repository data. + + + + -- In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests. -- Use Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in GitLab to add Jira comments, log time spent on the issue, or apply any issue transition. -- Showing pipeline, deployment, and feature flags in Jira issues. +### Use Jira Smart Commits -## Configuration +With Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html), +you can use GitLab to add Jira comments, log time spent on the issue, or apply any issue transition. + +For more information about using Jira Smart Commits to track time against an issue, specify +an issue transition, or add a custom comment, read the Atlassian page +[Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html). + +## Configure the integration <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview of how to configure Jira Development panel integration, see [Agile Management - GitLab Jira Development panel integration](https://www.youtube.com/watch?v=VjVTOmMl85M&feature=youtu.be). +For an overview of how to configure Jira Development panel integration, see +[Agile Management - GitLab Jira Development panel integration](https://www.youtube.com/watch?v=VjVTOmMl85M). -We recommend that a GitLab group maintainer or group owner, or instance administrator (in the case of -self-managed GitLab) set up the integration to simplify administration. +To simplify administration, we recommend that a GitLab group maintainer or group owner +(or instance administrator in the case of self-managed GitLab) set up the integration. -| If you use Jira on: | GitLab.com customers need: | GitLab self-managed customers need: | -|-|-|-| -| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab and Jira. | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab Jira Cloud application for self-managed instances](connect-app.md#install-the-gitlab-jira-cloud-application-for-self-managed-instances) for more information. | +| Jira usage | GitLab.com customers need | GitLab self-managed customers need | +|------------|---------------------------|------------------------------------| +| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab and Jira. | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab Jira Cloud application for self-managed instances](connect-app.md#install-the-gitlabcom-for-jira-cloud-application-for-self-managed-instances) for more information. | | Your own server | The Jira DVCS (distributed version control system) connector. This syncs data hourly. | The [Jira DVCS Connector](dvcs.md). | -Each GitLab project can be configured to connect to an entire Jira instance. That means one GitLab -project can interact with _all_ Jira projects in that instance, once configured. For: +Each GitLab project can be configured to connect to an entire Jira instance. That means after +configuration, one GitLab project can interact with all Jira projects in that instance. For: - The [view Jira issues](issues.md#view-jira-issues) feature, you must associate a GitLab project with a specific Jira project. @@ -68,88 +88,67 @@ documentation for [central administration of project integrations](../../user/ad To enable the Jira service in GitLab, you must: -1. Configure the project in Jira. -1. Enter the correct values in GitLab. +1. [Configure the project in Jira](dvcs.md#configure-jira-for-dvcs). + The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`. +1. [Enter the correct values in GitLab](#configure-gitlab). ### Configure GitLab -> **Notes:** -> -> - The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`. -> - In order to support Oracle's Access Manager, GitLab sends additional cookies -> to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with -> a value of `fromDialog`. - -To enable the Jira integration in a project: - -1. Go to the project's [Integrations page](../../user/project/integrations/overview.md#accessing-integrations) and select the - **Jira** service. +To enable the integration in your GitLab project, after you +[configure your Jira project](dvcs.md#configure-jira-for-dvcs): +1. Ensure your GitLab installation does not use a relative URL, as described in + [Limitations](#limitations). +1. Go to your project and select [**Settings > Integrations**](../../user/project/integrations/overview.md#accessing-integrations). +1. Select **Jira**. 1. Select **Enable integration**. - -1. Select **Trigger** actions. - This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, - should link the Jira issue back to that source commit/MR and transition the Jira issue, if - indicated. - -1. To include a comment on the Jira issue when the above reference is made in GitLab, select +1. Select **Trigger** actions. Your choice determines whether a mention of Jira issue + (in a GitLab commit, merge request, or both) creates a cross-link in Jira back to GitLab. +1. To comment in the Jira issue when a **Trigger** action is made in GitLab, select **Enable comments**. - -1. To transition Jira issues when a [closing reference](../../user/project/issues/managing_issues.md#closing-issues-automatically) is made in GitLab, - select **Enable Jira transitions**. - -1. Enter the further details on the page as described in the following table. - - | Field | Description | - | ----- | ----------- | - | `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. For example, `https://jira.example.com`. | - | `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira on Atlassian cloud**. | - | `Username or Email` | Created in [configure Jira](dvcs.md#configure-jira-for-dvcs) step. Use `username` for **Jira Server** or `email` for **Jira on Atlassian cloud**. | - | `Password/API token` | Created in [configure Jira](dvcs.md#configure-jira-for-dvcs) step. Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**. | - +1. To transition Jira issues when a + [closing reference](../../user/project/issues/managing_issues.md#closing-issues-automatically) + is made in GitLab, select **Enable Jira transitions**. +1. Provide Jira configuration information: + - **Web URL**: The base URL to the Jira instance web interface you're linking to + this GitLab project, such as `https://jira.example.com`. + - **Jira API URL**: The base URL to the Jira instance API, such as `https://jira-api.example.com`. + Defaults to the **Web URL** value if not set. Leave blank if using **Jira on Atlassian cloud**. + - **Username or Email**: Created when you [configured Jira](dvcs.md#configure-jira-for-dvcs). + For **Jira Server**, use `username`. For **Jira on Atlassian cloud**, use `email`. + - **Password/API token**: Created when you [configured Jira](dvcs.md#configure-jira-for-dvcs). + Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**. 1. To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and enter a Jira project key. **(PREMIUM)** - You can only display issues from a single Jira project within a given GitLab project. + You can display issues only from a single Jira project in a given GitLab project. WARNING: - If you enable Jira issues with the setting above, all users that have access to this GitLab project - are able to view all issues from the specified Jira project. - -1. To enable creation of issues for vulnerabilities, select **Enable Jira issues creation from vulnerabilities**. - - 1. Select the **Jira issue type**. If the dropdown is empty, select refresh (**{retry}**) and try again. + If you enable Jira issues with this setting, all users with access to this GitLab project + can view all issues from the specified Jira project. +1. To enable issue creation for vulnerabilities, select **Enable Jira issues creation from vulnerabilities**. +1. Select the **Jira issue type**. If the dropdown is empty, select refresh (**{retry}**) and try again. 1. To verify the Jira connection is working, select **Test settings**. - 1. Select **Save changes**. Your GitLab project can now interact with all Jira projects in your instance and the project now displays a Jira link that opens the Jira project. -## Usage - -After the integration is set up on GitLab and Jira, you can: - -- Refer to any Jira issue by its ID in GitLab branch names, commit messages, and merge request - titles. -- See the linked branches, commits, and merge requests in Jira issues (merge requests are - called "pull requests" in Jira issues). - -Jira issue IDs must be formatted in uppercase for the integration to work. - - +## Limitations -Click the links to see your GitLab repository data. +This integration is not supported on GitLab instances under a +[relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab). +For example, `http://example.com/gitlab`. - +## Related topics - +- [Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in Jira -For more information on using Jira Smart Commits to track time against an issue, specify an issue transition, or add a custom comment, see the Atlassian page [Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html). +## Troubleshooting -## Limitations +### Cookies for Oracle's Access Manager -This integration is not supported on GitLab instances under a -[relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab). -For example, `http://example.com/gitlab`. +To support Oracle's Access Manager, GitLab sends additional cookies +to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with +a value of `fromDialog`. diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md index 5d315ebd802..89d1d70d6aa 100644 --- a/doc/integration/jira/dvcs.md +++ b/doc/integration/jira/dvcs.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Jira DVCS connector +# Jira DVCS connector **(FREE)** Use the Jira DVCS (distributed version control system) connector if you self-host either your Jira instance or your GitLab instance, and you want to sync information @@ -18,7 +18,7 @@ are accessible. - **Jira Cloud**: Your instance must be accessible through the internet. - **Jira Server**: Your network must allow access to your instance. -## Smart commits +## Smart Commits When connecting GitLab with Jira with DVCS, you can process your Jira issues using special commands, called @@ -31,12 +31,34 @@ in your commit messages. With Smart Commits, you can: Commands must be in the first line of the commit message. The [Jira Software documentation](https://support.atlassian.com/jira-software-cloud/docs/process-issues-with-smart-commits/) -contains more information about how smart commits work, and what commands are available +contains more information about how Smart Commits work, and what commands are available for your use. -For smart commits to work, the committing user on GitLab must have a corresponding +For Smart Commits to work, the committing user on GitLab must have a corresponding user on Jira with the same email address or username. +### Smart Commit syntax + +Smart Commits should follow the pattern of: + +```plaintext +<ISSUE_KEY> <ignored text> #<command> <optional command parameters> +``` + +Some examples: + +- Adding a comment to a Jira issue: `KEY-123 fixes a bug #comment Bug is fixed.` +- Recording time tracking: `KEY-123 #time 2w 4d 10h 52m Tracking work time.` +- Closing an issue: `KEY-123 #close Closing issue` + +A Smart Commit message must not span more than one line (no carriage returns) but +you can still perform multiple actions in a single commit: + +- Time tracking, commenting, and transitioning to **Closed**: + `KEY-123 #time 2d 5h #comment Task completed ahead of schedule #close`. +- Commenting, transitioning to **In-progress**, and time tracking: + `KEY-123 #comment started working on the issue #in-progress #time 12d 5h`. + ## Configure a GitLab application for DVCS We recommend you create and use a `jira` user in GitLab, and use the account only @@ -72,7 +94,7 @@ for the groups you specify, into Jira. This import takes a few minutes and, afte it completes, refreshes every 60 minutes: 1. Ensure you have completed the [GitLab configuration](#configure-a-gitlab-application-for-dvcs). -1. Go to your DVCS account: +1. Go to your DVCS accounts: - *For Jira Server,* go to **Settings (gear) > Applications > DVCS accounts**. - *For Jira Cloud,* go to **Settings (gear) > Products > DVCS accounts**. 1. To create a new integration, select the appropriate value for **Host**: @@ -94,12 +116,15 @@ it completes, refreshes every 60 minutes: 1. For **Client ID**, use the **Application ID** value from the previous section. 1. For **Client Secret**, use the **Secret** value from the previous section. 1. Ensure that the rest of the checkboxes are checked. -1. Select **Add** to complete and create the integration. +1. Select **Add** and then **Continue** to create the DVCS account. +1. Jira redirects to GitLab where you have to confirm the authorization, + and then GitLab redirects back to Jira where you should see the synced + projects show up inside the new account. To connect additional GitLab projects from other GitLab top-level groups, or personal namespaces, repeat the previous steps with additional Jira DVCS accounts. -After you configure the integration, read more about [how to test and use it](development_panel.md#usage). +After you configure the integration, read more about [how to test and use it](development_panel.md). ## Refresh data imported to Jira @@ -135,7 +160,7 @@ Problems with SSL and TLS can cause this error message: Error obtaining access token. Cannot access https://gitlab.example.com from Jira. ``` -- The [GitLab Jira integration](../../user/project/integrations/jira.md) requires +- The [GitLab Jira integration](index.md) requires GitLab to connect to Jira. Any TLS issues that arise from a private certificate authority or self-signed certificate are resolved [on the GitLab server](https://docs.gitlab.com/omnibus/settings/ssl.html#other-certificate-authorities), @@ -198,9 +223,8 @@ encounter these issues: To resolve this issue: -- If you're using GitLab Free or GitLab Starter, be sure you're using - GitLab 13.4 or later. -- *If you're using GitLab versions 11.10-12.7,* upgrade to GitLab 12.8.10 or later +- If you're using GitLab Free, be sure you're using GitLab 13.4 or later. +- If you're using GitLab versions 11.10-12.7, upgrade to GitLab 12.8.10 or later to resolve [an identified issue](https://gitlab.com/gitlab-org/gitlab/-/issues/37012). [Contact GitLab Support](https://about.gitlab.com/support/) if none of these reasons apply. diff --git a/doc/integration/jira/img/jira_dev_panel_jira_setup_5.png b/doc/integration/jira/img/jira_dev_panel_jira_setup_5.png Binary files differindex 73dc867d301..b143fc24355 100644 --- a/doc/integration/jira/img/jira_dev_panel_jira_setup_5.png +++ b/doc/integration/jira/img/jira_dev_panel_jira_setup_5.png diff --git a/doc/integration/jira/img/jira_merge_request_close.png b/doc/integration/jira/img/jira_merge_request_close.png Binary files differdeleted file mode 100644 index 9a176daf5f4..00000000000 --- a/doc/integration/jira/img/jira_merge_request_close.png +++ /dev/null diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md index 221e50e5d66..2646a6c5e2e 100644 --- a/doc/integration/jira/index.md +++ b/doc/integration/jira/index.md @@ -62,6 +62,13 @@ The process for configuring Jira depends on whether you host Jira on your own se Atlassian cloud, an email and API token are required. For more information, read [set up a user in Jira on Atlassian cloud](jira_cloud_configuration.md). +## Privacy considerations + +If you integrate a private GitLab project with Jira using the [**Per-project Jira integration**](#per-project-jira-integration), +actions in GitLab issues and merge requests linked to a Jira issue leak information +about the private project to non-administrator Jira users. If your installation uses Jira Cloud, +you can use the [GitLab for Jira app](connect-app.md) to avoid this risk. + ## Troubleshooting If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured. diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md index d2cab59742b..91311f85310 100644 --- a/doc/integration/jira/issues.md +++ b/doc/integration/jira/issues.md @@ -6,168 +6,200 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Jira integration issue management **(FREE)** -By now you should have [configured Jira](development_panel.md#configuration) and enabled the -[Jira service in GitLab](development_panel.md#configure-gitlab). If everything is set up correctly -you should be able to reference and close Jira issues by just mentioning their -ID in GitLab commits and merge requests. +Integrating issue management with Jira requires you to [configure Jira](development_panel.md#configure-the-integration) +and [enable the Jira service](development_panel.md#configure-gitlab) in GitLab. +After you configure and enable the integration, you can reference and close Jira +issues by mentioning the Jira ID in GitLab commits and merge requests. -Jira issue IDs must be formatted in uppercase for the integration to work. +The Jira integration requires to you format any Jira issue IDs in uppercase. ## Reference Jira issues -When GitLab project has Jira issue tracker configured and enabled, mentioning -Jira issues in GitLab automatically adds a comment in Jira issue with the -link back to GitLab. This means that in comments in merge requests and commits -referencing an issue, `PROJECT-7` for example, adds a comment in Jira issue in the -format: +With this integration, you can cross-reference Jira issues while you work in +GitLab issues and merge requests. Mention a Jira issue in a GitLab issue, +merge request, or comment, and GitLab adds a formatted comment to the Jira issue. +The comment links back to your work in GitLab. -```plaintext -USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: -ENTITY_TITLE +For example, this commit references the Jira issue `GIT-1`: + +```shell +git commit -m "GIT-1 this is a test commit" ``` -- `USER` A user that mentioned the issue. This is the link to the user profile in GitLab. -- `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where Jira issue was mentioned. -- `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request. -- `PROJECT_NAME` GitLab project name. -- `ENTITY_TITLE` Merge request title or commit message first line. +GitLab adds a reference to the **Issue Links** section of Jira issue `GIT-1`: - + -For example, the following commit references the Jira issue with `PROJECT-1` as its ID: +GitLab also adds a comment to the issue, and uses this format: -```shell -git commit -m "PROJECT-1 Fix spelling and grammar" +```plaintext +USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|COMMENTLINK]: +ENTITY_TITLE ``` -## Close Jira issues +- `USER`: The name of the user who mentioned the issue, linked to their GitLab user profile. +- `COMMENTLINK`: A link to where the Jira issue was mentioned. +- `RESOURCE_NAME`: The type of resource, such as a commit or merge request, which referenced the issue. +- `PROJECT_NAME`: The GitLab project name. +- `ENTITY_TITLE`: The title of the merge request, or the first line of the commit. -Jira issues can be closed directly from GitLab by using trigger words in -commits and merge requests. When a commit which contains the trigger word -followed by the Jira issue ID in the commit message is pushed, GitLab -adds a comment in the mentioned Jira issue and immediately closes it (provided -the transition ID was set up correctly). +You can [disable comments](#disable-comments-on-jira-issues) on issues. -There are currently three trigger words, and you can use either one to achieve -the same goal: +### Require associated Jira issue for merge requests to be merged -- `Resolves PROJECT-1` -- `Closes PROJECT-1` -- `Fixes PROJECT-1` +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280766) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.12 behind a feature flag, disabled by default. +> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-the-ability-to-require-an-associated-jira-issue-on-merge-requests). **(ULTIMATE SELF)** -where `PROJECT-1` is the ID of the Jira issue. +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../../user/application_security/index.md#security-approvals-in-merge-requests). +Refer to this feature's version history for more details. -Note the following: +You can prevent merge requests from being merged if they do not refer to a Jira issue. +To enforce this: -- Only commits and merges into the project's default branch (usually `master`) - close an issue in Jira. You can change your project's default branch under - [project settings](img/jira_project_settings.png). -- The Jira issue is not transitioned if it has a resolution. +1. Navigate to your project's **Settings > General** page. +1. Expand the **Merge requests** section. +1. Under **Merge checks**, select the **Require an associated issue from Jira** check box. +1. Select **Save** for the changes to take effect. -Let's consider the following example: +After you enable this feature, a merge request that doesn't reference an associated +Jira issue can't be merged. The merge request displays the message +**To merge, a Jira issue key must be mentioned in the title or description.** -1. For the project named `PROJECT` in Jira, we implemented a new feature - and created a merge request in GitLab. -1. This feature was requested in Jira issue `PROJECT-7` and the merge request - in GitLab contains the improvement -1. In the merge request description we use the issue closing trigger - `Closes PROJECT-7`. -1. Once the merge request is merged, the Jira issue is automatically closed - with a comment and an associated link to the commit that resolved the issue. +## Close Jira issues in GitLab -In the following screenshot you can see what the link references to the Jira -issue look like. +If you have configured GitLab transition IDs, you can close a Jira issue directly +from GitLab. Use a trigger word followed by a Jira issue ID in a commit or merge request. +When you push a commit containing a trigger word and Jira issue ID, GitLab: - +1. Comments in the mentioned Jira issue. +1. Closes the Jira issue. If the Jira issue has a resolution, it isn't transitioned. -Once this merge request is merged, the Jira issue is automatically closed -with a link to the commit that resolved the issue. +For example, use any of these trigger words to close the Jira issue `PROJECT-1`: - +- `Resolves PROJECT-1` +- `Closes PROJECT-1` +- `Fixes PROJECT-1` -## View Jira issues **(PREMIUM)** +The commit or merge request must target your project's [default branch](../../user/project/repository/branches/default.md). +You can change your project's default branch under [project settings](img/jira_project_settings.png). -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +### Use case for closing issues -You can browse, search, and view issues from a selected Jira project directly in GitLab, -if your GitLab administrator [has configured it](development_panel.md#configure-gitlab): +Consider this example: -1. In the left navigation bar, go to **Jira > Issues list**. -1. The issue list sorts by **Created date** by default, with the newest issues listed at the top: +1. A user creates Jira issue `PROJECT-7` to request a new feature. +1. You create a merge request in GitLab to build the requested feature. +1. In the merge request, you add the issue closing trigger `Closes PROJECT-7`. +1. When the merge request is merged: + - GitLab closes the Jira issue for you: +  + - GitLab adds a formatted comment to Jira, linking back to the commit that + resolved the issue. You can [disable comments](#disable-comments-on-jira-issues). -  +## View Jira issues **(PREMIUM)** -1. To display the most recently updated issues first, click **Last updated**. -1. In GitLab versions 13.10 and later, you can view [individual Jira issues](#view-a-jira-issue). +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. -Issues are grouped into tabs based on their [Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html): +You can browse, search, and view issues from a selected Jira project directly in GitLab, +if your GitLab administrator [has configured it](development_panel.md#configure-gitlab). -- The **Open** tab displays all issues with a Jira status in any category other than Done. -- The **Closed** tab displays all issues with a Jira status categorized as Done. -- The **All** tab displays all issues of any status. +To do this, in GitLab, go to your project and select **Jira > Issues list**. The issue list +sorts by **Created date** by default, with the newest issues listed at the top: -## View a Jira issue + -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10 behind a feature flag, disabled by default. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.11. +- To display the most recently updated issues first, select **Last updated**. +- You can [search and filter](#search-and-filter-the-issues-list) the issues list. +- In GitLab [versions 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/299832), + you can select an issue from the list to view it in GitLab: +  -When viewing the [Jira issues list](#view-jira-issues), select an issue from the -list to open it in GitLab: +Issues are grouped into tabs based on their +[Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html): - +- **Open** tab: All issues with a Jira status in any category other than Done. +- **Closed** tab: All issues with a Jira status categorized as Done. +- **All** tab: All issues of any status. ## Search and filter the issues list To refine the list of issues, use the search bar to search for any text -contained in an issue summary (title) or description. - -You can also filter by labels, status, reporter, and assignee using URL parameters. -Enhancements to be able to use these through the user interface are [planned](https://gitlab.com/groups/gitlab-org/-/epics/3622). +contained in an issue summary (title) or description. Use any combination +of these filters: - To filter issues by `labels`, specify one or more labels as part of the `labels[]` -parameter in the URL. When using multiple labels, only issues that contain all specified -labels are listed. `/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA` - -- To filter issues by `status`, specify the `status` parameter in the URL. -`/-/integrations/jira/issues?status=In Progress` - + parameter in the URL. When using multiple labels, only issues that contain all specified + labels are listed: `/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA` +- To filter issues by `status`, specify the `status` parameter in the URL: + `/-/integrations/jira/issues?status=In Progress` - To filter issues by `reporter`, specify a reporter's Jira display name for the -`author_username` parameter in the URL. `/-/integrations/jira/issues?author_username=John Smith` - + `author_username` parameter in the URL: `/-/integrations/jira/issues?author_username=John Smith` - To filter issues by `assignee`, specify their Jira display name for the -`assignee_username` parameter in the URL. `/-/integrations/jira/issues?assignee_username=John Smith` + `assignee_username` parameter in the URL: `/-/integrations/jira/issues?assignee_username=John Smith` + +Enhancements to use these filters through the user interface +[are planned](https://gitlab.com/groups/gitlab-org/-/epics/3622). ## Automatic issue transitions > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/...) in GitLab 13.10. -In this mode the referenced Jira issue is transitioned to the next available status with a category of "Done". +When you configure automatic issue transitions, you can transition a referenced +Jira issue to the next available status with a category of **Done**. To configure +this setting: -See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting and select the **Move to Done** option. +1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions. +1. Select the **Enable Jira transitions** check box. +1. Select the **Move to Done** option. ## Custom issue transitions -For advanced workflows you can specify custom Jira transition IDs. +For advanced workflows, you can specify custom Jira transition IDs: -See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting, select the **Custom transitions** option, and enter your transition IDs in the text field. +1. Use the method based on your Jira subscription status: + - *(For users of Jira Cloud)* Obtain your transition IDs by editing a workflow + in the **Text** view. The transition IDs display in the **Transitions** column. + - *(For users of Jira Server)* Obtain your transition IDs in one of these ways: + - By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions`, + using an issue that is in the appropriate "open" state. + - By mousing over the link for the transition you want and looking for the + **action** parameter in the URL. + The transition ID may vary between workflows (for example, a bug instead of a + story), even if the status you're changing to is the same. +1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions. +1. Select the **Enable Jira transitions** setting. +1. Select the **Custom transitions** option. +1. Enter your transition IDs in the text field. If you insert multiple transition IDs + (separated by `,` or `;`), the issue is moved to each state, one after another, in the + order you specify. If a transition fails, the sequence is aborted. -If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. If a transition fails the sequence is aborted. +## Disable comments on Jira issues -To see the transition IDs on Jira Cloud, edit a workflow in the **Text** view. -The transition IDs display in the **Transitions** column. +GitLab can cross-link source commits or merge requests with Jira issues without +adding a comment to the Jira issue: -On Jira Server you can get the transition IDs in either of the following ways: +1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions. +1. Clear the **Enable comments** check box. -1. By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions` - using an issue that is in the appropriate "open" state -1. By mousing over the link for the transition you want and looking for the - "action" parameter in the URL +## Enable or disable the ability to require an associated Jira issue on merge requests -Note that the transition ID may vary between workflows (for example, bug vs. story), -even if the status you are changing to is the same. +The ability to require an associated Jira issue on merge requests is under development +and not ready for production use. It is deployed behind a feature flag that is +**disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can enable it. -## Disabling comments on Jira issues +To enable it: -You can continue to have GitLab cross-link a source commit/MR with a Jira issue while disabling the comment added to the issue. +```ruby +Feature.enable(:jira_issue_association_on_merge_request) +``` + +To disable it: -See the [Configure GitLab](development_panel.md#configure-gitlab) section and uncheck the **Enable comments** setting. +```ruby +Feature.disable(:jira_issue_association_on_merge_request) +``` diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md index fd58b3f33f7..7b3f2bcb249 100644 --- a/doc/integration/jira/jira_cloud_configuration.md +++ b/doc/integration/jira/jira_cloud_configuration.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Create an API token in Jira on Atlassian cloud **(FREE)** -You need an API token to [integrate with Jira](../../user/project/integrations/jira.md) +You need an API token to [integrate with Jira](index.md) on Atlassian cloud. To create the API token: 1. Sign in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index 3573a1f8b1e..21348416b73 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Jira Server credentials **(FREE)** -To [integrate Jira with GitLab](../../user/project/integrations/jira.md), you must +To [integrate Jira with GitLab](index.md), you must create a Jira user account for your Jira projects to access projects in GitLab. This Jira user account must have write access to your Jira projects. To create the credentials, you must: diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 5be076464d8..1984d275794 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -87,7 +87,7 @@ For source installations, make sure the `kerberos` gem group 1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -GitLab will now offer the `negotiate` authentication method for signing in and +GitLab now offers the `negotiate` authentication method for signing in and HTTP Git access, enabling Git clients that support this authentication protocol to authenticate with Kerberos tokens. @@ -159,7 +159,7 @@ knowledge can be a security risk. ## Link Kerberos and LDAP accounts together If your users sign in with Kerberos, but you also have [LDAP integration](../administration/auth/ldap/index.md) -enabled, your users will be linked to their LDAP accounts on their first sign-in. +enabled, your users are 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 @@ -170,7 +170,7 @@ The Kerberos realm must match the domain part of the LDAP user's Distinguished Name. For instance, if the Kerberos realm is `AD.EXAMPLE.COM`, then the LDAP user's Distinguished Name should end in `dc=ad,dc=example,dc=com`. -Taken together, these rules mean that linking will only work if your users' +Taken together, these rules mean that linking only works if your users' Kerberos usernames are of the form `foo@AD.EXAMPLE.COM` and their LDAP Distinguished Names look like `sAMAccountName=foo,dc=ad,dc=example,dc=com`. @@ -180,7 +180,7 @@ LDAP Distinguished Names look like `sAMAccountName=foo,dc=ad,dc=example,dc=com`. You can configure custom allowed realms when the user's Kerberos realm doesn't match the domain from the user's LDAP DN. The configuration value must specify -all domains that users may be expected to have. Any other domains will be +all domains that users may be expected to have. Any other domains are ignored and an LDAP identity won't be linked. **For Omnibus installations** @@ -236,8 +236,8 @@ authentication fails. For GitLab users to be able to use either `basic` or `negotiate` authentication with older Git versions, it is possible to offer Kerberos ticket-based -authentication on a different port (e.g. 8443) while the standard port will -keep offering only `basic` authentication. +authentication on a different port (e.g. 8443) while the standard port offers +only `basic` authentication. **For source installations with HTTPS** @@ -280,14 +280,14 @@ keep offering only `basic` authentication. 1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -After this change, all Git remote URLs will have to be updated to +After this change, Git remote URLs have to be updated to `https://gitlab.example.com:8443/mygroup/myproject.git` in order to use Kerberos ticket-based authentication. ## Upgrading from password-based to ticket-based Kerberos sign-ins Prior to GitLab 8.10 Enterprise Edition, users had to submit their -Kerberos username and password to GitLab when signing in. We will +Kerberos username and password to GitLab when signing in. We plan to remove support for password-based Kerberos sign-ins in a future release, so we recommend that you upgrade to ticket-based sign-ins. @@ -343,14 +343,14 @@ to a larger value in [the NGINX configuration](http://nginx.org/en/docs/http/ngx With Kerberos SPNEGO authentication, the browser is expected to send a list of mechanisms it supports to GitLab. If it doesn't support any of the mechanisms -GitLab supports, authentication will fail with a message like this in the log: +GitLab supports, authentication fails with a message like this in the log: ```plaintext OmniauthKerberosSpnegoController: failed to process Negotiate/Kerberos authentication: gss_accept_sec_context did not return GSS_S_COMPLETE: An unsupported mechanism was requested Unknown error ``` This is usually seen when the browser is unable to contact the Kerberos server -directly. It will fall back to an unsupported mechanism known as +directly. It falls back to an unsupported mechanism known as [`IAKERB`](https://k5wiki.kerberos.org/wiki/Projects/IAKERB), which tries to use the GitLab server as an intermediary to the Kerberos server. @@ -359,10 +359,10 @@ client machine and the Kerberos server - this is a prerequisite! Traffic may be blocked by a firewall, or the DNS records may be incorrect. Another failure mode occurs when the forward and reverse DNS records for the -GitLab server do not match. Often, Windows clients will work in this case, while -Linux clients will fail. They use reverse DNS while detecting the Kerberos -realm. If they get the wrong realm, then ordinary Kerberos mechanisms will fail, -so the client will fall back to attempting to negotiate `IAKERB`, leading to the +GitLab server do not match. Often, Windows clients work in this case while +Linux clients fail. They use reverse DNS while detecting the Kerberos +realm. If they get the wrong realm then ordinary Kerberos mechanisms fail, +so the client falls back to attempting to negotiate `IAKERB`, leading to the above error message. To fix this, ensure that the forward and reverse DNS for your GitLab server diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 842eb71f7f4..da1278b9edd 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -1,8 +1,8 @@ --- -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/#assignments +type: reference --- # SAML OmniAuth Provider **(FREE SELF)** @@ -86,7 +86,7 @@ in your SAML IdP: ``` 1. Ensure that the SAML [`NameID`](../user/group/saml_sso/index.md#nameid) and email address are fixed for each user, -as described in the section on [Security](#security). Otherwise, your users will be able to sign in as other authorized users. +as described in the section on [Security](#security). Otherwise, your users are able to sign in as other authorized users. 1. Add the provider configuration: @@ -137,7 +137,7 @@ as described in the section on [Security](#security). Otherwise, your users will for more details on these options. See the [notes on configuring your identity provider](#notes-on-configuring-your-identity-provider) for more information. -1. Change the value of `issuer` to a unique name, which will identify the application +1. Change the value of `issuer` to a unique name, which identifies the application to the IdP. 1. For the changes to take effect, you must [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab if you installed via Omnibus or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) if you installed from source. @@ -158,7 +158,7 @@ See [the assertions list](#assertions) for other available claims. On the sign in page there should now be a SAML button below the regular sign in form. Click the icon to begin the authentication process. If everything goes well the user -will be returned to GitLab and will be signed in. +is returned to GitLab and signed in. ### Notes on configuring your identity provider @@ -250,7 +250,7 @@ Your IdP passes Group Information to the SP (GitLab) in the SAML Response. You n - Which group membership is requisite to sign in via the `required_groups` setting When `required_groups` is not set or it is empty, anyone with proper authentication -will be able to use the service. +is able to use the service. Example: @@ -424,8 +424,8 @@ omniauth: auto_sign_in_with_provider: saml ``` -Keep in mind that every sign in attempt will be redirected to the SAML server; -you won't be able to sign in using local credentials. Ensure at least one of the +Keep in mind that every sign in attempt redirects to the SAML server; +you cannot sign in using local credentials. Ensure at least one of the SAML users has admin permissions. You may also bypass the auto sign-in feature by browsing to @@ -442,7 +442,7 @@ in the OmniAuth [`info` hash](https://github.com/omniauth/omniauth/wiki/Auth-Has For example, if your SAMLResponse contains an Attribute called `EmailAddress`, specify `{ email: ['EmailAddress'] }` to map the Attribute to the -corresponding key in the `info` hash. URI-named Attributes are also supported, e.g. +corresponding key in the `info` hash. URI-named Attributes are also supported, for example, `{ email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }`. This setting allows you tell GitLab where to look for certain attributes required @@ -463,7 +463,7 @@ args: { #### Setting a username -By default, the email in the SAML response will be used to automatically generate the user's GitLab username. If you'd like to set another attribute as the username, assign it to the `nickname` OmniAuth `info` hash attribute. For example, if you wanted to set the `username` attribute in your SAML Response to the username in GitLab, use the following setting: +By default, the email in the SAML response is used to automatically generate the user's GitLab username. If you'd like to set another attribute as the username, assign it to the `nickname` OmniAuth `info` hash attribute. For example, if you wanted to set the `username` attribute in your SAML Response to the username in GitLab, use the following setting: ```yaml args: { @@ -587,7 +587,7 @@ args: { } ``` -Your Identity Provider will encrypt the assertion with the public certificate of GitLab. GitLab will decrypt the EncryptedAssertion with its private key. +Your Identity Provider encrypts the assertion with the public certificate of GitLab. GitLab decrypts the EncryptedAssertion with its private key. NOTE: This integration uses the `certificate` and `private_key` settings for both assertion encryption and request signing. @@ -629,7 +629,7 @@ args: { } ``` -GitLab will sign the request with the provided private key. GitLab will include the configured public x500 certificate in the metadata for your Identity Provider to validate the signature of the received request with. For more information on this option, see the [Ruby SAML gem documentation](https://github.com/onelogin/ruby-saml/tree/v1.7.0). The Ruby SAML gem is used by the [OmniAuth SAML gem](https://github.com/omniauth/omniauth-saml) to implement the client side of the SAML authentication. +GitLab signs the request with the provided private key. GitLab includes the configured public x500 certificate in the metadata for your Identity Provider to validate the signature of the received request with. For more information on this option, see the [Ruby SAML gem documentation](https://github.com/onelogin/ruby-saml/tree/v1.7.0). The Ruby SAML gem is used by the [OmniAuth SAML gem](https://github.com/omniauth/omniauth-saml) to implement the client side of the SAML authentication. ## Security @@ -652,7 +652,7 @@ For information on the GitLab.com implementation, please see the [SAML SSO for G Group SAML SSO helps if you need to allow access via multiple SAML identity providers, but as a multi-tenant solution is less suited to cases where you administer your own GitLab instance. -To proceed with configuring Group SAML SSO instead, you'll need to enable the `group_saml` OmniAuth provider. This can be done from: +To proceed with configuring Group SAML SSO instead, enable the `group_saml` OmniAuth provider. This can be done from: - `gitlab.rb` for [Omnibus GitLab installations](#omnibus-installations). - `gitlab/config/gitlab.yml` for [source installations](#source-installations). @@ -715,17 +715,17 @@ The following guidance is based on this Okta article, on adding a [SAML Applicat 1. When the app screen comes up you see another button to **Create an App** and choose SAML 2.0 on the next screen. 1. Optionally, you can add a logo - (you can choose it from <https://about.gitlab.com/press/>). You'll have to + (you can choose it from <https://about.gitlab.com/press/>). You must crop and resize it. -1. Next, you'll need the to fill in the SAML general configuration with +1. Next, fill in the SAML general configuration with the assertion consumer service URL as "Single sign-on URL" and the issuer as "Audience URI" along with the [NameID](../user/group/saml_sso/index.md#nameid) and [assertions](#assertions). 1. The last part of the configuration is the feedback section where you can just say you're a customer and creating an app for internal use. -1. When you have your app you'll have a few tabs on the top of the app's +1. When you have your app you can see a few tabs on the top of the app's profile. Click on the SAML 2.0 configuration instructions button. 1. On the screen that comes up take note of the - **Identity Provider Single Sign-On URL** which you'll use for the + **Identity Provider Single Sign-On URL** which you can use for the `idp_sso_target_url` on your GitLab configuration file. 1. **Before you leave Okta, make sure you add your user and groups if any.** @@ -734,14 +734,14 @@ The following guidance is based on this Okta article, on adding a [SAML Applicat The following guidance is based on this Google Workspace article, on how to [Set up your own custom SAML application](https://support.google.com/a/answer/6087519?hl=en): Make sure you have access to a Google Workspace [Super Admin](https://support.google.com/a/answer/2405986#super_admin) account. - Follow the instructions in the linked Google Workspace article, where you'll need the following information: + Use the information below and follow the instructions in the linked Google Workspace article. | | Typical value | Description | |------------------|--------------------------------------------------|----------------------------------------------------------| | Name of SAML App | GitLab | Other names OK. | | ACS URL | `https://<GITLAB_DOMAIN>/users/auth/saml/callback` | ACS is short for Assertion Consumer Service. | | GITLAB_DOMAIN | `gitlab.example.com` | Set to the domain of your GitLab instance. | -| Entity ID | `https://gitlab.example.com` | A value unique to your SAML app, you'll set it to the `issuer` in your GitLab configuration. | +| Entity ID | `https://gitlab.example.com` | A value unique to your SAML app, set it to the `issuer` in your GitLab configuration. | | Name ID format | EMAIL | Required value. Also known as `name_identifier_format` | | Name ID | Primary email address | Make sure someone receives content sent to that address | | First name | `first_name` | Required value to communicate with GitLab. | @@ -806,7 +806,7 @@ section for further troubleshooting steps. ### Redirect back to the login screen with no evident error If after signing in into your SAML server you are redirected back to the sign in page and -no error is displayed, check your `production.log` file. It will most likely contain the +no error is displayed, check your `production.log` file. It most likely contains the message `Can't verify CSRF token authenticity`. This means that there is an error during the SAML request, but in GitLab 11.7 and earlier this error never reaches GitLab due to the CSRF check. @@ -814,7 +814,7 @@ the CSRF check. To bypass this you can add `skip_before_action :verify_authenticity_token` to the `omniauth_callbacks_controller.rb` file immediately after the `class` line and comment out the `protect_from_forgery` line using a `#`. Restart Unicorn for this -change to take effect. This will allow the error to hit GitLab, where it can then +change to take effect. This allows the error to hit GitLab, where it can then be seen in the usual logs, or as a flash message on the login screen. That file is located in `/opt/gitlab/embedded/service/gitlab-rails/app/controllers` @@ -838,11 +838,11 @@ audiences of the IdP server. The IdP server needs to pass certain information in order for GitLab to either create an account, or match the login information to an existing account. `email` is the minimum amount of information that needs to be passed. If the IdP server -is not providing this information, all SAML requests will fail. +is not providing this information, all SAML requests fail. Make sure this information is provided. -Another issue that can result in this error is when the correct information is being sent by the IdP, but the attributes don't match the names in the OmniAuth `info` hash. In this case, you'll need to set `attribute_statements` in the SAML configuration to [map the attribute names in your SAML Response to the corresponding OmniAuth `info` hash names](#attribute_statements). +Another issue that can result in this error is when the correct information is being sent by the IdP, but the attributes don't match the names in the OmniAuth `info` hash. In this case, you need to set `attribute_statements` in the SAML configuration to [map the attribute names in your SAML Response to the corresponding OmniAuth `info` hash names](#attribute_statements). ### Key validation error, Digest mismatch or Fingerprint mismatch @@ -859,8 +859,8 @@ For this you need take the following into account: the request to contain one. In this case the fingerprint or fingerprint validators are optional -Make sure that one of the above described scenarios is valid, or the requests will -fail with one of the mentioned errors. +If none of the above described scenarios is valid, the request +fails with one of the mentioned errors. ### User is blocked when signing in through SAML |
