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

When a guardrail declares an input with the same name, it passes its value through. That means you set these values in the guardrail's configuration in buildnote.json.

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

{
  "collect": ["env"]
}

env = guardrail.facts("env")

Facts

These are the fields of the document env collects. In a path, [] means each entry of the list before it, and [path] means a key of the object before it.

Fact	Meaning
ci	Whether the build is running on a CI runner at all, as opposed to a developer's workstation.
provider	CI provider recognised from its own variables: github, gitlab, jenkins, azure, circle, buildkite, teamcity, bitbucket, drone, travis, or local when none is recognised.
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.

If a collector can't finish, it prints what it gathered so far along with an incomplete key that says why. Facts after the point where it stopped are missing, so a check that depends on them should read incomplete first.

Example facts

Here are the facts the env collector gathers from an example project:

{
  "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