Dispatch action

Usage

- name: Build step
  id: prev-step
  run: ...

- name: Dispatch for tests
  uses: empirical-run/dispatch-action@v1
  with:
    auth-key: ${{ secrets.EMPIRICALRUN_KEY }}
    environment: production # or staging or mobile
    environment-variables: |
      BUILD_URL: ${{ steps.prev-step.outputs.url }}
    concurrency: |
      group: production/acme/web
      on-conflict: wait

Supported inputs

• auth-key: Required input, for authentication.
• environment: Required input, to specify which environment to run the tests against. Configure environments by contacting us.
• environment-variables: Optional environment variables for the test run, one per line (e.g. NAME: value). These override the environment's configured variables.
  • Use BUILD_URL to point the tests at the application build under test
  • For web, this points to a URL of the deployment (e.g. https://staging.your-app.com)
  • For mobile, this points to a downloadable file, ending in .apk, .aab or .ipa
• metadata: Optional key-value pairs for custom metadata, one per line (e.g. key: value)
• concurrency: Optional concurrency settings, with group and on-conflict (cancel or wait) on separate lines.
• wait: Optional, defaults to false. When true, the step polls the run until it finishes and fails unless the run ended with no failures (snoozed failures are ignored). Bound the wait with the job's timeout-minutes. If the job is cancelled or times out while waiting, the action cancels the test run.
• build-url: Deprecated, the build URL is sent to tests as the BUILD_URL environment variable — set it via environment-variables instead.

With metadata

- name: Dispatch for tests
  uses: empirical-run/dispatch-action@v1
  with:
    auth-key: ${{ secrets.EMPIRICALRUN_KEY }}
    environment: production
    environment-variables: |
      BUILD_URL: ${{ steps.prev-step.outputs.url }}
    metadata: |
      version: 1.2.3
      pr_number: 42

Wait for the run to finish

- name: Run tests
  uses: empirical-run/dispatch-action@v1
  timeout-minutes: 60
  with:
    auth-key: ${{ secrets.EMPIRICALRUN_KEY }}
    environment: production
    wait: true

Vercel deployments

If you are dispatching test run requests for Vercel deployments, it is a good idea to add the GITHUB_TOKEN environment variable to pull branch info.

- name: Dispatch for tests
  uses: empirical-run/dispatch-action@v1
  with:
    auth-key: ${{ secrets.EMPIRICALRUN_KEY }}
    environment: production # or staging or mobile
    environment-variables: |
      BUILD_URL: ${{ github.event.deployment_status.target_url }}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Versioning

Use @v1 to receive backwards-compatible fixes without automatically adopting breaking releases. Pin an exact version such as @v1.0.0 when you need an unchanging release reference.

Development

Source lives in the empirical monorepo under github-actions/dispatch (part of the pnpm workspace). The public empirical-run/dispatch-action repo is a distribution mirror (action.yml + generated dist/), published by the sync-github-action-dispatch workflow. Monorepo main syncs to both public main (v1 and legacy @main consumers) and public release/v2. Stable releases are published as exact and moving major-version tags. See the release guide for the release steps.

pnpm install
pnpm --filter @empiricalrun/shared-types build
pnpm --filter @empiricalrun/dispatch-action build