TerraTrue’s Jira integration makes it easy to create new launches from Jira issues. We’ll walk you through a few steps to create the integration. We’ll also discuss how to specify which Jira issues create launches. Finally, we’ll let you know where you can find more detailed information about importing existing Jira issues.
Jira integration setup
Step 1: Create an API token
To access your Jira instance, TerraTrue needs a way to authenticate with your system using an API token. It’s important to note:
- The Jira permissions granted by an API token will be the same as those of the account associated with the API token
- API tokens exist until they are revoked (deleted)
- API tokens are independent of a user’s login password, so revoking the token will not affect the Jira user’s login
To create an API token:
- Log in to Jira
- Go to https://id.atlassian.com/manage/api-tokens
- Click “Create API token”
- Save the token value so you can use it in a later step
Step 2: Enable the Jira Integration in Org Settings
- Log in to TerraTrue
- Navigate to Org Settings > Integrations > Jira or go to https://launch.terratrue.com/settings/integrations/jira
- Click the “Enable Jira Integration” toggle under the “Webhook Configuration” header
- Fill out the required fields as follows:
- Jira Instance URL: https://<your_Jira_instance>.atlassian.net
- Username: <Jira account username from step 1>
- API Token: <API token from step 1>
Step 3: Configure optional settings
When the Jira Integration is enabled, by default, only launches created by Jira are allowed. If you would still like to create TerraTrue launches in other ways, turn on the “Launch Flexibility” toggle.
Once enabled, you will have two options. If you would like to allow TerraTrue users to create launches without any restrictions, then choose “All launches” and click Save.
If you would like to limit the types of launches that can be created outside of Jira, select the “Launches with components” option. If selected, users will only be able to create launches outside of Jira when they are associated with a particular component. Simply specify the list of valid components and click Save.
By default, TerraTrue sends a label to the original Jira issue when a launch is completed. You can also configure TerraTrue to send comments to the original Jira issue when specific events, like completing a Data Spec, occur. To configure these optional comments, select the events you wish to track and then click Save.
Note: The creator of these optional comments will be the username specified in the Jira Integration.
Step 4: Define a webhook in Jira
- From the TerraTrue Jira Integration page, copy the URL in the Webhook section
- In Jira, navigate to Settings > System > Webhooks or go to https://<your_Jira_instance>.atlassian.net/plugins/servlet/webhooks
- Click “+ Create a WebHook”
- Fill out the name field and select enabled for status
- For the URL, paste in the webhook URL from TerraTrue
- In the Issue Related Events section, specify the Jira project or criteria for filtering in the JQL query box
- Under the Issues header, selected “created” and “updated”
- Save your new webhook
Customizing the Jira webhook
When configuring a webhook in the Issue Related Events section in Jira, we are given the ability to use JQL to determine which Jira issues will trigger the webhook. JQL is Jira’s search query language. Any search you would normally do in Jira can be directly copied into the Issue Related Events section of the webhook. This includes searches on multiple projects, field values, or any creative search strategy. You can find more information on JQL here.
Importing existing Jira issues
If you would like to import existing Jira issues into TerraTrue, see out detailed Jira integration guide for step-by-step instructions.
The Jira Integration is a bidirectional communication between Jira and TerraTrue. As a result, we ask you to provide a Jira username and API token so that we can authenticate with your Jira instance. TerraTrue will have access as that Jira user, so you should limit the Jira permissions provided to that Jira user to only those that are necessary.