Jira Cloud

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.

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.

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:

• You can create a custom role with webhook and flag link 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.

2. 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.

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. Click the gear icon in the left sidenav to view Organization settings. The General settings page appears.
2. Click Roles.
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.
14. Click Save role.

The custom role is now configured.

Here is an image of a 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:

Jira policy

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

This means that the Jira integration will only be able to do the following:

• Create webhooks: this is needed because the Jira integration creates a webhook to push change events from LaunchDarkly to Jira
• Delete webhooks: this is used when the Jira integration is uninstalled
• Create/Update/Delete flag links: the Jira integration can update the links section of the feature flag to provide a helpful link back to the Jira issue

The Jira integration cannot perform any other actions, including toggling flags. If a member of your organization wants to toggle a flag from Jira, they have to click the URL for the flag in Jira and toggle the flag from the LaunchDarkly UI. At this point they will only be able to perform actions permitted by their role.

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. Click the gear icon in the left sidenav to view Organization settings. The General settings page appears.
2. Click Authorization.
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

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.

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

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.

Create 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.

3. Select "Create feature flag." The LaunchDarkly "Create a feature flag" panel appears with the Jira issue pre-populated.
4. 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.

Connect 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.

To create a custom property:

1. Navigate to the Flags list.
2. Hover on the flag you wish to create a custom property for, and click the three-dot overflow menu that appears.
3. Click Manage flag settings. The flag's Settings tab appears.
4. Click Add custom property.
5. Name the custom property Jira issues.

6. Enter a list of Jira issue keys as the property value. You can list multiple issues if applicable.
7. Click Save with comment.

View 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:

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.

Remove a feature flag from a Jira issue

To remove a flag from a Jira issue:

1. Navigate to the Flags list.
2. Hover on the flag you wish to remove a custom property from, and click the three-dot overflow menu that appears.
3. Click Manage flag settings. The flag's Settings tab appears.
4. In the "Jira Issues" section, click the X on the Jira issue custom property you want to remove.
5. Click Save with comment.