LaunchDarkly Code References with GitHub Actions

This GitHub Action is a utility that automatically populates code references in LaunchDarkly. This is useful for finding references to feature flags in your code, both for reference and for code cleanup.

To find code references in pull requests, use launchdarkly/find-code-references-in-pull-request instead.

Configuration

Once you've created a LaunchDarkly access token, store the newly created access token as a repository secret titled LD_ACCESS_TOKEN. Under Settings > Secrets in your GitHub repo, you'll see a link to "Add a new secret". Click that and paste in your access token and click "Save secret".

(For help storing this see the GitHub docs.)

Next, create a new Actions workflow in your selected GitHub repository (e.g. code-references.yml) in the .github/workflows directory of your repository. Under "Edit new file", paste the following code:

on: pushname: Find LaunchDarkly flag code referencesconcurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}cancel-in-progress: truejobs:
launchDarklyCodeReferences:
name: LaunchDarkly Code Referencesruns-on: ubuntu-lateststeps:
- uses: actions/checkout@v4with:
fetch-depth: 11# This value must be set if the lookback configuration option is not disabled for find-code-references. Read more: https://github.com/launchdarkly/ld-find-code-refs#searching-for-unused-flags-extinctions
- name: LaunchDarkly Code Referencesuses: launchdarkly/find-code-references@v2.17.0with:
accessToken: ${{ secrets.LD_ACCESS_TOKEN }}projKey: LD_PROJECT_KEY

We strongly recommend that you update the second uses attribute value to reference the latest tag in the launchdarkly/find-code-references repository. This will pin your workflow to a particular version of the launchdarkly/find-code-references action. Also, make sure to change projKey to the key of the LaunchDarkly project associated with this repository.

Commit this file under a new branch. Submit as a PR to your code reviewers to be merged into your default branch. You do not need to have this new branch merged into the default branch for code references to appear in the LaunchDarkly UI for your flags. Code references appear for this new branch as soon as it is published.

As shown in the above example, the workflow should run on the push event, and contain an action provided by the launchdarkly/find-code-references repository. The LD_ACCESS_TOKEN configured in the previous step should be included as a secret, as well as a new environment variable containing your LaunchDarkly project key.

Using a private or mirrored container registry

The root Action (launchdarkly/find-code-references@v2) is a Docker container action. GitHub always pulls its image from the registry hardcoded in that Action's Dockerfile (Docker Hub), and that image reference cannot be overridden with an input.

If your organization must pull images through an internal registry or Docker Hub proxy, use the optional docker entry point in the same Action repository. It accepts a dockerImage input and runs the scanner with docker run after you authenticate to your registry.

on: pushname: Find LaunchDarkly flag code referencesjobs:
launchDarklyCodeReferences:
name: LaunchDarkly Code Referencesruns-on: ubuntu-lateststeps:
- uses: actions/checkout@v4with:
fetch-depth: 11
- uses: docker/login-action@v3with:
registry: your.registry.exampleusername: ${{ secrets.REGISTRY_USER }}password: ${{ secrets.REGISTRY_TOKEN }}
- name: LaunchDarkly Code References# Pin to a release that includes the docker/ entry point (see changelog).uses: launchdarkly/find-code-references/docker@v2.17.0with:
accessToken: ${{ secrets.LD_ACCESS_TOKEN }}projKey: LD_PROJECT_KEYdockerImage: your.registry.example/launchdarkly/ld-find-code-refs-github-action:2.17.0

Mirror the public image launchdarkly/ld-find-code-refs-github-action into your registry (pin dockerImage to the scanner image tag you mirrored; it can lag the Action tag). This entry point requires a Docker CLI on the runner (included on GitHub-hosted ubuntu-* runners). Existing workflows that use the root Action do not need to change.

Additional configuration

To customize additional configuration not referenced in Inputs, you may use a configuration file located at .launchdarkly/coderefs.yml. The following links provide more inforation about configurable options:

• All configuration options
• Monorepo configuration
• Alias configuration.

Additional Examples

The example below is the same as first, but it also excludes any dependabot branches. We suggest excluding any automatically generated branches where flags do not change.

on:
push:
branches-ignore:
- 'dependabot/**'name: Find LaunchDarkly flag code referencesconcurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}cancel-in-progress: truejobs:
launchDarklyCodeReferences:
name: LaunchDarkly Code Referencesruns-on: ubuntu-lateststeps:
- uses: actions/checkout@v4with:
fetch-depth: 11# This value must be set if the lookback configuration option is not disabled for find-code-references. Read more: https://github.com/launchdarkly/ld-find-code-refs#searching-for-unused-flags-extinctions
- name: LaunchDarkly Code Referencesuses: launchdarkly/find-code-references@v2.17.0with:
accessToken: ${{ secrets.LD_ACCESS_TOKEN }}projKey: LD_PROJECT_KEY

Troubleshooting

Once your workflow has been created, the best way to confirm that the workflow is executing correctly is to create a new pull request with the workflow file and verify that the newly created action succeeds.

If the action fails, there may be a problem with your configuration. To investigate, dig into the action's logs to view any error messages.

Inputs

name	description	required	default
accessToken	A token with write access to the LaunchDarkly project.	true	""
allowTags	Enable storing references for tags. Lists the tag as a branch.	false	false
baseUri	The base URL of the LaunchDarkly server for this configuration.	false	https://app.launchdarkly.com
contextLines	The number of context lines above and below a code reference for the job to send to LaunchDarkly. By default, the flag finder will not send any context lines to LaunchDarkly. If < 0, it will send no source code to LaunchDarkly. If 0, it will send only the lines containing flag references. If > 0, it will send that number of context lines above and below the flag reference. You may provide a maximum of 5 context lines.	false	2
debug	Enable verbose debug logging.	false	false
ignoreServiceErrors	If enabled, the scanner will terminate with exit code 0 when the LaunchDarkly API is unreachable or returns an unexpected response.	false	false
lookback	Set the number of commits to search in history for whether you removed a feature flag from code. You may set to 0 to disable this feature. Setting this option to a high value will increase search time.	false	10
projKey	Key of the LaunchDarkly project associated with this repository. Found under Account Settings -> Projects in the LaunchDarkly dashboard. Cannot be combined with projects block in configuration file.	false	""
repoName	The repository name. Defaults to the current GitHub repository.	false	""
prune	There is a known issue where the GitHub Action will not prune deleted branch data in private repos. Only enable this if you are running the action in a public repo.	false	false
subdirectory	The subdirectory to run the action in.	false	""