diff options
Diffstat (limited to 'doc/integration/jira')
| -rw-r--r-- | doc/integration/jira/configure.md | 6 | ||||
| -rw-r--r-- | doc/integration/jira/connect-app.md | 32 | ||||
| -rw-r--r-- | doc/integration/jira/development_panel.md | 127 | ||||
| -rw-r--r-- | doc/integration/jira/img/jira_dev_panel_jira_setup_3.png | bin | 80136 -> 0 bytes | |||
| -rw-r--r-- | doc/integration/jira/img/jira_dev_panel_jira_setup_4.png | bin | 21592 -> 0 bytes | |||
| -rw-r--r-- | doc/integration/jira/img/jira_dev_panel_jira_setup_5.png | bin | 10336 -> 0 bytes | |||
| -rw-r--r-- | doc/integration/jira/index.md | 8 | ||||
| -rw-r--r-- | doc/integration/jira/issues.md | 15 | ||||
| -rw-r--r-- | doc/integration/jira/jira_server_configuration.md | 10 | ||||
| -rw-r--r-- | doc/integration/jira/troubleshooting.md | 6 |
10 files changed, 112 insertions, 92 deletions
diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index 03d742703a1..3ef4dfac3f4 100644 --- a/doc/integration/jira/configure.md +++ b/doc/integration/jira/configure.md @@ -4,7 +4,7 @@ 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 --- -# Configure the Jira integration **(FREE)** +# Configure Jira **(FREE)** You can set up the [Jira integration](index.md#jira-integration) by configuring your project settings in GitLab. @@ -13,10 +13,10 @@ and for self-managed GitLab, at an [instance level](../../user/admin_area/settin Prerequisites: -- Ensure your GitLab installation does not use a [relative URL](development_panel.md#limitations). +- Ensure your GitLab installation does not use a [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configure-a-relative-url-for-gitlab). - 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 +- For **Jira 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). diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index 402efc409cb..8bbac021849 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -27,8 +27,8 @@ at least the Maintainer role in the GitLab.com namespace. This integration method supports [Smart Commits](dvcs/index.md#smart-commits). <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. +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: @@ -117,7 +117,7 @@ Jira apps can only link to one URL per marketplace listing. The official listing If your instance doesn't meet the 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. +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). ### Set up your instance @@ -285,3 +285,29 @@ To resolve this issue on GitLab self-managed, follow one of the solutions below, - 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. - 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. + +## Access to GitLab through OAuth + +GitLab does not share an access token with Jira. However, users must authenticate via OAuth to configure the app. + +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. + +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: + +- 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). + +## 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. diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index f36b9f2c4c1..57308c9a19e 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -4,99 +4,94 @@ 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 --- -# 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 view GitLab activity from the Jira development panel. - +When you're in GitLab, you can refer to a Jira issue by ID. +The [activity for that issue](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) +is displayed in the Jira development panel. -The information displayed in the Jira development panel depends on where you mention the Jira issue ID: +In the Jira development panel, you can create a GitLab merge request from a branch. +You can also create a GitLab branch from a Jira issue in the GitLab for Jira Cloud app +([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66032) in GitLab 14.2). -| 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. | +## Connected projects in GitLab -This integration connects all GitLab projects to projects in the Jira instance in either: +The Jira development panel connects to the entire Jira instance all GitLab projects in: -- 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. +- A top-level group, including all projects in its subgroups. +- A personal namespace. -## Use the integration +These GitLab projects can interact with all Jira projects in that instance. -After the integration is [set up on GitLab and Jira](#configure-the-integration), you can: +## Information displayed in the panel -- 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). +The information displayed in the Jira development panel depends on where you mention the Jira issue ID in GitLab. -At this time, merge requests are called "pull requests" in Jira issues. -This name may change in a future Jira release. +| 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 | +| 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 | -Select the links to see your GitLab repository data. +## Jira Smart Commits - +Jira Smart Commits are special commands to process a Jira issue. With these commands, you can use GitLab to: - +- 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. -### Use Jira Smart Commits +For more information, see the +[Atlassian documentation](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html). -With Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html), -you can use GitLab to add Jira comments, log time spent on the issue, or apply any issue transition. - -For more information about using Jira Smart Commits to track time against an issue, specify -an issue transition, or add a custom comment, read the Atlassian page -[Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html). - -## Configure the integration +## Configure the panel <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). +For an overview, see [Jira development panel integration](https://www.youtube.com/watch?v=VjVTOmMl85M). + +### For GitLab.com -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. +Prerequisite: -| 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. | +- You must have at least the Maintainer role for the group. -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: +To configure the Jira development panel on GitLab.com: -- 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. +- **For [Jira Cloud](https://www.atlassian.com/migration/assess/why-cloud)**: + - [From the Atlassian Marketplace, install the GitLab for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-for-jira-cloud?hosting=cloud&tab=overview). + - This method syncs data between GitLab.com and Jira in real time. + - This method requires inbound connections for the setup and outbound connections to push data to Jira. + - For more information, see [GitLab for Jira Cloud app](connect-app.md). +- **For Jira Server**: + - Use the [Jira DVCS connector](dvcs/index.md). + - This method syncs data every hour and works only with inbound connections. + - This method attempts to set up webhooks in GitLab to sync data in real time, which requires outbound connections. -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). +### For self-managed GitLab -## Limitations +Prerequisites: -- 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. +- You must have administrator access to the instance. +- Your GitLab installation must not use a [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configure-a-relative-url-for-gitlab) + (for example, `https://example.com/gitlab`). -## Troubleshoot the development panel +To configure the Jira development panel on self-managed GitLab: -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. +- **For [Jira Cloud](https://www.atlassian.com/migration/assess/why-cloud)**: + - [Install the GitLab for Jira Cloud app manually](connect-app.md#install-the-gitlab-for-jira-cloud-app-manually). + - This method requires inbound connections for the setup and outbound connection to push data to Jira. + - 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). +- **For Jira Server**: + - Use the [Jira DVCS connector](dvcs/index.md). + - This method syncs data every hour and works only with inbound connections. + - This method attempts to set up webhooks in GitLab to sync data in real time, which requires outbound connections. -### 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/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/index.md b/doc/integration/jira/index.md index 2ad71a19cf7..3ec4c7aee87 100644 --- a/doc/integration/jira/index.md +++ b/doc/integration/jira/index.md @@ -4,7 +4,7 @@ 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 --- -# 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 @@ -37,7 +37,7 @@ displays in the [development panel](https://support.atlassian.com/jira-software- 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). +[depending on your installation](development_panel.md#configure-the-panel). ### Direct feature comparison @@ -63,8 +63,8 @@ The authentication method in Jira depends on whether you host Jira on your own s 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). + Atlassian cloud, an email and API token are required. For more information, see + [Create a Jira Cloud API token](jira_cloud_configuration.md). ## Privacy considerations diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md index 3a5d8e66b2d..58da871926b 100644 --- a/doc/integration/jira/issues.md +++ b/doc/integration/jira/issues.md @@ -4,10 +4,10 @@ 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 --- -# 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. +To integrate issue management with Jira, [configure Jira](index.md#jira-integration) +and [enable the 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. @@ -47,12 +47,11 @@ 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**. diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index 7dee99b024e..5bac108b457 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -20,7 +20,7 @@ credentials, you must: This process creates a user named `gitlab`: 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 projects in Jira. @@ -43,9 +43,9 @@ group to assign permissions to the user. This process adds the `gitlab` user you created to a new group named `gitlab-developers`: 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**.  @@ -70,9 +70,9 @@ Next, create a permission scheme for your group. After creating the group in Jira, grant permissions to the group by creating a permission scheme: 1. Sign in to your Jira instance as 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**. 1. In the permissions scheme list, locate your new permissions scheme, and diff --git a/doc/integration/jira/troubleshooting.md b/doc/integration/jira/troubleshooting.md index 0e679693614..bf347c4698d 100644 --- a/doc/integration/jira/troubleshooting.md +++ b/doc/integration/jira/troubleshooting.md @@ -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 |
