ContextQMD
Back to Gitlabhq

GitLab for Jira Cloud app development

doc/development/integrations/jira_connect.md

18.11.211.2 KB
Original Source

Developers have several options for how set up a development environment for the GitLab for Jira Cloud app:

  1. A full environment with Jira. Use this when you need to test interactions with Jira.
  2. A full environment with a Jira Connect proxy. Use this when you need to test multiple GitLab instances connecting to Jira through a Jira Connect proxy, or when testing changes to the Jira Connect proxy itself.
  3. A local environment without Jira. You can use this quicker setup if you do not require Jira, for example when testing the GitLab frontend.

Set up with Jira

The following are required to install the app:

  • A Jira Cloud instance. Atlassian provides free instances for development and testing.

  • A GitLab instance available over the internet. For the app to work, Jira Cloud should 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:

    <!-- vale gitlab_base.Spelling = NO -->

    GitLab team members must not use tunneling tools such as Serveo or ngrok. These are security risks, and must not be run on GitLab developer laptops.

    <!-- vale gitlab_base.Spelling = YES -->

    Jira requires all connections to the app host to be over SSL. If you set up your own environment, remember to enable SSL and an appropriate certificate.

Setting up GitPod

If you are using Gitpod you must make port 3000 public.

Install the app in Jira

To install the app in Jira:

  1. Enable Jira development mode to install apps that are not from the Atlassian Marketplace:

    1. In Jira, go to Jira settings > Apps > Manage apps.
    2. Scroll to the bottom of the Manage apps page and select Settings.
    3. Select Enable development mode and select Apply.

  2. Install the app:

    1. In Jira, go to Jira settings > Apps > Manage apps.

    2. Select Upload app.

    3. 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:

      plaintext
      https://xxxx.gitpod.io/-/jira_connect/app_descriptor.json

    4. Select Upload.

    If the install was successful, you should see the GitLab for Jira Cloud app under Manage apps. You can also select Getting Started to open the configuration page rendered from your GitLab instance.

    [!note] any changes to the app descriptor requires you to uninstall then reinstall the app.

  3. If the Installed and ready to go! dialog opens asking you to Get started, do not get started yet and instead select Close.

  4. You must now set up the OAuth authentication flow.

Set up the GitLab OAuth authentication flow

GitLab for Jira users authenticate with GitLab using GitLab OAuth.

Ensure you have installed the app in Jira first before doing these steps, otherwise the app installation in Jira fails.

The following steps describe setting up an environment to test the GitLab OAuth flow:

  1. Start a Gitpod session.
  2. On your GitLab instance, go to Admin > Applications.
  3. Create a new application with the following settings:
    • Name: GitLab for Jira
    • Redirect URI: YOUR_GITPOD_INSTANCE/-/jira_connect/oauth_callbacks
    • Trusted: No
    • Confidential: No
    • Scopes: api
  4. Copy the Application ID value.
  5. Go to Admin > Settings > General.
  6. Expand GitLab for Jira App.
  7. Paste the Application ID value into Jira Connect Application ID.
  8. In Jira Connect Proxy URL, enter YOUR_GITPOD_INSTANCE (for example, https://xxxx.gitpod.io).
  9. Enable public key storage: Leave unchecked.
  10. Select Save changes.

Set up the app in Jira

Ensure you have set up OAuth first first before doing these steps, otherwise these steps fail.

  1. In Jira, go to Jira settings > Apps > Manage apps.
  2. Scroll to User-installed apps, find your GitLab for Jira Cloud app and expand it.
  3. Select Get started.

You should be able to authenticate with your GitLab instance and begin linking groups.

Troubleshooting

App installation fails

If the app installation fails, you might need to delete jira_connect_installations from your database.

  1. Open the database console.
  2. Run TRUNCATE TABLE jira_connect_installations CASCADE;.

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 will need to make GitPod port public.

Setting up a Jira Connect Proxy

When a GitLab Self-Managed instance installs the GitLab for Jira app from the Atlassian Marketplace, the instance must use GitLab.com as a Jira Connect proxy. You can emulate this setup if you need to develop or test features such as the handling of Jira lifecycle events and branch creation.

To set up a development Jira Connect Proxy:

  • A Jira Cloud instance. Atlassian provides free instances for development and testing.
  • Two GitLab instances available over the internet.

    • One to serve as the Jira Connect proxy (simulating GitLab.com)

    • One to serve as the GitLab instance that will connect to Jira through the Jira Connect proxy

    • For the app to work, Jira Cloud should be able to connect to the Jira Connect proxy 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:

      <!-- vale gitlab_base.Spelling = NO -->

      GitLab team members must not use tunneling tools such as Serveo or ngrok. These are security risks, and must not be run on GitLab developer laptops.

      <!-- vale gitlab_base.Spelling = YES -->

      Jira requires all connections to the app host to be over SSL. If you set up your own environment, remember to enable SSL and an appropriate certificate.

Setting up GitPod

If you are using Gitpod you must make port 3000 public.

Set up the Jira Connect proxy instance

  1. For the Jira Connect proxy instance, follow the GDK with Gitpod instructions to start a new Gitpod workspace.
  2. Set up OAuth authentication on the Jira Connect proxy by following the Set up the GitLab OAuth authentication flow section.
  3. Configure the Jira Connect proxy to serve as a proxy.

Install the GitLab for Jira Cloud app in Jira

Follow the Install the app in Jira section, but use the URL of your Jira Connect proxy instance for the app descriptor:

plaintext
https://JIRA_CONNECT_PROXY_INSTANCE/-/jira_connect/app_descriptor.json

If the Installed and ready to go! dialog opens, select Close (don't select Get started yet).

Set up the secondary GitLab instance

  1. Set up a second GitLab instance using Gitpod, following the same GDK with Gitpod instructions as for the proxy instance

  2. Set up OAuth authentication on this instance following the same steps as in Set up the GitLab OAuth authentication flow, but with a crucial difference:

    • When setting the Redirect URI, use the URL of your Jira Connect proxy instance, not this secondary instance:

      plaintext
      https://JIRA_CONNECT_PROXY_INSTANCE/-/jira_connect/oauth_callbacks

  3. Configure this GitLab instance to use the proxy:

    1. Go to Admin > Settings > General
    2. Expand GitLab for Jira App
    3. Paste the Application ID value into Jira Connect Application ID
    4. In Jira Connect Proxy URL, enter JIRA_CONNECT_PROXY_INSTANCE (for example, https://xxxx.gitpod.io)
    5. Select Save changes

Complete the setup in Jira

  1. In Jira, go to Jira settings > Apps > Manage apps.
  2. Scroll to User-installed apps, find your GitLab for Jira Cloud app and expand it.
  3. Select Get started.
  4. To link the app to the secondary GitLab instance, select Change GitLab version.
  5. Select all checkboxes, then select Next.
  6. In GitLab instance URL ,enter GITLAB_INSTANCE (for example, https://xxxx.gitpod.io), then select Save.
  7. Select Sign in to GitLab.
  8. Select Authorize. A list of groups is now visible.
  9. Select Link groups.
  10. To link to a group, select Link.

Setup without Jira

If you do not require Jira to test with, you can use the Jira connect test tool and your local GDK.

  1. Clone the Jira-connect-test-tool git clone [email protected]:gitlab-org/manage/integrations/jira-connect-test-tool.git.

  2. Start the app bundle exec rackup. (The app requires your GDK GitLab to be available on http://127.0.0.1:3000.).

  3. Open config/gitlab.yml and uncomment the jira_connect config.

  4. If running GDK on a domain other than localhost, you must add the domain to additional_iframe_ancestors. For example:

    yaml
    additional_iframe_ancestors: ['localhost:*', '127.0.0.1:*', 'gdk.test:*']

  5. Restart GDK.

  6. Go to http://127.0.0.1:3000/-/user_settings/personal_access_tokens.

  7. Create a new token with the api scope and copy the token.

  8. Go to http://localhost:9292.

  9. Paste the token and select Install GitLab.com Jira Cloud app.