Skip to content

G
gitlab-ce
Commit 7f7a0370 authored by Craig Norris's avatar Craig Norris
Browse files
Options

Merge branch '323622-aqualls-revise-jira' into 'master' 

Revise and clean up Jira issues page

See merge request gitlab-org/gitlab!60751
parents 19f4e5c2 50f0c55f
Show whitespace changes
Inline Side-by-side
Showing with 104 additions and 115 deletions
doc/integration/jira/issues.md
View file @ 7f7a0370
......@@ -6,168 +6,157 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Jira integration issue management **(FREE)**
By now you should have [configured Jira](development_panel.md#configuration) and enabled the
[Jira service in GitLab](development_panel.md#configure-gitlab). If everything is set up correctly
you should be able to reference and close Jira issues by just mentioning their
ID in GitLab commits and merge requests.
Integrating issue management with Jira requires you to [configure Jira](development_panel.md#configuration)
and [enable the Jira service](development_panel.md#configure-gitlab) in GitLab.
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.
Jira issue IDs must be formatted in uppercase for the integration to work.
The Jira integration requires to you format any Jira issue IDs in uppercase.
## Reference Jira issues
When GitLab project has Jira issue tracker configured and enabled, mentioning
Jira issues in GitLab automatically adds a comment in Jira issue with the
link back to GitLab. This means that in comments in merge requests and commits
referencing an issue, `PROJECT-7` for example, adds a comment in Jira issue in the
format:
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.
```plaintext
USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]:
ENTITY_TITLE
For example, this commit references the Jira issue `GIT-1`:
```shell
git commit -m "GIT-1 this is a test commit"
```
- `USER` A user that mentioned the issue. This is the link to the user profile in GitLab.
- `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where Jira issue was mentioned.
- `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request.
- `PROJECT_NAME` GitLab project name.
- `ENTITY_TITLE` Merge request title or commit message first line.
GitLab adds a reference to the **Issue Links** section of Jira issue `GIT-1`:
![example of mentioning or closing the Jira issue](img/jira_issue_reference.png)
![Example of mentioning or closing the Jira issue](img/jira_issue_reference.png)
For example, the following commit references the Jira issue with `PROJECT-1` as its ID:
GitLab also adds a comment to the issue, and uses this format:
```shell
git commit -m "PROJECT-1 Fix spelling and grammar"
```plaintext
USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|COMMENTLINK]:
ENTITY_TITLE
```
## Close Jira issues
- `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.
Jira issues can be closed directly from GitLab by using trigger words in
commits and merge requests. When a commit which contains the trigger word
followed by the Jira issue ID in the commit message is pushed, GitLab
adds a comment in the mentioned Jira issue and immediately closes it (provided
the transition ID was set up correctly).
You can [disable comments](#disable-comments-on-jira-issues) on issues.
There are currently three trigger words, and you can use either one to achieve
the same goal:
## Close Jira issues in GitLab
- `Resolves PROJECT-1`
- `Closes PROJECT-1`
- `Fixes PROJECT-1`
where `PROJECT-1` is the ID of the Jira issue.
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:
Note the following:
1. Comments in the mentioned Jira issue.
1. Closes the Jira issue. If the Jira issue has a resolution, it isn't transitioned.
- Only commits and merges into the project's default branch (usually `master`)
close an issue in Jira. You can change your project's default branch under
[project settings](img/jira_project_settings.png).
- The Jira issue is not transitioned if it has a resolution.
For example, use any of these trigger words to close the Jira issue `PROJECT-1`:
Let's consider the following example:
1. For the project named `PROJECT` in Jira, we implemented a new feature
and created a merge request in GitLab.
1. This feature was requested in Jira issue `PROJECT-7` and the merge request
in GitLab contains the improvement
1. In the merge request description we use the issue closing trigger
`Closes PROJECT-7`.
1. Once the merge request is merged, the Jira issue is automatically closed
with a comment and an associated link to the commit that resolved the issue.
- `Resolves PROJECT-1`
- `Closes PROJECT-1`
- `Fixes PROJECT-1`
In the following screenshot you can see what the link references to the Jira
issue look like.
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).
![A Git commit that causes the Jira issue to be closed](img/jira_merge_request_close.png)
### Use case for closing issues
Once this merge request is merged, the Jira issue is automatically closed
with a link to the commit that resolved the issue.
Consider this example:
![The GitLab integration closes Jira issue](img/jira_service_close_issue.png)
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).
## View Jira issues **(PREMIUM)**
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
You can browse, search, and view issues from a selected Jira project directly in GitLab,
if your GitLab administrator [has configured it](development_panel.md#configure-gitlab):
1. In the left navigation bar, go to **Jira > Issues list**.
1. The issue list sorts by **Created date** by default, with the newest issues listed at the top:
![Jira issues integration enabled](img/open_jira_issues_list_v13.2.png)
if your GitLab administrator [has configured it](development_panel.md#configure-gitlab).
1. To display the most recently updated issues first, click **Last updated**.
1. In GitLab versions 13.10 and later, you can view [individual Jira issues](#view-a-jira-issue).
To do this, in GitLab, go to your project and select **Jira > Issues list**. The issue list
sorts by **Created date** by default, with the newest issues listed at the top:
Issues are grouped into tabs based on their [Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html):
![Jira issues integration enabled](img/open_jira_issues_list_v13.2.png)
- The **Open** tab displays all issues with a Jira status in any category other than Done.
- The **Closed** tab displays all issues with a Jira status categorized as Done.
- The **All** tab displays all issues of any status.
- To display the most recently updated issues first, select **Last updated**.
- 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)
## View a Jira issue
Issues are grouped into tabs based on their
[Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html):
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10 behind a feature flag, disabled by default.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.11.
When viewing the [Jira issues list](#view-jira-issues), select an issue from the
list to open it in GitLab:
![Jira issue detail view](img/jira_issue_detail_view_v13.10.png)
- **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 issues list
To refine the list of issues, use the search bar to search for any text
contained in an issue summary (title) or description.
You can also filter by labels, status, reporter, and assignee using URL parameters.
Enhancements to be able to use these through the user interface are [planned](https://gitlab.com/groups/gitlab-org/-/epics/3622).
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`
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`
`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`
`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).
## Automatic issue transitions
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/...) in GitLab 13.10.
In this mode the referenced Jira issue is transitioned to the next available status with a category of "Done".
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:
See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting and select the **Move to Done** option.
1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions.
1. Select the **Enable Jira transitions** check box.
1. Select the **Move to Done** option.
## Custom issue transitions
For advanced workflows you can specify custom Jira transition IDs.
See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting, select the **Custom transitions** option, and 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, using the given order. If a transition fails the sequence is aborted.
To see the transition IDs on Jira Cloud, edit a workflow in the **Text** view.
The transition IDs display in the **Transitions** column.
On Jira Server you can get the transition IDs in either of the following ways:
1. 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
1. By mousing over the link for the transition you want and looking for the
"action" parameter in the URL
Note that the transition ID may vary between workflows (for example, bug vs. story),
even if the status you are changing to is the same.
## Disabling comments on Jira issues
You can continue to have GitLab cross-link a source commit/MR with a Jira issue while disabling the comment added to the issue.
See the [Configure GitLab](development_panel.md#configure-gitlab) section and uncheck the **Enable comments** setting.
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.
1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions.
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:
1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions.
1. Clear the **Enable comments** check box.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7