CI Environments

Buildkite Test Analytics collectors automatically detect common continuous integration (CI) environments. If available, test collectors gather information about your test runs, such as branch names and build IDs. Test collectors gather information from the following CI environments:

  • Buildkite
  • CircleCI
  • GitHub Actions

If you run test collectors inside containers or you're using another CI system, then you must set variables to report your CI details to Buildkite.

If you're not using a test collector, see Importing JSON and Importing JUnit XML to learn how to provide run environment data.

Containers and test collectors

If you're using containers within your CI system, then the environment variables used by test collectors may not be exposed to those containers by default. Make sure to export your CI environment's variables and your Buildkite API token to your containerized builds and tests.

For example, by default Docker does not receive the host's environment variables. To pass them through to the Docker container, use the --env option:

  docker run \
    --env BUILDKITE_ANALYTICS_TOKEN \
    --env BUILDKITE_BUILD_ID \
    --env BUILDKITE_BUILD_NUMBER \
    --env BUILDKITE_JOB_ID \
    --env BUILDKITE_BRANCH \
    --env BUILDKITE_COMMIT \
    --env BUILDKITE_MESSAGE \
    --env BUILDKITE_BUILD_URL \
    bundle exec rspec

Review the following sections for the environment variables expected by test collectors.

Buildkite

During Buildkite pipeline runs, test collectors upload information from the following environment variables, and test importers use the following field names:

Field name Environment variable Description
Field name run_env[branch] Environment variable BUILDKITE_BRANCH Description the branch or reference for this build
Field name run_env[key] Environment variable BUILDKITE_BUILD_ID Description the UUID for the build
Field name run_env[number] Environment variable BUILDKITE_BUILD_NUMBER Description the build number
Field name run_env[url] Environment variable BUILDKITE_BUILD_URL Description the URL for the build on Buildkite
Field name run_env[commit] Environment variable BUILDKITE_COMMIT Description the commit hash for the head of the branch
Field name run_env[job_id] Environment variable BUILDKITE_JOB_ID Description the job UUID
Field name run_env[message] Environment variable BUILDKITE_MESSAGE Description the commit message for the head of the branch

CircleCI

During CircleCI workflow runs, test collectors upload information from the following environment variables, and test importers use the following field names:

Field name Environment variable Description
Field name run_env[branch] Environment variable CIRCLE_BRANCH Description the branch or reference being built
Field name See note below Environment variable CIRCLE_BUILD_NUM Description the number for the job
Field name run_env[url] Environment variable CIRCLE_BUILD_URL Description the URL for the job on CircleCI
Field name run_env[commit_sha] Environment variable CIRCLE_SHA1 Description the commit hash for the head of the branch
Field name See note below Environment variable CIRCLE_WORKFLOW_ID Description the unique identifier for the workflow run

For CircleCI runs:

run_env[key]=$CIRCLE_WORKFLOW_ID-$CIRCLE_BUILD_NUM"

GitHub Actions

During GitHub Actions workflow runs,test collectors upload information from the following environment variables, and test importers use the following field names:

Field name Environment variable Description
Field name See note below Environment variable GITHUB_ACTION Description the name of the action running or its step ID
Field name run_env[branch] Environment variable GITHUB_REF_NAME Description the ref (branch or tag) that triggered the workflow run
Field name run_env[url] Environment variable GITHUB_REPOSITORY Description the repository owner and repository name
Field name See note below Environment variable GITHUB_RUN_ATTEMPT Description the numbered attempt of the workflow run
Field name run_env[commit_sha] Environment variable GITHUB_SHA Description the commit hash for the head of the branch
Field name See note below Environment variable GITHUB_RUN_ID Description the unique number for the workflow run
Field name run_env[number] Environment variable GITHUB_RUN_NUMBER Description the cumulative number of runs for the workflow

For GitHub Action runs:

run_env[key]=$GITHUB_ACTION-$GITHUB_RUN_NUMBER-$GITHUB_RUN_ATTEMPT"`

Other CI providers

If you're using other CI providers (or containers), then set environment variables for test collectors to gather information about your builds and tests. If you don't set these environment variables, then Test Analytics lacks the details needed to produce useful reports.

Each environment variable corresponds to a run_env key in the payload https://analytics-api.buildkite.com/v1/uploads. Read Importing JSON to learn how these keys are used to make API calls.

Field name Environment variable Description
Field name run_env[key] Environment variable BUILDKITE_ANALYTICS_KEY Description

A unique key for the build that initiated the CI run

Examples: c5636a53-b2d7-4224-92ee-1677b3e76910
Field name run_env[url] Environment variable BUILDKITE_ANALYTICS_URL Description

A URL that links to the build in your CI system

Examples: https://ci.example.com/project1/runs/a086005a/attempts/4
Field name run_env[branch] Environment variable BUILDKITE_ANALYTICS_BRANCH Description

A version control branch or reference for this run

Examples: main, ref/heads/develop, JIRA-3494-fix-off-by-one-error
Field name run_env[commit_sha] Environment variable BUILDKITE_ANALYTICS_SHA Description

A unique identifier for the version control revision for this run

Examples: 26a5144c, 49239:a94f28be2e6e, 26916
Field name run_env[number] Environment variable BUILDKITE_ANALYTICS_NUMBER Description

A counter for this build.

This number must be unique for each build key, but not necessarily globally unique.

Examples: 0, 1, 4
Field name run_env[job_id] Environment variable BUILDKITE_ANALYTICS_JOB_ID Description

An identifier for a job within a build

Examples: build_stage_1, smoke-test, publish
Field name run_env[message] Environment variable BUILDKITE_ANALYTICS_MESSAGE Description

The commit message or other description of the build

Examples: Fix off by one error