debian-mirror-gitlab/doc/integration/jira/issues.md

stage	group	info
Manage	Import and Integrate	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 issue management (FREE)

You can manage Jira issues directly in GitLab. You can then refer to Jira issues by ID in GitLab commits and merge requests. The Jira issue IDs must be in uppercase.

Cross-reference GitLab activity and Jira issues

With this integration, you can cross-reference Jira issues while you work in GitLab issues, merge requests, and Git. When you mention a Jira issue in a GitLab issue, merge request, comment, or commit:

• GitLab links to the Jira issue from the mention in GitLab.
• GitLab adds a formatted comment to the Jira issue that links back to the issue, merge request, or commit in GitLab.

For example, when this commit refers to a GIT-1 Jira issue:

git commit -m "GIT-1 this is a test commit"

GitLab adds to that Jira issue:

• A reference in the Web links section

• A comment in the Activity section that follows this format:

  USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|COMMENTLINK]:
  ENTITY_TITLE
  

  • USER: Name of the user who has mentioned the Jira issue with a link to their GitLab user profile.
  • RESOURCE_NAME: Type of resource (for example, a GitLab commit, issue, or merge request) that has referenced the Jira issue.
  • PROJECT_NAME: GitLab project name.
  • COMMENTLINK: Link to where the Jira issue is mentioned.
  • ENTITY_TITLE: Title of the GitLab commit (first line), issue, or merge request.

Only a single cross-reference comment appears in Jira per GitLab issue, merge request, or commit. For example, multiple comments on a GitLab merge request that reference a Jira issue create only a single cross-reference comment back to that merge request in Jira.

You can disable comments on issues.

Require associated Jira issue for merge requests to be merged (ULTIMATE)

• Introduced in GitLab 13.12 with a flag named jira_issue_association_on_merge_request. Disabled by default.
• Generally available in GitLab 14.2. Feature flag jira_issue_association_on_merge_request removed.

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.
2. On the left sidebar, select Settings > Merge requests.
3. In the Merge checks section, select Require an associated issue from Jira.
4. Select Save.

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.

Customize Jira issue matching in GitLab

Introduced in GitLab 15.10.

You can configure custom rules for how GitLab matches Jira issue keys by defining:

• A regex pattern
• A prefix

When you don't configure custom rules, the default behavior is used. For more information, see the RE2 wiki.

Use regular expression

To define a regex pattern for Jira issue keys:

1. On the top bar, select Main menu > Projects and find your project.
2. On the left sidebar, select Settings > Integrations.
3. Select Jira.
4. Go to the Jira issue matching section.
5. In the Jira issue regex text box, enter a regex pattern.
6. Select Save changes.

For more information, see the Atlassian documentation.

Use a prefix

To define a prefix for Jira issue keys:

1. On the top bar, select Main menu > Projects and find your project.
2. On the left sidebar, select Settings > Integrations.
3. Select Jira.
4. Go to the Jira issue matching section.
5. In the Jira issue prefix text box, enter a prefix.
6. Select Save changes.

Close Jira issues in GitLab

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:

1. Comments in the mentioned Jira issue.
2. Closes the Jira issue. If the Jira issue has a resolution, it isn't transitioned.

For example, use any of these trigger words to close the Jira issue PROJECT-1:

• Resolves PROJECT-1
• Closes PROJECT-1
• Fixes PROJECT-1

The commit or merge request must target your project's default branch. You can change your project's default branch in project settings.

Use case for closing issues

Consider this example:

1. A user creates Jira issue PROJECT-7 to request a new feature.
2. You create a merge request in GitLab to build the requested feature.
3. In the merge request, you add the issue closing trigger Closes PROJECT-7.
4. When the merge request is merged:
   • GitLab closes the Jira issue for you.
   • GitLab adds a formatted comment to Jira, linking back to the commit that resolved the issue. You can disable comments.

View Jira issues (PREMIUM)

Introduced in GitLab 13.2.

You can view and search issues from a selected Jira project directly in GitLab, provided your GitLab administrator has configured the integration.

To view Jira issues:

1. On the top bar, select Main menu > Projects and find your project.
2. On the left sidebar, select Issues > Jira issues.

The issues are sorted by Created date by default, with the most recently created issues listed at the top.

• To display the most recently updated issues first, select Updated date.
• You can search and filter the issue list.
• In GitLab 13.10 and later, you can select an issue from the list to view the issue in GitLab.

Issues are grouped into tabs based on their Jira status:

• 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.

Search and filter the issue list (PREMIUM)

To refine the list of issues, use the search bar to search for any text contained in an issue summary (title) or description. Use any combination of these filters:

• To filter issues by labels, specify one or more labels as part of the labels[] 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
• To filter issues by reporter, specify a reporter's Jira display name for the author_username parameter in the URL: /-/integrations/jira/issues?author_username=John Smith
• To filter issues by assignee, specify their Jira display name for the assignee_username parameter in the URL: /-/integrations/jira/issues?assignee_username=John Smith

Enhancements to use these filters through the user interface are planned.

Create a Jira issue for a vulnerability (ULTIMATE)

You can create a Jira issue for a vulnerability from a Vulnerability Page.

Automatic issue transitions

Introduced in GitLab 13.11.

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:

1. Refer to the Configure GitLab instructions.
2. Select the Enable Jira transitions checkbox.
3. Select the Move to Done option.

Custom issue transitions

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.
2. Refer to the Configure GitLab instructions.
3. Select the Enable Jira transitions setting.
4. Select the Custom transitions option.
5. 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:

1. Refer to the Configure GitLab instructions.
2. Clear the Enable comments checkbox.