Compass

Overview

This topic explains how to use the Compass integration for LaunchDarkly.

The Compass integration for LaunchDarkly pushes relevant feature flag change events to Compass' component activity timeline. This lets your team better understand how recent changes to feature flags may be impacting component health by viewing feature flag change events alongside other component events, such as deployments and incidents. Additionally, the integration provides a new Compass component tab that contains a complete list of relevant feature flags and their current states.

Prerequisites

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

• Be a Compass administrator on your Atlassian site.
• Have a personal or service API access token. To learn more, read API access tokens.

Generate a new LaunchDarkly access token

The Compass integration requires a LaunchDarkly personal or service API access token with a role policy that allows the token to perform the createIntegration, deleteIntegration, and viewProject actions.

Here's how to create an API access token with the appropriate inline policy:

1. Navigate to the Authorization tab on the Account settings page in LaunchDarkly.

2. Click Create token. The "Create access token" dialog appears.

3. Give your token a human-readable Name, such as "Compass integration."

4. Give your token an "Inline policy" Role.

5. Click the Advanced editor button and specify the following policy in the Editor field to allow the token to perform the createIntegration and deleteIntegration actions on integration resources and the viewProject action on project resources:

   Compass integration Inline policy

   [
     {
       "actions": ["createIntegration", "deleteIntegration"],
       "effect": "allow",
       "resources": ["integration/*"]
     },
     {
       "resources": ["proj/*"],
       "effect": "allow",
       "actions": ["viewProject"]
     }
   ]
   COPY

6. If you are on an Enterprise LaunchDarkly plan, select This is a service token.

7. Click Save token and copy the newly created token to your clipboard. You will need it to configure the integration in Compass.

Set up the Compass integration

The Compass integration is managed from the Atlassian Cloud site. Other than creating an API access token, there are no settings or preferences to configure in LaunchDarkly.

Here's how to set up your Compass integration:

1. Navigate to your Atlassian Compass site. For example, https://mysite.atlassian.net/compass.
2. In the top navigation, click Apps.
3. Find LaunchDarkly in the list of apps and click Install.
4. After the LaunchDarkly app is installed, click Configure.
5. Click Allow access. The "LaunchDarkly is requesting Access" screen appears.
6. Review the requested permissions, then click Accept.

7. Enter your LaunchDarkly API access token in the Access token field.
8. Click Submit.

The integration has connected LaunchDarkly and Compass when the Connected to LaunchDarkly success message is displayed.

Connecting Compass components to LaunchDarkly

Now that you've set up the integration, you must connect your LaunchDarkly projects to Compass components to view feature flag data in Compass.

To connect feature flags to a Compass component:

1. In LaunchDarkly, navigate to the Feature flags page for the project you want to connect.
2. Apply the "Tag(s)" filter if you would like to only connect a subset of feature flags that have a specified tag. To learn more, read Filtering feature flags.

3. Copy the page URL to your clipboard. For example, https://app.launchdarkly.com/starship-command/production/features?tag=compass. The URL contains the project name, environment, and optional tag filter.
4. Navigate to your Compass site. For example, https://mysite.atlassian.net/compass.
5. Navigate to the Compass component you want to connect to LaunchDarkly.
6. In the Other links section of your Compass component, paste the LaunchDarkly URL as a new link.
7. Click on the LaunchDarkly tab in the left navigation to verify that the component was successfully connected.

7. Repeat the above steps to associate your other LaunchDarkly projects to the applicable Compass components.

Viewing feature flag information for a Compass component

Once you have connected your Compass components to LaunchDarkly, you can view feature flag information on the component page in Compass.

Here's how:

1. Navigate to your Compass site. For example, https://mysite.atlassian.net/compass.
2. Navigate to the Compass component for which you want to view feature flag information.
3. Click on the LaunchDarkly tab in the left navigation.

Recent feature flag changes for a connected Compass component

You can view a history of recent feature flag changes for the associated LaunchDarkly project on the Recently updated subtab.

Here's how:

• Click the dot next to each item to view more details about the feature flag change.
• Click the feature flag name to view the feature flag in LaunchDarkly.

All feature flags for a connected Compass component

You can view a list of all feature flags for the associated LaunchDarkly project on the All feature flags subtab.

Here's how:

• Use the Filter by status dropdown to filter the list of flags displayed in the list.
• Click the column headings above the list to sort by the Flag, Status or Last requested column.
• Click the feature flag name to view the feature flag in LaunchDarkly.

Disconnecting Compass components from LaunchDarkly

The connection between a LaunchDarkly project and a Compass component is stored as a link on the Compass component, as described in the Connecting Compass components to LaunchDarkly section. If desired, you can remove this connection on the Compass component page.

Here's how:

1. Navigate to your Compass site. For example https://mysite.atlassian.net/compass.
2. Navigate to the Compass component you want to disconnect from LaunchDarkly.
3. In the Other links section of your Compass component, remove the LaunchDarkly link. Verify that the component was successfully disconnected by clicking on the LaunchDarkly tab in the left navigation. Feature flag information should no longer display on this tab.

Disconnecting your API access token

The Compass integration stores your LaunchDarkly API access token to read data from the LaunchDarkly API, as described in the Set up the Compass integration section. If you need to cycle your LaunchDarkly access token, or if you want to connect Compass to a different LaunchDarkly organization, you can disconnect your access token.

Here's how:

1. Open to your Atlassian Compass site. For example https://mysite.atlassian.net/compass.
2. In the top navigation, click the Apps link.
3. Find LaunchDarkly in the list of apps and click Configure.
4. Click Disconnect access token.
5. You can now provide Compass with a new access token if desired.

Removing the Compass integration

To remove the Compass integration:

1. Open your Atlassian Compass site. For example https://mysite.atlassian.net/compass.
2. In the top navigation, click Apps.
3. Find LaunchDarkly in the list of apps and click Uninstall.

This removes the Compass integration with LaunchDarkly.