summaryrefslogtreecommitdiff
path: root/doc/integration/jira
diff options
context:
space:
mode:
Diffstat (limited to 'doc/integration/jira')
-rw-r--r--doc/integration/jira/configure.md2
-rw-r--r--doc/integration/jira/connect-app.md28
-rw-r--r--doc/integration/jira/development_panel.md8
-rw-r--r--doc/integration/jira/dvcs.md44
-rw-r--r--doc/integration/jira/index.md13
-rw-r--r--doc/integration/jira/jira_cloud_configuration.md6
-rw-r--r--doc/integration/jira/jira_server_configuration.md2
7 files changed, 58 insertions, 45 deletions
diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md
index b11f367258d..d4e5a1bfca1 100644
--- a/doc/integration/jira/configure.md
+++ b/doc/integration/jira/configure.md
@@ -4,7 +4,7 @@ group: Integrations
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
+# Configure the Jira integration in GitLab **(FREE)**
You can set up the [Jira integration](index.md#jira-integration)
by configuring your project settings in GitLab.
diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md
index e32bd4559f9..7d32c080fff 100644
--- a/doc/integration/jira/connect-app.md
+++ b/doc/integration/jira/connect-app.md
@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
NOTE:
Only Jira users with administrator level access are able to install or configure
-the GitLab app for Jira Cloud.
+the GitLab.com for Jira Cloud app.
## GitLab.com for Jira Cloud app **(FREE SAAS)**
@@ -60,6 +60,14 @@ After a namespace is added:
Support for syncing past branch and commit data is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/263240).
+## Update the GitLab.com for Jira Cloud app
+
+Most updates to the app are fully automated and don't require any user interaction. See the
+[Atlassian Marketplace documentation](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/)
+for details.
+
+If the app requires additional permissions, [the update must first be manually approved in Jira](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/#changes-that-require-manual-customer-approval).
+
## 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
@@ -78,10 +86,10 @@ self-managed GitLab instances with Jira Cloud, you can either:
You can configure your Atlassian Cloud instance to allow you to install applications
from outside the Marketplace, which allows you to install the application:
-1. Sign in to your Jira instance as a user with administrator permissions.
+1. Sign in to your Jira instance as a user with an Administrator role.
1. Place your Jira instance into
[development mode](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-2--enable-development-mode).
-1. Sign in to your GitLab application as a user with [Administrator](../../user/permissions.md) permissions.
+1. Sign in to your GitLab application as a user with an [Administrator](../../user/permissions.md) role.
1. Install the GitLab application from your self-managed GitLab instance, as
described in the [Atlassian developer guides](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-3--install-and-test-your-app):
1. In your Jira instance, go to **Apps > Manage Apps** and click **Upload app**:
@@ -103,13 +111,13 @@ The **GitLab.com for Jira Cloud** app now displays under **Manage apps**. You ca
click **Get started** to open the configuration page rendered from your GitLab instance.
NOTE:
-If you make changes to the application descriptor, you must uninstall, then reinstall, the
+If a GitLab update makes changes to the application descriptor, you must uninstall, then reinstall, the
application.
### Create a Marketplace listing **(FREE SELF)**
If you prefer to not use development mode on your Jira instance, you can create
-your own Marketplace listing for your instance, which enables your application
+your own Marketplace listing for your instance. This enables your application
to be installed from the Atlassian Marketplace.
For full instructions, review the Atlassian [guide to creating a marketplace listing](https://developer.atlassian.com/platform/marketplace/installing-cloud-apps/#creating-the-marketplace-listing). To create a
@@ -127,11 +135,15 @@ Review the
for details.
NOTE:
-DVCS means distributed version control system.
+Using this method, [updates are automated](#update-the-gitlabcom-for-jira-cloud-app)
+the same way as when using our GitLab.com Marketplace listing.
-## Troubleshooting GitLab.com for Jira Cloud app
+## Troubleshoot 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, 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.
+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."
diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md
index c8ea224f18e..5a2ce8a0a75 100644
--- a/doc/integration/jira/development_panel.md
+++ b/doc/integration/jira/development_panel.md
@@ -65,11 +65,11 @@ 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).
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.
+(or, if possible, instance administrator in the case of self-managed GitLab) set up the integration.
| 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. 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. |
+| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab.com 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 app](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.com for Jira Cloud app 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
@@ -89,10 +89,6 @@ This integration is not supported on GitLab instances under a
[relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab).
For example, `http://example.com/gitlab`.
-## Related topics
-
-- [Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in Jira
-
## Troubleshooting
### Cookies for Oracle's Access Manager
diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md
index 7d97312757e..664a0361da4 100644
--- a/doc/integration/jira/dvcs.md
+++ b/doc/integration/jira/dvcs.md
@@ -8,15 +8,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w
Use the Jira DVCS (distributed version control system) connector if you self-host
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.
+between GitLab and Jira. If you use Jira Cloud, 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.
- **Self-managed GitLab**: Your GitLab instance must be accessible by Jira.
-- **Jira Cloud**: Your instance must be accessible through the internet.
- **Jira Server**: Your network must allow access to your instance.
+- **Jira Cloud**: Your instance must be accessible through the internet.
## Smart commits
@@ -61,25 +62,25 @@ you can still perform multiple actions in a single commit:
## Configure a GitLab application for DVCS
-We recommend you create and use a `jira` user in GitLab, and use the account only
-for integration work. A separate account ensures regular account maintenance does not affect
-your integration.
+We recommend you create and use a `jira` user in GitLab, and use the account
+only for integration work. A separate account ensures regular account
+maintenance does not affect your integration. If a `jira` user is not feasible,
+you can set up this integration with your own account instead.
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 with administrator permissions.
+ use to connect to GitLab. This user must be added to each project you want Jira to have access to,
+ or have an [Administrator](../../user/permissions.md) role to access all projects.
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. On the left sidebar, select **Applications**.
1. In the **Name** field, enter a descriptive name for the integration, such as `Jira`.
1. In the **Redirect URI** field, enter the URI appropriate for your version of GitLab,
replacing `<gitlab.example.com>` with your GitLab instance domain:
- *For GitLab versions 13.0 and later* **and** *Jira versions 8.14 and later,* use the
generated `Redirect URL` from
[Linking GitLab accounts with Jira](https://confluence.atlassian.com/adminjiraserver/linking-gitlab-accounts-1027142272.html).
- - *For GitLab versions 13.0 and later* **and** *Jira Cloud,* use `https://<gitlab.example.com>/login/oauth/callback`.
- - *For GitLab versions 11.3 and later,* use `https://<gitlab.example.com>/login/oauth/callback`.
+ - *For GitLab versions 13.0 and later* **and** *Jira Cloud,* use `https://<gitlab.example.com>/login/oauth/callback`.
+ - *For GitLab versions 11.3 and later* **and** *Jira versions 8.13 and earlier,* use `https://<gitlab.example.com>/login/oauth/callback`.
If you use GitLab.com, the URL is `https://gitlab.com/login/oauth/callback`.
- *For GitLab versions 11.2 and earlier,* use
`https://<gitlab.example.com>/-/jira/login/oauth/callback`.
@@ -105,9 +106,9 @@ it completes, refreshes every 60 minutes:
- *For Jira versions 8.13 and earlier:* Select **GitHub Enterprise**.
1. For **Team or User Account**, enter either:
- *For Jira versions 8.14 and later:*
- - The relative path of a top-level GitLab group that you have access to.
+ - The relative path of a top-level GitLab group that [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to.
- *For Jira versions 8.13 and earlier:*
- - The relative path of a top-level GitLab group that you have access to.
+ - The relative path of a top-level GitLab group that [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to.
- The relative path of your personal namespace.
1. In the **Host URL** field, enter the URI appropriate for your version of GitLab,
@@ -141,7 +142,7 @@ can refresh the data manually from the Jira interface:
column, select the icon:
![Refresh GitLab information in Jira](img/jira_dev_panel_manual_refresh.png)
-## Troubleshooting your DVCS connection
+## Troubleshoot your DVCS connection
Refer to the items in this section if you're having problems with your DVCS connector.
@@ -174,7 +175,8 @@ Error obtaining access token. Cannot access https://gitlab.example.com from Jira
must have the appropriate certificate (such as your organization's
root certificate) added to it .
-Refer to Atlassian's documentation and Atlassian Support for assistance setting up Jira correctly:
+Refer to Atlassian's documentation and Atlassian Support for assistance setting
+up Jira correctly:
- [Add a certificate](https://confluence.atlassian.com/kb/how-to-import-a-public-ssl-certificate-into-a-jvm-867025849.html)
to the trust store.
@@ -232,9 +234,17 @@ To resolve this issue:
[Contact GitLab Support](https://about.gitlab.com/support/) if none of these reasons apply.
+### `410 : Gone` error when connecting to Jira
+
+When you connect to Jira and synchronize repositories, you may receive a `410 : Gone` error.
+
+This issue occurs when you use the Jira DVCS connector and your integration is configured to use **GitHub Enterprise**.
+
+For more information and possible fixes, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340160).
+
### Fix synchronization issues
-If Jira displays incorrect information, such as deleted branches, you may need to
+If Jira displays incorrect information, such as deleted branches, you may have to
resynchronize the information. To do so:
1. In Jira, go to **Jira Administration > Applications > DVCS accounts**.
diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md
index febd9907028..85f99b49c41 100644
--- a/doc/integration/jira/index.md
+++ b/doc/integration/jira/index.md
@@ -26,9 +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](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).
+To set up the integration, [configure the settings](configure.md) in GitLab.
### Jira development panel integration
@@ -37,12 +35,9 @@ connects all GitLab projects under a group or personal namespace. When configure
relevant GitLab information, including related branches, commits, and merge requests,
displays in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/).
-To set up the Jira development panel integration:
-
-- *If your installation uses Jira Cloud,* use the
- [GitLab for Jira app](connect-app.md).
-- *If either your Jira or GitLab installation is self-managed,* use the
- [Jira DVCS Connector](dvcs.md).
+To set up the Jira development panel integration, use the GitLab.com for Jira Cloud app
+or the Jira DVCS (distributed version control system) connector,
+[depending on your installation](development_panel.md#configure-the-integration).
### Direct feature comparison
diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md
index e42a102e030..0cfffdb8ba4 100644
--- a/doc/integration/jira/jira_cloud_configuration.md
+++ b/doc/integration/jira/jira_cloud_configuration.md
@@ -11,10 +11,10 @@ on Atlassian cloud. To create the API token:
1. Sign in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens)
with your email address. Use an account with *write* access to Jira projects.
-1. Go to **Settings > API tokens**.
+1. Go to **Settings > Atlassian account settings > Security > Create and manage API tokens**.
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
+1. In the dialog, enter a label for your token and select **Create**.
+1. To copy the API token, select **Copy**, then paste the token somewhere safe. You need this value when you
[configure GitLab](configure.md).
You need the newly created token, and the email
diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md
index 52e7e5e412b..32a8cd430f9 100644
--- a/doc/integration/jira/jira_server_configuration.md
+++ b/doc/integration/jira/jira_server_configuration.md
@@ -25,7 +25,7 @@ This process creates a user named `gitlab` and adds it to a new group named `git
1. Create a new user account (`gitlab`) with write access to
projects in Jira.
- **Email address**: Jira requires a valid email address, and sends a verification
- email, which you need to set up the password.
+ email, which is required to set up the password.
- **Username**: Jira creates the username by using the email prefix. You can change
this username later.
- **Password**: You must create a password, because the GitLab integration doesn't
View Lorry Controller Status