Skip to content

Set up a Jira development environment

The following are required to install and test 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:

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

    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.

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, navigate 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, navigate 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:

      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 that any changes to the app descriptor requires you to uninstall then reinstall the app.

Simple setup

To avoid external dependencies like Gitpod and a Jira Cloud instance, use the Jira connect test tool and your local GDK:

  1. Clone the Jira-connect-test-tool git clone git@gitlab.com: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:

    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.

Test the GitLab OAuth authentication flow

GitLab for Jira users can authenticate with GitLab using GitLab OAuth.

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. Select Enable public key storage.
  10. Select Save changes.

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 might need to make the GDK port public by following these steps:

  1. Open your GitLab workspace in Gitpod.
  2. When the GDK is running, select Ports in the bottom-right corner.
  3. On the left sidebar, select the port the GDK is listening to (typically 3000).
  4. If the port is marked as private, select the lock icon to make it public.