LaunchDarkly Developer Documentation

Get started in under 30 minutes.
LaunchDarkly provides feature flags as a service for Java · Python · Ruby · Go · Node.js · PHP · .NET. Control feature launches -- who sees what and when -- without multiple code deploys. Easy dashboard for phased rollouts, targeting and segmenting.
Need more help? write us at support@launchdarkly.com

Get Started    Documentation

GitHub Actions

Overview

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

Prerequisites

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

  • A personal API access token with writer permissions, stored as a repository secret titled LD_ACCESS_TOKEN. To learn more, read Personal API access tokens.

Setting up GitHub Actions

To set up

  1. Log into GitHub and navigate to your repo.
  2. Navigate to Settings > Secrets and click Add a new secret.
  3. Paste in your access token to the field that appears and click Save secret.
GitHub's secret configuration screen.

GitHub's secret configuration screen.

  1. Return to your GitHub repository to create a new Actions workflow.
    • If you already have a 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:
on: push
name: Example Workflow
jobs:
  launchDarklyCodeReferences:
    name: LaunchDarkly Code References
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v1
    - name: LaunchDarkly Code References
      uses: launchdarkly/find-code-references@v3
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        LD_ACCESS_TOKEN: ${{ secrets.LD_ACCESS_TOKEN }}
        LD_PROJ_KEY: YOUR_PROJECT_KEY

Best practices for configuring an Actions file

We strongly recommend that you update the second uses attribute value to reference the latest tag in the launchdarkly/find-code-references repository.

This pins your workflow to a particular version of the launchdarkly/find-code-references action.

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

Code references are not blocked by PR approval

You do not need to have this branch merged into the master branch for code references to appear in the LaunchDarkly UI; code references will appear for this newly created 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 both the LD_ACCESS_TOKEN as a secret and a new environment variable containing your LaunchDarkly project key.

Troubleshooting

Once your workflow is 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, review the action's logs to view any error messages.

Additional configuration options

You can configure ld-find-code-refs with additional environment variables to enable more functionality.

Variable
Description
Required

LD_ACCESS_TOKEN

A LaunchDarkly personal access token with writer-level access, or access to the code-reference-repository custom role resource. Supply this as a GitHub repository secret.

yes

LD_PROJ_KEY

A LaunchDarkly project key. The flag finder searches this project for code references in this project.

yes

LD_EXCLUDE

A regular expression (PCRE) defining the files and directories which the flag finder should exclude. Partial matches are allowed.

Examples: vendor/, vendor/.*

no

LD_CONTEXT_LINES

The number of context lines above and below a code reference for the flag finder to send to LaunchDarkly.

If < 0, no source code will be sent to LaunchDarkly.

If 0, only the lines containing flag references will be sent.

If > 0, will send that number of context lines above and below the flag reference.

A maximum of 5 context lines may be provided. Defaults to 2.

no

LD_BASE_URI

Set the base URL of the LaunchDarkly server for this configuration. Defaults to https://app.launchdarkly.com.

no

LD_DEBUG

Enables verbose default logging. Defaults to false.

no

LD_DELIMITERS

Specifies additional delimiters used to match flag keys. Must be a non-control ASCII character. If you provide more than one character in delimiters, each character is treated as a separate delimiter.
This only matches flag keys surrounded by any of the specified delimeters.

You can also specify this option multiple times for multiple delimiters. By default, only flags delimited by single-quotes, double-quotes, and backticks are matched.

Default: [" ']`.

no

Here's an example of a workflow configured to exclude the vendor directory and send 1 line of context above and below each code reference for each flag in the default project:

on: push
name: Example Workflow
jobs:
  launchDarklyCodeReferences:
    name: LaunchDarkly Code References
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v1
    - name: LaunchDarkly Code References
      uses: launchdarkly/find-code-references@v3
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        LD_ACCESS_TOKEN: ${{ secrets.LD_ACCESS_TOKEN }}
        LD_PROJ_KEY: YOUR_PROJECT_KEY
        LD_EXCLUDE: "vendor/"
        LD_CONTEXT_LINES: "1"

GitHub Actions


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.