diff options
Diffstat (limited to 'doc/integration/jira')
26 files changed, 875 insertions, 0 deletions
diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md new file mode 100644 index 00000000000..b096d5bff61 --- /dev/null +++ b/doc/integration/jira/connect-app.md @@ -0,0 +1,130 @@ +--- +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 +--- + +# GitLab for Jira app **(FREE SAAS)** + +You can integrate GitLab.com and Jira Cloud using the +[GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) +app in the Atlassian Marketplace. The user configuring GitLab for Jira must have +[Maintainer](../../user/permissions.md) permissions in the GitLab 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. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a walkthrough of the integration with GitLab for Jira, watch +[Configure GitLab Jira Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube. + +1. Go to **Jira Settings > Apps > Find new apps**, then search for GitLab. +1. Click **GitLab for Jira**, then click **Get it now**, or go to the + [App in the marketplace directly](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud). + +  +1. After installing, click **Get started** to go to the configurations page. + This page is always available under **Jira Settings > Apps > Manage apps**. + +  +1. If not already signed in to GitLab.com, you must sign in as a user with + [Maintainer](../../user/permissions.md) permissions to add namespaces. + +  +1. Select **Add namespace** to open the list of available namespaces. + +1. Identify the namespace you want to link, and select **Link**. + +  + +NOTE: +The GitLab user only needs access when adding a new namespace. For syncing with +Jira, we do not depend on the user's token. + +After a namespace is added: + +- All future commits, branches, and merge requests of all projects under that namespace + are synced to Jira. +- From GitLab 13.8, past merge request data is synced to Jira. + +Support for syncing past branch and commit data [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/263240). + +## Install the GitLab Jira Cloud application for self-managed instances **(FREE SELF)** + +If your GitLab instance is self-managed, you must follow some +extra steps to install the GitLab Jira Cloud application. + +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/) +from the location you provide. The manifest file describes the application to the system. To support +self-managed GitLab instances with Jira Cloud, you can either: + +- [Install the application manually](#install-the-application-manually). +- [Create a Marketplace listing](#create-a-marketplace-listing). + +### Install the application manually **(FREE SELF)** + +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. 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. 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**: + +  + + 1. For **App descriptor URL**, provide full URL to your manifest file, modifying this + URL based on your instance configuration: `https://your.domain/your-path/-/jira_connect/app_descriptor.json` + 1. Click **Upload**, and Jira fetches the content of your `app_descriptor` file and installs + it for you. + 1. If the upload is successful, Jira displays a modal panel: **Installed and ready to go!** + Click **Get started** to configure the integration. + +  + +1. Disable [development mode](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-2--enable-development-mode) on your Jira instance. + +The **GitLab for Jira** app now displays under **Manage apps**. You can also +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 +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 +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 +Marketplace listing, you must: + +1. Register as a Marketplace vendor. +1. List your application, using the application descriptor URL. + - Your manifest file is located at: `https://your.domain/your-path/-/jira_connect/app_descriptor.json` + - GitLab recommends you list your application as `private`, because public + applications can be viewed and installed by any user. +1. Generate test license tokens for your application. + +Review the +[official Atlassian documentation](https://developer.atlassian.com/platform/marketplace/installing-cloud-apps/#creating-the-marketplace-listing) +for details. + +NOTE: +DVCS means distributed version control system. + +## Troubleshooting GitLab for Jira + +The GitLab for Jira 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. + +> "You need to sign in or sign up before continuing." + +In this case, use [Firefox](https://www.mozilla.org/en-US/firefox/) or enable cross-site cookies in your browser. diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md new file mode 100644 index 00000000000..1617e950104 --- /dev/null +++ b/doc/integration/jira/development_panel.md @@ -0,0 +1,155 @@ +--- +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 +--- + +# GitLab Jira Development panel integration **(FREE)** + +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/233149) to GitLab Free in 13.4. + +The Jira Development panel integration allows you to reference Jira issues in GitLab, displaying +activity in the [Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) +in the issue. + +It complements the [GitLab Jira integration](../../user/project/integrations/jira.md). You may choose +to configure both integrations to take advantage of both sets of features. See a +[feature comparison](index.md#direct-feature-comparison). + +## Features + +| Your mention of Jira issue ID in GitLab context | Automated effect in Jira issue | +|---------------------------------------------------|--------------------------------------------------------------------------------------------------------| +| 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 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. | + +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: + +- A top-level group. A top-level GitLab group is one that does not have any parent group itself. All + the projects of that top-level group, as well as projects of the top-level group's subgroups nesting + down, are connected. +- 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. + +Additional features provided by the Jira Development Panel integration include: + +- 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](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 + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +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). + +We recommend that a GitLab group maintainer or group owner, or instance administrator (in the case of +self-managed GitLab) set up the integration to simplify administration. + +| If you use Jira on: | 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-gitlab-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). | + +Each GitLab project can be configured to connect to an entire Jira instance. That means one GitLab +project can interact with _all_ Jira projects in that instance, once configured. For: + +- The [view Jira issues](issues.md#view-jira-issues) feature, 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. + +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: + +1. Configure the project in Jira. +1. Enter the correct values in GitLab. + +### Configure GitLab + +> **Notes:** +> +> - 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. Select **Enable integration**. + +1. Select **Trigger** actions. + This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, + 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**. + +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. Enter the further details on the page as described in the following table. + + | Field | Description | + | ----- | ----------- | + | `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`. | + | `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**. | + | `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 in [configure Jira](dvcs.md#configure-jira-for-dvcs) step. 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)** + + You can only display issues from a single Jira project within a given GitLab project. + + WARNING: + If you enable Jira issues with the setting above, all users that have access to this GitLab project + are able to 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 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. + +## Usage + +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. + + + + + +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). + +## Limitations + +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`. diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md new file mode 100644 index 00000000000..5d315ebd802 --- /dev/null +++ b/doc/integration/jira/dvcs.md @@ -0,0 +1,221 @@ +--- +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 +--- + +# Jira DVCS connector + +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. + +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. + +## Smart commits + +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/) +contains more information about how smart commits work, and what commands are available +for your use. + +For smart commits to work, the committing user on GitLab must have a corresponding +user on Jira with the same email address or username. + +## 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. + +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. +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`. +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 11.3 and later,* 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`. + +1. For **Scopes**, select `api` and clear any other checkboxes. +1. Select **Submit**. +1. GitLab displays the generated **Application ID** + and **Secret** values. Copy these values, as you need them to configure Jira. + +## Configure Jira for DVCS + +If you use Jira Cloud and GitLab.com, 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: + +1. Ensure you have completed the [GitLab configuration](#configure-a-gitlab-application-for-dvcs). +1. Go to your DVCS account: + - *For Jira Server,* go to **Settings (gear) > Applications > DVCS accounts**. + - *For Jira Cloud,* go to **Settings (gear) > Products > DVCS accounts**. +1. To create a new integration, select the appropriate value for **Host**: + - *For Jira versions 8.14 and later:* Select **GitLab** or + <!-- vale gitlab.Substitutions = NO --> + **GitLab Self-Hosted**. + <!-- vale gitlab.Substitutions = YES --> + - *For Jira versions 8.13 and earlier:* Select **GitHub Enterprise**. +1. For **Team or User Account**, enter either: + - The relative path of a top-level GitLab group that you have access to. + - The relative path of your personal namespace. + +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. +1. Ensure that the rest of the checkboxes are checked. +1. Select **Add** to complete and create the integration. + +To connect additional GitLab projects from other GitLab top-level groups, or +personal namespaces, repeat the previous steps with additional Jira DVCS accounts. + +After you configure the integration, read more about [how to test and use it](development_panel.md#usage). + +## 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: +  + +## Troubleshooting your DVCS connection + +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. +``` + +- The [GitLab Jira integration](../../user/project/integrations/jira.md) requires + GitLab to connect to Jira. Any TLS issues that arise from a private certificate + authority or self-signed certificate are resolved + [on the GitLab server](https://docs.gitlab.com/omnibus/settings/ssl.html#other-certificate-authorities), + 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 + issued by a public certificate authority, the Java Truststore on Jira's server + 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: + +- [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. + +- Troubleshooting 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 a java class called `SSLPoke`. +- 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. + +### Scope error when connecting Jira via DVCS + +```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 + the **Scopes** field and ensure the `api` check box is selected. + +### 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. +- An `Account is already integrated with JIRA` error when you click **Try Again**. +- An account is visible in the DVCS accounts view, but no repositories are listed. + +To resolve this issue: + +- If you're using GitLab Free or GitLab Starter, be sure you're using + GitLab 13.4 or later. +- *If you're using GitLab versions 11.10-12.7,* upgrade to GitLab 12.8.10 or later + 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. + +### Fix synchronization issues + +If Jira displays incorrect information, such as deleted branches, you may need to +resynchronize the information. To do so: + +1. In Jira, go to **Jira Administration > Applications > DVCS accounts**. +1. At the account (group or subgroup) level, Jira displays an option to + **Refresh repositories** in the **{ellipsis_h}** (ellipsis) menu. +1. For each project, there's a sync button displayed next to the **last activity** date. + - To perform a *soft resync*, click the button. + - To complete a *full sync*, shift-click the button. + +For more information, read +[Atlassian's documentation](https://support.atlassian.com/jira-cloud-administration/docs/synchronize-jira-cloud-to-bitbucket/). diff --git a/doc/integration/jira/img/jira-upload-app-success_v13_11.png b/doc/integration/jira/img/jira-upload-app-success_v13_11.png Binary files differnew file mode 100644 index 00000000000..c0d4c9744b6 --- /dev/null +++ b/doc/integration/jira/img/jira-upload-app-success_v13_11.png diff --git a/doc/integration/jira/img/jira-upload-app_v13_11.png b/doc/integration/jira/img/jira-upload-app_v13_11.png Binary files differnew file mode 100644 index 00000000000..88d1573f778 --- /dev/null +++ b/doc/integration/jira/img/jira-upload-app_v13_11.png diff --git a/doc/integration/jira/img/jira_added_user_to_group.png b/doc/integration/jira/img/jira_added_user_to_group.png Binary files differnew file mode 100644 index 00000000000..f5120a8d42e --- /dev/null +++ b/doc/integration/jira/img/jira_added_user_to_group.png diff --git a/doc/integration/jira/img/jira_create_new_group.png b/doc/integration/jira/img/jira_create_new_group.png Binary files differnew file mode 100644 index 00000000000..4ab7a5eae4e --- /dev/null +++ b/doc/integration/jira/img/jira_create_new_group.png diff --git a/doc/integration/jira/img/jira_dev_panel_jira_setup_3.png b/doc/integration/jira/img/jira_dev_panel_jira_setup_3.png Binary files differnew file mode 100644 index 00000000000..4049a65f56b --- /dev/null +++ b/doc/integration/jira/img/jira_dev_panel_jira_setup_3.png diff --git a/doc/integration/jira/img/jira_dev_panel_jira_setup_4.png b/doc/integration/jira/img/jira_dev_panel_jira_setup_4.png Binary files differnew file mode 100644 index 00000000000..81d84cb173d --- /dev/null +++ b/doc/integration/jira/img/jira_dev_panel_jira_setup_4.png diff --git a/doc/integration/jira/img/jira_dev_panel_jira_setup_5.png b/doc/integration/jira/img/jira_dev_panel_jira_setup_5.png Binary files differnew file mode 100644 index 00000000000..73dc867d301 --- /dev/null +++ b/doc/integration/jira/img/jira_dev_panel_jira_setup_5.png diff --git a/doc/integration/jira/img/jira_dev_panel_manual_refresh.png b/doc/integration/jira/img/jira_dev_panel_manual_refresh.png Binary files differnew file mode 100644 index 00000000000..dc92d533bde --- /dev/null +++ b/doc/integration/jira/img/jira_dev_panel_manual_refresh.png diff --git a/doc/integration/jira/img/jira_dev_panel_setup_com_1.png b/doc/integration/jira/img/jira_dev_panel_setup_com_1.png Binary files differnew file mode 100644 index 00000000000..18f0d5da043 --- /dev/null +++ b/doc/integration/jira/img/jira_dev_panel_setup_com_1.png diff --git a/doc/integration/jira/img/jira_dev_panel_setup_com_2.png b/doc/integration/jira/img/jira_dev_panel_setup_com_2.png Binary files differnew file mode 100644 index 00000000000..31dc13e1271 --- /dev/null +++ b/doc/integration/jira/img/jira_dev_panel_setup_com_2.png diff --git a/doc/integration/jira/img/jira_dev_panel_setup_com_3_v13_9.png b/doc/integration/jira/img/jira_dev_panel_setup_com_3_v13_9.png Binary files differnew file mode 100644 index 00000000000..fe791637d31 --- /dev/null +++ b/doc/integration/jira/img/jira_dev_panel_setup_com_3_v13_9.png diff --git a/doc/integration/jira/img/jira_dev_panel_setup_com_4_v13_9.png b/doc/integration/jira/img/jira_dev_panel_setup_com_4_v13_9.png Binary files differnew file mode 100644 index 00000000000..08787f12b67 --- /dev/null +++ b/doc/integration/jira/img/jira_dev_panel_setup_com_4_v13_9.png diff --git a/doc/integration/jira/img/jira_group_access.png b/doc/integration/jira/img/jira_group_access.png Binary files differnew file mode 100644 index 00000000000..42a9b4ae564 --- /dev/null +++ b/doc/integration/jira/img/jira_group_access.png diff --git a/doc/integration/jira/img/jira_issue_detail_view_v13.10.png b/doc/integration/jira/img/jira_issue_detail_view_v13.10.png Binary files differnew file mode 100644 index 00000000000..bf1607a35fe --- /dev/null +++ b/doc/integration/jira/img/jira_issue_detail_view_v13.10.png diff --git a/doc/integration/jira/img/jira_issue_reference.png b/doc/integration/jira/img/jira_issue_reference.png Binary files differnew file mode 100644 index 00000000000..db8bc4f0bb9 --- /dev/null +++ b/doc/integration/jira/img/jira_issue_reference.png diff --git a/doc/integration/jira/img/jira_merge_request_close.png b/doc/integration/jira/img/jira_merge_request_close.png Binary files differnew file mode 100644 index 00000000000..9a176daf5f4 --- /dev/null +++ b/doc/integration/jira/img/jira_merge_request_close.png diff --git a/doc/integration/jira/img/jira_project_settings.png b/doc/integration/jira/img/jira_project_settings.png Binary files differnew file mode 100644 index 00000000000..d96002b7db8 --- /dev/null +++ b/doc/integration/jira/img/jira_project_settings.png diff --git a/doc/integration/jira/img/jira_service_close_issue.png b/doc/integration/jira/img/jira_service_close_issue.png Binary files differnew file mode 100644 index 00000000000..73d6498192c --- /dev/null +++ b/doc/integration/jira/img/jira_service_close_issue.png diff --git a/doc/integration/jira/img/open_jira_issues_list_v13.2.png b/doc/integration/jira/img/open_jira_issues_list_v13.2.png Binary files differnew file mode 100644 index 00000000000..0cf58433b25 --- /dev/null +++ b/doc/integration/jira/img/open_jira_issues_list_v13.2.png diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md new file mode 100644 index 00000000000..221e50e5d66 --- /dev/null +++ b/doc/integration/jira/index.md @@ -0,0 +1,91 @@ +--- +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 +--- + +# 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 +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. + +## Compare Jira 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. + +<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 + +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): + +- *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). + +### Jira development panel integration + +The [Jira development panel integration](development_panel.md) +connects all GitLab projects under a group or personal namespace. When configured, +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/). + +### Direct feature comparison + +| Capability | Jira integration | Jira Development panel integration | +|-|-|-| +| Mention a Jira issue ID in a GitLab commit or merge request, and a link to the Jira issue is created. | Yes. | No. | +| Mention a Jira issue ID in GitLab and the Jira issue shows the GitLab issue or merge request. | Yes. A Jira comment with the GitLab issue or MR title links to GitLab. The first mention is also added to the Jira issue under **Web links**. | Yes, in the issue's Development panel. | +| Mention a Jira issue ID in a GitLab commit message and the Jira issue shows the commit message. | Yes. The entire commit message is displayed in the Jira issue as a comment and under **Web links**. Each message links back to the commit in GitLab. | Yes, in the issue's Development panel and optionally with a custom comment on the Jira issue using Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html). | +| Mention a Jira issue ID in a GitLab branch name and the Jira issue shows the branch name. | No. | Yes, in the issue's [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). | +| 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. | + +## Authentication in Jira + +The process for configuring Jira depends on whether you host Jira on your own server or on +[Atlassian cloud](https://www.atlassian.com/cloud): + +- **Jira Server** supports basic authentication. When connecting, a **username and password** are + required. Connecting to Jira Server via CAS is not possible. For more information, read + how to [set up a user in Jira Server](jira_server_configuration.md). +- **Jira on Atlassian cloud** supports authentication through an API token. When connecting to Jira on + Atlassian cloud, an email and API token are required. For more information, read + [set up a user in Jira on Atlassian cloud](jira_cloud_configuration.md). + +## Troubleshooting + +If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured. + +### GitLab is unable to comment on a Jira issue + +Make sure that the Jira user you set up for the integration has the +correct access permission to post comments on a Jira issue and also to transition +the issue, if you'd like GitLab to also be able to do so. +Jira issue references and update comments do not work if the GitLab issue tracker is disabled. + +### GitLab is unable to close a Jira issue + +Make sure the `Transition ID` you set within the Jira settings matches the one +your project needs to close an issue. + +Make sure that the Jira issue is not already marked as resolved; that is, +the Jira issue resolution field is not set. (It should not be struck through in +Jira lists.) + +### CAPTCHA + +CAPTCHA may be triggered after several consecutive failed login attempts +which may lead to a `401 unauthorized` error when testing your Jira integration. +If CAPTCHA has been triggered, you can't use Jira's REST API to +authenticate with the Jira site. You need to log in to your Jira instance +and complete the CAPTCHA. diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md new file mode 100644 index 00000000000..d2cab59742b --- /dev/null +++ b/doc/integration/jira/issues.md @@ -0,0 +1,173 @@ +--- +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 +--- + +# Jira integration issue management **(FREE)** + +By now you should have [configured Jira](development_panel.md#configuration) and enabled the +[Jira service in GitLab](development_panel.md#configure-gitlab). If everything is set up correctly +you should be able to reference and close Jira issues by just mentioning their +ID in GitLab commits and merge requests. + +Jira issue IDs must be formatted in uppercase for the integration to work. + +## Reference Jira issues + +When GitLab project has Jira issue tracker configured and enabled, mentioning +Jira issues in GitLab automatically adds a comment in Jira issue with the +link back to GitLab. This means that in comments in merge requests and commits +referencing an issue, `PROJECT-7` for example, adds a comment in Jira issue in the +format: + +```plaintext +USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: +ENTITY_TITLE +``` + +- `USER` A user that mentioned the issue. This is the link to the user profile in GitLab. +- `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where Jira issue was mentioned. +- `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request. +- `PROJECT_NAME` GitLab project name. +- `ENTITY_TITLE` Merge request title or commit message first line. + + + +For example, the following commit references the Jira issue with `PROJECT-1` as its ID: + +```shell +git commit -m "PROJECT-1 Fix spelling and grammar" +``` + +## Close Jira issues + +Jira issues can be closed directly from GitLab by using trigger words in +commits and merge requests. When a commit which contains the trigger word +followed by the Jira issue ID in the commit message is pushed, GitLab +adds a comment in the mentioned Jira issue and immediately closes it (provided +the transition ID was set up correctly). + +There are currently three trigger words, and you can use either one to achieve +the same goal: + +- `Resolves PROJECT-1` +- `Closes PROJECT-1` +- `Fixes PROJECT-1` + +where `PROJECT-1` is the ID of the Jira issue. + +Note the following: + +- Only commits and merges into the project's default branch (usually `master`) + close an issue in Jira. You can change your project's default branch under + [project settings](img/jira_project_settings.png). +- The Jira issue is not transitioned if it has a resolution. + +Let's consider the following example: + +1. For the project named `PROJECT` in Jira, we implemented a new feature + and created a merge request in GitLab. +1. This feature was requested in Jira issue `PROJECT-7` and the merge request + in GitLab contains the improvement +1. In the merge request description we use the issue closing trigger + `Closes PROJECT-7`. +1. Once the merge request is merged, the Jira issue is automatically closed + with a comment and an associated link to the commit that resolved the issue. + +In the following screenshot you can see what the link references to the Jira +issue look like. + + + +Once this merge request is merged, the Jira issue is automatically closed +with a link to the commit that resolved the issue. + + + +## View Jira issues **(PREMIUM)** + +> [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): + +1. In the left navigation bar, go to **Jira > Issues list**. +1. The issue list sorts by **Created date** by default, with the newest issues listed at the top: + +  + +1. To display the most recently updated issues first, click **Last updated**. +1. In GitLab versions 13.10 and later, you can view [individual Jira issues](#view-a-jira-issue). + +Issues are grouped into tabs based on their [Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html): + +- The **Open** tab displays all issues with a Jira status in any category other than Done. +- The **Closed** tab displays all issues with a Jira status categorized as Done. +- The **All** tab displays all issues of any status. + +## View a Jira issue + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10 behind a feature flag, disabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.11. + +When viewing the [Jira issues list](#view-jira-issues), select an issue from the +list to open it in GitLab: + + + +## Search and filter the issues list + +To refine the list of issues, use the search bar to search for any text +contained in an issue summary (title) or description. + +You can also filter by labels, status, reporter, and assignee using URL parameters. +Enhancements to be able to use these through the user interface are [planned](https://gitlab.com/groups/gitlab-org/-/epics/3622). + +- To filter issues by `labels`, specify one or more labels as part of the `labels[]` +parameter in the URL. When using multiple labels, only issues that contain all specified +labels are listed. `/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA` + +- To filter issues by `status`, specify the `status` parameter in the URL. +`/-/integrations/jira/issues?status=In Progress` + +- To filter issues by `reporter`, specify a reporter's Jira display name for the +`author_username` parameter in the URL. `/-/integrations/jira/issues?author_username=John Smith` + +- To filter issues by `assignee`, specify their Jira display name for the +`assignee_username` parameter in the URL. `/-/integrations/jira/issues?assignee_username=John Smith` + +## Automatic issue transitions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/...) in GitLab 13.10. + +In this mode the referenced Jira issue is transitioned to the next available status with a category of "Done". + +See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting and select the **Move to Done** option. + +## Custom issue transitions + +For advanced workflows you can specify custom Jira transition IDs. + +See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting, select the **Custom transitions** option, and enter your transition IDs in the text field. + +If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. If a transition fails the sequence is aborted. + +To see the transition IDs on Jira Cloud, edit a workflow in the **Text** view. +The transition IDs display in the **Transitions** column. + +On Jira Server you can get the transition IDs in either of the following ways: + +1. By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions` + using an issue that is in the appropriate "open" state +1. By mousing over the link for the transition you want and looking for the + "action" parameter in the URL + +Note that the transition ID may vary between workflows (for example, bug vs. story), +even if the status you are changing to is the same. + +## Disabling comments on Jira issues + +You can continue to have GitLab cross-link a source commit/MR with a Jira issue while disabling the comment added to the issue. + +See the [Configure GitLab](development_panel.md#configure-gitlab) section and uncheck the **Enable comments** setting. diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md new file mode 100644 index 00000000000..fd58b3f33f7 --- /dev/null +++ b/doc/integration/jira/jira_cloud_configuration.md @@ -0,0 +1,22 @@ +--- +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 +--- + +# Create an API token in Jira on Atlassian cloud **(FREE)** + +You need an API token to [integrate with Jira](../../user/project/integrations/jira.md) +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. 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). + +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). diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md new file mode 100644 index 00000000000..3573a1f8b1e --- /dev/null +++ b/doc/integration/jira/jira_server_configuration.md @@ -0,0 +1,83 @@ +--- +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 +--- + +# Jira Server credentials **(FREE)** + +To [integrate Jira with GitLab](../../user/project/integrations/jira.md), you must +create a Jira user account for your Jira projects to access projects in GitLab. +This Jira user account must have write access to your Jira projects. To create the +credentials, you must: + +1. [Create a Jira Server user](#create-a-jira-server-user). +1. [Create a Jira Server group](#create-a-jira-server-group) for the user to belong to. +1. [Create a permission scheme for your group](#create-a-permission-scheme-for-your-group). + +## Create a Jira Server user + +This process creates a user named `gitlab` and adds it to a new group named `gitlab-developers`: + +1. Sign in to your Jira instance as an administrator. +1. In the upper right corner of the top menu, go to the gear icon and + select **User Management**. +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. + - **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 + support SSO, such as SAML. To create the password, visit the user profile, look up + the username, and set a password. +1. Select **Create user**. + +After you create the user, create a group for it. + +## Create a Jira Server group + +After you [create a Jira Server user](#create-a-jira-server-user), you can create a +group to assign permissions to the user: + +1. Sign in to your Jira instance as an administrator. +1. In the upper right corner of the top menu, go to the gear icon and + select **User Management**. +1. From the sidebar, select **Groups**. + +  + +1. In the **Add group** section, enter a **Name** for the group (for example, + `gitlab-developers`), and then select **Add group**. +1. To add the `gitlab` user to the `gitlab-developers` group, select **Edit members**. + The `gitlab-developers` group should be listed in the leftmost box as a + selected group. +1. In the **Add members to selected group(s)** area, enter `gitlab`. +1. Select **Add selected users**. +Jira saves your selection, and `gitlab` should appear in the **Group member(s)** +area. + + + +Next, create a permission scheme for your group. + +## Create a permission scheme for your group + +After creating the group in Jira, grant permissions to the group by creating a permission scheme: + +1. Sign in to your Jira instance as an administrator. +1. In the upper right corner of the top menu, go to the gear icon and + select **Issues**. +1. From the sidebar, select **Permission Schemes**. +1. Select **Add Permission Scheme**, enter a **Name** and (optionally) a + **Description**, and then select **Add**. +1. In the permissions scheme list, locate your new permissions scheme, and + select **Permissions**. +1. Next to **Administer Projects**, select **Edit**. In + the **Group** list, select `gitlab-developers`. + +  + +Write down the new Jira username and its +password, as you need them when +[configuring GitLab](development_panel.md#configure-gitlab). |
