diff options
Diffstat (limited to 'doc/integration/jira/development_panel.md')
-rw-r--r-- | doc/integration/jira/development_panel.md | 127 |
1 files changed, 61 insertions, 66 deletions
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. -![Branch, Commit and Pull Requests links on Jira issue](img/jira_dev_panel_jira_setup_3.png) +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 -![GitLab commits details on a Jira issue](img/jira_dev_panel_jira_setup_4.png) +Jira Smart Commits are special commands to process a Jira issue. With these commands, you can use GitLab to: -![GitLab merge requests details on a Jira issue](img/jira_dev_panel_jira_setup_5.png) +- 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). |