> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Jira Cloud
**This integration is not available in federal environments**
To learn more, read LaunchDarkly in federal environments.
**Attention: EU Customers**
Read the EU documentation for instructions on using this integration with the LaunchDarkly European Union (EU) instance.
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](/docs/home/flags/links) 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.
**You may need to migrate from Jira Connect to Jira Forge**
If you set up an integration between LaunchDarkly and Jira before March 2026, you must migrate from Jira Connect to Jira Forge. To learn how, read [Migrating to Jira Forge](/docs/integrations/jira-forge).
**You may need to upgrade the LaunchDarkly for Jira Forge app**
If you already use the LaunchDarkly for Jira Forge app, you must clear and re-enter your API access token after upgrading to a new major version so LaunchDarkly can create an updated subscription. To learn how, read [Migrating to Jira Forge](/docs/integrations/jira-forge#upgrade-an-existing-jira-forge-installation).
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](https://marketplace.atlassian.com/apps/1219142/launchdarkly-for-jira?hosting=cloud\&tab=overview) in your Jira Cloud instance.
- The "LaunchDarkly for Jira (EU)" app from the [Atlassian Marketplace](https://marketplace.atlassian.com/apps/1238314/launchdarkly-for-jira-eu?hosting=cloud\&tab=overview) in your Jira Cloud instance.
- A personal or service API access token. To learn more, read [API access tokens](/docs/home/account/api).
## 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](#create-a-role-and-add-it-to-an-api-access-token), or
* You can [add the Writer base role to your personal access token](#add-the-writer-role-to-your-personal-access-token).
2. [Configure the LaunchDarkly integration in Jira with the API access token](#configure-the-launchdarkly-integration-in-jira).
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
**Service tokens and creating your own roles are available to customers on select plans**
Service tokens and creating your own roles are only available to customers on select plans. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To upgrade your plan, [contact Sales](https://launchdarkly.com/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:
```json title="Jira policy" expandable lines wrap theme={null}
[
{
"resources": [
"proj/*:env/*:flag/*"
],
"actions": [
"createFlagLink",
"updateFlagLink",
"deleteFlagLink"
],
"effect": "allow"
},
{
"resources": [
"proj/*"
],
"actions": [
"viewProject"
],
"effect": "allow"
},
{
"resources": [
"integration/*"
],
"actions": [
"createIntegration",
"deleteIntegration"
],
"effect": "allow"
}
]
```
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](/docs/home/flags/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](/docs/home/account/roles/role-create).
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
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](/docs/home/account/environment#critical-environments).
**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](https://support.atlassian.com/jira-work-management/docs/configure-field-layout-in-the-issue-view/).
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**.
**Feature flag information may take time to appear in Jira**
It can take up to 20 minutes for flag status and targeting changes to appear in your Jira issue.
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](/docs/home/infrastructure/custom-properties) 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**.
**Feature flag information may take time to appear in Jira**
It can take up to 20 minutes for flag status and targeting changes to appear in your Jira issue.
## 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](https://support.atlassian.com/jira-work-management/docs/jql-developer-status/).
## 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**.
**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.
## 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](/docs/integrations/jira-forge).
* A role with the `createJiraIssue` action for the alert resource. To learn more, read [Alert actions](/docs/home/account/roles/role-actions#alert-actions).
* LaunchDarkly observability enabled for your project. To learn more, read [Observability](/docs/home/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](/docs/home/observability/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](/docs/home/observability/vega#create-a-jira-issue-from-a-vega-investigation).