Skip to content

G
gitlab-ce
Commit 41c6e592 authored by Kati Paizee's avatar Kati Paizee
Browse files
Options

Merge branch 'bbodenmiller-master-patch-18051' into 'master' 

Improve Jira docs

See merge request gitlab-org/gitlab!65384
parents 267f4299 15926271
Hide whitespace changes
Inline Side-by-side
Showing with 45 additions and 43 deletions
doc/integration/jira/connect-app.md
View file @ 41c6e592
......@@ -4,21 +4,24 @@ 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
---
# GitLab.com for Jira Cloud app **(FREE SAAS)**
# GitLab.com for Jira Cloud app **(FREE)**
## GitLab.com for Jira Cloud app **(FREE SAAS)**
You can integrate GitLab.com and Jira Cloud using the
[GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud)
app in the Atlassian Marketplace. The user configuring GitLab.com for Jira Cloud must have
app in the Atlassian Marketplace. The user configuring GitLab.com for Jira Cloud app must have
[Maintainer](../../user/permissions.md) permissions in the GitLab.com namespace.
This integration method supports [smart commits](dvcs.md#smart-commits).
This method is recommended when using GitLab.com and Jira Cloud because data is
synchronized in real-time. The DVCS connector updates data only once per hour.
If you are not using both of these environments, use the [Jira DVCS Connector](dvcs.md) method.
If you are not using both of these environments, use the [Jira DVCS Connector](dvcs.md) method or
[steps to install GitLab.com for Jira Cloud app for self-managed instances](#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances).
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For a walkthrough of the integration with GitLab.com for Jira Cloud, watch
For a walkthrough of the integration with GitLab.com for Jira Cloud app, watch
[Configure GitLab.com Jira Could Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube.
1. Go to **Jira Settings > Apps > Find new apps**, then search for GitLab.
......@@ -52,10 +55,10 @@ After a namespace is added:
Support for syncing past branch and commit data [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/263240).
## Install the GitLab.com for Jira Cloud application for self-managed instances **(FREE SELF)**
## Install the GitLab.com for Jira Cloud app for self-managed instances **(FREE SELF)**
If your GitLab instance is self-managed, you must follow some
extra steps to install the GitLab.com for Jira Cloud application.
extra steps to install the GitLab.com for Jira Cloud app.
Each Jira Cloud application must be installed from a single location. Jira fetches
a [manifest file](https://developer.atlassian.com/cloud/jira/platform/connect-app-descriptor/)
......@@ -121,9 +124,9 @@ for details.
NOTE:
DVCS means distributed version control system.
## Troubleshooting GitLab.com for Jira Cloud
## Troubleshooting GitLab.com for Jira Cloud app
The GitLab.com for Jira Cloud app uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies. This can lead to a message saying that the user needs to log in on GitLab.com even though the user is already logged in.
The GitLab.com for Jira Cloud app uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies, which can lead to a message saying that the user needs to log in on GitLab.com even though the user is already logged in.
> "You need to sign in or sign up before continuing."
......
doc/integration/jira/development_panel.md
View file @ 41c6e592
......@@ -31,11 +31,6 @@ This integration connects all GitLab projects to projects in the Jira instance i
including the projects in its subgroups.
- A personal namespace: Connects the projects in that personal namespace to Jira.
This differs from the [Jira integration](index.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:
......@@ -44,7 +39,8 @@ After the integration is [set up on GitLab and Jira](#configure-the-integration)
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.
At this time, merge requests are called "pull requests" in Jira issues.
This name may change in a future Jira release.
Select the links to see your GitLab repository data.
......@@ -72,13 +68,13 @@ 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-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-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). |
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:
- 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 **(PREMIUM)**, you must associate a GitLab project with a
specific Jira project.
- Other features, you do not have to explicitly associate a GitLab project with any single Jira
project.
......@@ -86,16 +82,16 @@ 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 Jira service in GitLab, you must:
To enable the integration in GitLab, you must:
1. [Configure the project in Jira](dvcs.md#configure-jira-for-dvcs).
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](dvcs.md#configure-jira-for-dvcs):
[configure your Jira project](index.md#jira-integration):
1. Ensure your GitLab installation does not use a relative URL, as described in
[Limitations](#limitations).
......@@ -114,12 +110,14 @@ To enable the integration in your GitLab project, after you
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**: Created when you [configured Jira](dvcs.md#configure-jira-for-dvcs).
- **Username or Email**:
For **Jira Server**, use `username`. For **Jira on Atlassian cloud**, use `email`.
- **Password/API token**: Created when you [configured Jira](dvcs.md#configure-jira-for-dvcs).
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**.
1. To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and
enter a Jira project key. **(PREMIUM)**
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.
......@@ -127,7 +125,7 @@ To enable the integration in your GitLab project, after you
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, select **Enable Jira issues creation from vulnerabilities**.
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**.
......
doc/integration/jira/dvcs.md
View file @ 41c6e592
......@@ -7,9 +7,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Jira DVCS connector **(FREE)**
Use the Jira DVCS (distributed version control system) connector if you self-host
either your Jira instance or your GitLab instance, and you want to sync information
between them. If you use Jira Cloud and GitLab.com, you should use the
[GitLab for Jira app](connect-app.md) unless you specifically need the DVCS connector.
your Jira instance, and you want to sync information
between GitLab and Jira. If you use Jira Cloud and GitLab.com, you should use the
[GitLab.com for Jira Cloud app](connect-app.md) unless you specifically need the DVCS connector.
When you configure the Jira DVCS connector, make sure your GitLab and Jira instances
are accessible.
......@@ -67,8 +67,9 @@ your integration.
1. In GitLab, [create a user](../../user/profile/account/create_accounts.md) for Jira to
use to connect to GitLab. For Jira to access all projects,
a user with [Administrator](../../user/permissions.md) permissions must
create the user.
a user with [administrator](../../user/permissions.md) permissions must
create the user with administrator permissions.
1. Sign in as the `jira` user.
1. In the top right corner, click the account's avatar, and select **Edit profile**.
1. In the left sidebar, select **Applications**.
1. In the **Name** field, enter a descriptive name for the integration, such as `Jira`.
......@@ -90,9 +91,6 @@ your integration.
## Configure Jira for DVCS
If you use Jira Cloud, use the [GitLab for Jira app](connect-app.md)
unless you specifically need the DVCS Connector.
Configure this connection when you want to import all GitLab commits and branches,
for the groups you specify, into Jira. This import takes a few minutes and, after
it completes, refreshes every 60 minutes:
......
doc/integration/jira/index.md
View file @ 41c6e592
......@@ -7,12 +7,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Jira integrations **(FREE)**
If your organization uses [Jira](https://www.atlassian.com/software/jira) issues,
you can [migrate](../../user/project/import/jira.md) your issues from Jira and work
you can [migrate your issues from Jira](../../user/project/import/jira.md) **(PREMIUM)** and work
exclusively in GitLab. However, if you'd like to continue to use Jira, you can
integrate it with GitLab. GitLab offers two types of Jira integrations, and you
can use one or both depending on the capabilities you need.
can use one or both depending on the capabilities you need. It is recommended that you enable both.
## Compare Jira integrations
## Compare integrations
After you set up one or both of these integrations, you can cross-reference activity
in your GitLab project with any of your projects in Jira.
......@@ -20,10 +20,13 @@ in your GitLab project with any of your projects in Jira.
<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).
### Per-project Jira integration
### Jira integration
This integration connects a single GitLab project to a Jira instance. The Jira instance
can be hosted by you or in [Atlassian cloud](https://www.atlassian.com/cloud):
This integration connects one or more GitLab project to a Jira instance. The Jira instance
can be hosted by you or in [Atlassian cloud](https://www.atlassian.com/cloud).
The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`.
To simplify administration, we recommend that a GitLab group maintainer or group owner
(or instance administrator in the case of self-managed GitLab) set up the integration.
- *If your installation uses Jira Cloud,* use the
[GitLab for Jira app](connect-app.md).
......@@ -48,7 +51,7 @@ displays in the [development panel](https://support.atlassian.com/jira-software-
| Add Jira time tracking to an issue. | No. | Yes. Time can be specified using Jira Smart Commits. |
| Use a Git commit or merge request to transition or close a Jira issue. | Yes. Only a single transition type, typically configured to close the issue by setting it to Done. | Yes. Transition to any state using Jira Smart Commits. |
| Display a list of Jira issues. | Yes. **(PREMIUM)** | No. |
| Create a Jira issue from a vulnerability or finding. **(ULTIMATE)** | Yes. | No. |
| Create a Jira issue from a vulnerability or finding. | Yes. **(ULTIMATE)** | No. |
## Authentication in Jira
......@@ -64,10 +67,10 @@ The process for configuring Jira depends on whether you host Jira on your own se
## Privacy considerations
If you integrate a private GitLab project with Jira using the [**Per-project Jira integration**](#per-project-jira-integration),
If you integrate a private GitLab project with Jira using the [**Jira integration**](#jira-integration),
actions in GitLab issues and merge requests linked to a Jira issue leak information
about the private project to non-administrator Jira users. If your installation uses Jira Cloud,
you can use the [GitLab for Jira app](connect-app.md) to avoid this risk.
you can use the [GitLab.com for Jira Cloud app](connect-app.md) to avoid this risk.
## Troubleshooting
......
doc/integration/jira/issues.md
View file @ 41c6e592
......@@ -6,7 +6,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](development_panel.md#configure-the-integration)
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.
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.
......@@ -122,7 +122,7 @@ Issues are grouped into tabs based on their
- **Closed** tab: All issues with a Jira status categorized as Done.
- **All** tab: All issues of any status.
## Search and filter the issues list
### Search and filter the issues 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
......
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