Gearset's Jira integration (available for Teams or Enterprise license users) automatically posts updates to Jira tickets when you run validations and deployments, with a link back to the full report in Gearset. It makes tracking the status of your user stories and support tickets faster and easier.

These setup instructions are specifically for hosted Jira hosted. Read our Jira on-premise documentation for instructions on how to configure Gearset with your self-hosted Jira instance.

Initial Jira setup (team owner)

To get started, you'll need your Jira administrator to create an application link in Jira itself and your team owner to authorize Gearset. This provides a mechanism for Gearset to authenticate against Jira in order to post updates to tickets, and only has to be completed once. After this has been done, any subsequent users can set up a Jira connection in just a couple of clicks.

Step 1: Copy Gearset's public key

In Gearset, under My connections (in the menu on the left), click Source control and services.

[Note: you must be the owner of your Gearset team to complete these steps.]
Click + Connect to Jira.

Keep the generated public key and consumer key to hand as you'll need them for Step 2.

Step 2: Creating an application link in Jira

In a new tab, sign in to your Jira instance as an administrator and navigate to the Dashboard or Projects page. [Note: this must be completed in a new tab to preserve the generated consumer key.]
Go to Jira settings (which is the cog icon on top right).

Then go to Products > Application links. Click Create link.

Paste Gearset’s URL (https://app.gearset.com/) into the application URL text box, and click Create new link.
When prompted with a dialog to confirm the application URL, click Continue:

In the Link applications dialog, fill in the Application Name and Application Type. It's important to leave the Service Provider Name blank and to check Create incoming link before clicking Continue.

Select the three dots and edit the newly created application link
In the Incoming Authentication dialog, enter the Consumer Name and Gearset’s Consumer Key and Public Key from Step 1. Once the configuration is complete, click Save.

Once completed, Gearset should appear as an application link in your Jira instance.

Step 3: Authorize your Gearset to post on behalf of your Jira user

In Gearset, on the Source control and services page (in the My connections section), click + Connect to Jira.
Enter the URL (e.g. https://example.atlassian.net, remove any character after .net) of your Jira Cloud instance or Jira Self-hosted (on-premise) instance and click Connect.

Upon clicking Connect, you’ll be redirected to your Jira instance and prompted to log in, if you aren’t already. When prompted, grant Gearset permission to make changes to your Jira data by clicking Allow.
Once complete, Jira will redirect you back to Gearset.

Connecting to Jira (team members)

Once the Jira application link has been created and Gearset has been authorized by the team owner, the rest of the team members will be able to connect to Jira. When each Gearset user connects to Jira, that will be with their own Jira credentials, so that Jira comments are attributed to each teammate correctly.

In Gearset, on the Source control and services page (which is in the My connections section) and click + Connect to Jira.
Click Allow in the Welcome to JIRA dialogue box (as shown above).
You'll be redirected back to Gearset and can start linking Jira tickets.

Adding a Jira ticket

Once you have set up an application link in Jira, you and your team can start linking Jira tickets to your deployments and validations. For Gearset to automatically update your Jira ticket, simply add the Jira ticket reference before you deploy or run a validation.

To link a Jira ticket, follow the usual comparison process, selecting which metadata items you would like to deploy or include in your validated package.
Once the pre-deployment problem analysis has checked for any potential issues, you’ll be taken to the Summary of objects to deploy page.
Click on the Jira updates panel, add in your ticket reference, and you’re all set! When adding ticket references you can search ticket titles or descriptions to find the ones you need.
If you would like to search by ticket reference, you have to search for the exact reference in the format [Project ID]-[ticket ID].
From there you can either validate and schedule the deployment or deploy instantly as usual.

Within Jira, any actions performed will have been automatically recorded for you in your Jira ticket.

Any deployment notes added to your deployment will also appear as comments attached to your Jira ticket.

If you wanted to configure the messages posted to Jira, here are some additional config settings that you can access via the Preferences cog.

You can also set the status of the Jira ticket directly from Gearset. Note that the status update only triggers on a successful deployment.

With this feature you’ll be able to see exactly what changes have been made at each step of the user story, making it easier to review changes and speed up your release cycles.