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

# From CI/CD pipelines

> Run tests after production or pre-prod deployments

## Authentication

All of the methods below use API key to authenticate. Generate a new API key from the [dashboard](https://dash.empirical.run/).

## GitHub Actions

Use our [dispatch-action](https://github.com/empirical-run/dispatch-action) if you are using GitHub Actions for CI/CD.

```yml theme={null}
- name: Deploy step
  id: deploy-step
  run: ...

- name: Dispatch for tests
  uses: empirical-run/dispatch-action@main
  with:
    auth-key: ${{ secrets.EMPIRICALRUN_KEY }}
    environment: production
    environment-variables: |
      BUILD_URL: ${{ steps.deploy-step.outputs.url }}
```

Use the `environment-variables` input to set environment variables for the test
run, one per line in `NAME: value` format. These override the environment's
configured variables. The URL of the build under test is passed to tests as the
`BUILD_URL` environment variable.

<Note>
  The `build-url` input is deprecated. It is sent to tests as the `BUILD_URL`
  environment variable, so set `BUILD_URL` via `environment-variables` instead.
</Note>

### Vercel deployments

For Vercel deployments, trigger tests on the `deployment_status` event. You can
copy this workflow into `.github/workflows/trigger-e2e.yaml`:

```yml theme={null}
name: Trigger e2e tests

on:
  workflow_dispatch:
  deployment_status:

jobs:
  trigger-e2e-tests-production:
    if: github.event_name == 'workflow_dispatch' ||
        (github.event_name == 'deployment_status' &&
          github.event.deployment_status.state == 'success' &&
          github.event.deployment_status.environment == 'Production')
    runs-on: ubuntu-latest
    steps:
      - name: Dispatch for tests
        uses: empirical-run/dispatch-action@main
        with:
          auth-key: ${{ secrets.EMPIRICALRUN_KEY }}
          environment: production
          environment-variables: |
            BUILD_URL: ${{ github.event.deployment_status.target_url }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

The `GITHUB_TOKEN` environment variable lets the action pull branch info for
the deployment, which is attached to the test run report.

## Other providers

For other CI/CD providers, you can trigger a test run with an API call.

### Minimal snippet

```sh theme={null}
curl -X PUT \
  https://api.empirical.run/api/test-runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMPIRICALRUN_KEY" \
  -d '{ "environment": "production" }'
```

### Metadata for reporting

You can add more metadata which will associated to the test run reports.

* Repo where the trigger was sent from
* Details of the commit or branch
* Other metadata (key-value pairs)

```sh theme={null}
curl -X PUT \
  https://api.empirical.run/api/test-runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMPIRICALRUN_KEY" \
  -d '{
    "environment": "production",
    "build": {
      "url": "$BUILD_URL",
      "commit": "$COMMIT",
      "branch": "$BRANCH",
      "commit_url": "$COMMIT_URL"
    },
    "metadata": {
      "pairs": "of",
      "key": "value"
    },
    "environment_variables_overrides": [
      { "name": "MY_VAR", "value": "my_value" }
    ]
  }'
```