diff options
Diffstat (limited to 'doc/integration')
39 files changed, 1171 insertions, 553 deletions
diff --git a/doc/integration/README.md b/doc/integration/README.md index 9c3d39327f8..c725cc08556 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -63,7 +63,7 @@ or [Kroki](../administration/integration/kroki.md) to use diagrams in AsciiDoc a ## Integrations -Integration with services such as Campfire, Flowdock, HipChat, Pivotal Tracker, and Slack are available as [Integrations](../user/project/integrations/overview.md). +Integration with services such as Campfire, Flowdock, Jira, Pivotal Tracker, and Slack are available as [Integrations](../user/project/integrations/overview.md). ## Troubleshooting diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 5c9149ef49b..a6c3afceeea 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -91,6 +91,14 @@ Since Elasticsearch can read and use indices created in the previous major versi 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. +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 +features such as Zero-downtime reindexing. + ## Elasticsearch repository indexer For indexing Git repository data, GitLab uses an [indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). @@ -231,8 +239,8 @@ The following Elasticsearch settings are available: | `AWS Secret Access Key` | The AWS secret access key. | | `Maximum file size indexed` | See [the explanation in instance limits.](../administration/instance_limits.md#maximum-file-size-indexed). | | `Maximum field length` | See [the explanation in instance limits.](../administration/instance_limits.md#maximum-field-length). | -| `Maximum bulk request size (MiB)` | The Maximum Bulk Request size is used by the GitLab Golang-based indexer processes and indicates how much data it ought to collect (and store in memory) in a given indexing process before submitting the payload to Elasticsearch’s Bulk API. This setting should be used with the Bulk request concurrency setting (see below) and needs to accommodate the resource constraints of both the Elasticsearch host(s) and the host(s) running the GitLab Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | -| `Bulk request concurrency` | The Bulk request concurrency indicates how many of the GitLab Golang-based indexer processes (or threads) can run in parallel to collect data to subsequently submit to Elasticsearch’s Bulk API. This increases indexing performance, but fills the Elasticsearch bulk requests queue faster. This setting should be used together with the Maximum bulk request size setting (see above) and needs to accommodate the resource constraints of both the Elasticsearch host(s) and the host(s) running the GitLab Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | +| `Maximum bulk request size (MiB)` | The Maximum Bulk Request size is used by the GitLab Golang-based indexer processes and indicates how much data it ought to collect (and store in memory) in a given indexing process before submitting the payload to Elasticsearch's Bulk API. This setting should be used with the Bulk request concurrency setting (see below) and needs to accommodate the resource constraints of both the Elasticsearch 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. | WARNING: @@ -671,7 +679,7 @@ Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). Whenever a change or deletion is made to an indexed GitLab object (a merge request description is changed, a file is deleted from the master branch in a repository, a project is deleted, etc), a document in the index is deleted. However, since these are "soft" deletes, the overall number of "deleted documents", and therefore wasted space, increases. Elasticsearch does intelligent merging of segments in order to remove these deleted documents. However, depending on the amount and type of activity in your GitLab installation, it's possible to see as much as 50% wasted space in the index. -In general, we recommend simply letting Elasticsearch merge and reclaim space automatically, with the default settings. From [Lucene's Handling of Deleted Documents](https://www.elastic.co/blog/lucenes-handling-of-deleted-documents "Lucene's Handling of Deleted Documents"), _"Overall, besides perhaps decreasing the maximum segment size, it is best to leave Lucene's defaults as-is and not fret too much about when deletes are reclaimed."_ +In general, we recommend letting Elasticsearch merge and reclaim space automatically, with the default settings. From [Lucene's Handling of Deleted Documents](https://www.elastic.co/blog/lucenes-handling-of-deleted-documents "Lucene's Handling of Deleted Documents"), _"Overall, besides perhaps decreasing the maximum segment size, it is best to leave Lucene's defaults as-is and not fret too much about when deletes are reclaimed."_ However, some larger installations may wish to tune the merge policy settings: @@ -711,8 +719,7 @@ data). The use of Elasticsearch in GitLab is only ever as a secondary data store. This means that all of the data stored in Elasticsearch can always be derived again from other data sources, specifically PostgreSQL and Gitaly. Therefore, if -the Elasticsearch data store is ever corrupted for whatever reason, you can -simply reindex everything from scratch. +the Elasticsearch data store is ever corrupted for whatever reason, you can reindex everything from scratch. ## Troubleshooting @@ -908,7 +915,7 @@ In GitLab 13.9, a change was made where [binary file names are being indexed](ht ### Last resort to recreate an index There may be cases where somehow data never got indexed and it's not in the -queue, or the index is somehow in a state where migrations just simply cannot +queue, or the index is somehow in a state where migrations just cannot proceed. It is always best to try to troubleshoot the root cause of the problem using the above [troubleshooting](#troubleshooting) steps. @@ -936,3 +943,10 @@ sudo gitlab-rake gitlab:elastic:index cd /home/git/gitlab sudo -u git -H bundle exec rake gitlab:elastic:index ``` + +### How does Advanced Search handle private projects? + +Advanced Search will store all the projects in the same Elasticsearch indexes, +however searches will only surface results that can be viewed by the user. +Advanced Search will honor all permission checks in the application by +filtering out projects that a user does not have access to at search time. diff --git a/doc/integration/google_workspace_saml.md b/doc/integration/google_workspace_saml.md index 7b561750b0f..46a39a2e64b 100644 --- a/doc/integration/google_workspace_saml.md +++ b/doc/integration/google_workspace_saml.md @@ -1,163 +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 +redirect_to: 'saml.md' --- -# Google Workspace SSO provider +This document was moved to [another location](saml.md). -Google Workspace (formerly G Suite) is a [Single Sign-on provider](https://support.google.com/a/answer/60224?hl=en) that can be used to authenticate -with GitLab. - -The following documentation enables Google Workspace as a SAML provider for GitLab. - -## Configure the Google Workspace SAML app - -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: - -| | 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. | -| 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. | -| Last name | `last_name` | Required value to communicate with GitLab. | - -You will also need to setup the following SAML attribute mappings: - -| Google Directory attributes | App attributes | -|-----------------------------------|----------------| -| Basic information > Email | `email` | -| Basic Information > First name | `first_name` | -| Basic Information > Last name | `last_name` | - -You may also use some of this information when you [Configure GitLab](#configure-gitlab). - -When configuring the Google Workspace SAML app, be sure to record the following information: - -| | Value | Description | -|-------------|--------------|-----------------------------------------------------------------------------------| -| SSO URL | Depends | Google Identity Provider details. Set to the GitLab `idp_sso_target_url` setting. | -| Certificate | Downloadable | Run `openssl x509 -in <your_certificate.crt> -noout -fingerprint` to generate the SHA1 fingerprint that can be used in the `idp_cert_fingerprint` setting. | - -While the Google Workspace Admin provides IDP metadata, Entity ID and SHA-256 fingerprint, -GitLab does not need that information to connect to the Google Workspace SAML app. - ---- - -Now that the Google Workspace SAML app is configured, it's time to enable it in GitLab. - -## Configure GitLab - -1. See [Initial OmniAuth Configuration](../integration/omniauth.md#initial-omniauth-configuration) - for initial settings. - -1. To allow people to register for GitLab, through their Google accounts, add the following - values to your configuration: - - **For Omnibus GitLab installations** - - Edit `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_rails['omniauth_allow_single_sign_on'] = ['saml'] - gitlab_rails['omniauth_block_auto_created_users'] = false - ``` - - --- - - **For installations from source** - - Edit `config/gitlab.yml`: - - ```yaml - allow_single_sign_on: ["saml"] - block_auto_created_users: false - ``` - -1. If an existing GitLab user has the same email address as a Google Workspace user, the registration - process automatically links their accounts, if you add the following setting: - their email addresses match by adding the following setting: - - **For Omnibus GitLab installations** - - Edit `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_rails['omniauth_auto_link_saml_user'] = true - ``` - - --- - - **For installations from source** - - Edit `config/gitlab.yml`: - - ```yaml - auto_link_saml_user: true - ``` - -1. Add the provider configuration. - -For guidance on how to set up these values, see the [SAML General Setup steps](saml.md#general-setup). -Pay particular attention to the values for: - -- `assertion_consumer_service_url` -- `idp_cert_fingerprint` -- `idp_sso_target_url` -- `issuer` -- `name_identifier_format` - - **For Omnibus GitLab installations** - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - name: 'saml', - args: { - assertion_consumer_service_url: 'https://<GITLAB_DOMAIN>/users/auth/saml/callback', - idp_cert_fingerprint: '00:00:00:00:00:00:0:00:00:00:00:00:00:00:00:00', - idp_sso_target_url: 'https://accounts.google.com/o/saml2/idp?idpid=00000000', - issuer: 'https://<GITLAB_DOMAIN>', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress' - }, - label: 'Google Workspace' # optional label for SAML log in button, defaults to "Saml" - } - ] - ``` - - **For installations from source** - - ```yaml - - { - name: 'saml', - args: { - assertion_consumer_service_url: 'https://<GITLAB_DOMAIN>/users/auth/saml/callback', - idp_cert_fingerprint: '00:00:00:00:00:00:0:00:00:00:00:00:00:00:00:00', - idp_sso_target_url: 'https://accounts.google.com/o/saml2/idp?idpid=00000000', - issuer: 'https://<GITLAB_DOMAIN>', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress' - }, - label: 'Google Workspace' # optional label for SAML log in button, defaults to "Saml" - } - ``` - -1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for Omnibus and installations - from source respectively for the changes to take effect. - -To avoid caching issues, test the result on an incognito or private browser window. - -## Troubleshooting - -The Google Workspace documentation on [SAML app error messages](https://support.google.com/a/answer/6301076?hl=en) is helpful for debugging if you are seeing an error from Google while signing in. -Pay particular attention to the following 403 errors: - -- `app_not_configured` -- `app_not_configured_for_user` +<!-- This redirect file can be deleted after 2021-06-15>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/img/enabled-oauth-sign-in-sources.png b/doc/integration/img/enabled-oauth-sign-in-sources.png Binary files differdeleted file mode 100644 index e83f9d5cfdf..00000000000 --- a/doc/integration/img/enabled-oauth-sign-in-sources.png +++ /dev/null diff --git a/doc/integration/img/enabled-oauth-sign-in-sources_v13_10.png b/doc/integration/img/enabled-oauth-sign-in-sources_v13_10.png Binary files differnew file mode 100644 index 00000000000..86f6402c168 --- /dev/null +++ b/doc/integration/img/enabled-oauth-sign-in-sources_v13_10.png diff --git a/doc/integration/img/jira_dev_panel_gl_setup_1.png b/doc/integration/img/jira_dev_panel_gl_setup_1.png Binary files differdeleted file mode 100644 index 75279877c93..00000000000 --- a/doc/integration/img/jira_dev_panel_gl_setup_1.png +++ /dev/null diff --git a/doc/integration/img/jira_dev_panel_jira_setup_2.png b/doc/integration/img/jira_dev_panel_jira_setup_2.png Binary files differdeleted file mode 100644 index a4778a00dd5..00000000000 --- a/doc/integration/img/jira_dev_panel_jira_setup_2.png +++ /dev/null diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 1250ddee584..60c9faf938d 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -87,7 +87,7 @@ authorize the connection to GitLab. 1. On the Jenkins server, go to **Manage Jenkins > Manage Plugins**. 1. Install the [Jenkins GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin). 1. Go to **Manage Jenkins > Configure System**. -1. In the **GitLab** section, check the **Enable authentication for ‘/project’ end-point** checkbox. +1. In the **GitLab** section, check the **Enable authentication for '/project' end-point** checkbox. 1. Click **Add**, then choose **Jenkins Credential Provider**. 1. Choose **GitLab API token** as the token type. 1. Enter the GitLab personal access token's value in the **API Token** field and click **Add**. diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md new file mode 100644 index 00000000000..b096d5bff61 --- /dev/null +++ b/doc/integration/jira/connect-app.md @@ -0,0 +1,130 @@ +--- +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 for Jira 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. + +This integration method supports [smart commits](dvcs.md#smart-commits). + +This method is recommended when using GitLab.com and Jira Cloud because data is +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. + +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 + [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 +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 + are synced to Jira. +- From GitLab 13.8, past merge request data is synced to Jira. + +Support for syncing past branch and commit data [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/263240). + +## Install the GitLab 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. + +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/) +from the location you provide. The manifest file describes the application to the system. To support +self-managed GitLab instances with Jira Cloud, you can either: + +- [Install the application manually](#install-the-application-manually). +- [Create a Marketplace listing](#create-a-marketplace-listing). + +### Install the application manually **(FREE SELF)** + +You can configure your Atlassian Cloud instance to allow you to install applications +from outside the Marketplace, which allows you to install the application: + +1. Sign in to your Jira instance as a user with administrator permissions. +1. Place your Jira instance into + [development mode](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-2--enable-development-mode). +1. Sign in to your GitLab application as a user with [Administrator](../../user/permissions.md) permissions. +1. Install the GitLab application from your self-managed GitLab instance, as + described in the [Atlassian developer guides](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-3--install-and-test-your-app): + 1. In your Jira instance, go to **Apps > Manage Apps** and click **Upload app**: + +  + + 1. For **App descriptor URL**, provide full URL to your manifest file, modifying this + URL based on your instance configuration: `https://your.domain/your-path/-/jira_connect/app_descriptor.json` + 1. Click **Upload**, and Jira fetches the content of your `app_descriptor` file and installs + it for you. + 1. If the upload is successful, Jira displays a modal panel: **Installed and ready to go!** + Click **Get started** to configure the integration. + +  + +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 +click **Get started** to open the configuration page rendered from your GitLab instance. + +NOTE: +If you make changes to the application descriptor, you must uninstall, then reinstall, the +application. + +### Create a Marketplace listing **(FREE SELF)** + +If you prefer to not use development mode on your Jira instance, you can create +your own Marketplace listing for your instance, which enables your application +to be installed from the Atlassian Marketplace. + +For full instructions, review the Atlassian [guide to creating a marketplace listing](https://developer.atlassian.com/platform/marketplace/installing-cloud-apps/#creating-the-marketplace-listing). To create a +Marketplace listing, you must: + +1. Register as a Marketplace vendor. +1. List your application, using the application descriptor URL. + - Your manifest file is located at: `https://your.domain/your-path/-/jira_connect/app_descriptor.json` + - GitLab recommends you list your application as `private`, because public + applications can be viewed and installed by any user. +1. Generate test license tokens for your application. + +Review the +[official Atlassian documentation](https://developer.atlassian.com/platform/marketplace/installing-cloud-apps/#creating-the-marketplace-listing) +for details. + +NOTE: +DVCS means distributed version control system. + +## Troubleshooting GitLab for Jira + +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. + +> "You need to sign in or sign up before continuing." + +In this case, use [Firefox](https://www.mozilla.org/en-US/firefox/) or enable cross-site cookies in your browser. diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md new file mode 100644 index 00000000000..1617e950104 --- /dev/null +++ b/doc/integration/jira/development_panel.md @@ -0,0 +1,155 @@ +--- +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 Jira Development panel integration **(FREE)** + +> - [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. + +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 + +| 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). + +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. + +This differs from the [Jira integration](../../user/project/integrations/jira.md), where the mapping is between one GitLab project and the entire Jira instance. + +Additional features provided by the Jira Development Panel integration include: + +- 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. + +## Configuration + +<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). + +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. + +| 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. | +| 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: + +- The [view Jira issues](issues.md#view-jira-issues) feature, you must associate a GitLab project with a + specific Jira project. +- Other features, you do not have to explicitly associate a GitLab project with any single Jira + project. + +If you have a single Jira instance, you can pre-fill the settings. For more information, read the +documentation for [central administration of project integrations](../../user/admin_area/settings/project_integration_management.md). + +To enable the Jira service in GitLab, you must: + +1. Configure the project in Jira. +1. Enter the correct values in 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. + +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 + **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 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. + + 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. + +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. + + + +Click the links to see your GitLab repository data. + + + + + +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). + +## Limitations + +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`. diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md new file mode 100644 index 00000000000..5d315ebd802 --- /dev/null +++ b/doc/integration/jira/dvcs.md @@ -0,0 +1,221 @@ +--- +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 +--- + +# Jira DVCS connector + +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 +between them. If you use Jira Cloud and GitLab.com, you should use the +[GitLab for Jira app](connect-app.md) unless you specifically need the DVCS connector. + +When you configure the Jira DVCS connector, make sure your GitLab and Jira instances +are accessible. + +- **Self-managed GitLab**: Your GitLab instance must be accessible by Jira. +- **Jira Cloud**: Your instance must be accessible through the internet. +- **Jira Server**: Your network must allow access to your instance. + +## Smart commits + +When connecting GitLab with Jira with DVCS, you can process your Jira issues using +special commands, called +[Smart Commits](https://support.atlassian.com/jira-software-cloud/docs/process-issues-with-smart-commits/), +in your commit messages. With Smart Commits, you can: + +- Comment on issues. +- Record time-tracking information against issues. +- Transition issues to any status defined in the Jira project's workflow. + +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 +for your use. + +For smart commits to work, the committing user on GitLab must have a corresponding +user on Jira with the same email address or username. + +## Configure a GitLab application for DVCS + +We recommend you create and use a `jira` user in GitLab, and use the account only +for integration work. A separate account ensures regular account maintenance does not affect +your integration. + +1. In GitLab, [create a user](../../user/profile/account/create_accounts.md) for Jira to + use to connect to GitLab. For Jira to access all projects, + a user with [Administrator](../../user/permissions.md) permissions must + create the user. +1. In the top right corner, click the account's avatar, and select **Edit profile**. +1. In the left sidebar, select **Applications**. +1. In the **Name** field, enter a descriptive name for the integration, such as `Jira`. +1. In the **Redirect URI** field, enter the URI appropriate for your version of GitLab, + replacing `<gitlab.example.com>` with your GitLab instance domain: + - *For GitLab versions 11.3 and later,* use `https://<gitlab.example.com>/login/oauth/callback`. + If you use GitLab.com, the URL is `https://gitlab.com/login/oauth/callback`. + - *For GitLab versions 11.2 and earlier,* use + `https://<gitlab.example.com>/-/jira/login/oauth/callback`. + +1. For **Scopes**, select `api` and clear any other checkboxes. +1. Select **Submit**. +1. GitLab displays the generated **Application ID** + and **Secret** values. Copy these values, as you need them to configure Jira. + +## Configure Jira for DVCS + +If you use Jira Cloud and GitLab.com, use the [GitLab for Jira app](connect-app.md) +unless you specifically need the DVCS Connector. + +Configure this connection when you want to import all GitLab commits and branches, +for the groups you specify, into Jira. This import takes a few minutes and, after +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: + - *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**: + - *For Jira versions 8.14 and later:* Select **GitLab** or + <!-- vale gitlab.Substitutions = NO --> + **GitLab Self-Hosted**. + <!-- vale gitlab.Substitutions = YES --> + - *For Jira versions 8.13 and earlier:* Select **GitHub Enterprise**. +1. For **Team or User Account**, enter either: + - The relative path of a top-level GitLab group that you have access to. + - The relative path of your personal namespace. + +1. In the **Host URL** field, enter the URI appropriate for your version of GitLab, + replacing `<gitlab.example.com>` with your GitLab instance domain: + - *For GitLab versions 11.3 and later,* use `https://<gitlab.example.com>`. + - *For GitLab versions 11.2 and earlier,* use + `https://<gitlab.example.com>/-/jira`. + +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. + +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). + +## Refresh data imported to Jira + +Jira imports the commits and branches every 60 minutes for your projects. You +can refresh the data manually from the Jira interface: + +1. Sign in to your Jira instance as the user you configured the integration with. +1. Go to **Settings (gear) > Applications**. +1. Select **DVCS accounts**. +1. In the table, for the repository you want to refresh, in the **Last Activity** + column, select the icon: +  + +## Troubleshooting your DVCS connection + +Refer to the items in this section if you're having problems with your DVCS connector. + +### Jira cannot access GitLab server + +If you complete the **Add New Account** form, authorize access, and you receive +this error, Jira and GitLab cannot connect. No other error messages +appear in any logs: + +```plaintext +Error obtaining access token. Cannot access https://gitlab.example.com from Jira. +``` + +### SSL and TLS problems + +Problems with SSL and TLS can cause this error message: + +```plaintext +Error obtaining access token. Cannot access https://gitlab.example.com from Jira. +``` + +- 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 certificate are resolved + [on the GitLab server](https://docs.gitlab.com/omnibus/settings/ssl.html#other-certificate-authorities), + as GitLab is the TLS client. +- The Jira Development panel integration requires Jira to connect to GitLab, which + causes Jira to be the TLS client. If your GitLab server's certificate is not + issued by a public certificate authority, the Java Truststore on Jira's server + must have the appropriate certificate (such as your organization's + root certificate) added to it . + +Refer to Atlassian's documentation and Atlassian Support for assistance setting up Jira correctly: + +- [Add a certificate](https://confluence.atlassian.com/kb/how-to-import-a-public-ssl-certificate-into-a-jvm-867025849.html) + to the trust store. + - The simplest approach is [`keytool`](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html). + - Add additional roots to Java's default Truststore (`cacerts`) to allow Jira to + also trust public certificate authorities. + - If the integration stops working after upgrading Jira's Java runtime, the + `cacerts` Truststore may have been replaced during the upgrade. + +- Troubleshooting connectivity [up to and including TLS handshaking](https://confluence.atlassian.com/kb/unable-to-connect-to-ssl-services-due-to-pkix-path-building-failed-error-779355358.html), + using the a java class called `SSLPoke`. +- Download the class from Atlassian's knowledge base to a directory on Jira's server, such as `/tmp`. +- Use the same Java runtime as Jira. +- Pass all networking-related parameters that Jira is called with, such as proxy + settings or an alternative root Truststore (`-Djavax.net.ssl.trustStore`): + +```shell +${JAVA_HOME}/bin/java -Djavax.net.ssl.trustStore=/var/atlassian/application-data/jira/cacerts -classpath /tmp SSLPoke gitlab.example.com 443 +``` + +The message `Successfully connected` indicates a successful TLS handshake. + +If there are problems, the Java TLS library generates errors that you can +look up for more detail. + +### Scope error when connecting Jira via DVCS + +```plaintext +The requested scope is invalid, unknown, or malformed. +``` + +Potential resolutions: + +1. Verify that the URL shown in the browser after being redirected from Jira in the + [Jira DVCS connector setup](#configure-jira-for-dvcs) includes `scope=api` in + the query string. +1. If `scope=api` is missing from the URL, edit the + [GitLab account configuration](#configure-a-gitlab-application-for-dvcs). Review + the **Scopes** field and ensure the `api` check box is selected. + +### Jira error adding account and no repositories listed + +After you complete the **Add New Account** form in Jira and authorize access, you might +encounter these issues: + +- An `Error! Failed adding the account: [Error retrieving list of repositories]` error. +- An `Account is already integrated with JIRA` error when you click **Try Again**. +- An account is visible in the DVCS accounts view, but no repositories are listed. + +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 + 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. + +### Fix synchronization issues + +If Jira displays incorrect information, such as deleted branches, you may need to +resynchronize the information. To do so: + +1. In Jira, go to **Jira Administration > Applications > DVCS accounts**. +1. At the account (group or subgroup) level, Jira displays an option to + **Refresh repositories** in the **{ellipsis_h}** (ellipsis) menu. +1. For each project, there's a sync button displayed next to the **last activity** date. + - To perform a *soft resync*, click the button. + - To complete a *full sync*, shift-click the button. + +For more information, read +[Atlassian's documentation](https://support.atlassian.com/jira-cloud-administration/docs/synchronize-jira-cloud-to-bitbucket/). diff --git a/doc/integration/jira/img/jira-upload-app-success_v13_11.png b/doc/integration/jira/img/jira-upload-app-success_v13_11.png Binary files differnew file mode 100644 index 00000000000..c0d4c9744b6 --- /dev/null +++ b/doc/integration/jira/img/jira-upload-app-success_v13_11.png diff --git a/doc/integration/jira/img/jira-upload-app_v13_11.png b/doc/integration/jira/img/jira-upload-app_v13_11.png Binary files differnew file mode 100644 index 00000000000..88d1573f778 --- /dev/null +++ b/doc/integration/jira/img/jira-upload-app_v13_11.png diff --git a/doc/integration/jira/img/jira_added_user_to_group.png b/doc/integration/jira/img/jira_added_user_to_group.png Binary files differnew file mode 100644 index 00000000000..f5120a8d42e --- /dev/null +++ b/doc/integration/jira/img/jira_added_user_to_group.png diff --git a/doc/integration/jira/img/jira_create_new_group.png b/doc/integration/jira/img/jira_create_new_group.png Binary files differnew file mode 100644 index 00000000000..4ab7a5eae4e --- /dev/null +++ b/doc/integration/jira/img/jira_create_new_group.png diff --git a/doc/integration/img/jira_dev_panel_jira_setup_3.png b/doc/integration/jira/img/jira_dev_panel_jira_setup_3.png Binary files differindex 4049a65f56b..4049a65f56b 100644 --- a/doc/integration/img/jira_dev_panel_jira_setup_3.png +++ b/doc/integration/jira/img/jira_dev_panel_jira_setup_3.png diff --git a/doc/integration/img/jira_dev_panel_jira_setup_4.png b/doc/integration/jira/img/jira_dev_panel_jira_setup_4.png Binary files differindex 81d84cb173d..81d84cb173d 100644 --- a/doc/integration/img/jira_dev_panel_jira_setup_4.png +++ b/doc/integration/jira/img/jira_dev_panel_jira_setup_4.png diff --git a/doc/integration/img/jira_dev_panel_jira_setup_5.png b/doc/integration/jira/img/jira_dev_panel_jira_setup_5.png Binary files differindex 73dc867d301..73dc867d301 100644 --- a/doc/integration/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/img/jira_dev_panel_manual_refresh.png b/doc/integration/jira/img/jira_dev_panel_manual_refresh.png Binary files differindex dc92d533bde..dc92d533bde 100644 --- a/doc/integration/img/jira_dev_panel_manual_refresh.png +++ b/doc/integration/jira/img/jira_dev_panel_manual_refresh.png diff --git a/doc/integration/img/jira_dev_panel_setup_com_1.png b/doc/integration/jira/img/jira_dev_panel_setup_com_1.png Binary files differindex 18f0d5da043..18f0d5da043 100644 --- a/doc/integration/img/jira_dev_panel_setup_com_1.png +++ b/doc/integration/jira/img/jira_dev_panel_setup_com_1.png diff --git a/doc/integration/img/jira_dev_panel_setup_com_2.png b/doc/integration/jira/img/jira_dev_panel_setup_com_2.png Binary files differindex 31dc13e1271..31dc13e1271 100644 --- a/doc/integration/img/jira_dev_panel_setup_com_2.png +++ b/doc/integration/jira/img/jira_dev_panel_setup_com_2.png diff --git a/doc/integration/img/jira_dev_panel_setup_com_3_v13_9.png b/doc/integration/jira/img/jira_dev_panel_setup_com_3_v13_9.png Binary files differindex fe791637d31..fe791637d31 100644 --- a/doc/integration/img/jira_dev_panel_setup_com_3_v13_9.png +++ b/doc/integration/jira/img/jira_dev_panel_setup_com_3_v13_9.png diff --git a/doc/integration/img/jira_dev_panel_setup_com_4_v13_9.png b/doc/integration/jira/img/jira_dev_panel_setup_com_4_v13_9.png Binary files differindex 08787f12b67..08787f12b67 100644 --- a/doc/integration/img/jira_dev_panel_setup_com_4_v13_9.png +++ b/doc/integration/jira/img/jira_dev_panel_setup_com_4_v13_9.png diff --git a/doc/integration/jira/img/jira_group_access.png b/doc/integration/jira/img/jira_group_access.png Binary files differnew file mode 100644 index 00000000000..42a9b4ae564 --- /dev/null +++ b/doc/integration/jira/img/jira_group_access.png diff --git a/doc/integration/jira/img/jira_issue_detail_view_v13.10.png b/doc/integration/jira/img/jira_issue_detail_view_v13.10.png Binary files differnew file mode 100644 index 00000000000..bf1607a35fe --- /dev/null +++ b/doc/integration/jira/img/jira_issue_detail_view_v13.10.png diff --git a/doc/integration/jira/img/jira_issue_reference.png b/doc/integration/jira/img/jira_issue_reference.png Binary files differnew file mode 100644 index 00000000000..db8bc4f0bb9 --- /dev/null +++ b/doc/integration/jira/img/jira_issue_reference.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 differnew file mode 100644 index 00000000000..9a176daf5f4 --- /dev/null +++ b/doc/integration/jira/img/jira_merge_request_close.png diff --git a/doc/integration/jira/img/jira_project_settings.png b/doc/integration/jira/img/jira_project_settings.png Binary files differnew file mode 100644 index 00000000000..d96002b7db8 --- /dev/null +++ b/doc/integration/jira/img/jira_project_settings.png diff --git a/doc/integration/jira/img/jira_service_close_issue.png b/doc/integration/jira/img/jira_service_close_issue.png Binary files differnew file mode 100644 index 00000000000..73d6498192c --- /dev/null +++ b/doc/integration/jira/img/jira_service_close_issue.png diff --git a/doc/integration/jira/img/open_jira_issues_list_v13.2.png b/doc/integration/jira/img/open_jira_issues_list_v13.2.png Binary files differnew file mode 100644 index 00000000000..0cf58433b25 --- /dev/null +++ b/doc/integration/jira/img/open_jira_issues_list_v13.2.png diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md new file mode 100644 index 00000000000..221e50e5d66 --- /dev/null +++ b/doc/integration/jira/index.md @@ -0,0 +1,91 @@ +--- +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 +--- + +# Jira integrations **(FREE)** + +If your organization uses [Jira](https://www.atlassian.com/software/jira) issues, +you can [migrate](../../user/project/import/jira.md) your issues from Jira and work +exclusively in GitLab. However, if you'd like to continue to use Jira, you can +integrate it with GitLab. GitLab offers two types of Jira integrations, and you +can use one or both depending on the capabilities you need. + +## Compare Jira integrations + +After you set up one or both of these integrations, you can cross-reference activity +in your GitLab project with any of your projects in Jira. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be). + +### Per-project Jira integration + +This integration connects a single GitLab project to a Jira instance. The Jira instance +can be hosted by you or in [Atlassian cloud](https://www.atlassian.com/cloud): + +- *If your installation uses Jira Cloud,* use the + [GitLab for Jira app](connect-app.md). +- *If either your Jira or GitLab installation is self-managed,* use the + [Jira DVCS Connector](dvcs.md). + +### Jira development panel integration + +The [Jira development panel integration](development_panel.md) +connects all GitLab projects under a group or personal namespace. When configured, +relevant GitLab information, including related branches, commits, and merge requests, +displays in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). + +### Direct feature comparison + +| Capability | Jira integration | Jira Development panel integration | +|-|-|-| +| Mention a Jira issue ID in a GitLab commit or merge request, and a link to the Jira issue is created. | Yes. | No. | +| Mention a Jira issue ID in GitLab and the Jira issue shows the GitLab issue or merge request. | Yes. A Jira comment with the GitLab issue or MR title links to GitLab. The first mention is also added to the Jira issue under **Web links**. | Yes, in the issue's Development panel. | +| Mention a Jira issue ID in a GitLab commit message and the Jira issue shows the commit message. | Yes. The entire commit message is displayed in the Jira issue as a comment and under **Web links**. Each message links back to the commit in GitLab. | Yes, in the issue's Development panel and optionally with a custom comment on the Jira issue using Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html). | +| Mention a Jira issue ID in a GitLab branch name and the Jira issue shows the branch name. | No. | Yes, in the issue's [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). | +| Add Jira time tracking to an issue. | No. | Yes. Time can be specified using Jira Smart Commits. | +| Use a Git commit or merge request to transition or close a Jira issue. | Yes. Only a single transition type, typically configured to close the issue by setting it to Done. | Yes. Transition to any state using Jira Smart Commits. | +| Display a list of Jira issues. | Yes. **(PREMIUM)** | No. | +| Create a Jira issue from a vulnerability or finding. **(ULTIMATE)** | Yes. | No. | + +## Authentication in Jira + +The process for configuring Jira depends on whether you host Jira on your own server or on +[Atlassian cloud](https://www.atlassian.com/cloud): + +- **Jira Server** supports basic authentication. When connecting, a **username and password** are + required. Connecting to Jira Server via CAS is not possible. For more information, read + how to [set up a user in Jira Server](jira_server_configuration.md). +- **Jira on Atlassian cloud** supports authentication through an API token. When connecting to Jira on + 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). + +## Troubleshooting + +If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured. + +### GitLab is unable to comment on a Jira issue + +Make sure that the Jira user you set up for the integration has the +correct access permission to post comments on a Jira issue and also to transition +the issue, if you'd like GitLab to also be able to do so. +Jira issue references and update comments do not work if the GitLab issue tracker is disabled. + +### GitLab is unable to close a Jira issue + +Make sure the `Transition ID` you set within the Jira settings matches the one +your project needs to close an issue. + +Make sure that the Jira issue is not already marked as resolved; that is, +the Jira issue resolution field is not set. (It should not be struck through in +Jira lists.) + +### CAPTCHA + +CAPTCHA may be triggered after several consecutive failed login attempts +which may lead to a `401 unauthorized` error when testing your Jira integration. +If CAPTCHA has been triggered, you can't use Jira's REST API to +authenticate with the Jira site. You need to log in to your Jira instance +and complete the CAPTCHA. diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md new file mode 100644 index 00000000000..d2cab59742b --- /dev/null +++ b/doc/integration/jira/issues.md @@ -0,0 +1,173 @@ +--- +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 +--- + +# 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. + +Jira issue IDs must be formatted in uppercase for the integration to work. + +## 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: + +```plaintext +USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: +ENTITY_TITLE +``` + +- `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. + + + +For example, the following commit references the Jira issue with `PROJECT-1` as its ID: + +```shell +git commit -m "PROJECT-1 Fix spelling and grammar" +``` + +## Close Jira issues + +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). + +There are currently three trigger words, and you can use either one to achieve +the same goal: + +- `Resolves PROJECT-1` +- `Closes PROJECT-1` +- `Fixes PROJECT-1` + +where `PROJECT-1` is the ID of the Jira issue. + +Note the following: + +- 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. + +Let's consider the following example: + +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. + +In the following screenshot you can see what the link references to the Jira +issue look like. + + + +Once this merge request is merged, the Jira issue is automatically closed +with a link to the commit that resolved the issue. + + + +## View Jira issues **(PREMIUM)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. + +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): + +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. 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). + +Issues are grouped into tabs based on their [Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html): + +- 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. + +## 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. + +When viewing the [Jira issues list](#view-jira-issues), select an issue from the +list to open it in GitLab: + + + +## 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). + +- 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` + +- 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` + +- 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` + +## 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". + +See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting and select the **Move to Done** option. + +## Custom issue transitions + +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. + +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. + +To see the transition IDs on Jira Cloud, edit a workflow in the **Text** view. +The transition IDs display in the **Transitions** column. + +On Jira Server you can get the transition IDs in either of the following ways: + +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 + +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. + +## Disabling comments on Jira issues + +You can continue to have GitLab cross-link a source commit/MR with a Jira issue while disabling the comment added to the issue. + +See the [Configure GitLab](development_panel.md#configure-gitlab) section and uncheck the **Enable comments** setting. diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md new file mode 100644 index 00000000000..fd58b3f33f7 --- /dev/null +++ b/doc/integration/jira/jira_cloud_configuration.md @@ -0,0 +1,22 @@ +--- +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 +--- + +# Create an API token in Jira on Atlassian cloud **(FREE)** + +You need an API token to [integrate with Jira](../../user/project/integrations/jira.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) + with your email address. Use an account with *write* access to Jira projects. +1. Go to **Settings > API tokens**. +1. Select **Create API token** to display a modal window with an API token. +1. To copy the API token, select **Copy to clipboard**, or select **View** and write + down the new API token. You need this value when you + [configure GitLab](development_panel.md#configure-gitlab). + +You need the newly created token, and the email +address you used when you created it, when you +[configure GitLab](development_panel.md#configure-gitlab). diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md new file mode 100644 index 00000000000..3573a1f8b1e --- /dev/null +++ b/doc/integration/jira/jira_server_configuration.md @@ -0,0 +1,83 @@ +--- +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 +--- + +# Jira Server credentials **(FREE)** + +To [integrate Jira with GitLab](../../user/project/integrations/jira.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: + +1. [Create a Jira Server user](#create-a-jira-server-user). +1. [Create a Jira Server group](#create-a-jira-server-group) for the user to belong to. +1. [Create a permission scheme for your group](#create-a-permission-scheme-for-your-group). + +## Create a Jira Server user + +This process creates a user named `gitlab` and adds it to a new group named `gitlab-developers`: + +1. Sign in to your Jira instance as an administrator. +1. In the upper right corner of the top menu, go to the gear icon and + select **User Management**. +1. Create a new user account (`gitlab`) with write access to + projects in Jira. + - **Email address**: Jira requires a valid email address, and sends a verification + email, which you need to set up the password. + - **Username**: Jira creates the username by using the email prefix. You can change + this username later. + - **Password**: You must create a password, because the GitLab integration doesn't + support SSO, such as SAML. To create the password, visit the user profile, look up + the username, and set a password. +1. Select **Create user**. + +After you create the user, create a group for it. + +## Create a Jira Server group + +After you [create a Jira Server user](#create-a-jira-server-user), you can create a +group to assign permissions to the user: + +1. Sign in to your Jira instance as an administrator. +1. In the upper right corner of the top menu, go to the gear icon and + select **User Management**. +1. From the sidebar, select **Groups**. + +  + +1. In the **Add group** section, enter a **Name** for the group (for example, + `gitlab-developers`), and then select **Add group**. +1. To add the `gitlab` user to the `gitlab-developers` group, select **Edit members**. + The `gitlab-developers` group should be listed in the leftmost box as a + selected group. +1. In the **Add members to selected group(s)** area, enter `gitlab`. +1. Select **Add selected users**. +Jira saves your selection, and `gitlab` should appear in the **Group member(s)** +area. + + + +Next, create a permission scheme for your group. + +## Create a permission scheme for your group + +After creating the group in Jira, grant permissions to the group by creating a permission scheme: + +1. Sign in to your Jira instance as an administrator. +1. In the upper right corner of the top menu, go to the gear icon and + select **Issues**. +1. From the sidebar, select **Permission Schemes**. +1. Select **Add Permission Scheme**, enter a **Name** and (optionally) a + **Description**, and then select **Add**. +1. In the permissions scheme list, locate your new permissions scheme, and + select **Permissions**. +1. Next to **Administer Projects**, select **Edit**. In + the **Group** list, select `gitlab-developers`. + +  + +Write down the new Jira username and its +password, as you need them when +[configuring GitLab](development_panel.md#configure-gitlab). diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md index 59a96970d75..152c1df3538 100644 --- a/doc/integration/jira_development_panel.md +++ b/doc/integration/jira_development_panel.md @@ -1,327 +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 +redirect_to: 'jira/index.md' --- -# GitLab Jira Development Panel integration **(FREE)** +This document was moved to [another location](jira/index.md). -> - [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. - -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](../user/project/integrations/jira_integrations.md#feature-comparison). - -Depending on your environment, you can enable this integration by either: - -- Configuring [the Jira DVCS connector](#jira-dvcs-configuration). -- Using the [GitLab for Jira app](#gitlab-for-jira-app) in the Atlassian Marketplace. - -See the [Configuration](#configuration) section for details. - -## Features - -| 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). - -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. - -This differs from the [Jira integration](../user/project/integrations/jira.md), where the mapping is between one GitLab project and the entire Jira instance. - -## Configuration - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Agile Management - GitLab-Jira Development Panel Integration](https://www.youtube.com/watch?v=VjVTOmMl85M&feature=youtu.be). - -If you're using: - -- GitLab.com and Jira Cloud, we recommend you enable this integration by installing the - [GitLab for Jira app](#gitlab-for-jira-app) from the Atlassian Marketplace, which offers a real-time - sync between GitLab and Jira. -- Self-managed GitLab, self-managed Jira, or both, configure the integration using - [Jira's DVCS Connector](#jira-dvcs-configuration), which syncs data hourly. - -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. - -### Jira DVCS configuration - -If you're using GitLab.com and Jira Cloud, use the -[GitLab for Jira app](#gitlab-for-jira-app) unless you have a specific need for the DVCS Connector. - -When configuring Jira DVCS Connector: - -- If you are using self-managed GitLab, make sure your GitLab instance is accessible by Jira. -- If you're connecting to Jira Cloud, ensure your instance is accessible through the internet. -- If you are using Jira Server, make sure your instance is accessible however your network is set up. - -#### GitLab account configuration for DVCS - -NOTE: -To ensure that regular user account maintenance doesn't impact your integration, -create and use a single-purpose `jira` user in GitLab. - -1. In GitLab, create a new application to allow Jira to connect with your GitLab account. -1. Sign in to the GitLab account that you want Jira to use to connect to GitLab. -1. In the top-right corner, select your avatar. -1. Select **Edit profile**. -1. In the left sidebar, select **Applications**. -1. In the **Name** field, enter a descriptive name for the integration, such as `Jira`. -1. In the **Redirect URI** field, enter `https://<gitlab.example.com>/login/oauth/callback`, - 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: - 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 - application. - -  - -1. Check **API** in the **Scopes** section, and clear any other checkboxes. -1. Click **Save application**. GitLab displays the generated **Application ID** - and **Secret** values. Copy these values, which you use in Jira. - -#### Jira DVCS Connector setup - -If you're using GitLab.com and Jira Cloud, use the -[GitLab for Jira app](#gitlab-for-jira-app) unless you have a specific need for the DVCS Connector. - -1. Ensure you have completed the [GitLab configuration](#gitlab-account-configuration-for-dvcs). -1. If you're using Jira Server, go to **Settings (gear) > Applications > DVCS accounts**. - If you're using Jira Cloud, go to **Settings (gear) > Products > DVCS accounts**. -1. Click **Link GitHub Enterprise account** to start creating a new integration. - (We're pretending to be GitHub in this integration, until there's additional platform support in Jira.) -1. Complete the form: - -1. Select **GitHub Enterprise** for the **Host** field. - -1. In the **Team or User Account** field, enter either: - - - The relative path of a top-level GitLab group that you have access to. - - The relative path of your personal namespace. - -  - -1. In the **Host URL** field, enter `https://<gitlab.example.com>/`, - replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com, - this would be `https://gitlab.com/`. - - NOTE: - If using a GitLab version earlier than 11.3 the **Host URL** value should be `https://<gitlab.example.com>/-/jira` - -1. For the **Client ID** field, use the **Application ID** value from the previous section. - -1. For the **Client Secret** field, use the **Secret** value from the previous section. - -1. Ensure that the rest of the checkboxes are checked. - -1. Click **Add** to complete and create the integration. - - Jira takes up to a few minutes to know about (import behind the scenes) all the commits and branches - for all the projects in the GitLab group you specified in the previous step. These are refreshed - every 60 minutes. - - In the future, we plan on implementing real-time integration. If you need - to refresh the data manually, you can do this from the `Applications -> DVCS - accounts` screen where you initially set up the integration: - -  - -To connect additional GitLab projects from other GitLab top-level groups (or personal namespaces), repeat the previous -steps with additional Jira DVCS accounts. - -Now that the integration is configured, read more about how to test and use it in [Usage](#usage). - -#### Troubleshooting your DVCS connection - -Refer to the items in this section if you're having problems with your DVCS connector. - -##### Jira cannot access GitLab server - -```plaintext -Error obtaining access token. Cannot access https://gitlab.example.com from Jira. -``` - -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 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 - certificate [are resolved on the GitLab server](https://docs.gitlab.com/omnibus/settings/ssl.html#other-certificate-authorities), - as GitLab is the TLS client. -- The Jira Development Panel integration requires Jira to connect to GitLab, which - causes Jira to be the TLS client. If your GitLab server's certificate is not - issued by a public certificate authority, the Java Truststore on Jira's server - needs to have the appropriate certificate added to it (such as your organization's - root certificate). - -Refer to Atlassian's documentation and Atlassian Support for assistance setting up Jira correctly: - -- [Adding a certificate to the trust store](https://confluence.atlassian.com/kb/how-to-import-a-public-ssl-certificate-into-a-jvm-867025849.html). - - Simplest approach is to use [`keytool`](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html). - - Add additional roots to Java's default Truststore (`cacerts`) to allow Jira to - also trust public certificate authorities. - - If the integration stops working after upgrading Jira's Java runtime, this - might be because the `cacerts` Truststore got replaced. - -- [Troubleshooting connectivity up to and including TLS handshaking](https://confluence.atlassian.com/kb/unable-to-connect-to-ssl-services-due-to-pkix-path-building-failed-error-779355358.html), - using the a java class called `SSLPoke`. - -- Download the class from Atlassian's knowledge base to Jira's server, for example to `/tmp`. -- Use the same Java runtime as Jira. -- Pass all networking-related parameters that Jira is called with, such as proxy - settings or an alternative root Truststore (`-Djavax.net.ssl.trustStore`): - -```shell -${JAVA_HOME}/bin/java -Djavax.net.ssl.trustStore=/var/atlassian/application-data/jira/cacerts -classpath /tmp SSLPoke gitlab.example.com 443 -``` - -The message `Successfully connected` indicates a successful TLS handshake. - -If there are problems, the Java TLS library generates errors that you can -look up for more detail. - -##### Scope error when connecting Jira via DVCS - -```plaintext -The requested scope is invalid, unknown, or malformed. -``` - -Potential resolutions: - -- Verify the URL shown in the browser after being redirected from Jira in step 5 of [Jira DVCS Connector Setup](#jira-dvcs-connector-setup) includes `scope=api` in the query string. -- If `scope=api` is missing from the URL, return to [GitLab account configuration](#gitlab-account-configuration-for-dvcs) and ensure the application you created in step 1 has the `api` box checked under scopes. - -##### Jira error adding account and no repositories listed - -```plaintext -Error! -Failed adding the account: [Error retrieving list of repositories] -``` - -This error message is generated in Jira after completing the **Add New Account** -form in Jira and authorizing access. Attempting to click **Try Again** returns -`Account is already integrated with JIRA.` The account is set up in the DVCS -accounts view, but no repositories are listed. - -Potential resolutions: - -- 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). -- If you're using GitLab Free 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. - -#### Fixing synchronization issues - -If Jira displays incorrect information (such as deleted branches), you may need to -resynchronize the information. To do so: - -1. In Jira, go to **Jira Administration > Applications > DVCS accounts**. -1. At the account (group or subgroup) level, Jira displays an option to - **Refresh repositories** in the `...` (ellipsis) menu. -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://support.atlassian.com/jira-cloud-administration/docs/synchronize-jira-cloud-to-bitbucket/). - -### GitLab for Jira 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. - -This method is recommended when using GitLab.com and Jira Cloud because data is 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](#jira-dvcs-configuration) 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. - -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 - [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 -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 - are synced to Jira. -- From GitLab 13.8, past merge request data is synced to Jira. - -Support for syncing past branch and commit data [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/263240). - -For more information, see [Usage](#usage). - -#### Troubleshooting GitLab for Jira - -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. - -> "You need to sign in or sign up before continuing." - -In this case, use [Firefox](https://www.mozilla.org/en-US/firefox/) or enable cross-site cookies in your browser. - -## 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. - - - -Click the links to see your GitLab repository data. - - - - - -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). - -## Limitations - -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`. +<!-- This redirect file can be deleted after <2021-06-24>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 377c8ec82d0..490397cdf1b 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -33,17 +33,18 @@ OAuth 2 can be used: The 'GitLab Importer' feature also uses OAuth 2 to give access to repositories without sharing user credentials to your GitLab.com account. -GitLab supports two ways of adding a new OAuth 2 application to an instance: +GitLab supports several ways of adding a new OAuth 2 application to an instance: -- As a regular user, for applications owned by an individual. -- Through the Admin Area menu for instance-wide apps. +- [User owned applications](#user-owned-applications) +- [Group owned applications](#group-owned-applications) +- [Instance-wide applications](#instance-wide-applications) -The only difference between these two methods is the [permission](../user/permissions.md) +The only difference between these methods is the [permission](../user/permissions.md) levels. The default callback URL is `http://your-gitlab.example.com/users/auth/gitlab/callback`. -## Add an application through the profile +## User owned applications -To add a new application via your profile: +To add a new application for your user: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. @@ -55,7 +56,22 @@ To add a new application via your profile: - Application ID: OAuth 2 Client ID. - Secret: OAuth 2 Client Secret. -## OAuth applications in the Admin Area +## Group owned applications + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16227) in GitLab 13.11. + +To add a new application for a group: + +1. Navigate to the desired group. +1. In the left sidebar, select **Settings > Applications**. +1. Enter a **Name**, **Redirect URI** and OAuth 2 scopes as defined in [Authorized Applications](#authorized-applications). + The **Redirect URI** is the URL where users are sent after they authorize with GitLab. +1. Select **Save application**. GitLab displays: + + - Application ID: OAuth 2 Client ID. + - Secret: OAuth 2 Client Secret. + +## Instance-wide applications To create an application for your GitLab instance, select **Admin Area > Applications > New application**. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index e3b18c0b82b..45d44582607 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -22,40 +22,50 @@ of the configured mechanisms. ## Supported Providers -This is a list of the current supported OmniAuth providers. Before proceeding -on each provider's documentation, make sure to first read this document as it -contains some settings that are common for all providers. - -- [GitHub](github.md) -- [Bitbucket](bitbucket.md) -- [GitLab.com](gitlab.md) -- [Google](google.md) -- [Facebook](facebook.md) -- [Twitter](twitter.md) -- [Shibboleth](shibboleth.md) -- [SAML](saml.md) -- [Crowd](../administration/auth/crowd.md) -- [Azure](azure.md) -- [Auth0](auth0.md) -- [Authentiq](../administration/auth/authentiq.md) -- [OAuth2Generic](oauth2_generic.md) -- [JWT](../administration/auth/jwt.md) -- [OpenID Connect](../administration/auth/oidc.md) -- [Salesforce](salesforce.md) -- [AWS Cognito](../administration/auth/cognito.md) +This is a list of the current supported OmniAuth providers. Before proceeding on each provider's documentation, +make sure to first read this document as it contains some settings that are common for all providers. + +|Provider documentation |OmniAuth provider name | +|-----------------------------------------------------------------|--------------------------| +|[Atlassian Crowd](../administration/auth/crowd.md) |`crowd` | +|[Atlassian](../administration/auth/atlassian.md) |`atlassian_oauth2` | +|[Auth0](auth0.md) |`auth0` | +|[Authentiq](../administration/auth/authentiq.md) |`authentiq` | +|[AWS Cognito](../administration/auth/cognito.md) |`cognito` | +|[Azure v2](azure.md#microsoft-azure-oauth2-omniauth-provider-v2) |`azure_activedirectory_v2`| +|[Azure v1](azure.md) |`azure_oauth2` | +|[Bitbucket Cloud](bitbucket.md) |`bitbucket` | +|[CAS](cas.md) |`cas3` | +|[Facebook](facebook.md) |`facebook` | +|[Generic OAuth2](oauth2_generic.md) |`oauth2_generic` | +|[GitHub](github.md) |`github` | +|[GitLab.com](gitlab.md) |`gitlab` | +|[Google](google.md) |`google_oauth2` | +|[JWT](../administration/auth/jwt.md) |`jwt` | +|[Kerberos](kerberos.md) |`kerberos` | +|[OpenID Connect](../administration/auth/oidc.md) |`openid_connect` | +|[Salesforce](salesforce.md) |`salesforce` | +|[SAML](saml.md) |`saml` | +|[Shibboleth](shibboleth.md) |`shibboleth` | +|[Twitter](twitter.md) |`twitter` | ## Initial OmniAuth Configuration -Before configuring individual OmniAuth providers there are a few global settings -that are in common for all providers that we need to consider. +The OmniAuth provider names from the table above are needed to configure a few global settings that are in common for all providers. NOTE: Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an 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 can't sign in by using OmniAuth. +- `allow_single_sign_on` allows you to specify the providers that automatically + create a GitLab account. For example, if you wish to enable Azure (v2) and Google, + in Omnibus, specify a list of provider names: + + ```ruby + gitlab_rails['omniauth_allow_single_sign_on'] = ['azure_activedirectory_v2', 'google_oauth2'] + ``` + + The value defaults to `false`. If `false` users must be created manually, or they can't sign in by using 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 have their LDAP identity created in GitLab as well. @@ -239,9 +249,6 @@ from the OmniAuth provider's documentation. If you have successfully set up a provider that is not shipped with GitLab itself, please let us know. -You can help others by reporting successful configurations and probably share a -few insights or provide warnings for common errors or pitfalls. - While we can't officially support every possible authentication mechanism out there, we'd like to at least help those with specific needs. @@ -257,9 +264,9 @@ To enable/disable an OmniAuth provider: 1. In the top navigation bar, go to **Admin Area**. 1. In the left sidebar, go to **Settings**. 1. Scroll to the **Sign-in Restrictions** section, and click **Expand**. -1. Next to **Enabled OAuth Sign-In sources**, select the check box for each provider you want to enable or disable. +1. Below **Enabled OAuth Sign-In sources**, select the check box for each provider you want to enable or disable. -  +  ## Disabling OmniAuth @@ -328,20 +335,20 @@ You can add the `auto_sign_in_with_provider` setting to your GitLab configuration to redirect login requests to your OmniAuth provider for authentication. This removes the need to click a button before actually signing in. -For example, when using the Azure integration, set the following to enable auto +For example, when using the [Azure v2 integration](azure.md#microsoft-azure-oauth2-omniauth-provider-v2), set the following to enable auto sign-in: For Omnibus package: ```ruby -gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_oauth2' +gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_activedirectory_v2' ``` For installations from source: ```yaml omniauth: - auto_sign_in_with_provider: azure_oauth2 + auto_sign_in_with_provider: azure_activedirectory_v2 ``` Keep in mind that every sign-in attempt is redirected to the OmniAuth @@ -356,3 +363,32 @@ You may also bypass the auto sign in feature by browsing to The [Generated passwords for users created through integrated authentication](../security/passwords_for_integrated_authentication_methods.md) guide provides an overview about how GitLab generates and sets passwords for users created with OmniAuth. + +## Custom OmniAuth provider icon + +Most supported providers include a built-in icon for the rendered sign-in button. +After you ensure your image is optimized for rendering at 64 x 64 pixels, +you can override this icon in one of two ways: + +- **Provide a custom image path**: + 1. *If you are hosting the image outside of your GitLab server domain,* ensure + your [content security policies](https://docs.gitlab.com/omnibus/settings/configuration.html#content-security-policy) + are configured to allow access to the image file. + 1. Depending on your method of installing GitLab, add a custom `icon` parameter + to your GitLab configuration file. Read [OpenID Connect OmniAuth provider](../administration/auth/oidc.md) + for an example for the OpenID Connect provider. +- **Directly embed an image in a configuration file**: This example creates a Base64-encoded + version of your image you can serve through a + [Data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs): + 1. Encode your image file with GNU `base64` command (such as `base64 -w 0 <logo.png>`) + which returns a single-line `<base64-data>` string. + 1. Add the Base64-encoded data to a custom `icon` parameter in your GitLab configuration file: + + ```yaml + omniauth: + providers: + - { name: '...' + icon: 'data:image/png;base64,<base64-data>' + ... + } + ``` diff --git a/doc/integration/saml.md b/doc/integration/saml.md index d68cf8e2f34..842eb71f7f4 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -11,14 +11,14 @@ This page describes instance-wide SAML for self-managed GitLab instances. For SA You should also reference the [OmniAuth documentation](omniauth.md) for general settings that apply to all OmniAuth providers. -## Common SAML Terms +## Glossary of common terms | Term | Description | |--------------------------------|-------------| -| Identity Provider (IdP) | The service which manages your user identities, such as ADFS, Okta, OneLogin, or Ping Identity. | -| Service Provider (SP) | SAML considers GitLab to be a service provider. | +| Identity provider (IdP) | The service which manages your user identities, such as Okta or OneLogin. | +| Service provider (SP) | GitLab can be configured as a SAML 2.0 SP. | | Assertion | A piece of information about a user's identity, such as their name or role. Also known as claims or attributes. | -| SSO | Single Sign-On. | +| Single Sign-On (SSO) | Name of authentication scheme. | | Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. | | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | | Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | @@ -26,8 +26,8 @@ You should also reference the [OmniAuth documentation](omniauth.md) for general ## General Setup GitLab can be configured to act as a SAML 2.0 Service Provider (SP). This allows -GitLab to consume assertions from a SAML 2.0 Identity Provider (IdP) such as -Microsoft ADFS to authenticate users. +GitLab to consume assertions from a SAML 2.0 Identity Provider (IdP), such as +Okta to authenticate users. First configure SAML 2.0 support in GitLab, then register the GitLab application in your SAML IdP: @@ -52,7 +52,7 @@ in your SAML IdP: ``` 1. To allow your users to use SAML to sign up without having to manually create - an account first, don't forget to add the following values to your configuration: + an account first, add the following values to your configuration: For Omnibus package: @@ -85,7 +85,8 @@ in your SAML IdP: auto_link_saml_user: true ``` -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. +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. 1. Add the provider configuration: @@ -102,7 +103,7 @@ in your SAML IdP: issuer: 'https://gitlab.example.com', name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' }, - label: 'Company Login' # optional label for SAML login button, defaults to "Saml" + label: 'Provider name' # optional label for SAML login button, defaults to "Saml" } ] ``` @@ -134,6 +135,7 @@ in your SAML IdP: be a SHA1 fingerprint; check [the OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml) 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 to the IdP. @@ -151,16 +153,57 @@ configuration information to the IdP. To build the metadata URL for GitLab, appe https://gitlab.example.com/users/auth/saml/metadata ``` -At a minimum the IdP *must* provide a claim containing the user's email address, using -claim name `email` or `mail`. The email will be used to automatically generate the GitLab -username. GitLab will also use claims with name `name`, `first_name`, `last_name` -(see [the OmniAuth SAML gem](https://github.com/omniauth/omniauth-saml/blob/master/lib/omniauth/strategies/saml.rb) -for supported claims). +At a minimum the IdP *must* provide a claim containing the user's email address using `email` or `mail`. +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. +### Notes on configuring your identity provider + +When configuring a SAML app on the IdP, you need at least: + +- Assertion consumer service URL +- Issuer +- [`NameID`](../user/group/saml_sso/index.md#nameid) +- [Email address claim](#assertions) + +Your identity provider may require additional configuration, such as the following: + +| Field | Value | Notes | +|-------|-------|-------| +| SAML profile | Web browser SSO profile | GitLab uses SAML to sign users in through their browser. No requests are made directly to the identity provider. | +| SAML request binding | HTTP Redirect | GitLab (the service provider) redirects users to your identity provider with a base64 encoded `SAMLRequest` HTTP parameter. | +| SAML response binding | HTTP POST | Specifies how the SAML token is sent by your identity provider. Includes the `SAMLResponse`, which a user's browser submits back to GitLab. | +| Sign SAML response | Required | Prevents tampering. | +| X.509 certificate in response | Required | Signs the response and checks against the provided fingerprint. | +| Fingerprint algorithm | SHA-1 | GitLab uses a SHA-1 hash of the certificate to sign the SAML Response. | +| Signature algorithm | SHA-1/SHA-256/SHA-384/SHA-512 | Determines how a response is signed. Also known as the digest method, this can be specified in the SAML response. | +| Encrypt SAML assertion | Optional | Uses TLS between your identity provider, the user's browser, and GitLab. | +| Sign SAML assertion | Optional | Validates the integrity of a SAML assertion. When active, signs the whole response. | +| Check SAML request signature | Optional | Checks the signature on the SAML response. | +| Default RelayState | Optional | Specifies the URL users should end up on after successfully signing in through SAML at your identity provider. | +| NameID format | Persistent | See [NameID format details](../user/group/saml_sso/index.md#nameid-format). | +| Additional URLs | Optional | May include the issuer (or identifier) or the assertion consumer service URL in other fields on some providers. | + +For example configurations, see the [notes on specific providers](#providers). + +### Assertions + +| Field | Supported keys | +|-----------------|----------------| +| Email (required)| `email`, `mail` | +| Username | `username`, `nickname` | +| Full Name | `name` | +| First Name | `first_name`, `firstname`, `firstName` | +| Last Name | `last_name`, `lastname`, `lastName` | + +If a username is not specified, the email address is used to generate the GitLab username. + +Please refer to [the OmniAuth SAML gem](https://github.com/omniauth/omniauth-saml/blob/master/lib/omniauth/strategies/saml.rb) +for a full list of supported assertions. + ## SAML Groups You can require users to be members of a certain group, or assign users [external](../user/permissions.md#external-users), admin or [auditor](../user/permissions.md#auditor-users) roles based on group membership. @@ -649,6 +692,81 @@ Group SAML on a self-managed instance is limited when compared to the recommende - { name: 'group_saml' } ``` +## Providers + +GitLab support of SAML means that you can sign in to GitLab with a wide range of identity providers. +Your identity provider may have additional documentation. Some identity providers include +documentation on how to use SAML to sign in to GitLab. + +Examples: + +- [ADFS (Active Directory Federation Services)](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) +- [Auth0](https://auth0.com/docs/protocols/saml-protocol/configure-auth0-as-saml-identity-provider) +- [PingOne by Ping Identity](https://docs.pingidentity.com/bundle/pingone/page/xsh1564020480660-1.html) + +Please note that GitLab provides the following setup notes for guidance only. +If you have any questions on configuring the SAML app, please contact your provider's support. + +### Okta setup notes + +The following guidance is based on this Okta article, on adding a [SAML Application with an Okta Developer account](https://support.okta.com/help/s/article/Why-can-t-I-add-a-SAML-Application-with-an-Okta-Developer-account?language=en_US): + +1. In the Okta admin section, make sure to select Classic UI view in the top left corner. From there, choose to **Add an App**. +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 + crop and resize it. +1. Next, you'll need the to 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 + 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 + `idp_sso_target_url` on your GitLab configuration file. +1. **Before you leave Okta, make sure you add your user and groups if any.** + +### Google workspace setup notes + +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: + +| | 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. | +| 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. | +| Last name | `last_name` | Required value to communicate with GitLab. | + +You also need to setup the following SAML attribute mappings: + +| Google Directory attributes | App attributes | +|-----------------------------------|----------------| +| Basic information > Email | `email` | +| Basic Information > First name | `first_name` | +| Basic Information > Last name | `last_name` | + +You may also use some of this information when you [configure GitLab](#general-setup). + +When configuring the Google Workspace SAML app, be sure to record the following information: + +| | Value | Description | +|-------------|--------------|-----------------------------------------------------------------------------------| +| SSO URL | Depends | Google Identity Provider details. Set to the GitLab `idp_sso_target_url` setting. | +| Certificate | Downloadable | Run `openssl x509 -in <your_certificate.crt> -noout -fingerprint` to generate the SHA1 fingerprint that can be used in the `idp_cert_fingerprint` setting. | + +While the Google Workspace Admin provides IdP metadata, Entity ID and SHA-256 fingerprint, +GitLab does not need that information to connect to the Google Workspace SAML app. + ## Troubleshooting ### SAML Response @@ -670,6 +788,21 @@ for the SAML user. Ensure the IdP provides a claim containing the user's email address, using the claim name `email` or `mail`. +### 422 error after login + +If you see a "422 error" in GitLab when you are redirected from the SAML +sign-in page, you might have an incorrectly configured assertion consumer +service (ACS) URL on the identity provider. + +Make sure the ACS URL points to `https://gitlab.example.com/users/auth/saml/callback`, where +`gitlab.example.com` is the URL of your GitLab instance. + +If the ACS URL is correct, and you still have errors, review the other +[Troubleshooting](#troubleshooting) sections. + +If you are sure that the ACS URL is correct, proceed to the [Redirect back to the login screen with no evident error](#redirect-back-to-the-login-screen-with-no-evident-error) +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 @@ -735,3 +868,11 @@ The following are the most likely reasons that a user is blocked when signing in - In the configuration, `gitlab_rails['omniauth_block_auto_created_users'] = true` is set and this is the user's first time signing in. - There are [`required_groups`](#required-groups) configured, but the user is not a member of one. + +### Google workspace troubleshooting tips + +The Google Workspace documentation on [SAML app error messages](https://support.google.com/a/answer/6301076?hl=en) is helpful for debugging if you are seeing an error from Google while signing in. +Pay particular attention to the following 403 errors: + +- `app_not_configured` +- `app_not_configured_for_user` diff --git a/doc/integration/vault.md b/doc/integration/vault.md index 362ae36389b..c98990bcb0e 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -76,15 +76,25 @@ The following assumes you already have Vault installed and running. This configuration is saved under the name of the role you are creating. In this case, we are creating a `demo` role. Later, we show how you can access this role through the Vault CLI. + WARNING: + If you're using a public GitLab instance (GitLab.com or any other instance publicly + accessible), it's paramount to specify the `bound_claims` to allow access only to + members of your group/project. Otherwise, anyone with a public account can access + your Vault instance. + ```shell - vault write auth/oidc/role/demo \ - user_claim="sub" \ - allowed_redirect_uris="http://localhost:8250/oidc/callback,http://127.0.0.1:8200/ui/vault/auth/oidc/oidc/callback" \ - bound_audiences="your_application_id" \ - role_type="oidc" \ - oidc_scopes="openid" \ - policies=demo \ - ttl=1h + vault write auth/oidc/role/demo -<<EOF + { + "user_claim": "sub", + "allowed_redirect_uris": "your_vault_instance_redirect_uris", + "bound_audiences": "your_application_id", + "oidc_scopes": "openid", + "role_type": "oidc", + "policies": "demo", + "ttl": "1h", + "bound_claims": { "groups": ["yourGroup/yourSubgrup"] } + } + EOF ``` 1. **Sign in to Vault:** |
