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

# Flag Evaluations

<View title="Developer" />

<View title="Federal docs" />

<View title="EU docs" />

This topic explains how to use the Flag Evaluations GitHub Actions integration. The integration lets you evaluate LaunchDarkly feature flags as a step in your [GitHub workflow jobs](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions#jobs) and use those values in later steps.

GitHub Actions is a platform that allows you to automate, customize, and execute your software development workflows in your repository. Using LaunchDarkly feature flags, you can gain additional flexibility and control over your CI/CD pipeline.

## Prerequisites

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

* An SDK token for the LaunchDarkly environment you are using for flag evaluation. Store the token as a repository secret titled `LAUNCHDARKLY_SDK_KEY`.

## Set up Flag Evaluations

To set up Flag Evaluations:

1. Log in to GitHub and navigate to your repo.
2. Navigate to **Settings**, then **Secrets** and click **Add a new secret**.
3. Paste in your SDK key 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 `eval-flags` 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 `eval-flags` job declaration below into the **Edit file** section.

<CodeGroup>
  ```yaml title="Sample workflow: eval-flags job declaration" expandable lines wrap theme={null}
  name: Evaluate LaunchDarkly flags
  on: push
  jobs:
    eval-flags:
      runs-on: ubuntu-latest
      steps:
        - name: Evaluate flags
          id: ld
          uses: launchdarkly/gha-flags@v1.0.1
          with:
            sdk-key: ${{ secrets.LAUNCHDARKLY_SDK_KEY }}
            flags: test-boolean-flag,false
        - name: If true
          if: fromJSON(steps.ld.outputs.test-boolean-flag) == true
          run: echo "It's true"
        - name: If false
          if: fromJSON(steps.ld.outputs.test-boolean-flag) == false
          run: echo "It's false"
  ```
</CodeGroup>

<Tip>
  **Best practices for configuring an actions file**

  We strongly recommend that you update the `uses` attribute value to reference the most recent tag in the [launchdarkly/gha-flags](https://github.com/launchdarkly/gha-flags) repository. This pins your workflow to a particular version of the `launchdarkly/gha-flags` action.
</Tip>

5. Commit this file to the default branch of your repository.

## Format of a flag evaluation

The workflow evaluates the flags listed under the `flags` key of the action. Each flag that the workflow evaluates must include a flag key and fallback value.

The flag key identifies the flag. The SDK serves the fallback value if LaunchDarkly is unreachable or if the flag does not have an off variation set.

<Card icon="rectangle-terminal" horizontal>
  Configure your SDK: [Flag variation evaluation](/docs/sdk/features/evaluating)
</Card>

In the example workflow above, the key is `test-boolean-flag` and the fallback value is `false`.

## Use output in subsequent steps

Each of the flag keys included in the job will have their evaluation output accessible at `steps.<job id>.outputs.<flag key>`.

In the example above the flag key `test-boolean-flag` is available using `steps.ld.outputs.test-boolean-flag`.

GitHub Actions casts all value types to string in the output.

## Contexts created by the integration

Each time you execute this action, the action creates up to three contexts. You can view the created contexts on your [**Contexts** list](/docs/home/flags/contexts-list).

This action creates or updates contexts based on the following mappings:

* The action maps environment variables starting with `GITHUB_` to a context with the kind `GitHub`.
* The action maps environment variables starting with `RUNNER_` to a context with the kind `GitHubRunner`.
* If you pass additional variables into the action, the action maps any variables starting with `LD_` to a context with the kind `GitHubCustomAttributes`.

For a list of the automatically mapped in environment variables, read GitHub's [default environment variables](https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables).

## Limitations

This integration currently has the following limitations:

* Use of JSON feature flags is not officially supported.
* GitHub Actions casts output to `string` type.
* If no fallback value is provided for a feature flag, `null` is returned for the value.
* [Code References](/docs/home/flags/code-references) does not surface flags used in workflow files.

## Troubleshooting

After you create the workflow, you can confirm that it's working correctly by pushing an empty commit 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.