debian-mirror-gitlab/doc/integration/jira/dvcs.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

284 lines
13 KiB
Markdown
Raw Normal View History

2021-04-29 21:17:54 +05:30
---
2022-11-25 23:54:43 +05:30
stage: Manage
2021-10-27 15:23:28 +05:30
group: Integrations
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2021-04-29 21:17:54 +05:30
---
2021-06-08 01:23:25 +05:30
# Jira DVCS connector **(FREE)**
2021-04-29 21:17:54 +05:30
Use the Jira DVCS (distributed version control system) connector if you self-host
2021-09-30 23:02:18 +05:30
your Jira instance, and you want to sync information
2021-11-11 11:23:49 +05:30
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.
2021-04-29 21:17:54 +05:30
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 Server**: Your network must allow access to your instance.
2021-11-11 11:23:49 +05:30
- **Jira Cloud**: Your instance must be accessible through the internet.
2021-04-29 21:17:54 +05:30
2021-12-11 22:18:48 +05:30
## Smart Commits
2021-04-29 21:17:54 +05:30
When connecting GitLab with Jira with DVCS, you can process your Jira issues using
special commands, called
[Smart Commits](https://support.atlassian.com/jira-software-cloud/docs/process-issues-with-smart-commits/),
in your commit messages. With Smart Commits, you can:
- Comment on issues.
- Record time-tracking information against issues.
- Transition issues to any status defined in the Jira project's workflow.
Commands must be in the first line of the commit message. The
[Jira Software documentation](https://support.atlassian.com/jira-software-cloud/docs/process-issues-with-smart-commits/)
2021-06-08 01:23:25 +05:30
contains more information about how Smart Commits work, and what commands are available
2021-04-29 21:17:54 +05:30
for your use.
2021-06-08 01:23:25 +05:30
For Smart Commits to work, the committing user on GitLab must have a corresponding
2021-04-29 21:17:54 +05:30
user on Jira with the same email address or username.
2021-06-08 01:23:25 +05:30
### Smart Commit syntax
Smart Commits should follow the pattern of:
```plaintext
<ISSUE_KEY> <ignored text> #<command> <optional command parameters>
```
Some examples:
2021-12-11 22:18:48 +05:30
- Add a comment to a Jira issue: `KEY-123 fixes a bug #comment Bug is fixed.`
- Record time tracking: `KEY-123 #time 2w 4d 10h 52m Tracking work time.`
- Close an issue: `KEY-123 #close Closing issue`
2021-06-08 01:23:25 +05:30
A Smart Commit message must not span more than one line (no carriage returns) but
2021-12-11 22:18:48 +05:30
you can still perform multiple actions in a single commit. For example:
2021-06-08 01:23:25 +05:30
2021-12-11 22:18:48 +05:30
- Add time tracking, add a comment, and transition to **Closed**:
```plaintext
KEY-123 #time 2d 5h #comment Task completed ahead of schedule #close
```
- Add a comment, transition to **In-progress**, and add time tracking:
```plaintext
KEY-123 #comment started working on the issue #in-progress #time 12d 5h
```
2021-06-08 01:23:25 +05:30
2021-04-29 21:17:54 +05:30
## Configure a GitLab application for DVCS
2022-07-23 23:45:48 +05:30
For projects in a single group we recommend you create a [group application](../oauth_provider.md#group-owned-applications).
For projects across multiple groups we recommend you create and use a `jira` user in GitLab, and use the account
2021-11-11 11:23:49 +05:30
only for integration work. A separate account ensures regular account
2022-07-23 23:45:48 +05:30
maintenance does not affect your integration. If a `jira` user or group application is not feasible,
you can set up this integration as an [instance-wide application](../oauth_provider.md#instance-wide-applications)
or with a [user owned application](../oauth_provider.md#user-owned-applications) instead.
1. Navigate to the [appropriate **Applications** section](../oauth_provider.md#introduction-to-oauth).
2021-04-29 21:17:54 +05:30
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:
2021-09-04 01:27:46 +05:30
- *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).
2021-11-11 11:23:49 +05:30
- *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`.
2021-04-29 21:17:54 +05:30
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`.
1. For **Scopes**, select `api` and clear any other checkboxes.
2021-12-11 22:18:48 +05:30
- The DVCS connector requires a _write-enabled_ `api` scope to automatically create and manage required webhooks.
2021-04-29 21:17:54 +05:30
1. Select **Submit**.
2021-12-11 22:18:48 +05:30
1. Copy the **Application ID** and **Secret** values.
You need them to configure Jira.
2021-04-29 21:17:54 +05:30
## Configure Jira for DVCS
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:
2021-12-11 22:18:48 +05:30
1. Complete the [GitLab configuration](#configure-a-gitlab-application-for-dvcs).
2021-06-08 01:23:25 +05:30
1. Go to your DVCS accounts:
2021-12-11 22:18:48 +05:30
- *For Jira Server,* select **Settings (gear) > Applications > DVCS accounts**.
- *For Jira Cloud,* select **Settings (gear) > Products > DVCS accounts**.
2021-04-29 21:17:54 +05:30
1. To create a new integration, select the appropriate value for **Host**:
- *For Jira versions 8.14 and later:* Select **GitLab** or
2021-09-04 01:27:46 +05:30
**GitLab Self-Managed**.
2021-12-11 22:18:48 +05:30
- *For Jira Cloud or Jira versions 8.13 and earlier:* Select **GitHub Enterprise**.
2021-04-29 21:17:54 +05:30
1. For **Team or User Account**, enter either:
2021-09-04 01:27:46 +05:30
- *For Jira versions 8.14 and later:*
2021-12-11 22:18:48 +05:30
- The relative path of a top-level GitLab group that
[the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to.
- *For Jira Cloud or Jira versions 8.13 and earlier:*
- The relative path of a top-level GitLab group that
[the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to.
2021-09-04 01:27:46 +05:30
- The relative path of your personal namespace.
2021-04-29 21:17:54 +05:30
1. In the **Host URL** field, enter the URI appropriate for your version of GitLab,
replacing `<gitlab.example.com>` with your GitLab instance domain:
- *For GitLab versions 11.3 and later,* use `https://<gitlab.example.com>`.
- *For GitLab versions 11.2 and earlier,* use
`https://<gitlab.example.com>/-/jira`.
1. For **Client ID**, use the **Application ID** value from the previous section.
1. For **Client Secret**, use the **Secret** value from the previous section.
2021-12-11 22:18:48 +05:30
1. Ensure that the rest of the checkboxes are selected.
1. To create the DVCS account, select **Add** and then **Continue**.
1. Jira redirects to GitLab where you have to confirm the authorization.
GitLab then redirects back to Jira where the synced
projects should display in the new account.
2021-04-29 21:17:54 +05:30
2021-12-11 22:18:48 +05:30
To connect additional GitLab projects from other GitLab top-level groups or
2021-04-29 21:17:54 +05:30
personal namespaces, repeat the previous steps with additional Jira DVCS accounts.
2021-06-08 01:23:25 +05:30
After you configure the integration, read more about [how to test and use it](development_panel.md).
2021-04-29 21:17:54 +05:30
## Refresh data imported to Jira
Jira imports the commits and branches every 60 minutes for your projects. You
can refresh the data manually from the Jira interface:
1. Sign in to your Jira instance as the user you configured the integration with.
1. Go to **Settings (gear) > Applications**.
1. Select **DVCS accounts**.
1. In the table, for the repository you want to refresh, in the **Last Activity**
column, select the icon:
![Refresh GitLab information in Jira](img/jira_dev_panel_manual_refresh.png)
2021-11-11 11:23:49 +05:30
## Troubleshoot your DVCS connection
2021-04-29 21:17:54 +05:30
Refer to the items in this section if you're having problems with your DVCS connector.
### Jira cannot access GitLab server
If you complete the **Add New Account** form, authorize access, and you receive
this error, Jira and GitLab cannot connect. No other error messages
appear in any logs:
```plaintext
Error obtaining access token. Cannot access https://gitlab.example.com from Jira.
```
### SSL and TLS problems
Problems with SSL and TLS can cause this error message:
```plaintext
Error obtaining access token. Cannot access https://gitlab.example.com from Jira.
```
2021-06-08 01:23:25 +05:30
- The [GitLab Jira integration](index.md) requires
2021-04-29 21:17:54 +05:30
GitLab to connect to Jira. Any TLS issues that arise from a private certificate
authority or self-signed certificate are resolved
2022-10-11 01:57:18 +05:30
[on the GitLab server](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates),
2021-04-29 21:17:54 +05:30
as GitLab is the TLS client.
- The Jira Development panel integration requires Jira to connect to GitLab, which
causes Jira to be the TLS client. If your GitLab server's certificate is not
2021-12-11 22:18:48 +05:30
issued by a public certificate authority, add the appropriate certificate
(such as your organization's root certificate) to the Java Truststore on Jira's server.
2021-04-29 21:17:54 +05:30
2021-11-11 11:23:49 +05:30
Refer to Atlassian's documentation and Atlassian Support for assistance setting
up Jira correctly:
2021-04-29 21:17:54 +05:30
- [Add a certificate](https://confluence.atlassian.com/kb/how-to-import-a-public-ssl-certificate-into-a-jvm-867025849.html)
to the trust store.
- The simplest approach is [`keytool`](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html).
- Add additional roots to Java's default Truststore (`cacerts`) to allow Jira to
also trust public certificate authorities.
- If the integration stops working after upgrading Jira's Java runtime, the
`cacerts` Truststore may have been replaced during the upgrade.
2021-12-11 22:18:48 +05:30
- Troubleshoot connectivity [up to and including TLS handshaking](https://confluence.atlassian.com/kb/unable-to-connect-to-ssl-services-due-to-pkix-path-building-failed-error-779355358.html),
using the `SSLPoke` Java class.
2021-04-29 21:17:54 +05:30
- Download the class from Atlassian's knowledge base to a directory on Jira's server, such as `/tmp`.
- Use the same Java runtime as Jira.
- Pass all networking-related parameters that Jira is called with, such as proxy
settings or an alternative root Truststore (`-Djavax.net.ssl.trustStore`):
```shell
${JAVA_HOME}/bin/java -Djavax.net.ssl.trustStore=/var/atlassian/application-data/jira/cacerts -classpath /tmp SSLPoke gitlab.example.com 443
```
The message `Successfully connected` indicates a successful TLS handshake.
If there are problems, the Java TLS library generates errors that you can
look up for more detail.
2021-12-11 22:18:48 +05:30
### Scope error when connecting to Jira using DVCS
2021-04-29 21:17:54 +05:30
```plaintext
The requested scope is invalid, unknown, or malformed.
```
Potential resolutions:
1. Verify that the URL shown in the browser after being redirected from Jira in the
[Jira DVCS connector setup](#configure-jira-for-dvcs) includes `scope=api` in
the query string.
1. If `scope=api` is missing from the URL, edit the
[GitLab account configuration](#configure-a-gitlab-application-for-dvcs). Review
2021-10-27 15:23:28 +05:30
the **Scopes** field and ensure the `api` checkbox is selected.
2021-04-29 21:17:54 +05:30
### Jira error adding account and no repositories listed
After you complete the **Add New Account** form in Jira and authorize access, you might
encounter these issues:
- An `Error! Failed adding the account: [Error retrieving list of repositories]` error.
2021-12-11 22:18:48 +05:30
- An `Account is already integrated with JIRA` error when you select **Try Again**.
2021-04-29 21:17:54 +05:30
- An account is visible in the DVCS accounts view, but no repositories are listed.
To resolve this issue:
2021-12-11 22:18:48 +05:30
- If you're using GitLab Free, ensure you're using GitLab 13.4 or later.
2021-06-08 01:23:25 +05:30
- If you're using GitLab versions 11.10-12.7, upgrade to GitLab 12.8.10 or later
2021-04-29 21:17:54 +05:30
to resolve [an identified issue](https://gitlab.com/gitlab-org/gitlab/-/issues/37012).
[Contact GitLab Support](https://about.gitlab.com/support/) if none of these reasons apply.
2021-11-11 11:23:49 +05:30
### `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).
2021-12-11 22:18:48 +05:30
### Synchronization issues
2021-04-29 21:17:54 +05:30
2021-11-11 11:23:49 +05:30
If Jira displays incorrect information, such as deleted branches, you may have to
2021-12-11 22:18:48 +05:30
resynchronize the information:
1. In Jira, select **Jira Administration > Applications > DVCS accounts**.
1. For the account (group or subgroup), select
**Refresh repositories** from the **{ellipsis_h}** (ellipsis) menu.
1. For each project, next to the **Last activity** date:
- To perform a *soft resync*, select the sync icon.
- To complete a *full sync*, press `Shift` and select the sync icon.
2021-04-29 21:17:54 +05:30
For more information, read
2022-08-27 11:52:29 +05:30
[Atlassian's documentation](https://support.atlassian.com/jira-cloud-administration/docs/integrate-with-development-tools/).
2022-01-26 12:08:38 +05:30
### `Sync Failed` error when refreshing repository data
If you get a `Sync Failed` error in Jira when [refreshing repository data](#refresh-data-imported-to-jira) for specific projects, check your DVCS connector logs. Look for errors that occur when executing requests to API resources in GitLab. For example:
```plaintext
Failed to execute request [https://gitlab.com/api/v4/projects/:id/merge_requests?page=1&per_page=100 GET https://gitlab.com/api/v4/projects/:id/merge_requests?page=1&per_page=100 returned a response status of 403 Forbidden] errors:
{"message":"403 Forbidden"}
```
2022-07-23 23:45:48 +05:30
If you find a `{"message":"403 Forbidden"}` error, it is possible that this specific project has some [GitLab features disabled](../../user/project/settings/index.md#configure-project-visibility-features-and-permissions).
2022-01-26 12:08:38 +05:30
In the example above, the merge requests feature is disabled.
To resolve the issue, enable the relevant feature:
2022-10-11 01:57:18 +05:30
1. On the top bar, select **Main menu > Projects** and find your project.
2022-01-26 12:08:38 +05:30
1. On the left sidebar, select **Settings > General**.
1. Expand **Visibility, project features, permissions**.
1. Use the toggles to enable the features as needed.