Guardrails / Collectors

CI environment

Where the build is running: which CI provider, whether the runner is hosted or self hosted, what triggered it, and whether federated credentials are available to it.

Facts key	env
Version	v1
Script	env.py
Timeout	30 seconds

Inputs

Input	Description	Default	Environment
envFile	Read the environment from this KEY=VALUE file instead of the process environment. Meant for testing a guardrail against a runner you are not on.	``	GUARDRAIL_INPUT_ENVFILE

A guardrail that declares an input of the same name passes it through, so the guardrail's configuration in buildnote.json is what decides these values.

A guardrail asks for these facts by name, and reads them back the same way:

{
  "collect": ["env"]
}

env = guardrail.facts("env")

Facts

The document env collects. A path carrying [] is an entry of the list before it, and one carrying [path] is a key of the object before it.

Fact	Meaning
ci	Whether the build is running on a CI runner at all rather than on somebody's workstation.
provider	CI provider recognised from its own variables: github, gitlab, jenkins, azure, circle, buildkite, teamcity, bitbucket, drone, travis, or local when none of them.
hosted	Whether the runner is the provider's own hosted fleet. false for a self hosted runner, null when the provider does not say.
trigger	What started the build, as the provider names it, or null.
pullRequest	Whether the build is for a pull or merge request.
fork	Whether that request came from a fork, null when the provider does not say. A fork build is the one that must run without secrets.
runner.os	Operating system the runner reports, or null.
runner.arch	Architecture the runner reports, or null.
runner.name	Name the runner reports, or null.
oidc	Whether a federated identity token is available to this job, so a pipeline can reach a cloud without a long lived key.
variables	Names of the CI variables that were set. Names only, never values: the facts are attached to the run event and a value can be a credential.

A collector that cannot finish prints what it had along with an incomplete key saying why, so the facts below the point it stopped are absent. A check that cares reads incomplete before the rest.

Example facts

The example facts collected by env collector:

{
  "provider": "github",
  "ci": true,
  "hosted": true,
  "trigger": "pull_request",
  "pullRequest": true,
  "fork": null,
  "runner": {
    "os": "Linux",
    "arch": "X64",
    "name": "GitHub Actions 4"
  },
  "oidc": true,
  "variables": [
    "CI",
    "GITHUB_ACTIONS",
    "GITHUB_BASE_REF",
    "GITHUB_EVENT_NAME",
    "GITHUB_HEAD_REF",
    "GITHUB_RUN_ID",
    "GITHUB_WORKFLOW",
    "RUNNER_ARCH",
    "RUNNER_ENVIRONMENT",
    "RUNNER_NAME",
    "RUNNER_OS"
  ]
}

Collected for

Guardrail	Category	Inputs
build/runs-on-hosted-ci	build	none

All collectors