Jira Cloud

This topic explains how the Jira Cloud integration lets you link feature flags to Jira issues and create Jira issues from observability data. When you connect a feature flag to a Jira issue, LaunchDarkly automatically adds a Jira flag link to the flag. You can also add Jira as a destination for observability alert notifications, and LaunchDarkly creates a Jira issue each time the alert notifies. You can create Jira issues from errors as well to track remediation work. 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 role with webhook and flag link permissions, then add the role to a personal or service access token, or
   • You can add the Writer base 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 role with appropriate permissions, then add the role to a personal or service access token, or you can add the Writer base role to your personal access token.

​

Create a role and add it to an API access token

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

Service tokens and creating your own roles are available to customers on select plansService tokens and creating your own roles are only available to customers on select plans. To learn more, read about our pricing. To upgrade your plan, contact Sales.

To create a role for the API access token:

1. Click the gear icon to view Organization settings. The General settings page appears.
2. Click Roles.
3. Click New role. The “New role” page appears.
4. Enter a human-readable Name for the role.
5. Enter a Key for the role.
6. (Optional) Enter a Description to explain what the role does.
7. In the “Edit policy” section, click View JSON to open the advanced editor.
8. Enter this policy in the “Editor” field:

Jira policy

[
{
  "resources": [
    "proj/*:env/*:flag/*"
  ],
  "actions": [
    "createFlagLink",
    "updateFlagLink",
    "deleteFlagLink"
  ],
  "effect": "allow"
},
{
  "resources": [
    "proj/*"
  ],
  "actions": [
    "viewProject"
  ],
  "effect": "allow"
},
{
  "resources": [
    "integration/*"
  ],
  "actions": [
    "createIntegration",
    "deleteIntegration"
  ],
  "effect": "allow"
}
]

See all 32 lines

10. Click Create role.

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

This means that the Jira integration can only do the following:

• Create, update, and delete flag links: This allows the Jira integration to update the links section of the feature flag to provide a link back to the Jira issue.
• Show all of your organization’s LaunchDarkly projects: This is a necessary permission to allow the Jira integration to take any action in your LaunchDarkly project.
• Create and delete integrations: This is a necessary permission to allow the Jira integration to be uninstalled.

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 can only perform actions permitted by their role.To learn more about role policies, read Creating roles and policies.Next, add the role to the API token to grant the Jira integration additional permissions.To add the role to the API token:

1. Click the gear icon 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” dialog appears.
4. Select “Custom” from the Role menu.
5. Check the checkbox next to the role you just created.
6. Click Save token.

Your token now has the custom role.

​

Add the Writer role to your personal access token

Expand Add the Writer role to your personal access token

To add the Writer base role to a personal access token:

1. Click the gear icon to view Organization settings. The General settings page appears.
2. Click Authorization.
3. Find the personal access token you want to add permissions to and select “Edit token” from its overflow menu. The “Edit” dialog appears.
4. Select “Writer” from the Role menu.
5. Click Save token.

Your personal token now has the Writer base 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 environments the app tracks for each of your LaunchDarkly projects. By default, the app tracks your critical 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 you have configured the Jira app, you can connect feature flags to Jira issues. If an existing Jira issue has no associated flags, 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 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 and open the flag you want to add a custom property to.
2. Click the three-dot overflow menu.
3. Select Add custom property.
4. Select “Jira issues” as the Type.
5. Enter a list of Jira issue keys in the Values field. You can list multiple issues if applicable.
6. Click Save.

​

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 Jira Query Language (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 and open the flag you want to remove an issue from.
2. Click the x on the Jira issue custom property you want to remove in the “Jira issues” section.
3. Click Save.

​

Create Jira issues from observability data

You can create Jira issues directly from alerts and errors in LaunchDarkly observability. For alerts, you can create issues on demand or automatically every time the alert triggers. For errors, you create issues on demand. When you create an issue, LaunchDarkly files a ticket in your connected Jira Cloud project and links it back to the observability data that prompted it. Your team can track remediation work in Jira without leaving the context of the alert or error. To create Jira issues from observability data, you need the following:

• The Jira Cloud integration configured using Jira Forge, as described earlier in this topic. Issue creation is not available with the older Jira Connect integration. To learn more, read Migrating to Jira Forge.
• A role with the createJiraIssue action for the alert resource. To learn more, read Alert actions.
• LaunchDarkly observability enabled for your project. To learn more, read Observability.

​

Create a Jira issue from an alert

When an observability alert surfaces a problem in your application, you can open a Jira issue to track the work to resolve it. To create a Jira issue from an alert:

1. Open the Telemetry section and navigate to the Alerts list.
2. Click the alert for which you want to create an issue. The alert details page appears.
3. Open the actions menu and select Create Jira issue. The “Create Jira issue” dialog appears.
4. Select a Project. This is the Jira project where the issue will be created.
5. Select an Issue type, such as “Bug” or “Task.”
6. Review the Description. LaunchDarkly pre-populates a link back to the alert in LaunchDarkly Observability. Edit the description to add more detail if you want.
7. Click Create issue.

After LaunchDarkly creates the issue, the Jira issue key appears in the dialog as a link. Click the link to open the issue in Jira.

​

Create Jira issues automatically from alerts

You can add Jira as a notification destination for an observability alert instead of creating issues one at a time. Each time the alert enters an alert or warning state, LaunchDarkly creates a Jira issue using the project and issue type you select. To add Jira as an alert notification destination:

1. Open the Telemetry section and navigate to the Alerts list.
2. Find the alert you want to add the destination to, then select Edit alert from its three-dot overflow menu. The “Edit” page appears.
3. Click + Add notification.
4. Select Jira as the notification destination.
5. Select the Project where LaunchDarkly creates the issues.
6. Select an Issue type, such as “Bug” or “Task.”
7. Click Save.

After you save the alert, LaunchDarkly creates a new Jira issue each time the alert notifies. Use the alert Cooldown period and Alert window to control how often LaunchDarkly generates new notifications and Jira issues. Each issue that LaunchDarkly creates has a title of “[Alert]” followed by the alert name. The description contains the product, project, value, group, and query for the alert, along with a link back to the alert in LaunchDarkly. LaunchDarkly also applies the observability and alert labels to the issue. LaunchDarkly creates a Jira issue only when an alert enters an alert or warning state. It does not create an issue when an alert resolves or when you create or update the alert’s configuration. If issue creation fails, LaunchDarkly still sends the alert’s other notifications, such as member, Slack, and webhook notifications. To learn more about alert notifications, read Alerts.

​

Create a Jira issue from an error

You can also create a Jira issue from an observability error to track the work to fix it. To create a Jira issue from an error:

1. Open the Telemetry section and navigate to the Errors list.
2. Click the error you want to create an issue for. The error details page appears.
3. Open the actions menu and select Create Jira issue. The “Create Jira issue” dialog appears.
4. Select a Project. This is the Jira project where the issue will be created.
5. Select an Issue type, such as “Bug” or “Task.”
6. Review the Description. LaunchDarkly pre-populates a link back to the error in LaunchDarkly observability. Edit the description to add more detail if you want.
7. Click Create issue.

After LaunchDarkly creates the issue, the Jira issue key appears in the dialog as a link. Click the link to open the issue in Jira.

​

Create a Jira issue with Vega

If your account uses Vega for auto-remediation, you can ask Vega to open a Jira issue for the follow-up work it recommends after it investigates an alert, error, or session. Vega drafts the title and description, asks you which project and issue type to use, and confirms with you before it files the issue. To learn more, read Create a Jira issue from a Vega investigation.