151 lines
7.4 KiB
Markdown
151 lines
7.4 KiB
Markdown
---
|
|
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
|
|
---
|
|
|
|
# Jira DVCS connector **(FREE)**
|
|
|
|
WARNING:
|
|
The Jira DVCS connector for Jira Cloud was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/362168) in GitLab 15.1
|
|
and is planned for removal in 16.0. Use the [GitLab for Jira Cloud app](../connect-app.md) instead.
|
|
|
|
Use the Jira DVCS (distributed version control system) connector if you self-host
|
|
your Jira instance and want to sync information between GitLab and Jira.
|
|
If you're using the Jira DVCS connector with Jira Cloud, [migrate to the GitLab for Jira Cloud app](#migrate-to-the-gitlab-for-jira-cloud-app).
|
|
|
|
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.
|
|
|
|
## Smart Commits
|
|
|
|
When connecting GitLab and Jira with the Jira DVCS connector, you can process your Jira issues with
|
|
special commands called [Smart Commits](https://support.atlassian.com/jira-software-cloud/docs/process-issues-with-smart-commits/).
|
|
With Smart Commits, you can:
|
|
|
|
- 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. For more information about how Smart Commits work and what commands are available
|
|
for use, see the [Atlassian documentation](https://support.atlassian.com/jira-software-cloud/docs/process-issues-with-smart-commits/).
|
|
|
|
For Smart Commits to work, the GitLab user must have a corresponding
|
|
Jira user with the same email address or username.
|
|
|
|
### Smart Commit syntax
|
|
|
|
Smart Commits must follow this pattern:
|
|
|
|
```plaintext
|
|
<ISSUE_KEY> <ignored text> #<command> <optional command parameters>
|
|
```
|
|
|
|
Some examples:
|
|
|
|
- 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`
|
|
|
|
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:
|
|
|
|
- Add time tracking, add a comment, and transition to **Closed**:
|
|
|
|
```plaintext
|
|
KEY-123 #time 2d 5h #comment Task completed ahead of schedule #close
|
|
```
|
|
|
|
- Add a comment, transition to **In-progress**, and add time tracking:
|
|
|
|
```plaintext
|
|
KEY-123 #comment started working on the issue #in-progress #time 12d 5h
|
|
```
|
|
|
|
## Configure a GitLab application for DVCS
|
|
|
|
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 new user account in GitLab for Jira integration work only.
|
|
A separate account ensures regular account maintenance does not affect your integration.
|
|
|
|
If a separate user account or group application is not possible, 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).
|
|
|
|
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 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 Jira for DVCS
|
|
|
|
To import all GitLab commits and branches into Jira for the groups you specify,
|
|
configure Jira for DVCS. 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 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](#configure-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](#configure-a-gitlab-application-for-dvcs).
|
|
1. For **Client Secret**, use the [**Secret** value](#configure-a-gitlab-application-for-dvcs).
|
|
1. Ensure that all other 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.
|
|
|
|
To connect additional GitLab projects from other GitLab top-level groups or
|
|
personal namespaces, repeat the previous steps with additional Jira DVCS accounts.
|
|
|
|
For more information about how to use the integration, see [Jira development panel](../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:
|
|
|
|
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're using the Jira DVCS connector with 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).
|
|
|
|
### Feature comparison of DVCS and GitLab for Jira Cloud app
|
|
|
|
| Feature | DVCS | 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.
|