2021-04-14 11:09:04 -04:00
---
2021-08-02 11:08:56 -04:00
stage: Ecosystem
group: Integrations
2021-04-14 11:09:04 -04:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Jira integration issue management **(FREE)**
2021-07-12 11:09:19 -04:00
Integrating issue management with Jira requires you to [configure Jira ](index.md#jira-integration )
2021-07-28 11:09:57 -04:00
and [enable the Jira integration ](configure.md ) in GitLab.
2021-05-03 14:10:17 -04:00
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.
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
The Jira integration requires to you format any Jira issue IDs in uppercase.
2021-04-14 11:09:04 -04:00
## Reference Jira issues
2021-05-03 14:10:17 -04:00
With this integration, you can cross-reference Jira issues while you work in
GitLab issues and merge requests. Mention a Jira issue in a GitLab issue,
merge request, or comment, and GitLab adds a formatted comment to the Jira issue.
The comment links back to your work in GitLab.
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
For example, this commit references the Jira issue `GIT-1` :
```shell
git commit -m "GIT-1 this is a test commit"
2021-04-14 11:09:04 -04:00
```
2021-05-03 14:10:17 -04:00
GitLab adds a reference to the **Issue Links** section of Jira issue `GIT-1` :
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
![Example of mentioning or closing the Jira issue ](img/jira_issue_reference.png )
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
GitLab also adds a comment to the issue, and uses this format:
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
```plaintext
USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|COMMENTLINK]:
ENTITY_TITLE
2021-04-14 11:09:04 -04:00
```
2021-05-03 14:10:17 -04:00
- `USER` : The name of the user who mentioned the issue, linked to their GitLab user profile.
- `COMMENTLINK` : A link to where the Jira issue was mentioned.
- `RESOURCE_NAME` : The type of resource, such as a commit or merge request, which referenced the issue.
- `PROJECT_NAME` : The GitLab project name.
- `ENTITY_TITLE` : The title of the merge request, or the first line of the commit.
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
You can [disable comments ](#disable-comments-on-jira-issues ) on issues.
2021-04-14 11:09:04 -04:00
2021-07-28 20:09:04 -04:00
### Require associated Jira issue for merge requests to be merged **(ULTIMATE)**
2021-05-17 14:10:42 -04:00
2021-08-13 05:09:58 -04:00
> - [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).
2021-06-30 11:08:27 -04:00
> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61722) in GitLab 14.1.
2021-08-13 05:09:58 -04:00
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/335280) in GitLab 14.2.
2021-05-17 14:10:42 -04:00
You can prevent merge requests from being merged if they do not refer to a Jira issue.
To enforce this:
1. Navigate to your project's **Settings > General** page.
1. Expand the **Merge requests** section.
2021-08-12 20:09:14 -04:00
1. Under **Merge checks** , select the **Require an associated issue from Jira** checkbox.
2021-05-17 14:10:42 -04:00
1. Select **Save** for the changes to take effect.
After you enable this feature, a merge request that doesn't reference an associated
Jira issue can't be merged. The merge request displays the message
**To merge, a Jira issue key must be mentioned in the title or description.**
2021-05-03 14:10:17 -04:00
## Close Jira issues in GitLab
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
If you have configured GitLab transition IDs, you can close a Jira issue directly
from GitLab. Use a trigger word followed by a Jira issue ID in a commit or merge request.
When you push a commit containing a trigger word and Jira issue ID, GitLab:
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
1. Comments in the mentioned Jira issue.
1. Closes the Jira issue. If the Jira issue has a resolution, it isn't transitioned.
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
For example, use any of these trigger words to close the Jira issue `PROJECT-1` :
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
- `Resolves PROJECT-1`
- `Closes PROJECT-1`
- `Fixes PROJECT-1`
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
The commit or merge request must target your project's [default branch ](../../user/project/repository/branches/default.md ).
You can change your project's default branch under [project settings ](img/jira_project_settings.png ).
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
### Use case for closing issues
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
Consider this example:
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
1. A user creates Jira issue `PROJECT-7` to request a new feature.
1. You create a merge request in GitLab to build the requested feature.
1. In the merge request, you add the issue closing trigger `Closes PROJECT-7` .
1. When the merge request is merged:
- GitLab closes the Jira issue for you:
![The GitLab integration closes Jira issue ](img/jira_service_close_issue.png )
- GitLab adds a formatted comment to Jira, linking back to the commit that
resolved the issue. You can [disable comments ](#disable-comments-on-jira-issues ).
2021-04-14 11:09:04 -04:00
## View Jira issues **(PREMIUM)**
2021-09-20 08:11:04 -04:00
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in GitLab 13.2.
2021-04-14 11:09:04 -04:00
You can browse, search, and view issues from a selected Jira project directly in GitLab,
2021-07-28 11:09:57 -04:00
if your GitLab administrator [has configured it ](configure.md ).
2021-04-14 11:09:04 -04:00
2021-11-19 07:12:41 -05:00
To do this, in GitLab, go to your project and select **Issues > Jira issues** . The issue list
2021-05-03 14:10:17 -04:00
sorts by **Created date** by default, with the newest issues listed at the top:
2021-04-14 11:09:04 -04:00
2021-11-19 07:12:41 -05:00
![Jira issues integration enabled ](img/open_jira_issues_list_v14_6.png )
2021-04-14 11:09:04 -04:00
2022-03-24 11:09:10 -04:00
- To display the most recently updated issues first, select **Updated date** .
2021-05-03 14:10:17 -04:00
- You can [search and filter ](#search-and-filter-the-issues-list ) the issues list.
- In GitLab [versions 13.10 and later ](https://gitlab.com/gitlab-org/gitlab/-/issues/299832 ),
you can select an issue from the list to view it in GitLab:
![Jira issue detail view ](img/jira_issue_detail_view_v13.10.png )
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
Issues are grouped into tabs based on their
[Jira status ](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html ):
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
- **Open** tab: All issues with a Jira status in any category other than Done.
- **Closed** tab: All issues with a Jira status categorized as Done.
- **All** tab: All issues of any status.
2021-04-14 11:09:04 -04:00
2021-07-12 11:09:19 -04:00
### Search and filter the issues list **(PREMIUM)**
2021-04-14 11:09:04 -04:00
To refine the list of issues, use the search bar to search for any text
2021-05-03 14:10:17 -04:00
contained in an issue summary (title) or description. Use any combination
of these filters:
2021-04-14 11:09:04 -04:00
- To filter issues by `labels` , specify one or more labels as part of the `labels[]`
2021-05-03 14:10:17 -04:00
parameter in the URL. When using multiple labels, only issues that contain all specified
labels are listed: `/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA`
- To filter issues by `status` , specify the `status` parameter in the URL:
`/-/integrations/jira/issues?status=In Progress`
2021-04-14 11:09:04 -04:00
- To filter issues by `reporter` , specify a reporter's Jira display name for the
2021-05-03 14:10:17 -04:00
`author_username` parameter in the URL: `/-/integrations/jira/issues?author_username=John Smith`
2021-04-14 11:09:04 -04:00
- To filter issues by `assignee` , specify their Jira display name for the
2021-05-03 14:10:17 -04:00
`assignee_username` parameter in the URL: `/-/integrations/jira/issues?assignee_username=John Smith`
Enhancements to use these filters through the user interface
[are planned ](https://gitlab.com/groups/gitlab-org/-/epics/3622 ).
2021-04-14 11:09:04 -04:00
2022-05-04 05:09:02 -04:00
## Create a Jira issue for a vulnerability **(ULTIMATE)**
You can create a Jira issue for a vulnerability from a [Vulnerability Page ](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability ).
2021-04-14 11:09:04 -04:00
## Automatic issue transitions
2021-11-30 04:09:53 -05:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55773) in GitLab 13.11.
2021-04-14 11:09:04 -04:00
2021-05-03 14:10:17 -04:00
When you configure automatic issue transitions, you can transition a referenced
Jira issue to the next available status with a category of **Done** . To configure
this setting:
2021-04-14 11:09:04 -04:00
2021-07-28 11:09:57 -04:00
1. Refer to the [Configure GitLab ](configure.md ) instructions.
2021-08-12 20:09:14 -04:00
1. Select the **Enable Jira transitions** checkbox.
2021-05-03 14:10:17 -04:00
1. Select the **Move to Done** option.
2021-04-14 11:09:04 -04:00
## Custom issue transitions
2021-05-03 14:10:17 -04:00
For advanced workflows, you can specify custom Jira transition IDs:
1. Use the method based on your Jira subscription status:
- *(For users of Jira Cloud)* Obtain your transition IDs by editing a workflow
in the **Text** view. The transition IDs display in the **Transitions** column.
- *(For users of Jira Server)* Obtain your transition IDs in one of these ways:
- By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions` ,
using an issue that is in the appropriate "open" state.
- By mousing over the link for the transition you want and looking for the
**action** parameter in the URL.
The transition ID may vary between workflows (for example, a bug instead of a
story), even if the status you're changing to is the same.
2021-07-28 11:09:57 -04:00
1. Refer to the [Configure GitLab ](configure.md ) instructions.
2021-05-03 14:10:17 -04:00
1. Select the **Enable Jira transitions** setting.
1. Select the **Custom transitions** option.
1. Enter your transition IDs in the text field. If you insert multiple transition IDs
(separated by `,` or `;` ), the issue is moved to each state, one after another, in the
order you specify. If a transition fails, the sequence is aborted.
## Disable comments on Jira issues
GitLab can cross-link source commits or merge requests with Jira issues without
adding a comment to the Jira issue:
2021-07-28 11:09:57 -04:00
1. Refer to the [Configure GitLab ](configure.md ) instructions.
2021-08-12 20:09:14 -04:00
1. Clear the **Enable comments** checkbox.