diff options
Diffstat (limited to 'doc/integration/jira')
27 files changed, 492 insertions, 517 deletions
diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index 03d742703a1..3f3511c3838 100644 --- a/doc/integration/jira/configure.md +++ b/doc/integration/jira/configure.md @@ -1,26 +1,31 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Configure the Jira integration **(FREE)** +# Jira issue integration **(FREE)** -You can set up the [Jira integration](index.md#jira-integration) -by configuring your project settings in GitLab. -You can also configure these settings at a [group level](../../user/admin_area/settings/project_integration_management.md#manage-group-level-default-settings-for-a-project-integration), -and for self-managed GitLab, at an [instance level](../../user/admin_area/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration). +The Jira issue integration connects one or more GitLab projects to a Jira instance. You can host the Jira instance yourself or in [Jira Cloud](https://www.atlassian.com/migration/assess/why-cloud). The supported Jira versions are `6.x`, `7.x`, `8.x`, and `9.x`. + +## Configure the integration Prerequisites: -- Ensure your GitLab installation does not use a [relative URL](development_panel.md#limitations). -- For **Jira Server**, ensure you have a Jira username and password. - See [authentication in Jira](index.md#authentication-in-jira). -- For **Jira on Atlassian cloud**, ensure you have an API token - and the email address you used to create the token. - See [authentication in Jira](index.md#authentication-in-jira). +- Your GitLab installation must not use a [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configure-a-relative-url-for-gitlab). +- **For Jira Cloud**, you must have a [Jira Cloud API token](#create-a-jira-cloud-api-token) and + the email address you used to create the token. +- **For Jira Data Center or Jira Server**, you must have one of the following: + - [Jira username and password](jira_server_configuration.md). + - Jira personal access token. + +You can enable the Jira issue integration by configuring your project settings in GitLab. +You can also configure these settings at the: + +- [Group level](../../user/admin_area/settings/project_integration_management.md#manage-group-level-default-settings-for-a-project-integration) +- [Instance level](../../user/admin_area/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration) for self-managed GitLab -To configure your project: +To configure your project settings in GitLab: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. @@ -34,14 +39,21 @@ To configure your project: [closing reference](../../user/project/issues/managing_issues.md#closing-issues-automatically) is made in GitLab, select **Enable Jira transitions**. 1. Provide Jira configuration information: - - **Web URL**: The base URL to the Jira instance web interface you're linking to - this GitLab project, such as `https://jira.example.com`. - - **Jira API URL**: The base URL to the Jira instance API, such as `https://jira-api.example.com`. - Defaults to the **Web URL** value if not set. Leave blank if using **Jira on Atlassian cloud**. - - **Username or Email**: - For **Jira Server**, use `username`. For **Jira on Atlassian cloud**, use `email`. - - **Password/API token**: - Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**. + - **Web URL**: Base URL for the Jira instance web interface you're linking to + this GitLab project (for example, `https://jira.example.com`). + - **Jira API URL**: Base URL for the Jira instance API (for example, `https://jira-api.example.com`). + If this URL is not set, the **Web URL** value is used by default. For Jira Cloud, leave **Jira API URL** blank. + - **Authentication type**: From the dropdown list, select: + - **Basic** + - **Jira personal access token (Jira Data Center and Jira Server only)** + - **Email or username** (relevant to **Basic** authentication only): + - For Jira Cloud, enter an email. + - For Jira Data Center or Jira Server, enter a username. + - **New API token, password, or Jira personal access token**: + - For **Basic** authentication: + - For Jira Cloud, enter an API token. + - For Jira Data Center or Jira Server, enter a password. + - For **Jira personal access token** authentication, enter a personal access token. 1. To enable users to [view Jira issues](issues.md#view-jira-issues) inside the GitLab project, select **Enable Jira issues** and enter a Jira project key. @@ -52,13 +64,29 @@ To configure your project: can view all issues from the specified Jira project. 1. To enable [issue creation for vulnerabilities](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability), select **Enable Jira issue creation from vulnerabilities**. -1. Select the **Jira issue type**. If the dropdown list is empty, select refresh (**{retry}**) and try again. +1. Select the **Jira issue type**. If the dropdown list 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 +Your GitLab project can now interact with all Jira projects in your instance, and the project displays a Jira link that opens the Jira project. +## Create a Jira Cloud API token + +To configure the Jira issue integration for Jira Cloud, you must have a Jira Cloud API token. +To create a Jira Cloud API token: + +1. Sign in to [Atlassian](https://id.atlassian.com/manage-profile/security/api-tokens) + from an account with **write** access to Jira projects. + + The link opens the **API tokens** page. Alternatively, from your Atlassian + profile, select **Account Settings > Security > Create and manage API tokens**. + +1. Select **Create API token**. +1. In the dialog, enter a label for your token and select **Create**. + +To copy the API token, select **Copy** and paste the token somewhere safe. + ## Migrate from Jira Server to Jira Cloud in GitLab To migrate from Jira Server to Jira Cloud in GitLab and maintain your Jira integration: @@ -68,7 +96,9 @@ To migrate from Jira Server to Jira Cloud in GitLab and maintain your Jira integ 1. Select **Jira**. 1. In **Web URL**, enter the new Jira site URL (for example, `https://myjirasite.atlassian.net`). 1. In **Username or Email**, enter the username or email registered on your Jira profile. -1. [Create an API token](jira_cloud_configuration.md), and copy that value. +1. [Create a Jira Cloud API token](#create-a-jira-cloud-api-token), and copy the token value. 1. In **Password or API token**, paste the API token value. 1. Optional. Select **Test settings** to check if the connection is working. 1. Select **Save changes**. + +To update existing Jira issue references in GitLab to use the new Jira site URL, you must [invalidate the Markdown cache](../../administration/invalidate_markdown_cache.md#invalidate-the-cache). diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index 402efc409cb..e60eeb8fba1 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -1,69 +1,52 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab for Jira Cloud app **(FREE)** -You can integrate GitLab and Jira Cloud using the -[GitLab for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) -app in the Atlassian Marketplace. +With the [GitLab for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app, you can connect GitLab and Jira Cloud to sync development information in real time. You can view this information in the [Jira development panel](development_panel.md). -Only Jira users with administrator access can install or configure -the GitLab for Jira Cloud app. +You can use the GitLab for Jira Cloud app to link top-level groups or subgroups. It's not possible to directly link projects or personal namespaces. -## Install the GitLab for Jira Cloud app **(FREE SAAS)** +- **For GitLab.com**: + - [Install the GitLab for Jira Cloud app](#install-the-gitlab-for-jira-cloud-app). +- **For self-managed GitLab**, do one of the following: + - [Connect the GitLab for Jira Cloud app for self-managed instances](#connect-the-gitlab-for-jira-cloud-app-for-self-managed-instances) (GitLab 15.7 and later). + - [Install the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually). -If you use GitLab.com and Jira Cloud, you can install the GitLab for Jira Cloud app. -If you do not use both of these environments, use the [Jira DVCS Connector](dvcs/index.md) or -[install the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually). -We recommend the GitLab for Jira Cloud app, because data is -synchronized in real time. The DVCS connector updates data only once per hour. +If you use Jira Data Center or Jira Server, use the [Jira DVCS connector](dvcs/index.md) instead. -To configure the GitLab for Jira Cloud app, you must have -at least the Maintainer role in the GitLab.com namespace. +## Install the GitLab for Jira Cloud app **(FREE SAAS)** -This integration method supports [Smart Commits](dvcs/index.md#smart-commits). +Prerequisites: -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a walkthrough of the integration with GitLab for Jira Cloud app, watch -[Configure GitLab.com Jira Could Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube. +- You must have at least the Maintainer role for the GitLab group. +- You must have administrator access to the Jira instance. +- Your network must allow inbound and outbound connections between GitLab and Jira. To install the GitLab for Jira Cloud app: -1. In Jira, go to **Jira Settings > Apps > Find new apps**, then search for GitLab. -1. Select **GitLab for Jira Cloud**, then select **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, to go to the configurations page, select **Get started**. - This page is always available under **Jira Settings > Apps > Manage apps**. - -  -1. To add namespaces, ensure you're signed in to GitLab.com - as a user with at least the Maintainer role. - -  -1. To open the list of available namespaces, select **Add namespace**. - -1. Identify the namespace you want to link, and select **Link**. - - You must have at least the Maintainer role for the namespace. - - Only Jira site administrators can add or remove namespaces for an installation. +1. In Jira, select **Jira Settings > Apps > Find new apps**, and search for GitLab. +1. Select **GitLab for Jira Cloud**, and select **Get it now**. -  + Alternatively, [get the app directly from the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud). -NOTE: -The GitLab.com user only needs access when adding a new namespace. For syncing with -Jira, we do not depend on the user's token. +1. To go to the configurations page, select **Get started**. + You can always access this page in **Jira Settings > Apps > Manage apps**. +1. For a list of groups to link, select **Add namespace**. +1. To link to a group, select **Link**. -After a namespace is added: +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see +[Configure the GitLab for Jira Cloud app from the Atlassian Marketplace](https://youtu.be/SwR-g1s1zTo). -- 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. +After you add a group, the following data is synced to Jira for all projects in that group: -Support for syncing past branch and commit data is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/263240). +- New merge requests, branches, and commits +- Existing merge requests (GitLab 13.8 and later) +- Existing branches and commits (GitLab 15.11 and later) ## Update the GitLab for Jira Cloud app @@ -73,15 +56,15 @@ for details. If the app requires additional permissions, [the update must first be manually approved in Jira](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/#changes-that-require-manual-customer-approval). -## Set up OAuth authentication +## Set up OAuth authentication for self-managed instances **(FREE SELF)** The GitLab for Jira Cloud app is [switching to OAuth authentication](https://gitlab.com/gitlab-org/gitlab/-/issues/387299). To enable OAuth authentication, you must create an OAuth application on the GitLab instance. -Enabling OAuth authentication is: +You must enable OAuth authentication to: -- Required to [connect the GitLab for Jira Cloud app for self-managed instances](#connect-the-gitlab-for-jira-cloud-app-for-self-managed-instances). -- Recommended to [install the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually). +- [Connect the GitLab for Jira Cloud app for self-managed instances](#connect-the-gitlab-for-jira-cloud-app-for-self-managed-instances). +- [Install the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually). To create an OAuth application: @@ -96,42 +79,50 @@ To create an OAuth application: 1. Select **Save application**. 1. Copy the **Application ID** value. 1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). -1. Expand the **GitLab for Jira App** section. +1. Expand **GitLab for Jira App**. 1. Paste the **Application ID** value into **Jira Connect Application ID**. 1. Select **Save changes**. -1. Optional. Enable the `jira_connect_oauth` [feature flag](../../administration/feature_flags.md) to avoid [authentication problems in some browsers](#browser-displays-a-sign-in-message-when-already-signed-in). ## Connect the GitLab for Jira Cloud app for self-managed instances **(FREE SELF)** > Introduced in GitLab 15.7. -Prerequisites: - -- GitLab.com must serve as a proxy for the instance. -- The instance must be publicly available. -- The instance must be on version 15.7 or later. - You can link self-managed instances after installing the GitLab for Jira Cloud app from the marketplace. Jira apps can only link to one URL per marketplace listing. The official listing links to GitLab.com. -If your instance doesn't meet the prerequisites or you don't want to use the official marketplace listing, you can +NOTE: +With this method, GitLab.com serves as a proxy for Jira traffic from your instance. + +If your instance doesn't meet the [prerequisites](#prerequisites) or you don't want to use the official marketplace listing, you can [install the app manually](#install-the-gitlab-for-jira-cloud-app-manually). -It's not possible to create branches from Jira for self-managed instances. +With this method, it's not possible to create branches from Jira Cloud for self-managed instances. +For more information, see [issue 391432](https://gitlab.com/gitlab-org/gitlab/-/issues/391432). +To create branches from Jira Cloud, [install the app manually](#install-the-gitlab-for-jira-cloud-app-manually). + +### Prerequisites + +- The instance must be publicly available. +- The instance must be on GitLab version 15.7 or later. +- You must set up [OAuth authentication](#set-up-oauth-authentication-for-self-managed-instances). +- Your network must allow inbound and outbound connections between GitLab and Jira. ### Set up your instance +[Prerequisites](#prerequisites) + To set up your self-managed instance for the GitLab for Jira Cloud app in GitLab 15.7 and later: -1. [Set up OAuth authentication](#set-up-oauth-authentication). 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). -1. Expand the **GitLab for Jira App** section. +1. Expand **GitLab for Jira App**. 1. In **Jira Connect Proxy URL**, enter `https://gitlab.com`. 1. Select **Save changes**. ### Link your instance +[Prerequisites](#prerequisites) + To link your self-managed instance to the GitLab for Jira Cloud app: 1. Install the [GitLab for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?tab=overview&hosting=cloud). @@ -144,13 +135,6 @@ To link your self-managed instance to the GitLab for Jira Cloud app: If your GitLab instance is self-managed and you don't want to use the official marketplace listing, you can install the app manually. -Prerequisites: - -- The instance must be publicly available. -- You must set up [OAuth authentication](#set-up-oauth-authentication). - -### Set up your Jira app - 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 @@ -159,30 +143,30 @@ self-managed GitLab instances with Jira Cloud, you can do one of the following: - [Install the application in development mode](#install-the-application-in-development-mode). - [Create a Marketplace listing](#create-a-marketplace-listing). -#### Install the application in development mode +### Prerequisites + +- The instance must be publicly available. +- You must set up [OAuth authentication](#set-up-oauth-authentication-for-self-managed-instances). -You can configure your Atlassian Cloud instance to allow you to install applications -from outside the Marketplace, which allows you to install the application: +### Install the application in development mode + +[Prerequisites](#prerequisites-1) + +To configure your Jira instance so you can install applications +from outside the Marketplace: 1. Sign in to your Jira instance as an administrator. 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 access. -1. Install the GitLab application from your Jira 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. Install the GitLab application from your Jira instance as + described in the [Atlassian developer guide](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 select **Upload app**: - -  - - 1. For **App descriptor URL**, provide the full URL to your manifest file, based + 1. For **App descriptor URL**, provide the full URL to your manifest file based on your instance configuration. By default, your manifest file is located at `/-/jira_connect/app_descriptor.json`. For example, if your GitLab self-managed instance domain is `app.pet-store.cloud`, your manifest file is located at `https://app.pet-store.cloud/-/jira_connect/app_descriptor.json`. 1. Select **Upload**. Jira fetches the content of your `app_descriptor` file and installs it. - 1. If the upload is successful, Jira displays a modal panel: **Installed and ready to go!** - To configure the integration, select **Get started**. - -  - + 1. To configure the integration, select **Get started**. 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 Cloud** app now displays under **Manage apps**. You can also @@ -192,19 +176,20 @@ NOTE: If a GitLab update makes changes to the application descriptor, you must uninstall, then reinstall the application. -#### Create a Marketplace listing +### Create a Marketplace listing + +[Prerequisites](#prerequisites-1) -If you prefer to not use development mode on your Jira instance, you can create -your own Marketplace listing for your instance. This enables your application -to be installed from the Atlassian Marketplace. +If you don't want to use development mode on your Jira instance, you can create +your own Marketplace listing. This way, your application +can 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: 1. Register as a Marketplace vendor. -1. List your application using the application descriptor URL. +1. List your application with the application descriptor URL. - Your manifest file is located at: `https://your.domain/your-path/-/jira_connect/app_descriptor.json` - - We recommend you list your application as `private`, because public + - You should list your application as `private` because public applications can be viewed and installed by any user. 1. Generate test license tokens for your application. @@ -212,22 +197,51 @@ NOTE: This method uses [automated updates](#update-the-gitlab-for-jira-cloud-app) the same way as our GitLab.com Marketplace listing. -## Configure your GitLab instance to serve as a proxy for the GitLab for Jira Cloud app +For more information about creating a Marketplace listing, see the [Atlassian documentation](https://developer.atlassian.com/platform/marketplace/installing-cloud-apps/#creating-the-marketplace-listing). -A GitLab instance can serve as a proxy for other GitLab instances using the GitLab for Jira Cloud app. -This can be useful if you are managing multiple GitLab instance but only want to [manually install](#install-the-gitlab-for-jira-cloud-app-manually) -the GitLab for Jira app once. +## Configure your GitLab instance to serve as a proxy for the GitLab for Jira Cloud app **(FREE SELF)** + +A GitLab instance can serve as a proxy for other GitLab instances through the GitLab for Jira Cloud app. +You might want to use a proxy if you're managing multiple GitLab instances but only want to +[manually install](#install-the-gitlab-for-jira-cloud-app-manually) the GitLab for Jira Cloud app once. To configure your GitLab instance to serve as a proxy: 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). -1. Expand the **GitLab for Jira App** section. +1. Expand **GitLab for Jira App**. 1. Select **Enable public key storage**. 1. Select **Save changes**. -1. [Install the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually) +1. [Install the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually). + +Other GitLab instances that use the proxy must configure the **Jira Connect Proxy URL** and the [OAuth application](#set-up-oauth-authentication-for-self-managed-instances) **Redirect URI** settings to point to the proxy instance. + +## Security considerations + +The GitLab for Jira Cloud app connects GitLab and Jira. Data must be shared between the two applications, and access must be granted in both directions. + +### Access to GitLab through OAuth **(FREE SELF)** + +GitLab does not share an access token with Jira. However, users must authenticate through OAuth to configure the app. + +An access token is retrieved through a [PKCE](https://www.rfc-editor.org/rfc/rfc7636) OAuth flow and stored only on the client side. +The app frontend that initializes the OAuth flow is a JavaScript application that's loaded from GitLab through an iframe on Jira. + +The OAuth application must have the `api` scope, which grants complete read and write access to the API. +This access includes all groups and projects, the container registry, and the package registry. +However, the GitLab for Jira Cloud app only uses this access to: + +- Display groups to link. +- Link groups. + +Access through OAuth is only needed for the time a user configures the GitLab for Jira Cloud app. For more information, see [Access token expiration](../oauth_provider.md#access-token-expiration). + +### Access to Jira through access token -Other GitLab instances using the proxy must configure the **Jira Connect Proxy URL** setting and the [OAuth application](#set-up-oauth-authentication) **Redirect URI** to point to the proxy instance. +Jira shares an access token with GitLab to authenticate and authorize data pushes to Jira. +As part of the app installation process, Jira sends a handshake request to GitLab containing the access token. +The handshake is signed with an [asymmetric JWT](https://developer.atlassian.com/cloud/jira/platform/understanding-jwt-for-connect-apps/), +and the access token is stored encrypted with `AES256-GCM` on GitLab. ## Troubleshooting @@ -240,14 +254,20 @@ when you're already signed in: You need to sign in or sign up before continuing. ``` -The GitLab for Jira Cloud app uses an iframe to add namespaces on the +The GitLab for Jira Cloud app uses an iframe to add groups on the settings page. Some browsers block cross-site cookies, which can lead to this issue. -To resolve this issue, set up [OAuth authentication](#set-up-oauth-authentication) and enable the `jira_connect_oauth` [feature flag](../../administration/feature_flags.md). +To resolve this issue, set up [OAuth authentication](#set-up-oauth-authentication-for-self-managed-instances). ### Manual installation fails -You might get an error if you have installed the GitLab for Jira Cloud app from the official marketplace listing and replaced it with manual installation. To resolve this issue, disable the **Jira Connect Proxy URL** setting. +You might get an error if you have installed the GitLab for Jira Cloud app from the official marketplace listing and replaced it with manual installation: + +```plaintext +The app "gitlab-jira-connect-gitlab.com" could not be installed as a local app as it has previously been installed from Atlassian Marketplace +``` + +To resolve this issue, disable the **Jira Connect Proxy URL** setting. - In GitLab 15.7: @@ -258,7 +278,7 @@ You might get an error if you have installed the GitLab for Jira Cloud app from 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). - 1. Expand the **GitLab for Jira App** section. + 1. Expand **GitLab for Jira App**. 1. Clear the **Jira Connect Proxy URL** text box. 1. Select **Save changes**. @@ -282,6 +302,37 @@ To resolve this issue on GitLab self-managed, follow one of the solutions below, - If you [installed the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually): - In GitLab 14.9 and later: - - Contact the [Jira Software Cloud support](https://support.atlassian.com/jira-software-cloud/) and ask to trigger a new installed lifecycle event for the GitLab for Jira Cloud app in your namespace. + - Contact the [Jira Software Cloud support](https://support.atlassian.com/jira-software-cloud/) and ask to trigger a new installed lifecycle event for the GitLab for Jira Cloud app in your group. - In all GitLab versions: - - Re-install the GitLab for Jira Cloud app. This might remove all already synced development panel data. + - Re-install the GitLab for Jira Cloud app. This method might remove all synced data from the Jira development panel. + +### `Failed to update GitLab version` error when setting up the GitLab for Jira Cloud app for self-managed instances + +When you set up the GitLab for Jira Cloud app, you might get the following message after you enter your +self-managed instance URL: + +```plaintext +Failed to update GitLab version. Please try again. +``` + +To resolve this issue, ensure all prerequisites for your installation method have been met: + +- [Prerequisites for connecting the GitLab for Jira Cloud app](#prerequisites) +- [Prerequisites for installing the GitLab for Jira Cloud app manually](#prerequisites-1) + +If you're using GitLab 15.8 and earlier and have previously enabled both the `jira_connect_oauth_self_managed` +and the `jira_connect_oauth` feature flags, you must disable the `jira_connect_oauth_self_managed` flag +due to a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/388943). To check for these flags: + +1. Open a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session). +1. Execute the following code: + + ```ruby + # Check if both feature flags are enabled. + # If the flags are enabled, these commands return `true`. + Feature.enabled?(:jira_connect_oauth) + Feature.enabled?(:jira_connect_oauth_self_managed) + + # If both flags are enabled, disable the `jira_connect_oauth_self_managed` flag. + Feature.disable(:jira_connect_oauth_self_managed) + ``` diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index f36b9f2c4c1..009e620f121 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -1,102 +1,99 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Jira development panel integration **(FREE)** +# Jira development panel **(FREE)** > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/233149) from GitLab Premium to GitLab Free in 13.4. -With the Jira development panel integration, you can reference Jira issues in GitLab. -When configured, activity (such as pipeline, deployment, and feature flags) displays in the Jira issue's -[development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). -From the development panel, you can open a detailed view and -[take various actions](#use-the-integration), including creating a new merge request from a branch: +You can use the Jira development panel to view GitLab activity for a Jira issue directly in Jira. +To set up the Jira development panel: - +- **For Jira Cloud**, use the [GitLab for Jira Cloud app](connect-app.md) developed by GitLab. +- **For Jira Data Center or Jira Server**, use the [Jira DVCS connector](dvcs/index.md) developed by Atlassian. -The information displayed in the Jira development panel depends on where you mention the Jira issue ID: - -| Your mention of Jira issue ID in GitLab context | Automated effect in Jira issue | -|---------------------------------------------------|--------------------------------------------------------------------------------------------------------| -| In a merge request title or description | Link to the MR is displayed in the development panel. | -| In a branch name | Link to the branch is displayed in the development panel. | -| In a commit message | Link to the commit is displayed in the development panel. | -| In a commit message with Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) | Displays your custom comment or logged time spent and/or performs specified issue transition on merge. | - -This integration connects all GitLab projects to projects in the Jira instance in either: - -- A top-level GitLab group: Connects the projects in a group with no parent group, - including the projects in its subgroups. -- A personal namespace: Connects the projects in that personal namespace to Jira. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Jira development panel integration](https://www.youtube.com/watch?v=VjVTOmMl85M). -## Use the integration +## Feature availability -After the integration is [set up on GitLab and Jira](#configure-the-integration), you can: +This table shows the features available with the Jira DVCS connector and the GitLab for Jira Cloud app: -- Refer to any Jira issue by its ID (in uppercase) in GitLab branch names, - commit messages, and merge request titles. -- See the linked branches, commits, and merge requests in Jira issues. -- Create GitLab branches from Jira Cloud issues ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66032) in GitLab 14.2 for the GitLab for Jira app). +| Feature | Jira DVCS connector | GitLab for Jira Cloud app | +|---------------------|------------------------|---------------------------| +| Smart Commits | **{check-circle}** Yes | **{check-circle}** Yes | +| Sync merge requests | **{check-circle}** Yes | **{check-circle}** Yes | +| Sync branches | **{check-circle}** Yes | **{check-circle}** Yes | +| Sync commits | **{check-circle}** Yes | **{check-circle}** Yes | +| Sync existing data | **{check-circle}** Yes | **{check-circle}** Yes | +| Sync builds | **{dotted-circle}** No | **{check-circle}** Yes | +| Sync deployments | **{dotted-circle}** No | **{check-circle}** Yes | +| Sync feature flags | **{dotted-circle}** No | **{check-circle}** Yes | +| Sync interval | Up to 60 minutes | Real time | +| Create branches | **{dotted-circle}** No | **{check-circle}** Yes (GitLab SaaS only) | +| Create merge request from branch | **{check-circle}** Yes | **{check-circle}** Yes | +| Create branch from Jira issue | **{dotted-circle}** No | **{check-circle}** Yes ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66032) in GitLab 14.2) | -At this time, merge requests are called "pull requests" in Jira issues. -This name may change in a future Jira release. +## Connected projects in GitLab -Select the links to see your GitLab repository data. +The Jira development panel connects a Jira instance with all its projects to the following: - +- **For the [GitLab for Jira Cloud app](connect-app.md)**, linked GitLab groups or subgroups and their projects +- **For the [Jira DVCS connector](dvcs/index.md)**, linked GitLab groups, subgroups, or personal namespaces and their projects - +## Information displayed in the development panel -### Use Jira Smart Commits +You can [view GitLab activity for a Jira issue](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) +in the Jira development panel by referring to the Jira issue by ID in GitLab. The information displayed in the development panel +depends on where you mention the Jira issue ID in GitLab. -With Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html), -you can use GitLab to add Jira comments, log time spent on the issue, or apply any issue transition. +| GitLab: where you mention the Jira issue ID | Jira development panel: what information is displayed | +|------------------------------------------------|-------------------------------------------------------| +| Merge request title or description | Link to the merge request<br>Link to the branch ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354373) in GitLab 15.11) | +| Branch name | Link to the branch | +| Commit message | Link to the commit | +| [Jira Smart Commit](#jira-smart-commits) | Custom comment, logged time, or workflow transition | -For more information about using Jira Smart Commits to track time against an issue, specify -an issue transition, or add a custom comment, read the Atlassian page -[Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html). +## Jira Smart Commits -## Configure the integration +Prerequisites: -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview of how to configure the Jira development panel integration, see -[Agile Management - GitLab Jira development panel integration](https://www.youtube.com/watch?v=VjVTOmMl85M). +- You must have GitLab and Jira user accounts with the same email address or username. +- The commands must be in the first line of the commit message. +- The commit message must not span more than one line. -To simplify administration, we recommend that a GitLab group maintainer or group owner -(or, if possible, instance administrator in the case of self-managed GitLab) set up the integration. +Jira Smart Commits are special commands to process a Jira issue. With these commands, you can use GitLab to: -| Jira usage | GitLab.com customers need | GitLab self-managed customers need | -|------------|---------------------------|------------------------------------| -| [Atlassian cloud](https://www.atlassian.com/migration/assess/why-cloud) | The [GitLab for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) from the [Atlassian Marketplace](https://marketplace.atlassian.com). This method offers real-time sync between GitLab.com and Jira. The method requires inbound connections for the setup and then pushes data to Jira through outbound connections. For more information, see [GitLab for Jira Cloud app](connect-app.md). | The GitLab for Jira Cloud app [installed manually](connect-app.md#install-the-gitlab-for-jira-cloud-app-manually). By default, you can install the app from the [Atlassian Marketplace](https://marketplace.atlassian.com/). The method requires inbound connections for the setup and then pushes data to Jira through outbound connections. For more information, see [Connect the GitLab for Jira Cloud app for self-managed instances](connect-app.md#connect-the-gitlab-for-jira-cloud-app-for-self-managed-instances). | -| Your own server | The [Jira DVCS connector](dvcs/index.md). This method syncs data every hour and works only with inbound connections. The method tries to set up webhooks in GitLab to implement real-time data sync, which does not work without outbound connections. | The [Jira DVCS connector](dvcs/index.md). This method syncs data every hour and works only with inbound connections. The method tries to set up webhooks in GitLab to implement real-time data sync, which does not work without outbound connections. | +- Add a custom comment to a Jira issue. +- Log time against a Jira issue. +- Transition a Jira issue to any status defined in the project workflow. -Each GitLab project can be configured to connect to an entire Jira instance. That means after -configuration, one GitLab project can interact with all Jira projects in that instance. For: +Smart Commits must follow this syntax: -- 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. +```plaintext +<ISSUE_KEY> <ignored text> #<command> <optional command parameters> +``` -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). +You can execute one or more commands in a single commit. -## Limitations +### Smart Commit syntax -- This integration is not supported on GitLab instances under a -[relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configure-a-relative-url-for-gitlab) -(for example, `http://example.com/gitlab`). -- [Creating a branch](https://gitlab.com/gitlab-org/gitlab/-/issues/2647) is only supported by the GitLab for Jira app and is not available within the DVCS integration. See [officially supported DVCS features](https://confluence.atlassian.com/adminjiraserver/integrating-with-development-tools-938846890.html) for more information. +| Commands | Syntax | +|-------------------------------------------------|--------------------------------------------------------------| +| Add a comment | `KEY-123 #comment Bug is fixed` | +| Log time | `KEY-123 #time 2w 4d 10h 52m Tracking work time` | +| Close an issue | `KEY-123 #close Closing issue` | +| Log time and close an issue | `KEY-123 #time 2d 5h #close` | +| Add a comment and transition to **In-progress** | `KEY-123 #comment Started working on the issue #in-progress` | -## Troubleshoot the development panel +For more information about how Smart Commits work and what commands are available to use, see: -If you use Jira on your own server, go to the [Atlassian documentation](https://confluence.atlassian.com/jirakb/troubleshoot-the-development-panel-in-jira-server-574685212.html) -for general troubleshooting information. +- [Process issues with Smart Commits](https://support.atlassian.com/jira-software-cloud/docs/process-issues-with-smart-commits/) +- [Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) -### Cookies for Oracle's Access Manager +## Troubleshooting -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 troubleshoot the Jira development panel on your own server, see the +[Atlassian documentation](https://confluence.atlassian.com/jirakb/troubleshoot-the-development-panel-in-jira-server-574685212.html). diff --git a/doc/integration/jira/dvcs/index.md b/doc/integration/jira/dvcs/index.md index e07f0e579b2..0406fef3f1e 100644 --- a/doc/integration/jira/dvcs/index.md +++ b/doc/integration/jira/dvcs/index.md @@ -1,179 +1,77 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira DVCS connector **(FREE)** -Use the Jira DVCS (distributed version control system) connector if you self-host -your Jira instance, and you want to sync information -between GitLab and Jira. If you use Jira Cloud, you should use the -[GitLab for Jira Cloud 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 Server**: Your network must allow access to your instance. -- **Jira Cloud**: Your instance must be accessible through the internet. - -NOTE: -When using GitLab 15.0 and later (including GitLab.com) with Jira Server, you might experience a [session token bug in Jira](https://jira.atlassian.com/browse/JSWSERVER-21389). As a workaround, ensure Jira Server is version 9.1.0 and later or 8.20.11 and later. - -## 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: +WARNING: +The Jira DVCS connector for Jira Cloud was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/362168) in GitLab 15.1 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118126) in 16.0. Use the [GitLab for Jira Cloud app](../connect-app.md) instead. +The Jira DVCS connector was also deprecated and removed for Jira 8.13 and earlier. You can only use the Jira DVCS connector with Jira Data Center or Jira Server in Jira 8.14 and later. Upgrade your Jira instance to Jira 8.14 or later, and reconfigure the Jira integration in your GitLab instance. -- 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. - -### Smart Commit syntax - -Smart Commits should follow the pattern of: +Use the Jira DVCS (distributed version control system) connector if you self-host +your Jira instance with Jira Data Center or Jira Server and want to use the [Jira development panel](../development_panel.md). -```plaintext -<ISSUE_KEY> <ignored text> #<command> <optional command parameters> -``` +If you're on Jira Cloud, migrate to the GitLab for Jira Cloud app. For more information, see [Install the GitLab for Jira Cloud app](../connect-app.md#install-the-gitlab-for-jira-cloud-app). -Some examples: +## Configure the Jira DVCS connector -- Add a comment to a Jira issue: `KEY-123 fixes a bug #comment Bug is fixed.` -- Record time tracking: `KEY-123 #time 2w 4d 10h 52m Tracking work time.` -- Close an issue: `KEY-123 #close Closing issue` +### Prerequisites -A Smart Commit message must not span more than one line (no carriage returns) but -you can still perform multiple actions in a single commit. For example: +- Your GitLab instance must be accessible by Jira. +- You must have at least the Maintainer role for the GitLab group. +- Your network must allow inbound and outbound connections between GitLab and Jira. -- Add time tracking, add a comment, and transition to **Closed**: +### Create a GitLab application for DVCS - ```plaintext - KEY-123 #time 2d 5h #comment Task completed ahead of schedule #close - ``` +- **For projects in a single group**, you should create a [group application](../../oauth_provider.md#create-a-group-owned-application). +- **For projects across multiple groups**, you should create a separate GitLab user account for Jira integration work only. + This account ensures regular maintenance does not affect your integration. +- **If you cannot create a group application or separate user account**, you can create instead: + - [An instance-wide application](../../oauth_provider.md#create-an-instance-wide-application) + - [A user-owned application](../../oauth_provider.md#create-a-user-owned-application) -- Add a comment, transition to **In-progress**, and add time tracking: +To create a GitLab application for DVCS: - ```plaintext - KEY-123 #comment started working on the issue #in-progress #time 12d 5h - ``` +1. Go to the [appropriate **Applications** section](../../oauth_provider.md). +1. In the **Name** text box, enter a descriptive name for the integration (for example, `Jira`). +1. In the **Redirect URI** text box, enter the generated **Redirect URL** from + [linking GitLab accounts](https://confluence.atlassian.com/adminjiraserver/linking-gitlab-accounts-1027142272.html). +1. In **Scopes**, select `api` and clear any other checkboxes. + The Jira DVCS connector requires a **write-enabled** `api` scope to automatically create and manage required webhooks. +1. Select **Submit**. +1. Copy the **Application ID** and **Secret** values. + You need these values to configure Jira. -## Configure a GitLab application for DVCS +### Configure Jira for DVCS -For projects in a single group we recommend you create a [group application](../../oauth_provider.md#create-a-group-owned-application). -For projects across multiple groups 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. If a `jira` user or group application is not feasible, -you can set up this integration as an [instance-wide application](../../oauth_provider.md#create-an-instance-wide-application) -or with a [user owned application](../../oauth_provider.md#create-a-user-owned-application) instead. +To configure Jira for DVCS: -1. Navigate to the [appropriate **Applications** section](../../oauth_provider.md). -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 13.0 and later* **and** *Jira versions 8.14 and later,* use the - generated `Redirect URL` from - [Linking GitLab accounts with Jira](https://confluence.atlassian.com/adminjiraserver/linking-gitlab-accounts-1027142272.html). - - *For GitLab versions 13.0 and later* **and** *Jira Cloud,* use `https://<gitlab.example.com>/login/oauth/callback`. - - *For GitLab versions 11.3 and later* **and** *Jira versions 8.13 and earlier,* 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. Go to your DVCS account. **For Jira Server**, select **Settings (gear) > Applications > DVCS accounts**. +1. To create a new integration, for **Host**, select **GitLab** or **GitLab Self-Managed**. +1. For **Team or User Account**, enter the relative path of a top-level GitLab group that [the GitLab user](#create-a-gitlab-application-for-dvcs) can access. +1. In the **Host URL** text box, enter the appropriate URL. + Replace `<gitlab.example.com>` with your GitLab instance domain. + Use `https://<gitlab.example.com>`. +1. For **Client ID**, use the [**Application ID** value](#create-a-gitlab-application-for-dvcs). +1. For **Client Secret**, use the [**Secret** value](#create-a-gitlab-application-for-dvcs). +1. Ensure that all other checkboxes are selected. +1. To create the DVCS account, select **Add**, then **Continue**. -1. For **Scopes**, select `api` and clear any other checkboxes. - - The DVCS connector requires a _write-enabled_ `api` scope to automatically create and manage required webhooks. -1. Select **Submit**. -1. Copy the **Application ID** and **Secret** values. - You need them to configure Jira. - -## Configure Jira for DVCS - -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. Complete the [GitLab configuration](#configure-a-gitlab-application-for-dvcs). -1. Go to your DVCS accounts: - - *For Jira Server,* select **Settings (gear) > Applications > DVCS accounts**. - - *For Jira Cloud,* select **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 - **GitLab Self-Managed**. - - *For Jira Cloud or Jira versions 8.13 and earlier:* Select **GitHub Enterprise**. -1. For **Team or User Account**, enter either: - - *For Jira versions 8.14 and later:* - - The relative path of a top-level GitLab group that - [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to. - - *For Jira Cloud or Jira versions 8.13 and earlier:* - - The relative path of a top-level GitLab group that - [the GitLab user](#configure-a-gitlab-application-for-dvcs) has 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 selected. -1. To create the DVCS account, select **Add** and then **Continue**. -1. Jira redirects to GitLab where you have to confirm the authorization. - GitLab then redirects back to Jira where the synced - projects should display in the new account. +Jira redirects to GitLab where you have to confirm the authorization. GitLab then redirects back to Jira +where the synced projects are displayed in the new account. The initial sync takes a few minutes. +After the initial sync, it can take up to 60 minutes to refresh. 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). - ## 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: +Jira imports commits and branches for GitLab projects every 60 minutes. To refresh the data manually in Jira: 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. - -## Migrate to the GitLab for Jira Cloud app - -If you are using DVCS with Jira Cloud, you should consider migrating to the GitLab for Jira app. -[DVCS for Jira Cloud will be deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/362168) in GitLab 16.0. - -To get started using the GitLab for Jira Cloud app, follow the guide [Install the GitLab for Jira Cloud app](../connect-app.md#install-the-gitlab-for-jira-cloud-app) . - -### Feature comparison of DVCS and GitLab for Jira Cloud app - -| Feature | DVCS (Jira Cloud) | GitLab for Jira Cloud app | -|--------------------|--------------------|---------------------------------------| -| Smart Commits | **{check-circle}** Yes | **{check-circle}** Yes | -| Sync MRs | **{check-circle}** Yes | **{check-circle}** Yes | -| Sync branches | **{check-circle}** Yes | **{check-circle}** Yes | -| Sync commits | **{check-circle}** Yes | **{check-circle}** Yes| -| Sync builds | **{dotted-circle}** No | **{check-circle}** Yes | -| Sync deployments | **{dotted-circle}** No | **{check-circle}** Yes | -| Sync feature flags | **{dotted-circle}** No | **{check-circle}** Yes | -| Sync interval | 60 Minutes | Real time | -| Create branches | **{dotted-circle}** No | **{check-circle}** Yes (Only GitLab SaaS) | -| Historic data sync | **{check-circle}** Yes | **{dotted-circle}** No | - -### Risks of migrating - -The GitLab for Jira Cloud app has a limited ability to sync historic data. -Only branches, commits, builds, deployments, and feature flags created after installing the GitLab for Jira Cloud app are synced with Jira. +1. In the **Last activity** column, next to the repository you want to refresh, select **Refresh** (**{retry}**). diff --git a/doc/integration/jira/dvcs/troubleshooting.md b/doc/integration/jira/dvcs/troubleshooting.md index e40c188c1c3..541c743b609 100644 --- a/doc/integration/jira/dvcs/troubleshooting.md +++ b/doc/integration/jira/dvcs/troubleshooting.md @@ -1,12 +1,12 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Jira DVCS connector **(FREE)** -Refer to the items in this section if you're having problems with your DVCS connector. +Refer to the items in this section if you're having problems with your Jira DVCS connector. ## Jira cannot access GitLab server @@ -18,6 +18,12 @@ appear in any logs: Error obtaining access token. Cannot access https://gitlab.example.com from Jira. ``` +## Session token bug in Jira + +When using GitLab 15.0 and later (including GitLab.com) with Jira Server, you might experience +a [session token bug in Jira](https://jira.atlassian.com/browse/JSWSERVER-21389). As a workaround, +ensure Jira Server is version 9.1.0 and later or 8.20.11 and later. + ## SSL and TLS problems Problems with SSL and TLS can cause this error message: @@ -26,12 +32,12 @@ Problems with SSL and TLS can cause this error message: Error obtaining access token. Cannot access https://gitlab.example.com from Jira. ``` -- The [GitLab Jira integration](../index.md) requires +- The [Jira integration](../index.md) requires GitLab to connect to Jira. Any TLS issues that arise from a private certificate authority or self-signed certificate are resolved - [on the GitLab server](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates), + [on the GitLab server](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates), as GitLab is the TLS client. -- The Jira Development panel integration requires Jira to connect to GitLab, which +- The Jira development panel 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, add the appropriate certificate (such as your organization's root certificate) to the Java Truststore on Jira Server. @@ -74,7 +80,7 @@ Potential resolutions: [Jira DVCS connector setup](index.md#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](index.md#configure-a-gitlab-application-for-dvcs). Review + [GitLab account configuration](index.md#create-a-gitlab-application-for-dvcs). Review the **Scopes** field and ensure the `api` checkbox is selected. ## Jira error adding account and no repositories listed @@ -119,7 +125,7 @@ For more information, see the ## `Sync Failed` error when refreshing repository data -If you get a `Sync Failed` error in Jira when [refreshing repository data](index.md#refresh-data-imported-to-jira) for specific projects, check your DVCS connector logs. Look for errors that occur when executing requests to API resources in GitLab. For example: +If you get a `Sync Failed` error in Jira when [refreshing repository data](index.md#refresh-data-imported-to-jira) for specific projects, check your Jira DVCS connector logs. Look for errors that occur when executing requests to API resources in GitLab. For example: ```plaintext Failed to execute request [https://gitlab.com/api/v4/projects/:id/merge_requests?page=1&per_page=100 GET https://gitlab.com/api/v4/projects/:id/merge_requests?page=1&per_page=100 returned a response status of 403 Forbidden] errors: 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 differdeleted file mode 100644 index c0d4c9744b6..00000000000 --- a/doc/integration/jira/img/jira-upload-app-success_v13_11.png +++ /dev/null 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 differdeleted file mode 100644 index 88d1573f778..00000000000 --- a/doc/integration/jira/img/jira-upload-app_v13_11.png +++ /dev/null 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 differdeleted file mode 100644 index f5120a8d42e..00000000000 --- a/doc/integration/jira/img/jira_added_user_to_group.png +++ /dev/null diff --git a/doc/integration/jira/img/jira_create_new_group.png b/doc/integration/jira/img/jira_create_new_group.png Binary files differdeleted file mode 100644 index 4ab7a5eae4e..00000000000 --- a/doc/integration/jira/img/jira_create_new_group.png +++ /dev/null diff --git a/doc/integration/jira/img/jira_dev_panel_jira_setup_3.png b/doc/integration/jira/img/jira_dev_panel_jira_setup_3.png Binary files differdeleted file mode 100644 index c58f1d5cecc..00000000000 --- a/doc/integration/jira/img/jira_dev_panel_jira_setup_3.png +++ /dev/null diff --git a/doc/integration/jira/img/jira_dev_panel_jira_setup_4.png b/doc/integration/jira/img/jira_dev_panel_jira_setup_4.png Binary files differdeleted file mode 100644 index 81d84cb173d..00000000000 --- a/doc/integration/jira/img/jira_dev_panel_jira_setup_4.png +++ /dev/null diff --git a/doc/integration/jira/img/jira_dev_panel_jira_setup_5.png b/doc/integration/jira/img/jira_dev_panel_jira_setup_5.png Binary files differdeleted file mode 100644 index b143fc24355..00000000000 --- a/doc/integration/jira/img/jira_dev_panel_jira_setup_5.png +++ /dev/null diff --git a/doc/integration/jira/img/jira_dev_panel_setup_com_1.png b/doc/integration/jira/img/jira_dev_panel_setup_com_1.png Binary files differdeleted file mode 100644 index 18f0d5da043..00000000000 --- a/doc/integration/jira/img/jira_dev_panel_setup_com_1.png +++ /dev/null diff --git a/doc/integration/jira/img/jira_dev_panel_setup_com_2.png b/doc/integration/jira/img/jira_dev_panel_setup_com_2.png Binary files differdeleted file mode 100644 index 31dc13e1271..00000000000 --- a/doc/integration/jira/img/jira_dev_panel_setup_com_2.png +++ /dev/null diff --git a/doc/integration/jira/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 differdeleted file mode 100644 index fe791637d31..00000000000 --- a/doc/integration/jira/img/jira_dev_panel_setup_com_3_v13_9.png +++ /dev/null diff --git a/doc/integration/jira/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 differdeleted file mode 100644 index 08787f12b67..00000000000 --- a/doc/integration/jira/img/jira_dev_panel_setup_com_4_v13_9.png +++ /dev/null diff --git a/doc/integration/jira/img/jira_group_access.png b/doc/integration/jira/img/jira_group_access.png Binary files differdeleted file mode 100644 index 42a9b4ae564..00000000000 --- a/doc/integration/jira/img/jira_group_access.png +++ /dev/null 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 differdeleted file mode 100644 index bf1607a35fe..00000000000 --- a/doc/integration/jira/img/jira_issue_detail_view_v13.10.png +++ /dev/null diff --git a/doc/integration/jira/img/jira_issue_reference.png b/doc/integration/jira/img/jira_issue_reference.png Binary files differdeleted file mode 100644 index db8bc4f0bb9..00000000000 --- a/doc/integration/jira/img/jira_issue_reference.png +++ /dev/null diff --git a/doc/integration/jira/img/jira_project_settings.png b/doc/integration/jira/img/jira_project_settings.png Binary files differdeleted file mode 100644 index d96002b7db8..00000000000 --- a/doc/integration/jira/img/jira_project_settings.png +++ /dev/null diff --git a/doc/integration/jira/img/jira_service_close_issue.png b/doc/integration/jira/img/jira_service_close_issue.png Binary files differdeleted file mode 100644 index 73d6498192c..00000000000 --- a/doc/integration/jira/img/jira_service_close_issue.png +++ /dev/null diff --git a/doc/integration/jira/img/open_jira_issues_list_v14_6.png b/doc/integration/jira/img/open_jira_issues_list_v14_6.png Binary files differdeleted file mode 100644 index 6f06b7fec9a..00000000000 --- a/doc/integration/jira/img/open_jira_issues_list_v14_6.png +++ /dev/null diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md index 2ad71a19cf7..2b6395f437b 100644 --- a/doc/integration/jira/index.md +++ b/doc/integration/jira/index.md @@ -1,70 +1,52 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Jira integrations **(FREE)** +# Jira **(FREE)** -If your organization uses [Jira](https://www.atlassian.com/software/jira) issues, -you can [migrate your issues from Jira](../../user/project/import/jira.md) 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. We recommend you enable both. +If your organization uses [Jira](https://www.atlassian.com/software/jira), +you can [migrate your issues from Jira to GitLab](../../user/project/import/jira.md). +If you want to continue to use Jira, you can integrate Jira with GitLab instead. -## Compare integrations +## 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. +GitLab offers two types of Jira integrations. You can use one or both integrations +[depending on the capabilities you need](#jira-integration-capabilities). -### Jira integration +### Jira issue integration -This integration connects one or more GitLab projects to a Jira instance. You can host -the Jira instance yourself or in [Atlassian Cloud](https://www.atlassian.com/migration/assess/why-cloud). -The supported Jira versions are `6.x`, `7.x`, `8.x`, and `9.x`. +You can use the [Jira issue integration](configure.md) developed by GitLab with Jira Cloud, Jira Data Center, or Jira Server. With this integration, you can: -<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). +- View and search Jira issues directly in GitLab. +- Refer to Jira issues by ID in GitLab commits and merge requests. +- Create Jira issues for vulnerabilities. -To set up the integration, [configure the settings](configure.md) in GitLab. +### Jira development panel -### Jira development panel integration +You can use the [Jira development panel](development_panel.md) to [view GitLab activity for an issue](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) +including related branches, commits, and merge requests. To configure the Jira development panel: -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/). +- **For Jira Cloud**, use the [GitLab for Jira Cloud app](connect-app.md) developed by GitLab. +- **For Jira Data Center or Jira Server**, use the [Jira DVCS connector](dvcs/index.md) developed by Atlassian. -To set up the Jira development panel integration, use the GitLab for Jira Cloud app -or the Jira DVCS (distributed version control system) connector, -[depending on your installation](development_panel.md#configure-the-integration). +## Jira integration capabilities -### Direct feature comparison +This table shows the capabilities available with the Jira issue integration and the Jira development panel: -| Capability | Jira integration | Jira development panel integration | +| Capability | Jira issue integration | Jira development panel | |-|-|-| -| 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](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). | -| 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](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) 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](issues.md#view-jira-issues). | Yes. | No. | -| Create a Jira issue from a [vulnerability or finding](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability). | Yes. | No. | -| Create a GitLab branch from a Jira issue. | No. | Yes, in the issue's [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). | -| Mention a Jira issue ID in a GitLab merge request, and deployments are synced. | No. | Yes, in the issue's [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). | - -## Authentication in Jira - -The authentication method in Jira depends on whether you host Jira on your own server or on -[Atlassian cloud](https://www.atlassian.com/migration/assess/why-cloud): - -- **Jira Server** supports basic authentication. When connecting, a **username and password** are - required. Connecting to Jira Server using the Central Authentication Service (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 - [create an API token for Jira in Atlassian cloud](jira_cloud_configuration.md). +| Mention a Jira issue ID in a GitLab commit or merge request, and a link to the Jira issue is created | **{check-circle}** Yes | **{dotted-circle}** No | +| Mention a Jira issue ID in GitLab, and the Jira issue shows the GitLab issue or merge request | **{check-circle}** Yes, a Jira comment with the GitLab issue or merge request title links to GitLab. The first mention is also added to the Jira issue under **Web links** | **{check-circle}** Yes, in the issue's [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) | +| Mention a Jira issue ID in a GitLab commit message, and the Jira issue shows the commit message | **{check-circle}** 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 | **{check-circle}** Yes, in the issue's development panel and optionally with a custom comment on the Jira issue by 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 | **{dotted-circle}** No | **{check-circle}** Yes, in the issue's development panel | +| Add time tracking to a Jira issue | **{dotted-circle}** No | **{check-circle}** Yes, time can be specified by using Jira Smart Commits | +| Use a Git commit or merge request to transition or close a Jira issue |**{check-circle}** Yes, only a single transition type. Typically configured to close the issue by setting it to **Done** | **{check-circle}** Yes, transition to any state by using Jira Smart Commits | +| [View a list of Jira issues](issues.md#view-jira-issues) | **{check-circle}** Yes | **{dotted-circle}** No | +| [Create a Jira issue for a vulnerability](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability) | **{check-circle}** Yes | **{dotted-circle}** No | +| Create a GitLab branch from a Jira issue | **{dotted-circle}** No | **{check-circle}** Yes, in the issue's development panel | +| Mention a Jira issue ID in a GitLab merge request, and deployments are synced | **{dotted-circle}** No | **{check-circle}** Yes, in the issue's development panel | ## Privacy considerations @@ -72,8 +54,8 @@ All Jira integrations share data with Jira to make it visible outside of GitLab. If you integrate a private GitLab project with Jira, the private data is shared with users who have access to your Jira project. -The [**Jira project integration**](#jira-integration) posts GitLab data in the form of comments in Jira issues. -The GitLab for Jira Cloud app and Jira DVCS connector share this data through the [**Jira Development Panel**](development_panel.md). +The [Jira issue integration](configure.md) posts GitLab data in the form of comments in Jira issues. +The GitLab for Jira Cloud app and Jira DVCS connector share this data through the [Jira development panel](development_panel.md). This method provides more fine-grained access control because access can be restricted to certain user groups or roles. ## Third-party Jira integrations diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md index 3a5d8e66b2d..086d478ac15 100644 --- a/doc/integration/jira/issues.md +++ b/doc/integration/jira/issues.md @@ -1,58 +1,59 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Jira integration issue management **(FREE)** +# Jira issue management **(FREE)** -Integrating issue management with Jira requires you to [configure Jira](index.md#jira-integration) -and [enable the Jira integration](configure.md) in GitLab. -After you configure and enable the integration, you can reference and close Jira -issues by mentioning the Jira ID in GitLab commits and merge requests. +You can [manage Jira issues directly in GitLab](configure.md). +You can then refer to Jira issues by ID in GitLab commits and merge requests. +The Jira issue IDs must be in uppercase. -The Jira integration requires to you format any Jira issue IDs in uppercase. - -## Reference Jira issues +## Cross-reference GitLab activity and Jira issues With this integration, you can cross-reference Jira issues while you work in -GitLab issues and merge requests. Mention a Jira issue in a GitLab issue, -merge request, or comment, and GitLab adds a formatted comment to the Jira issue. -The comment links back to your work in GitLab. +GitLab issues, merge requests, and Git. +When you mention a Jira issue in a GitLab issue, merge request, comment, or commit: + +- GitLab links to the Jira issue from the mention in GitLab. +- GitLab adds a formatted comment to the Jira issue that links back to the issue, merge request, or commit in GitLab. -For example, this commit references the Jira issue `GIT-1`: +For example, when this commit refers to a `GIT-1` Jira issue: ```shell git commit -m "GIT-1 this is a test commit" ``` -GitLab adds a reference to the **Issue Links** section of Jira issue `GIT-1`: +GitLab adds to that Jira issue: - +- A reference in the **Web links** section +- A comment in the **Activity** section that follows this format: -GitLab also adds a comment to the issue, and uses this format: + ```plaintext + USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|COMMENTLINK]: + ENTITY_TITLE + ``` -```plaintext -USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|COMMENTLINK]: -ENTITY_TITLE -``` + - `USER`: Name of the user who has mentioned the Jira issue with a link to their GitLab user profile. + - `RESOURCE_NAME`: Type of resource (for example, a GitLab commit, issue, or merge request) that has referenced the Jira issue. + - `PROJECT_NAME`: GitLab project name. + - `COMMENTLINK`: Link to where the Jira issue is mentioned. + - `ENTITY_TITLE`: Title of the GitLab commit (first line), issue, or merge request. -- `USER`: The name of the user who mentioned the issue, linked to their GitLab user profile. -- `COMMENTLINK`: A link to where the Jira issue was mentioned. -- `RESOURCE_NAME`: The type of resource, such as a commit or merge request, which referenced the issue. -- `PROJECT_NAME`: The GitLab project name. -- `ENTITY_TITLE`: The title of the merge request, or the first line of the commit. +Only a single cross-reference comment appears in Jira per GitLab issue, merge request, or commit. +For example, multiple comments on a GitLab merge request that reference a Jira issue +create only a single cross-reference comment back to that merge request in Jira. You can [disable comments](#disable-comments-on-jira-issues) on issues. ### Require associated Jira issue for merge requests to be merged **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280766) in GitLab 13.12, disabled behind `jira_issue_association_on_merge_request` [feature flag](../../administration/feature_flags.md). -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61722) in GitLab 14.1. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/335280) in GitLab 14.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280766) in GitLab 13.12 [with a flag](../../administration/feature_flags.md) named `jira_issue_association_on_merge_request`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/335280) in GitLab 14.2. Feature flag `jira_issue_association_on_merge_request` removed. -You can prevent merge requests from being merged if they do not refer to a Jira issue. -To enforce this: +With this integration, you can prevent merge requests from being merged if they do not refer to a Jira issue. +To enable this feature: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Merge requests**. @@ -63,6 +64,41 @@ After you enable this feature, a merge request that doesn't reference an associa Jira issue can't be merged. The merge request displays the message **To merge, a Jira issue key must be mentioned in the title or description.** +## Customize Jira issue matching in GitLab + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112826) in GitLab 15.10. + +You can configure custom rules for how GitLab matches Jira issue keys by defining: + +- [A regex pattern](#use-regular-expression) +- [A prefix](#use-a-prefix) + +When you don't configure custom rules, the [default behavior](https://gitlab.com/gitlab-org/gitlab/-/blob/710d83af298d8896f2b940faf48a46d2feb4cbaf/lib/gitlab/regex.rb#L552) is used. For more information, see the [RE2 wiki](https://github.com/google/re2/wiki/Syntax). + +### Use regular expression + +To define a regex pattern for Jira issue keys: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Jira**. +1. Go to the **Jira issue matching** section. +1. In the **Jira issue regex** text box, enter a regex pattern. +1. Select **Save changes**. + +For more information, see the [Atlassian documentation](https://confluence.atlassian.com/adminjiraserver073/changing-the-project-key-format-861253229.html). + +### Use a prefix + +To define a prefix for Jira issue keys: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Jira**. +1. Go to the **Jira issue matching** section. +1. In the **Jira issue prefix** text box, enter a prefix. +1. Select **Save changes**. + ## Close Jira issues in GitLab If you have configured GitLab transition IDs, you can close a Jira issue directly @@ -79,7 +115,7 @@ For example, use any of these trigger words to close the Jira issue `PROJECT-1`: - `Fixes PROJECT-1` The commit or merge request must target your project's [default branch](../../user/project/repository/branches/default.md). -You can change your project's default branch under [project settings](img/jira_project_settings.png). +You can change your project's default branch in [project settings](../../user/project/settings/index.md). ### Use case for closing issues @@ -89,8 +125,7 @@ Consider this example: 1. You create a merge request in GitLab to build the requested feature. 1. In the merge request, you add the issue closing trigger `Closes PROJECT-7`. 1. When the merge request is merged: - - GitLab closes the Jira issue for you: -  + - GitLab closes the Jira issue for you. - GitLab adds a formatted comment to Jira, linking back to the commit that resolved the issue. You can [disable comments](#disable-comments-on-jira-issues). @@ -98,19 +133,19 @@ Consider this example: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in GitLab 13.2. -You can browse, search, and view issues from a selected Jira project directly in GitLab, -if your GitLab administrator [has configured it](configure.md). +You can view and search issues from a selected Jira project directly in GitLab, +provided your GitLab administrator [has configured the integration](configure.md#configure-the-integration). -To do this, in GitLab, go to your project and select **Issues > Jira issues**. The issue list -sorts by **Created date** by default, with the newest issues listed at the top: +To view Jira issues: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues > Jira issues**. - +The issues are sorted by **Created date** by default, with the most recently created issues listed at the top. - To display the most recently updated issues first, select **Updated date**. -- You can [search and filter](#search-and-filter-the-issues-list) the issues list. -- In GitLab [versions 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/299832), - you can select an issue from the list to view it in GitLab: -  +- You can [search and filter the issue list](#search-and-filter-the-issue-list). +- In GitLab 13.10 and later, you can [select an issue from the list to view the issue in GitLab](https://gitlab.com/gitlab-org/gitlab/-/issues/299832). Issues are grouped into tabs based on their [Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html): @@ -119,7 +154,7 @@ Issues are grouped into tabs based on their - **Closed** tab: All issues with a Jira status categorized as Done. - **All** tab: All issues of any status. -### Search and filter the issues list **(PREMIUM)** +### Search and filter the issue list **(PREMIUM)** To refine the list of issues, use the search bar to search for any text contained in an issue summary (title) or description. Use any combination diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md index 9d52368f528..83321df0420 100644 --- a/doc/integration/jira/jira_cloud_configuration.md +++ b/doc/integration/jira/jira_cloud_configuration.md @@ -1,23 +1,11 @@ --- -stage: Manage -group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'configure.md#create-a-jira-cloud-api-token' +remove_date: '2023-07-07' --- -# Create a Jira Cloud API token **(FREE)** +This document was moved to [another location](configure.md#create-a-jira-cloud-api-token). -You need an API token to [integrate with Jira](index.md) -in Atlassian Cloud. To create the API token: - -1. Sign in to [Atlassian](https://id.atlassian.com/manage-profile/security/api-tokens) - using an account with *write* access to Jira projects. - - The link opens the API tokens page. Alternatively, to go to this page from your Atlassian - profile, select **Account Settings > Security > Create and manage API tokens**. -1. Select **Create API token**. -1. In the dialog, enter a label for your token and select **Create**. -1. To copy the API token, select **Copy**, then paste the token somewhere safe. - -You need the newly created token, and the email -address you used when you created it, when you -[configure GitLab](configure.md). +<!-- This redirect file can be deleted after <2023-07-07>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index 7dee99b024e..c840e1ebde5 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -1,87 +1,75 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira Server credentials **(FREE)** -To [integrate Jira with GitLab](index.md), you must -create a Jira user account for your Jira projects to access projects in GitLab. -This Jira user account must have write access to your Jira projects. To create the -credentials, you must: +To [integrate Jira with GitLab](configure.md), you should create a separate 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: 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). +1. [Create a Jira Server group for the user](#create-a-jira-server-group-for-the-user). +1. [Create a permission scheme for the group](#create-a-permission-scheme-for-the-group). + +Alternatively, you can use an existing Jira user account, provided the user belongs to a Jira group that +has been granted the **Administer Projects** [permission scheme](#create-a-permission-scheme-for-the-group). + +After you select a Jira user account, [configure the integration](configure.md#configure-the-integration) in GitLab to use the account. ## Create a Jira Server user -This process creates a user named `gitlab`: +To create a Jira Server user: 1. Sign in to your Jira instance as a Jira administrator. -1. In the upper right corner of the top menu, go to the gear icon and +1. On the top bar, in the upper-right corner, select the gear icon, then select **User Management**. -1. Create a new user account (`gitlab`) with write access to +1. [Create a new user account manually](https://confluence.atlassian.com/adminjiraserver/create-edit-or-remove-a-user-938847025.html#Create,edit,orremoveauser-CreateusersmanuallyinJira) with write access to projects in Jira. - - **Email address**: Jira requires a valid email address, and sends a verification - email, which is required 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, go to the user profile, look up - the username, and set a password. + - **Email address**: You should use a valid email address. + - **Username**: Set the username to `gitlab`. + - **Password**: You must set a password because the Jira issue integration does not + support SSO such as SAML. 1. Select **Create user**. -After you create the user, create a group for it. +Now that you've created a user named `gitlab`, it's time to create a group for the user. -## Create a Jira Server group +## Create a Jira Server group for the user -After you [create a Jira Server user](#create-a-jira-server-user), create a -group to assign permissions to the user. - -This process adds the `gitlab` user you created to a new group named `gitlab-developers`: +To create a Jira Server group for the user: 1. Sign in to your Jira instance as a Jira administrator. -1. In the upper right corner of the top menu, go to the gear icon and +1. On the top bar, in the upper-right corner, select the gear icon, then select **User Management**. -1. On the sidebar, select **Groups**. - -  - +1. On the left sidebar, select **Groups**. 1. In the **Add group** section, enter a **Name** for the group (for example, - `gitlab-developers`), and then select **Add group**. + `gitlab-developers`), 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. + The `gitlab-developers` group appears as a selected group. <!-- vale gitlab.BadPlurals = NO --> 1. In the **Add members to selected group(s)** section, enter `gitlab`. 1. Select **Add selected users**. - The `gitlab` user appears in the **Group member(s)** - section. + The `gitlab` user appears as a group member. <!-- vale gitlab.BadPlurals = YES --> -  - -Next, create a permission scheme for your group. +Now that you've added the `gitlab` user to a new group named `gitlab-developers`, +it's time to create a permission scheme for the group. -## Create a permission scheme for your group +## Create a permission scheme for the group -After creating the group in Jira, grant permissions to the group by creating a permission scheme: +To create a permission scheme for the group: 1. Sign in to your Jira instance as a Jira administrator. -1. In the upper right corner of the top menu, go to the gear icon and +1. On the top bar, in the upper-right corner, select the gear icon, then select **Issues**. -1. On the sidebar, select **Permission Schemes**. +1. On the left sidebar, select **Permission Schemes**. 1. Select **Add Permission Scheme**, enter a **Name** and (optionally) a - **Description**, and then select **Add**. + **Description**, then select **Add**. 1. In the permissions scheme list, locate your new permissions scheme, and select **Permissions**. 1. Next to **Administer Projects**, select **Edit**. -1. From the **Group** dropdown list, select `gitlab-developers`, and then select **Grant**. - -  +1. From the **Group** dropdown list, select `gitlab-developers`, then select **Grant**. -Write down the new Jira username and its -password, as you need them when -[configuring GitLab](configure.md). +You need the new Jira username and password when you [configure the integration](configure.md#configure-the-integration) in GitLab. diff --git a/doc/integration/jira/troubleshooting.md b/doc/integration/jira/troubleshooting.md index 0e679693614..586f09be751 100644 --- a/doc/integration/jira/troubleshooting.md +++ b/doc/integration/jira/troubleshooting.md @@ -1,17 +1,17 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Troubleshooting Jira integrations **(FREE)** +# Troubleshooting Jira **(FREE)** This page contains a list of common issues you might encounter when working with Jira integrations. ## GitLab cannot comment on a Jira issue If GitLab cannot comment on Jira issues, make sure the Jira user you -set up for the integration has permission to: +set up for the [Jira integration](configure.md) has permission to: - Post comments on a Jira issue. - Transition the Jira issue. @@ -91,16 +91,16 @@ To reset the Jira user's password for all projects with active Jira integrations run the following in a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session): ```ruby -p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN services s ON p.id = s.project_id WHERE s.type = 'JiraService' AND s.active = true") +p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN integrations i ON p.id = i.project_id WHERE i.type_new = 'Integrations::Jira' AND i.active = true") p.each do |project| project.jira_integration.update_attribute(:password, '<your-new-password>') end ``` -## `500 Whoops` when accessing a Jira issue in GitLab +## `500 We're sorry` when accessing a Jira issue in GitLab -When accessing a Jira issue in GitLab, you might get a `500 Whoops, something went wrong on our end` error. +When accessing a Jira issue in GitLab, you might get a `500 We're sorry. Something went wrong on our end` error. Check [`production.log`](../../administration/logs/index.md#productionlog) to see if it contains the following exception: ```plaintext |
