Skip to content

G
gitlab-ce
Commit 9d18bd71 authored by Amy Qualls's avatar Amy Qualls
Browse files
Options

Merge branch 'kpaizee-jira-integrations-docs' into 'master' 

Move Jira integration steps to separate page

See merge request gitlab-org/gitlab!66906
parents cefcc037 2762afcb
Hide whitespace changes
Inline Side-by-side
Showing with 70 additions and 62 deletions
doc/integration/jira/configure.md 0 → 100644
View file @ 9d18bd71
---
stage: Create
group: Ecosystem
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
---
# Configure the Jira integration in GitLab
You can set up the [Jira integration](index.md#jira-integration)
by configuring your project settings in GitLab.
You can also configure these settings at a [group level](../../user/admin_area/settings/project_integration_management.md#manage-group-level-default-settings-for-a-project-integration),
and for self-managed GitLab, at an [instance level](../../user/admin_area/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration).
Prerequisites:
- Ensure your GitLab installation does not use a [relative URL](development_panel.md#limitations).
- For **Jira Server**, ensure you have a Jira username and password.
See [authentication in Jira](index.md#authentication-in-jira).
- For **Jira on Atlassian cloud**, ensure you have an API token
and the email address you used to create the token.
See [authentication in Jira](index.md#authentication-in-jira).
To configure your project:
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 **Trigger** actions. Your choice determines whether a mention of Jira issue
(in a GitLab commit, merge request, or both) creates a cross-link in Jira back to GitLab.
1. To comment in the Jira issue when a **Trigger** action is made in GitLab, select
**Enable comments**.
1. To transition Jira issues when a
[closing reference](../../user/project/issues/managing_issues.md#closing-issues-automatically)
is made in GitLab, select **Enable Jira transitions**.
1. Provide Jira configuration information:
- **Web URL**: The base URL to the Jira instance web interface you're linking to
this GitLab project, such as `https://jira.example.com`.
- **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**.
- **Username or Email**:
For **Jira Server**, use `username`. For **Jira on Atlassian cloud**, use `email`.
- **Password/API token**:
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 **(PREMIUM)**, select **Enable Jira issues** and
enter a Jira project key.
You can display issues only from a single Jira project in a given GitLab project.
WARNING:
If you enable Jira issues with this setting, all users with access to this GitLab project
can view all issues from the specified Jira project.
1. To enable issue creation for vulnerabilities **(ULTIMATE)**, 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. Select **Save changes**.
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.
doc/integration/jira/development_panel.md
View file @ 9d18bd71
......@@ -68,8 +68,8 @@ To simplify administration, we recommend that a GitLab group maintainer or group
| 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-app-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). |
| [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. For more information, see the documentation for the [GitLab.com for Jira Cloud app](connect-app.md). | 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-app-for-self-managed-instances) for more information. |
| Your own server | The [Jira DVCS (distributed version control system) connector](dvcs.md). 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 after
configuration, one GitLab project can interact with all Jira projects in that instance. For:
......@@ -82,57 +82,6 @@ configuration, one GitLab project can interact with all Jira projects in that in
If you have a single Jira instance, you can pre-fill the settings. For more information, read the
documentation for [central administration of project integrations](../../user/admin_area/settings/project_integration_management.md).
To enable the integration in GitLab, you must:
1. [Configure the project in Jira](index.md#jira-integration).
The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`.
1. [Enter the correct values in GitLab](#configure-gitlab).
### Configure GitLab
To enable the integration in your GitLab project, after you
[configure your Jira project](index.md#jira-integration):
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 **Trigger** actions. Your choice determines whether a mention of Jira issue
(in a GitLab commit, merge request, or both) creates a cross-link in Jira back to GitLab.
1. To comment in the Jira issue when a **Trigger** action is made in GitLab, select
**Enable comments**.
1. To transition Jira issues when a
[closing reference](../../user/project/issues/managing_issues.md#closing-issues-automatically)
is made in GitLab, select **Enable Jira transitions**.
1. Provide Jira configuration information:
- **Web URL**: The base URL to the Jira instance web interface you're linking to
this GitLab project, such as `https://jira.example.com`.
- **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**.
- **Username or Email**:
For **Jira Server**, use `username`. For **Jira on Atlassian cloud**, use `email`.
See [authentication in Jira](index.md#authentication-in-jira).
- **Password/API token**:
Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**.
See [authentication in Jira](index.md#authentication-in-jira).
1. To enable users to view Jira issues inside the GitLab project **(PREMIUM)**, select **Enable Jira issues** and
enter a Jira project key.
You can display issues only from a single Jira project in a given GitLab project.
WARNING:
If you enable Jira issues with this setting, all users with access to this GitLab project
can view all issues from the specified Jira project.
1. To enable issue creation for vulnerabilities **(ULTIMATE)**, 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. Select **Save changes**.
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.
## Limitations
This integration is not supported on GitLab instances under a
......
doc/integration/jira/index.md
View file @ 9d18bd71
......@@ -26,7 +26,7 @@ The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be).
To set up the integration, [configure the project settings](development_panel.md#configure-gitlab) in GitLab.
To set up the integration, [configure the project settings](configure.md) in GitLab.
You can also configure these settings at a [group level](../../user/admin_area/settings/project_integration_management.md#manage-group-level-default-settings-for-a-project-integration),
and for self-managed GitLab, at an [instance level](../../user/admin_area/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration).
......
doc/integration/jira/issues.md
View file @ 9d18bd71
......@@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Jira integration issue management **(FREE)**
Integrating issue management with Jira requires you to [configure Jira](index.md#jira-integration)
and [enable the Jira service](development_panel.md#configure-gitlab) in GitLab.
and [enable the Jira integration](configure.md) 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.
......@@ -102,7 +102,7 @@ Consider this example:
> [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).
if your GitLab administrator [has configured it](configure.md).
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:
......@@ -149,7 +149,7 @@ 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](development_panel.md#configure-gitlab) instructions.
1. Refer to the [Configure GitLab](configure.md) instructions.
1. Select the **Enable Jira transitions** check box.
1. Select the **Move to Done** option.
......@@ -167,7 +167,7 @@ For advanced workflows, you can specify custom Jira transition IDs:
**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. Refer to the [Configure GitLab](configure.md) 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
......@@ -179,7 +179,7 @@ For advanced workflows, you can specify custom Jira transition IDs:
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. Refer to the [Configure GitLab](configure.md) instructions.
1. Clear the **Enable comments** check box.
## Enable or disable the ability to require an associated Jira issue on merge requests
......
doc/integration/jira/jira_cloud_configuration.md
View file @ 9d18bd71
......@@ -15,8 +15,8 @@ on Atlassian cloud. To create the API token:
1. Select **Create API token** to display a modal window with an API token.
1. To copy the API token, select **Copy to clipboard**, or select **View** and write
down the new API token. You need this value when you
[configure GitLab](development_panel.md#configure-gitlab).
[configure GitLab](configure.md).
You need the newly created token, and the email
address you used when you created it, when you
[configure GitLab](development_panel.md#configure-gitlab).
[configure GitLab](configure.md).
doc/integration/jira/jira_server_configuration.md
View file @ 9d18bd71
......@@ -80,4 +80,4 @@ After creating the group in Jira, grant permissions to the group by creating a p
Write down the new Jira username and its
password, as you need them when
[configuring GitLab](development_panel.md#configure-gitlab).
[configuring GitLab](configure.md).
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