doc/integration/jira/configure.md
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
The Jira issues integration connects one or more GitLab projects to a Jira instance.
You can host the Jira instance yourself or in Jira Cloud.
The supported Jira versions are 6.x, 7.x, 8.x, 9.x, and 10.x.
{{< history >}}
jira_multiple_project_keys. Disabled by default.jira_multiple_project_keys removed.{{< /history >}}
Prerequisites:
You can enable the Jira issues integration by configuring your project settings in GitLab. You can also configure the integration for a specific group or an entire instance on GitLab Self-Managed.
With this integration, your GitLab project can interact with all Jira projects on your instance. To configure your project settings in GitLab:
https://jira.example.com).https://jira-api.example.com).
If this URL is not set, the Web URL value is used by default.
For Jira Cloud, leave Jira API URL blank.Select the View Jira issues checkbox.
[!warning] When you enable this setting, all users with access to your GitLab project can view all issues from the Jira projects you've specified.
Enter one or more Jira project keys. Leave blank to include all available keys.
Select the Create Jira issues for vulnerabilities checkbox.
[!note] You can enable this setting only for individual projects and groups.
Enter a Jira project key.
Select Fetch issue types for this project key ({{< icon name="retry" >}}), then select the type of Jira issues to create.
Optional. Select the Customize Jira issues checkbox to be able to review, modify, or add details to a Jira issue when it's created for a vulnerability.
{{< details >}}
{{< /details >}}
{{< history >}}
jira_multiple_project_keys. Disabled by default.jira_multiple_project_keys removed.{{< /history >}}
Prerequisites:
You can enable Jira issues for a specific group or project, but you can view the issues in GitLab projects only. To view issues from one or more Jira projects in a GitLab project:
By default, the issues are sorted by Created date. The most recently created issues appear at the top. You can filter issues and select an issue to view that issue in GitLab.
Issues are grouped into the following tabs based on their Jira status:
{{< details >}}
{{< /details >}}
{{< history >}}
jira_multiple_project_keys. Disabled by default.jira_multiple_project_keys removed.{{< /history >}}
Prerequisites:
When you view Jira issues in GitLab, you can filter the issues by text in summaries and descriptions. You can also filter the issues by:
labels[] parameter in the URL.
When you specify multiple labels, only the issues that have all the specified labels appear
(for example, /-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA).status parameter in the URL
(for example, /-/integrations/jira/issues?status=In Progress).author_username parameter in the URL
(for example, /-/integrations/jira/issues?author_username=John Smith).assignee_username parameter in the URL
(for example, /-/integrations/jira/issues?assignee_username=John Smith).project parameter in the URL
(for example, /-/integrations/jira/issues?project=GTL).{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
Prerequisites:
You can set up verification rules to ensure Jira issues referenced in commit messages meet specific criteria before allowing pushes. This feature helps maintain consistent workflows between GitLab and Jira.
To configure Jira verification:
Ready, In Progress, Review). This field is only available when Check issue status is enabled.When a user attempts to push changes that don't meet the verification criteria, GitLab displays an error message indicating why the push was rejected.
[!note] If a commit message contains multiple Jira issue keys, only the first one is used for verification checks.
If a referenced Jira issue doesn't exist (when Check issue exists is enabled):
Jira issue PROJECT-123 does not exist.
If a referenced Jira issue isn't assigned to the committer (when Check assignee is enabled):
Jira issue PROJECT-123 is not assigned to you. It is assigned to Jane Doe.
If a referenced Jira issue has a status that's not in the allowed list (when Check issue status is enabled):
Jira issue PROJECT-123 has status 'Done', which is not in the list of allowed statuses: Ready, In Progress, Review.
Consider this example:
This ensures your team follows the correct workflow by preventing code changes from being pushed when the corresponding Jira issue isn't in the right state.
{{< details >}}
{{< /details >}}
Prerequisites:
You can create a Jira issue from GitLab to track any action taken to resolve or mitigate a vulnerability. To create a Jira issue for a vulnerability:
In the top bar, select Search or go to and find your project.
Select Secure > Vulnerability report.
Select the vulnerability's description.
Select Create Jira issue.
If the Customize Jira issues setting is selected, you will be redirected to the issue creation form on your Jira instance, pre-filled with vulnerability data. You can review, modify, or add details before creating the Jira issue.
The issue is created in the target Jira project with information from the vulnerability report.
To create a GitLab issue, see create a GitLab issue for a vulnerability.
To configure the Jira issues integration for Jira Cloud, you must have a Jira Cloud API token. To create a Jira Cloud API token:
Sign in to Atlassian from an account with write access to Jira projects.
The link opens the API tokens page. Alternatively, from your Atlassian profile, select Account Settings > Security > Create and manage API tokens.
Select Create API token.
On the dialog, enter a label for your token and select Create.
To copy the API token, select Copy.
{{< history >}}
{{< /history >}}
To migrate from one Jira site to another in GitLab and maintain your Jira issues integration:
https://myjirasite.atlassian.net).In GitLab 18.6 and later, existing Jira issue references are automatically updated to use the new Jira site URL.
In GitLab 18.5 and earlier, you must invalidate the Markdown cache to update existing Jira issue references.