• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
No results for ""
EXPAND ALL

GIVE DOCS FEEDBACK

Jira Cloud

Read time: 7 minutes
Last edited: Feb 15, 2024
The Jira Cloud integration is a Pro and Enterprise feature

The Jira Cloud integration is available to customers on a Pro or Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

Overview

This topic explains how LaunchDarkly's Jira Cloud integration allows you to link your feature flags to your team's Jira issues. When you connect a feature flag to a Jira issue, LaunchDarkly automatically creates a Jira flag link. To learn more, read Flag links.

This integration is for Jira Cloud only

The LaunchDarkly Jira integration is only for Jira Cloud product offerings. It does not work in Jira Data Center or Jira Server.

When a feature flag is turned on or off or has its targeting rules updated, its associated Jira issue pages display the flag's current status.

Additional Atlassian integrations are also available

If you use Jira Cloud, you may use other Atlassian products. You can also set up integrations for those. To learn more, read about the LaunchDarkly integrations with Compass, Confluence, and Trello.

Prerequisites

To complete this procedure, you must have the following prerequisites:

  • The LaunchDarkly for Jira app from the Atlassian Marketplace in your Jira Cloud instance.
  • A personal or service API access token. To learn more, read API access tokens.

Set up the Jira integration

To set up the Jira integration, you must complete the following steps:

  1. Give your API access token the required permissions:
  1. Configure the LaunchDarkly integration in Jira with the API access token.

This allows LaunchDarkly to communicate with Jira any time you change a flag.

Give your API access token the required permissions

You can create a custom role with appropriate permissions then add the custom role to a personal or service access token, or you can add the built-in Writer role to your personal access token.

You may need to update your access token

If you configured the Jira integration prior to February 15, 2022, you may need to update your access token's custom role to include a statement allowing access to proj/*:env/*:flag/* resources with the createFlagLink, updateFlagLink, and deleteFlagLink actions.

Create a custom role and add it to an API access token

Expand Create a custom role and add it to an API access token
Service tokens and custom roles are Enterprise features

Service tokens and custom roles are available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

To create a custom role for the API access token:

  1. Navigate to the Account settings page.
  2. Click into the Roles tab.
  3. Click Create role. The "Create custom role" panel appears.
  4. Give the custom role a human-readable name.
  5. In the "Role policy" section, enter webhook/* in the Choose resources for this policy statement field.
  6. Select "Allow" from the Allow or deny actions on the resource menu.
  7. Choose createWebhook and deleteWebhook from the Choose actions to allow or deny menu.
  8. Click Update statement.
  9. Click + Add statement.
  10. In the "Role policy" section, enter proj/*:env/*:flag/* in the Choose resources for this policy statement field.
  11. Select "Allow" from the Allow or deny actions on the resource menu.
  12. Choose createFlagLink, updateFlagLink, and deleteFlagLink from the Choose actions to allow or deny menu.
  13. Click Update statement.

The custom role is now configured.

Here is an image of a custom role configured to grant access to webhooks and flag links:

An access token's custom role configured to grant access to webhooks and flag links.
An access token's custom role configured to grant access to webhooks and flag links.

You can also use the advanced role policy editor to grant permissions by adding this policy:

[
{
"effect": "allow",
"actions": ["createWebhook", "deleteWebhook"],
"resources": ["webhook/*"]
},
{
"effect": "allow",
"actions": ["createFlagLink", "updateFlagLink", "deleteFlagLink"],
"resources": ["proj/*:env/*:flag/*"]
}
]

To learn more about custom role policies, read Creating custom roles and policies.

Next, add the custom role to the API token to grant the Jira integration additional permissions.

To add the custom role to the API token:

  1. Navigate to the Account settings page.
  2. Click into the Authorization tab.
  3. Find the API access token you want to add permissions to and select "Edit token" from its overflow menu. The "Edit" panel appears.
  4. In the Role menu, select "Custom."
  5. Check the checkbox next to the custom role you just created.
  6. Click Save token.

The custom role is applied to the API token.

Add the built-in Writer role to your personal access token

Expand Add the built-in Writer role to your personal access token

To add the built-in Writer role to a personal access token:

  1. Navigate to the Account settings page.
  2. Click into the Authorization tab.
  3. Find the personal access token you want to add permissions to and select "Edit token" from its overflow menu. The "Edit" panel appears.
  4. In the Role menu, select "Writer."
  5. Click Save token.

Your personal token now has the Writer role.

Configure the LaunchDarkly integration in Jira

Use your access token to configure the Jira integration for your LaunchDarkly account.

  1. Navigate to your Jira instance's app management page, and click the Configuration button for the LaunchDarkly app. The "Configure LaunchDarkly Integration" screen appears.
  2. Set your API access token.
  3. Select which environment the app will track for each of your LaunchDarkly projects. By default, the app will track your production environments.
The Jira configuration screen.
The Jira configuration screen.
Environment selection

If selected environments are reconfigured after issues have already been associated with flags, the existing connections display the environments they were historically connected to until the next time that flag is updated.

New flag connections display the flag configuration for the updated environment.

After you have set up the LaunchDarkly for Jira app, a "Releases" panel appears when you view issues on your Jira board.

Enable the release panel

The Jira issue view, which contains the release panel, is a per-user setting. If it is off, the release panel does not appear. To learn more, read Jira's documentation.

Now that the Jira app is configured, you can connect feature flags to Jira issues. If no flags are associated with an existing Jira issue, you can add one with a button. If you already have one or more flags associated with a Jira issue, the rollout status of each connected feature flag on each Jira issue appears.

Creating a new feature flag from a Jira issue

To create a new flag with Jira issues:

  1. Navigate to your Jira issue's feature flag panel.
  2. In the "Details" section, click Add feature flag.
The "Releases" menu with the "Create feature flag" option called out.
The "Releases" menu with the "Create feature flag" option called out.
  1. Select "Create feature flag." The LaunchDarkly "Create a feature flag" panel appears with the Jira issue pre-populated.
  2. Finish configuring your flag and click Save flag.

When you toggle the flag on or off or make any targeting rule changes, those changes will appear in your Jira issue.

Connecting an existing feature flag to a Jira issue from LaunchDarkly

If you have already created a feature flag for your Jira issue, you can add a Jira issue to your existing flag by creating a custom property for your flag.

  1. Navigate to the flag's Settings page.
  2. Name the custom property Jira issues.
The flag's "Settings" page, configured with a "Jira issues" custom property.
The flag's "Settings" page, configured with a "Jira issues" custom property.
  1. Enter a list of Jira issue keys as the property value. You can list multiple issues if applicable.
  2. Click Save changes.

Viewing a flag's status in a Jira issue

To view a flag's status in a Jira issue:

  1. Navigate to your Jira issue's feature flag panel.
  2. In the "Details" section, click on the name of the feature flag. A dialog with a Feature flags tab appears:
The "Feature flags" tab of a Jira issue displaying the flag's information and status.
The "Feature flags" tab of a Jira issue displaying the flag's information and status.

Using JQL to search for Jira issues with feature flags

You can use JQL to query for Jira issues that are connected to feature flags. To learn more about JQL, read Atlassian's documentation.

Removing a feature flag from a Jira issue

To remove a flag from a Jira issue:

  1. Navigate to the flag's Settings tab.
  2. In the "Jira Issues" section, click the X on the Jira issue custom property you want to remove:
  3. Click Save with comment.
Adding issues to an existing flag

Your Jira issue must exist before you associate it with your feature flag. If you accidentally added a Jira issue to your flag, delete the custom property, and try connecting your Jira issue again.