Every variable hushrun reads: the HUSHRUN_ ones you set, and the ones CI providers and other tools set. A command-line flag wins over its variable, as Configuration explains.
- An empty value counts as unset, except in two variables, where it turns something off:
HUSHRUN_BACKEND= turns results off, and HUSHRUN_CACHE_DIR= the cache. HUSHRUN_CONFIG, HUSHRUN_FORMAT, HUSHRUN_NO_CI_OUTPUT, HUSHRUN_FORCE_FULL, HUSHRUN_GIT_READER and HUSHRUN_LOG stand in for flags, and never stop a command. The true-or-false ones also take 1, 0, yes, no, on and off, in any case. A value hushrun can't read is ignored, with one line on stderr, such as hushrun: HUSHRUN_FORMAT is "xml", not text, json, env or dotenv, so it's ignored, and the command goes on with the default. The same goes for an unknown HUSHRUN_PROVIDER, and for a HUSHRUN_RUN_ATTEMPT or GITHUB_RUN_ATTEMPT that isn't a positive whole number. -q drops these lines. A bad flag on the command line is still a usage error.- Variables such as
HUSHRUN_MODE and HUSHRUN_DIGEST are outputs hushrun prints, not settings: see Output formats.
What hushrun run uses to find its backend, and the token it sends there. Where results go has the rules in full.
| Variable | Default | What it does | Secret |
|---|
HUSHRUN_BACKEND | Unset | The organization's URL where hushrun run records and looks up results, such as https://api.hushrun.com/o/acme. It ranks first, before the backend in package.json and the one hushrun login saved. Set to nothing, it turns results off: every check runs, and nothing is recorded. A URL that isn't https://, or http:// on localhost, 127.0.0.1 or [::1], turns them off too, with a message. hushrun login signs in to it, and hushrun token manages its tokens, when no URL is given | No |
HUSHRUN_TOKEN | Unset | A token for the results backend. It goes only to the backend HUSHRUN_BACKEND names. An agent token, hra_…, also goes to the repository's or the login's backend when it is on HUSHRUN_HOST, and to the repository's URL on that server, in CI too. An agent token's results need the key it came with, in HUSHRUN_MACHINE_KEY or HUSHRUN_MACHINE_KEY_FILE. The hushrun token commands never use it | Yes |
HUSHRUN_HOST | https://api.hushrun.com | hushrun's hosted server: where hushrun login signs in when nothing names a backend, and npx hushrun init when package.json names none. It is the only server an agent token follows package.json's backend, the login's, or hushrun.yaml's repository URL to | No |
For coding agents in sandboxes, and for checks that hushrun run --isolated runs in containers. See Agents and sandboxes.
| Variable | Default | What it does | Secret |
|---|
HUSHRUN_PROVIDER | Detected, see CI detection | The CI provider running hushrun, instead of detecting it: github, gitlab, buildkite, circleci, generic or local. Set local in a sandbox that sets CI=true, so that hushrun doesn't treat it as CI. Another value is ignored, with a line saying so, and hushrun detects the provider | No |
HUSHRUN_INVOKED_BY | Unset | A label for who ran the command, agent:<id> or human:<id>, such as agent:worker-1, to tell a fleet's runs apart. Run results and signed events record it; nothing decides on it. In hushrun run without a stage, another form is left out with a line saying so; commands that sign events exit 2 | No |
HUSHRUN_MACHINE_KEY | Unset | This machine's key itself, as PEM, for sandboxes that keep no files. It wins over the key file. An agent's is the key its token came with, which hushrun token create and the dashboard's Agents page show once: with an agent token, hushrun signs results only with this or HUSHRUN_MACHINE_KEY_FILE, never a key a sign-in left on the machine, and without either it records nothing. In CI, hushrun signs events with a machine key only when this or HUSHRUN_MACHINE_KEY_FILE is set | Yes |
HUSHRUN_CONTAINER_RUNTIME | docker, else podman, found on PATH | The container runtime hushrun run --isolated uses: docker, podman, or the path of a Docker-compatible CLI | No |
HUSHRUN_RESTRICTED_NETWORK | Unset | The Docker or Podman network, whose egress you restrict, that a check declaring network: restricted runs on. Without it, such a check can't run isolated, and the command exits 2 | No |
Run identity on CI other than GitHub Actions and GitLab CI, which set their own (see Set by CI providers), and a token for GitLab's API.
| Variable | Default | What it does | Secret |
|---|
HUSHRUN_RUN_ID | Unset | On CI other than GitHub Actions and GitLab CI, the run's id, which signed events record. There, a command that records events exits 2 without it, unless it carries out a plan, whose id it takes | No |
HUSHRUN_RUN_ATTEMPT | Unset | On GitLab CI and other CI, this run's attempt, a positive whole number. Without it, commands take the plan's attempt, else 1, and hushrun plan counts one more than recorded. Another value is ignored, with a line saying so. GitHub Actions' attempt comes from GITHUB_RUN_ATTEMPT, read the same way | No |
HUSHRUN_RUN_URL | Unset | On CI other than GitHub Actions and GitLab CI, a link to the run, which run results and events record | No |
HUSHRUN_GITLAB_TOKEN | Unset | A GitLab project access token with read_api. With it, hushrun plan asks GitLab whether an upstream pipeline is still running, and hushrun doctor checks protected branches and who may set pipeline variables | Yes |
How commands that record promotion events sign them, and what verifies signatures. All of it comes from the environment, never from the repository's files. See Evidence from agents.
| Variable | Default | What it does | Secret |
|---|
HUSHRUN_SIGNING | A set signing key means key; else, in GitHub Actions with an ID token, sigstore; else machine, when there is a machine key, which in CI only HUSHRUN_MACHINE_KEY or HUSHRUN_MACHINE_KEY_FILE gives; else, in CI with SIGSTORE_ID_TOKEN, sigstore | How events are signed: key, sigstore (keyless, through Sigstore) or machine (this machine's key, which hushrun login registered, or HUSHRUN_MACHINE_KEY). Another value exits 2, and so does a command that signs with no signer | No |
HUSHRUN_SIGNING_KEY | Unset | A signing key's PEM, Ed25519 or ECDSA P-256, for key. It wins over HUSHRUN_SIGNING_KEY_FILE | Yes |
HUSHRUN_SIGNING_KEY_FILE | Unset | The path of a signing key's PEM file, for key. An isolated run refuses a key file inside the files it exports | No; the file is a private key |
HUSHRUN_CUSTODY | ci in CI; isolated for checks hushrun run --isolated runs; else local | The custody signed events claim: local, isolated, sandbox or ci. isolated is recorded only for --isolated runs; otherwise hushrun records local, with a warning. Another value exits 2 | No |
HUSHRUN_TSA | https://timestamp.sigstore.dev/api/v1/timestamp | The timestamp authorities for each signature, URLs separated by commas, tried in order. none turns timestamps off, which keyless signing refuses | No |
HUSHRUN_FULCIO_URL | https://fulcio.sigstore.dev | The Fulcio that certifies keyless signatures | No |
HUSHRUN_OIDC_ISSUER | https://oauth2.sigstore.dev/auth | Outside CI, for keyless signing as yourself: where you sign in with your browser. Without a terminal, hushrun signs in only to an issuer this variable names | No |
HUSHRUN_OIDC_CLIENT_ID | sigstore | The client id for that sign-in | No |
HUSHRUN_SIGSTORE_TRUSTED_ROOT | The trust root hushrun sigstore refresh cached, else the one built into hushrun | The path of a Sigstore trusted_root.json that verifies certificates and timestamps | No |
HUSHRUN_SIGSTORE_TUF_URL | https://tuf-repo-cdn.sigstore.dev | Another Sigstore TUF repository for the trust root. Set it with HUSHRUN_SIGSTORE_TUF_ROOT, or neither; with both, hushrun needs a cached trust root from hushrun sigstore refresh | No |
HUSHRUN_SIGSTORE_TUF_ROOT | The root built into hushrun | The path of the TUF root that repository starts from | No |
Where the promotion commands read and write the repository's events, with which token, and from which plan and hushrun.yaml. Configuration has the order, which differs in CI.
| Variable | Default | What it does | Secret |
|---|
HUSHRUN_REPOSITORY_URL | Unset | The repository's URL on hushrun, such as https://api.hushrun.com/l/acme/shop. In CI it is the URL that counts: when hushrun.yaml's repository_url names another, or --repository-url does, the command exits 2 | No |
HUSHRUN_REPOSITORY_BASE | Unset | One URL for an organization: each repository's URL is <base>/<repository id>, such as https://api.hushrun.com/l/acme/github.com/acme/shop. In CI, the id comes from the CI provider, and hushrun.yaml's repository and repository_url must agree with it, or the command exits 2. HUSHRUN_REPOSITORY_URL wins when both are set. It is also hushrun adopt's default --repository-base | No |
HUSHRUN_REPOSITORY_TOKEN | Unset | A token for the repository's server. It goes only to a URL that HUSHRUN_REPOSITORY_URL or --repository-url names, or in CI one HUSHRUN_REPOSITORY_BASE gives, never to one only hushrun.yaml names | Yes |
HUSHRUN_REPOSITORY_TOKEN_COMMAND | Unset | A command that prints that token and nothing else, run with sh -c (cmd /C on Windows) and with HUSHRUN_REPOSITORY_URL set to the server's URL. hushrun reuses what it prints for 5 minutes. Its token goes where HUSHRUN_REPOSITORY_TOKEN goes, which wins when both are set | No; it prints one |
HUSHRUN_CONFIG | hushrun.yaml in the content being evaluated | The path of hushrun.yaml, as --config | No |
HUSHRUN_PLAN_JSON | Unset | The plan itself, as JSON, for the commands that carry one out, run --stage, attest, mark, guard and artifact resolve, when --plan isn't given | No |
HUSHRUN_FORCE_FULL | false | true makes hushrun plan build and run every check whatever the evidence, as --force-full | No |
Without a token from these, the repository's server gets, in GitHub Actions, the job's ID token; else an agent token in HUSHRUN_TOKEN, when the server is HUSHRUN_HOST, in CI too; else, outside CI, the token hushrun login saved for that server.
<config dir> is ~/.config on Linux, ~/Library/Application Support on macOS and %APPDATA% on Windows; <cache dir> is ~/.cache, ~/Library/Caches and %LOCALAPPDATA%. Configuration lists what each file holds.
| Variable | Default | What it does | Secret |
|---|
HUSHRUN_CREDENTIALS | <config dir>/hushrun/credentials.json | The file hushrun login keeps its tokens in, readable by you only | No; the file holds tokens |
HUSHRUN_MACHINE_KEY_FILE | machine-key.pem beside the credentials file | This machine's key file. hushrun refuses one inside the repository it runs in. With an agent token, and in CI, set it to the agent's key file, such as a GitLab File variable, for hushrun to sign with it | No; the file is a private key |
HUSHRUN_CACHE_DIR | <cache dir>/hushrun | hushrun's cache: hushrun run's results when no backend applies, file hashes, the tokens this machine registered with, the Sigstore trust root hushrun sigstore refresh keeps, and isolated runs' exports. Set to nothing, it turns the cache off, and with it the results kept on this machine | No |
HUSHRUN_EXPORT_DIR | exports in hushrun's cache directory, else the system's temporary directory | Where hushrun run --isolated exports the files a check runs on. Point it at a case-sensitive directory when two paths differ only in case | No |
| Variable | Default | What it does | Secret |
|---|
HUSHRUN_NPM_PACKAGE | hushrun@^<version> | The package hushrun init adds to devDependencies. The npm package's hushrun command sets it to its own name and version unless it is set | No |
HUSHRUN_BINARY | Unset | Read by the npm package's hushrun command: a hushrun binary to run where the package has none for this platform | No |
| Variable | Default | What it does | Secret |
|---|
HUSHRUN_FORMAT | text | The output format, as --format: text, json, env or dotenv | No |
HUSHRUN_NO_CI_OUTPUT | false | true writes no CI outputs, step summaries or annotations, as --no-ci-output | No |
HUSHRUN_LOG | warn | The log filter on stderr, such as info or debug, when neither -v nor -q is given. A value hushrun can't read is ignored, with a line saying so. -q leaves errors only | No |
HUSHRUN_GIT_READER | auto | How hushrun reads git objects: auto, gix or cli. Meant for hushrun's own tests | No |
hushrun takes the first of these that is true or 1 as the CI it runs in, unless HUSHRUN_PROVIDER names one. In CI, the promotion commands take the repository's URL by CI's rules; sign keylessly by default in GitHub Actions with an ID token, and elsewhere with the agent's machine key the environment gives; claim custody ci; and send no person's login to the repository's server, only an agent token, to HUSHRUN_HOST. hushrun approve refuses to run; and hushrun run records which CI a result came from, so that a later skip says passed in CI.
| Variable | What hushrun uses it for |
|---|
GITHUB_ACTIONS | GitHub Actions |
GITLAB_CI | GitLab CI |
BUILDKITE | Buildkite, identified as generic CI: runs need HUSHRUN_RUN_ID |
CIRCLECI | CircleCI, identified as generic CI: runs need HUSHRUN_RUN_ID |
CI | Any other CI, generic: runs need HUSHRUN_RUN_ID |
| Variable | What hushrun uses it for |
|---|
ACTIONS_ID_TOKEN_REQUEST_URL, ACTIONS_ID_TOKEN_REQUEST_TOKEN | Set when the job has permissions: id-token: write. hushrun asks for ID tokens with them: for the results backend, for the repository's server, and for keyless signing, each with its own audience |
GITHUB_RUN_ID, GITHUB_RUN_ATTEMPT | The run's identity, which events record, and the run's link in run results |
GITHUB_REPOSITORY | The repository, owner/name: the id hushrun run records results under, the one HUSHRUN_REPOSITORY_BASE uses, and the default of hushrun token create and hushrun adopt |
GITHUB_SERVER_URL | GitHub's address, https://github.com by default, for the repository's id and the run's link |
GITHUB_REPOSITORY_ID | The repository's numeric id. When the server names another id as the repository's CI, hushrun exits 2 |
GITHUB_EVENT_NAME | What started the run: push; workflow_run as upstream; workflow_dispatch and repository_dispatch as manual; schedule. pull_request and pull_request_target make it a pull request's pipeline |
GITHUB_EVENT_PATH | The event's payload: the upstream run of a workflow_run, and the repository's default branch |
GITHUB_BASE_REF | The branch a pull request merges into, which --config-ref must name |
GITHUB_REF | The branch, from refs/heads/… |
GITHUB_SHA | The revision the run is for |
GITHUB_JOB | The job, which events record |
GITHUB_OUTPUT, GITHUB_STEP_SUMMARY | Where plan, digest, guard, attest and artifact write their outputs and a step summary |
GITHUB_TOKEN, GH_TOKEN | When set, a token with actions: read: hushrun plan asks GitHub's API whether an upstream run is still going, and hushrun doctor checks the default branch |
GITHUB_API_URL | GitHub's API, https://api.github.com by default |
| Variable | What hushrun uses it for |
|---|
SIGSTORE_ID_TOKEN | The ID token for keyless signing: on GitLab, the job's id_tokens entry SIGSTORE_ID_TOKEN with aud: sigstore. On other CI, any ID token Fulcio takes |
CI_PIPELINE_ID, CI_PIPELINE_URL | The run's identity and link |
CI_PIPELINE_SOURCE | What started the run: push; pipeline, parent_pipeline and trigger as upstream; web and api as manual; schedule. merge_request_event makes it a merge request's pipeline |
CI_MERGE_REQUEST_TARGET_BRANCH_NAME | The branch a merge request merges into, which --config-ref must name |
CI_COMMIT_BRANCH | The branch |
CI_COMMIT_SHA | The revision the run is for |
CI_JOB_NAME, CI_JOB_ID | The job, which events record |
CI_PROJECT_URL | The repository: the id hushrun run records results under, and the one HUSHRUN_REPOSITORY_BASE uses |
CI_PROJECT_ID | The project's numeric id. When the server names another id as the repository's CI, hushrun exits 2. With HUSHRUN_GITLAB_TOKEN, the project hushrun asks GitLab's API about |
CI_PROJECT_PATH | The project for GitLab's API, when CI_PROJECT_ID isn't set |
CI_DEFAULT_BRANCH | The repository's default branch |
CI_API_V4_URL | GitLab's API, https://gitlab.com/api/v4 by default |
| Variable | What hushrun uses it for |
|---|
npm_lifecycle_event | The script npm, pnpm, Yarn and Bun are running. hushrun run without NAME names the check after it, unless it is npx, which npx and npm exec set, or isn't a valid name |
| Variable | What hushrun uses it for |
|---|
NO_COLOR | Set, it turns off colored logs under --color auto |
BROWSER | The command that opens the sign-in page for keyless signing as yourself, at a terminal; without it, the system's opener |
DOCKER_CONFIG | The directory whose config.json holds registry credentials, ~/.docker by default: its credHelpers, credsStore and auths |
PATH, PATHEXT | Where hushrun run finds the command. On Windows, a bare name is looked up with PATHEXT's .com, .exe, .bat and .cmd, so vitest finds node_modules\.bin\vitest.cmd |
XDG_CONFIG_HOME, XDG_CACHE_HOME | On Linux, the configuration and cache directories, ~/.config and ~/.cache by default |