| In a merge request | Link to the MR is displayed in Development panel. |
| In a merge request | Link to the MR is displayed in Development panel. |
| In a branch name | Link to the branch is displayed in Development panel. |
| In a branch name | Link to the branch is displayed in Development panel. |
| In a commit message | Link to the commit is displayed in Development panel. |
| In a commit message | Link to the commit is displayed in Development panel. |
| In a commit message with Jira Smart Commit format | Displays your custom comment or logged time spent and/or performs specified issue transition on merge. |
| In a commit message with Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) | Displays your custom comment or logged time spent and/or performs specified issue transition on merge. |
With this integration, you can access related GitLab merge requests, branches, and commits directly from a Jira issue, reflecting your work in GitLab. From the Development panel, you can open a detailed view and take actions including creating a new merge request from a branch. For more information, see [Usage](#usage).
This integration connects all GitLab projects to projects in the Jira instance in either:
This integration connects all GitLab projects to projects in the Jira instance in either:
- A top-level group. A top-level GitLab group is one that does not have any parent group itself. All
- A top-level GitLab group: Connects the projects in a group with no parent group,
the projects of that top-level group, as well as projects of the top-level group's subgroups nesting
including the projects in its subgroups.
down, are connected.
- A personal namespace: Connects the projects in that personal namespace to Jira.
- A personal namespace, which then connects the projects in that personal namespace to Jira.
This differs from the [Jira integration](../../user/project/integrations/jira.md),
where the mapping is between one GitLab project and the entire Jira instance.
You can install both integrations to take advantage of both sets of features.
A [feature comparison](index.md#direct-feature-comparison) is available.
## Use the integration
After the integration is [set up on GitLab and Jira](#configure-the-integration), you can:
This differs from the [Jira integration](../../user/project/integrations/jira.md), where the mapping is between one GitLab project and the entire Jira instance.
- Refer to any Jira issue by its ID (in uppercase) in GitLab branch names,
commit messages, and merge request titles.
- See the linked branches, commits, and merge requests in Jira issues:
Additional features provided by the Jira Development Panel integration include:
Merge requests are called "pull requests" in Jira issues.
Select the links to see your GitLab repository data.
- In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests.
### Use Jira Smart Commits
- Use Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in GitLab to add Jira comments, log time spent on the issue, or apply any issue transition.
- Showing pipeline, deployment, and feature flags in Jira issues.
## Configuration
With Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html),
you can use GitLab to add Jira comments, log time spent on the issue, or apply any issue transition.
For more information about using Jira Smart Commits to track time against an issue, specify
an issue transition, or add a custom comment, read the Atlassian page
For an overview of how to configure Jira Development panel integration, see [Agile Management - GitLab Jira Development panel integration](https://www.youtube.com/watch?v=VjVTOmMl85M&feature=youtu.be).
For an overview of how to configure Jira Development panel integration, see
[Agile Management - GitLab Jira Development panel integration](https://www.youtube.com/watch?v=VjVTOmMl85M).
We recommend that a GitLab group maintainer or group owner, or instance administrator (in the case of
To simplify administration, we recommend that a GitLab group maintainer or group owner
self-managed GitLab) set up the integration to simplify administration.
(or instance administrator in the case of self-managed GitLab) set up the integration.
| If you use Jira on: | GitLab.com customers need: | GitLab self-managed customers need: |
| Jira usage | GitLab.com customers need | GitLab self-managed customers need |
| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab and Jira. | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab Jira Cloud application for self-managed instances](connect-app.md#install-the-gitlabcom-for-jira-cloud-application-for-self-managed-instances) for more information. |
| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab and Jira. | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab Jira Cloud application for self-managed instances](connect-app.md#install-the-gitlabcom-for-jira-cloud-application-for-self-managed-instances) for more information. |
| Your own server | The Jira DVCS (distributed version control system) connector. This syncs data hourly. | The [Jira DVCS Connector](dvcs.md). |
| Your own server | The Jira DVCS (distributed version control system) connector. This syncs data hourly. | The [Jira DVCS Connector](dvcs.md). |
Each GitLab project can be configured to connect to an entire Jira instance. That means one GitLab
Each GitLab project can be configured to connect to an entire Jira instance. That means after
project can interact with _all_ Jira projects in that instance, once configured. For:
configuration, one GitLab project can interact with all Jira projects in that instance. For:
- The [view Jira issues](issues.md#view-jira-issues) feature, you must associate a GitLab project with a
- The [view Jira issues](issues.md#view-jira-issues) feature, you must associate a GitLab project with a
specific Jira project.
specific Jira project.
...
@@ -68,88 +88,67 @@ documentation for [central administration of project integrations](../../user/ad
...
@@ -68,88 +88,67 @@ documentation for [central administration of project integrations](../../user/ad
To enable the Jira service in GitLab, you must:
To enable the Jira service in GitLab, you must:
1. Configure the project in Jira.
1.[Configure the project in Jira](dvcs.md#configure-jira-for-dvcs).
1. Enter the correct values in GitLab.
The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`.
1.[Enter the correct values in GitLab](#configure-gitlab).
### Configure GitLab
### Configure GitLab
> **Notes:**
To enable the integration in your GitLab project, after you
>
[configure your Jira project](dvcs.md#configure-jira-for-dvcs):
> - The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`.
> - In order to support Oracle's Access Manager, GitLab sends additional cookies
> to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with
> a value of `fromDialog`.
To enable the Jira integration in a project:
1. Go to the project's [Integrations page](../../user/project/integrations/overview.md#accessing-integrations) and select the
**Jira** service.
1. Ensure your GitLab installation does not use a relative URL, as described in
[Limitations](#limitations).
1. Go to your project and select [**Settings > Integrations**](../../user/project/integrations/overview.md#accessing-integrations).
1. Select **Jira**.
1. Select **Enable integration**.
1. Select **Enable integration**.
1. Select **Trigger** actions. Your choice determines whether a mention of Jira issue
1. Select **Trigger** actions.
(in a GitLab commit, merge request, or both) creates a cross-link in Jira back to GitLab.
This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both,
1. To comment in the Jira issue when a **Trigger** action is made in GitLab, select
should link the Jira issue back to that source commit/MR and transition the Jira issue, if
indicated.
1. To include a comment on the Jira issue when the above reference is made in GitLab, select
**Enable comments**.
**Enable comments**.
1. To transition Jira issues when a
1. To transition Jira issues when a [closing reference](../../user/project/issues/managing_issues.md#closing-issues-automatically) is made in GitLab,
is made in GitLab, select **Enable Jira transitions**.
1. Provide Jira configuration information:
1. Enter the further details on the page as described in the following table.
-**Web URL**: The base URL to the Jira instance web interface you're linking to
this GitLab project, such as `https://jira.example.com`.
| Field | Description |
-**Jira API URL**: The base URL to the Jira instance API, such as `https://jira-api.example.com`.
| ----- | ----------- |
Defaults to the **Web URL** value if not set. Leave blank if using **Jira on Atlassian cloud**.
| `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. For example, `https://jira.example.com`. |
-**Username or Email**: Created when you [configured Jira](dvcs.md#configure-jira-for-dvcs).
| `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira on Atlassian cloud**. |
For **Jira Server**, use `username`. For **Jira on Atlassian cloud**, use `email`.
| `Username or Email` | Created in [configure Jira](dvcs.md#configure-jira-for-dvcs) step. Use `username` for **Jira Server** or `email` for **Jira on Atlassian cloud**. |
-**Password/API token**: Created when you [configured Jira](dvcs.md#configure-jira-for-dvcs).
| `Password/API token` | Created in [configure Jira](dvcs.md#configure-jira-for-dvcs) step. Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**. |
Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**.
1. To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and
1. To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and
enter a Jira project key. **(PREMIUM)**
enter a Jira project key. **(PREMIUM)**
You can only display issues from a single Jira project within a given GitLab project.
You can display issues only from a single Jira project in a given GitLab project.
WARNING:
WARNING:
If you enable Jira issues with the setting above, all users that have access to this GitLab project
If you enable Jira issues with this setting, all users with access to this GitLab project
are able to view all issues from the specified Jira project.
can view all issues from the specified Jira project.
1. To enable creation of issues for vulnerabilities, select **Enable Jira issues creation from vulnerabilities**.
1. Select the **Jira issue type**. If the dropdown is empty, select refresh (**{retry}**) and try again.
1. To enable issue creation for vulnerabilities, select **Enable Jira issues creation from vulnerabilities**.
1. Select the **Jira issue type**. If the dropdown is empty, select refresh (**{retry}**) and try again.
1. To verify the Jira connection is working, select **Test settings**.
1. To verify the Jira connection is working, select **Test settings**.
1. Select **Save changes**.
1. Select **Save changes**.
Your GitLab project can now interact with all Jira projects in your instance and the project now
Your GitLab project can now interact with all Jira projects in your instance and the project now
displays a Jira link that opens the Jira project.
displays a Jira link that opens the Jira project.
## Usage
## Limitations
After the integration is set up on GitLab and Jira, you can:
- Refer to any Jira issue by its ID in GitLab branch names, commit messages, and merge request
titles.
- See the linked branches, commits, and merge requests in Jira issues (merge requests are
called "pull requests" in Jira issues).
Jira issue IDs must be formatted in uppercase for the integration to work.
Click the links to see your GitLab repository data.
This integration is not supported on GitLab instances under a
## Related topics
-[Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in Jira
For more information on using Jira Smart Commits to track time against an issue, specify an issue transition, or add a custom comment, see the Atlassian page [Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html).
## Troubleshooting
## Limitations
### Cookies for Oracle's Access Manager
This integration is not supported on GitLab instances under a
To support Oracle's Access Manager, GitLab sends additional cookies
