diff options
Diffstat (limited to 'doc/integration/jira/development_panel.md')
| -rw-r--r-- | doc/integration/jira/development_panel.md | 135 |
1 files changed, 66 insertions, 69 deletions
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). |