diff options
Diffstat (limited to 'doc/integration/jira/connect-app.md')
| -rw-r--r-- | doc/integration/jira/connect-app.md | 227 |
1 files changed, 122 insertions, 105 deletions
diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index 8bbac021849..fa7d48ba44d 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -6,64 +6,47 @@ info: To determine the technical writer assigned to the Stage/Group associated w # 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. - -Only Jira users with administrator access can install or configure -the GitLab for Jira Cloud app. - -## Install the GitLab for Jira Cloud app **(FREE SAAS)** +With the [GitLab for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app, +you can integrate GitLab and Jira Cloud. 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. - -To configure the GitLab for Jira Cloud app, you must have -at least the Maintainer role in the GitLab.com namespace. +If you do not use both of these environments, use the [Jira DVCS Connector](dvcs/index.md) instead +or [install the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually). +You should use the GitLab for Jira Cloud app because data is synchronized +in real time. The Jira DVCS connector updates data only once per hour. This integration method supports [Smart Commits](dvcs/index.md#smart-commits). -<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). - -To install the GitLab for Jira Cloud app: +## Install the GitLab for Jira Cloud app **(FREE SAAS)** -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). +Prerequisites: -  -1. After installing, to go to the configurations page, select **Get started**. - This page is always available under **Jira Settings > Apps > Manage apps**. +- You must have at least the Maintainer role for the GitLab namespace. +- You must have administrator access to the Jira instance. -  -1. To add namespaces, ensure you're signed in to GitLab.com - as a user with at least the Maintainer role. +To install the GitLab for Jira Cloud app: -  -1. To open the list of available namespaces, select **Add namespace**. +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**. -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. + Alternatively, [get the app directly from the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud). -  +1. To go to the configurations page, select **Get started**. + You can always access this page in **Jira Settings > Apps > Manage apps**. +1. To open the list of available namespaces, select **Add namespace**. +1. To link to a namespace, select **Link**. -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. +<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). After a namespace is added: -- All future commits, branches, and merge requests of all projects under that namespace +- All future commits, branches, and merge requests of all projects in that namespace are synced to Jira. -- From GitLab 13.8, past merge request data is synced to Jira. +- In GitLab 13.8 and later, existing merge request data is synced to Jira. -Support for syncing past branch and commit data is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/263240). +For more information about syncing existing branch and commit data, see [issue 263240](https://gitlab.com/gitlab-org/gitlab/-/issues/263240). ## 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: @@ -105,25 +88,29 @@ To create an OAuth application: > 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. For more information, see [issue 391432](https://gitlab.com/gitlab-org/gitlab/-/issues/391432). +### 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). + ### Set up your instance +See [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. @@ -132,6 +119,8 @@ To set up your self-managed instance for the GitLab for Jira Cloud app in GitLab ### Link your instance +See [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 +133,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 +141,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). + +### Install the application in development mode -You can configure your Atlassian Cloud instance to allow you to install applications -from outside the Marketplace, which allows you to install the application: +See [prerequisites](#prerequisites-1). + +To configure your Atlassian Cloud 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 +174,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 -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. + +See [prerequisites](#prerequisites-1). -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,11 +195,13 @@ 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). + +## 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 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. +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: @@ -225,9 +210,36 @@ To configure your GitLab instance to serve as a proxy: 1. Expand the **GitLab for Jira App** section. 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 namespaces to be linked. +- Link namespaces. + +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). -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. +### Access to Jira through access token + +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 @@ -243,7 +255,7 @@ You need to sign in or sign up before continuing. The GitLab for Jira Cloud app uses an iframe to add namespaces 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) and enable the `jira_connect_oauth` [feature flag](../../administration/feature_flags.md). ### Manual installation fails @@ -286,28 +298,33 @@ To resolve this issue on GitLab self-managed, follow one of the solutions below, - In all GitLab versions: - Re-install the GitLab for Jira Cloud app. This might remove all already synced development panel data. -## Security considerations - -The GitLab for Jira Cloud app connects GitLab and Jira, as data must be shared between the two applications and access must be granted in both directions. +### `Failed to update GitLab version` error when setting up the GitLab for Jira Cloud app for self-managed instances -## Access to GitLab through OAuth +When you set up the GitLab for Jira Cloud app, you might get the following message after you enter your +self-managed instance URL: -GitLab does not share an access token with Jira. However, users must authenticate via OAuth to configure the app. +```plaintext +Failed to update GitLab version. Please try again. +``` -An access token is retrieved via [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, which is loaded from GitLab through an iframe on Jira. +To resolve this issue, ensure all prerequisites for your installation method have been met: -The OAuth application requires the `api` scope that grants complete read/write access to the API, including to all groups and projects, the container registry, and the package registry. -However, the GitLab for Jira Cloud app only uses this access to: +- [Prerequisites for connecting the GitLab for Jira Cloud app](#prerequisites) +- [Prerequisites for installing the GitLab for Jira Cloud app manually](#prerequisites-1) -- Display namespaces to be linked. -- Link namespaces. +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: -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). +1. Open a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session). +1. Execute the following code: -## Access to Jira through access token + ```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) -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. + # If both flags are enabled, disable the `jira_connect_oauth_self_managed` flag. + Feature.disable(:jira_connect_oauth_self_managed) + ``` |