> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub code references

> This topic explains how to use the ld-find-code-refs utility with GitHub code references to automatically populate code references in LaunchDarkly.

> For the complete documentation index, see [llms.txt](/llms.txt). For the full documentation snapshot, see [llms-full.txt](/llms-full.txt).

<Note title="Code references are available to customers on select plans">
  Code references 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/).
</Note>

<Note title="On a Developer or Foundation plan?">
  If you're on a Developer or Foundation plan, instead you can use the [Flag Code References in Pull Request GitHub Action](/integrations/github-actions/find-code-references).
</Note>

<Tip title="Additional GitHub Action integrations are also available">
  LaunchDarkly has multiple integrations with GitHub Actions. To learn more, read about the LaunchDarkly integrations [Find Code References in Pull Request](/integrations/github-actions/find-code-references) and [Flag Evaluations](/integrations/github-actions/flag-evaluations).
</Tip>

## Overview

This topic explains how to use the [`ld-find-code-refs`](https://github.com/launchdarkly/ld-find-code-refs/) utility with [GitHub Actions](https://github.com/features/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](https://github.com/marketplace/actions/launchdarkly-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](/home/account/api) and [Code reference actions](/home/account/roles/role-actions#code-reference-actions).

## Set up Git

Hub 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. Paste in your access token to the field that appears and click **Save secret**.
4. 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:

<CodeGroup>
  ```yaml title="YAML" theme={null}
        name: Find LaunchDarkly flag code references
        on: push
        # cancel in-flight workflow run if another push was triggered
        concurrency:
            group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
            cancel-in-progress: true

        jobs:
          launchDarklyCodeReferences:
            name: LaunchDarkly Code References
            runs-on: ubuntu-latest
            steps:
            - uses: actions/checkout@v4
              with:
                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 References
              uses: launchdarkly/find-code-references@v2
              with:
                accessToken: ${{ secrets.LD_ACCESS_TOKEN }}
                projKey: YOUR_PROJECT_KEY
  ```
</CodeGroup>

<Tip title="Best practices for configuring an Actions file">
  We strongly recommend that you update the second `uses` attribute value to reference the most recent tag in the [launchdarkly/find-code-references](https://github.com/launchdarkly/find-code-references) repository. This pins your workflow to a particular version of the `launchdarkly/find-code-references` action.
</Tip>

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

<Note title="Code references are not blocked by PR approval">
  You do not need to have this branch merged into the main branch for code references to appear in the LaunchDarkly user interface (UI). Code references will appear for this newly created branch.
</Note>

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](https://github.com/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](/home/account/project#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](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepswith) to enable more functionality. You can find additional configuration options at the bottom of the [LaunchDarkly Code References marketplace page](https://github.com/marketplace/actions/launchdarkly-code-references#inputs).

In addition to inputs, you can skip searching files and directories using a [`.ldignore`](https://github.com/launchdarkly/ld-find-code-refs/blob/main/docs/CONFIGURATION.md#ignoring-files-and-directories) file.

You can also use the [`.launchdarkly/coderefs.yaml`](https://github.com/launchdarkly/ld-find-code-refs/blob/main/docs/CONFIGURATION.md#advanced-yaml-configuration) file for advanced configuration options, such as configuring custom delimiters and aliases for your flag keys.