debian-mirror-gitlab/doc/development/integrations/jira_connect.md

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

113 lines
4.5 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +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-01-29 00:20:46 +05:30
---
2019-07-31 22:56:46 +05:30
2021-04-17 20:07:23 +05:30
# Set up a development environment **(FREE)**
2019-07-31 22:56:46 +05:30
2021-01-29 00:20:46 +05:30
The following are required to install and test the app:
2019-07-31 22:56:46 +05:30
2021-01-29 00:20:46 +05:30
- A Jira Cloud instance. Atlassian provides [free instances for development and testing](https://developer.atlassian.com/platform/marketplace/getting-started/#free-developer-instances-to-build-and-test-your-app).
- A GitLab instance available over the internet. For the app to work, Jira Cloud should
2021-03-08 18:12:59 +05:30
be able to connect to the GitLab instance through the internet. For this we
recommend using Gitpod or a similar cloud development environment. For more
information on using Gitpod with GDK, see the:
2019-07-31 22:56:46 +05:30
2021-03-08 18:12:59 +05:30
- [GDK in Gitpod](https://www.loom.com/share/9c9711d4876a40869b9294eecb24c54d)
video.
2021-06-08 01:23:25 +05:30
- [GDK with Gitpod](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/gitpod.md)
2021-03-08 18:12:59 +05:30
documentation.
2021-10-27 15:23:28 +05:30
<!-- vale gitlab.Spelling = NO -->
You **must not** use tunneling tools such as Serveo or `ngrok`. These are
2021-03-08 18:12:59 +05:30
security risks, and must not be run on developer laptops.
2021-10-27 15:23:28 +05:30
<!-- vale gitlab.Spelling = YES -->
2021-03-11 19:13:27 +05:30
Jira requires all connections to the app host to be over SSL. If you set up
2021-03-08 18:12:59 +05:30
your own environment, remember to enable SSL and an appropriate certificate.
2019-07-31 22:56:46 +05:30
2021-01-29 00:20:46 +05:30
## Install the app in Jira
2019-07-31 22:56:46 +05:30
2021-01-29 00:20:46 +05:30
To install the app in Jira:
2019-07-31 22:56:46 +05:30
2021-01-29 00:20:46 +05:30
1. Enable Jira development mode to install apps that are not from the Atlassian
Marketplace:
2019-07-31 22:56:46 +05:30
2021-01-29 00:20:46 +05:30
1. In Jira, navigate to **Jira settings > Apps > Manage apps**.
2022-07-23 23:45:48 +05:30
1. Scroll to the bottom of the **Manage apps** page and select **Settings**.
1. Select **Enable development mode** and select **Apply**.
2019-07-31 22:56:46 +05:30
2021-01-29 00:20:46 +05:30
1. Install the app:
2019-07-31 22:56:46 +05:30
2021-01-29 00:20:46 +05:30
1. In Jira, navigate to **Jira settings > Apps > Manage apps**.
2022-07-23 23:45:48 +05:30
1. Select **Upload app**.
2019-07-31 22:56:46 +05:30
1. In the **From this URL** field, provide a link to the app descriptor. The host and port must point to your GitLab instance.
For example:
2019-09-30 21:07:59 +05:30
2020-04-22 19:07:51 +05:30
```plaintext
2021-03-08 18:12:59 +05:30
https://xxxx.gitpod.io/-/jira_connect/app_descriptor.json
2019-07-31 22:56:46 +05:30
```
2019-09-30 21:07:59 +05:30
2022-07-23 23:45:48 +05:30
1. Select **Upload**.
2019-07-31 22:56:46 +05:30
2021-11-11 11:23:49 +05:30
If the install was successful, you should see the **GitLab.com for Jira Cloud** app under **Manage apps**.
2022-07-23 23:45:48 +05:30
You can also select **Getting Started** to open the configuration page rendered from your GitLab instance.
2019-07-31 22:56:46 +05:30
_Note that any changes to the app descriptor requires you to uninstall then reinstall the app._
2021-02-22 17:27:13 +05:30
### Troubleshooting
If the app install failed, you might need to delete `jira_connect_installations` from your database.
2021-06-08 01:23:25 +05:30
1. Open the [database console](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/postgresql.md#access-postgresql).
2021-02-22 17:27:13 +05:30
1. Run `TRUNCATE TABLE jira_connect_installations CASCADE;`.
2022-05-07 20:08:51 +05:30
#### Not authorized to access the file
If you use Gitpod and you get an error about Jira not being able to access the descriptor file, you might need to make the GDK's port public by following these steps:
1. Open your GitLab workspace in Gitpod.
1. When the GDK is running, select **Ports** in the bottom-right corner.
1. On the left sidebar, select the port the GDK is listening to (typically `3000`).
1. If the port is marked as private, select the lock icon to make it public.
## Test the GitLab OAuth authentication flow
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/81126) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `jira_connect_oauth`. Disabled by default.
2022-06-21 17:19:12 +05:30
GitLab for Jira users can authenticate with GitLab using GitLab OAuth.
2022-05-07 20:08:51 +05:30
WARNING:
This feature is not ready for production use. The feature flag should only be enabled in development.
The following steps describe setting up an environment to test the GitLab OAuth flow:
1. Start a Gitpod session and open the rails console.
```shell
bundle exec rails console
```
1. Enable the feature flag.
```shell
Feature.enable(:jira_connect_oauth)
```
1. On your GitLab instance, go to **Admin > Applications**.
1. Create a new application with the following settings:
- Name: `Jira Connect`
- Redirect URI: `YOUR_GITPOD_INSTANCE/-/jira_connect/oauth_callbacks`
- Scopes: `api`
- Trusted: **No**
- Confidential: **No**
1. Copy the Application ID.
2022-07-23 23:45:48 +05:30
1. Go to **Admin > Settings > General**.
1. Scroll down and expand the GitLab for Jira App section.
2022-05-07 20:08:51 +05:30
1. Go to [gitpod.io/variables](https://gitpod.io/variables).
2022-07-23 23:45:48 +05:30
1. Paste the Application ID into the **Jira Connect Application ID** field and click **Save changes**