Code references

Read time: 5 minutes

Last edited: Oct 31, 2022

Code references is an Enterprise feature

Code references is available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

Overview

This topic explains how to use code references in LaunchDarkly to find and manage references to your feature flags.

The code references feature lets you find references to your feature flags. This makes it easy to determine which projects reference your feature flags, and simplifies removal of technical debt.

We've open-sourced a utility called ld-find-code-refs that scans your code and pushes code reference information to LaunchDarkly. You can integrate this utility into your CI/CD process, or use other trigger mechanisms like GitHub code references, cron jobs, or commit-triggered Lambda functions.

Integrating ld-find-code-refs with your toolchain

We've designed this feature so that LaunchDarkly services do not need direct access to your source code. The ld-find-code-refs utility is agnostic to where your code is hosted.

Our approach makes it possible to push references to LaunchDarkly whether you're using GitHub, GitHub Enterprise, Bitbucket, Bitbucket Enterprise, GitLab, Azure DevOps, or any other Git code hosting tool.

If your workflow does not have a direct integration, we have an ld-find-code-refs Docker container on Docker Hub.

We offer built-in configurations for common trigger mechanisms and CI/CD providers, including:

You can also invoke the ld-find-code-refs utility from the command line. Run this utility in any custom workflow, such as a bash script or cron job.

Prerequisites

To set up code references in LaunchDarkly, you must have the following prerequisites:

You must have an API access token with Writer-level access or higher. Create an API access token on the Account settings page, on the Authorization tab. To learn more, read API access tokens.
You must have a custom role that allows all actions on code references.
You must allow ld-find-code-refs to run in environment that has access to your source code.

API access tokens can also use custom roles

Alternatively, you can give the access token access to a custom role with the code-reference-repository resource specifier. To learn more, read Custom roles.

Using code references

You can view existing code references for feature flags in the flags list. To view existing code references, visit a feature flag's Code references tab.

Go to Code references by clicking the tab from a feature flag's page or the code reference count on the flags list.

Code reference count may not be available

The code reference count displays when there is at least one code reference for that flag, or when you filter by code reference count. To learn more, read Filtering feature flags.

The screenshot below shows the Code references tab displaying an active code reference:

The "Code references" tab of a feature flag.

You can also use the REST API: Code references

Understanding extinction events

After you remove all code references mentioning that flag from the codebase and rerun the scanning tool, LaunchDarkly creates an extinction event. This event appears as a message on the Code references tab of the feature flag. It indicates that all code references for the flag have been removed from the codebase as of a specified commit.

You can also use the REST API: List extinctions

Here is an image of an extinction event on the Code references tab of a feature flag:

The "Code references" tab of a feature flag with an extinction event.

To disable extinctions, set lookback to 0 in the ld-find-code-refs configuration settings.

You can toggle a repository on or off to allow or forbid code reference triggers from pushing new data to it.

Using code references in federal environments

If you are using ld-find-code-refs in an environment that requires the use of FIPS 140-2 validated encryption modules, such as the LaunchDarkly federal instance, you may need to take additional steps to ensure compliance. To learn more, read LaunchDarkly in environments requiring FIPS 140-2 validated encryption modules.

Managing code references

Manage code references on the Integrations page for your project. Code references are organized into repositories, which the ld-find-code-refs tool creates automatically.

After a repository appears on the Integrations page, you can either temporarily disable it, which prevents new code references from being added to LaunchDarkly, or delete all code references associated with the repository.

To disable the repository, click the toggle switch to Off.

To delete the repository, click Delete.

If you click Delete, LaunchDarkly purges all data associated with that repository. It will no longer have any record of the code reference or any source context lines. Deleting is permanent and cannot be undone.

Remove code references before you click Delete

If you want to remove a connection permanently, be sure to remove any ld-find-code-refs triggers from your code. If you're not sure how or where the trigger is invoked, you can also delete the access token your trigger uses. If you delete a repository with automated code reference updates enabled, the connection is recreated the next time an automated code reference trigger executes.

The disabling and delete options appear below:

The "Code reference" section of the "Integrations" page.

Configuring context lines

The ld-find-code-refs utility sends two lines of surrounding source context to LaunchDarkly.

Two lines of code appear above, and two lines appear below the actual reference.

The screenshot below shows code references with context lines:

Having a few lines of context can make it easier to understand references to a feature flag. However, these lines are optional. You can disable this feature when you configure ld-find-code-refs.

The following screenshot shows code references without context lines:

Sending metadata only

You can disable contextLines as shown in Configuring context lines. When you disable contextLines no snippets of code leave your repository. All code scanning always happens within infrastructure your team manages as outlined in Integrating ld-find-code-refs with your toolchain

Metadata sent to LaunchDarkly:

Organization name, if applicable
Repository name
Commit ID
Synced time
File name
Line number

Metadata sent to LaunchDarkly if extinctions are enabled and an extinction is found:

All of the metadata listed in the section above
Commit message when extinction was recorded

ld-find-code-refs is open source and available for review. Code reference give your team additional insights, such as surfacing flag usage in the code base to provide additional safety checks when archiving flags, during the lifecycle of the flag while still maintaining a secure SDLC.

Finding flag aliases

Aliases help you find indirect references to feature flags, such as flag keys stored in variables or in wrapped SDK code.

Here's how to find references to firstFeatureFlag throughout your code base:

var firstFeatureFlag = 'first-flag-key'

aliases:
  - type: camelcase

This identifies all references to firstFeatureFlag in your code base.

To learn more about aliases, read the aliases documentation.

Using ld-find-code-refs with a monorepo

ld-find-code-refs version 2.5.0+ provides support for monorepos. This means a single scan of code references can find feature flags and aliases from multiple LaunchDarkly projects stored in the same repository. You can specify an optional starting subdirectory for each project, which limits your scan to directories below the initial subdirectory only. The required top-level dir value should still be the overall git repository root directory.

To learn more about monorepo support, read Projects in the ld-find-code-refs configuration documentation.

Limitations

The LaunchDarkly code references API asserts various limits to limit the number of "false positive" code references. ld-find-code-refs logs warning messages if you exceed any of these limits. Above certain values, LaunchDarkly may ignore some files and references.

These limits include:

LaunchDarkly does not scan code references for flags with keys that have fewer than three characters.
LaunchDarkly stores up to 10,000 files with code references per repository. Additional files are ignored.
LaunchDarkly allows up to 500 characters per line of source code stored. Additional characters are truncated.
LaunchDarkly allows up to 25,000 code references per file. Additional references are ignored.

If you've encountered any of these limits, or are noticing a large number of false positives being detected by ld-find-code-refs, you can configure an .ldignore file in your repository with rules matching the files and directories you'd like to exclude.

To learn more about .ldignore files, read the ld-find-code-refs documentation.

Using ld-find-code-refs with the React SDK

The code references feature scans your source code for occurrences of your flag keys. This process requires your source code to reference flag keys exactly as they appear in LaunchDarkly.

However, by default, the React SDK changes all flag keys to camel-case for easier access with dot notation. To use the code references feature in conjunction with the React SDK, configure ld-find-code-refs to generate camel-case aliases for the flag keys, or configure the React SDK to disable this camel-casing feature. To learn more, read Flag keys transposed to common casing conventions in the ld-find-code-refs documentation and Flag keys in the React SDK documentation.