GitHub code references

Overview

This topic explains how to use the ld-find-code-refs utility with GitHub Actions to automatically populate code references in LaunchDarkly. To learn more about the utility and check for the latest version, read LaunchDarkly Code References with GitHub code references.

Prerequisites

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

• An API access token with write permissions for the code-reference-repository resource, either through a base role, a LaunchDarkly-provided project role, or another role that you have created. The token must be stored as a repository secret titled LD_ACCESS_TOKEN. To learn more, read API access tokens and Code reference actions.

Set up GitHub code references

To set up GitHub code references:

1. Log into GitHub and navigate to your repo.
2. Navigate to Settings then Secrets and click Add a new secret.
3. In the field that appears, enter your access token.
4. Click Save secret.
5. Return to your GitHub repository to create a new Actions workflow.

• If you already have an action.yml file: Copy and paste the launchDarklyCodeReferences job declaration below into the jobs section in your action.yml file.

• If you don’t already have a workflow file: Create a new file titled action.yml in the .github/workflows directory of your repository. Paste the following code in the Edit file section:

  YAML

  1
  name: Find LaunchDarkly flag code references
  2
  on: push
  3
  # cancel in-flight workflow run if another push was triggered
  4
  concurrency:
  5
      group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  6
      cancel-in-progress: true
  7
  8
  jobs:
  9
    launchDarklyCodeReferences:
  10
      name: LaunchDarkly Code References
  11
      runs-on: ubuntu-latest
  12
      steps:
  13
      - uses: actions/checkout@v4
  14
        with:
  15
          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
  16
      - name: LaunchDarkly Code References
  17
        uses: launchdarkly/find-code-references@v2
  18
        with:
  19
          accessToken: ${{ secrets.LD_ACCESS_TOKEN }}
  20
          projKey: YOUR_PROJECT_KEY

6. Commit this file under a new branch and submit as a PR to your code reviewers to be merged into your main branch.

As shown in the example above, the workflow should run on the push event and contain an action provided by the launchdarkly/find-code-references repository.

Include the LD_ACCESS_TOKEN as a secret, and include a new environment variable containing your LaunchDarkly project key. This is represented by YOUR_PROJECT_KEY in the above example. Do not use an environment’s SDK key, mobile key, or client-side ID for this purpose. To learn how to find your project key, read Project keys.

Troubleshooting

After you create the workflow, you can confirm that it’s working correctly by creating a new pull request with the workflow file and verifying that the newly created action succeeds.

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

Additional configuration options

You can configure find-code-references with additional inputs to enable more functionality. You can find additional configuration options at the bottom of the LaunchDarkly Code References marketplace page.

In addition to inputs, you can skip searching files and directories using a .ldignore file.

You can also use the .launchdarkly/coderefs.yaml file for advanced configuration options, such as configuring custom delimiters and aliases for your flag keys.