Configuring guardrails

The guardrails section of buildnote.json lists the guardrails that buildnote guardrails runs. Each entry names a guardrail from the shared library and configures it for your project. The same block in a separate file is a policy, which applies to one part of a repository instead of the whole thing.

{
  "guardrails": {
    "failOn": "error",
    "checks": [
      {
        "use": "git/conventional-commits@v1",
        "severity": "error",
        "with": {
          "baseRef": "origin/main"
        },
        "exemptions": [
          "^Revert "
        ]
      }
    ]
  }
}

Option	Type	Default	Description
failOn	string	error	The severity at which a failing guardrail fails the build. One of error, warning, never.
sources	array	[]	Libraries that references resolve against after buildnote/guardrails.
checks	array	[]	The guardrails to run.

A guardrail runs if it's listed in checks. Delete its entry to stop running it, or use --only <id> to run a single guardrail without editing the file.

sources

References always resolve against buildnote/guardrails on GitHub first, and that's the only library you need for the guardrails Buildnote ships. sources adds your own libraries after it, in the order you list them. If buildnote/guardrails doesn't declare a reference, each source is checked in turn, and the first one that declares it wins.

{
  "guardrails": {
    "sources": [
      "github://company/our-guardrails",
      "./guardrails"
    ],
    "checks": [
      {
        "use": "team/no-todo-in-main@v1"
      }
    ]
  }
}

Form	Resolves to
github://<owner>/<repository>	https://raw.githubusercontent.com/<owner>/<repository>/<version>/..., so the reference's version is the git ref, and a tag pins it
a path such as ./guardrails	that directory on the machine running the command. A directory has a single version, so the reference's version is ignored

A use reference can also name a repository inline as github://<owner>/<repository>/<category>/<name>@<version>. That reference resolves against that repository only, ignoring both buildnote/guardrails and sources. The exception is collectors and the helper: if that repository doesn't ship them, the CLI falls back to buildnote/guardrails, so "collect": ["git"] works even in a guardrail Buildnote never shipped.

If no source declares a guardrail, that's a configuration error, not a skip, so a mistyped id never passes quietly. A source that can't be reached at all counts as missing evidence instead, and is recorded as skipped.

What a source runs on your machine

A guardrail resolved from one of your own sources downloads a check script and its collectors' scripts, and runs them on the machine running the command. Run buildnote --verbose guardrails to print the resolved location and the SHA-256 of every script it runs, for collectors as well as checks. sha256 on a check entry pins the check script only, not the collector scripts it reads facts from. So for a github:// source you don't own, point it at a tag, never a branch.

checks

Option	Type	Default	Description
use	string	required	The guardrail reference, [github://<owner>/<repository>/]<category>/<name>@<version>. It names a guardrail from the library the CLI ships, from a sources entry, or from the repository named in the reference itself. The version is required. See Writing a guardrail.
severity	string	definition value	Overrides the definition's severity. One of error, warning, info.
with	object	{}	Values for the guardrail's inputs, overriding the defaults in its definition.
exemptions	array	[]	Regular expressions matched against a violation's evidence line. Matching violations are dropped before the verdict is decided.
sha256	string	none	Pins the check script's SHA-256. If it doesn't match, the guardrail is skipped with a warning instead of running.

Each shipped guardrail's page has an example you can copy, with that guardrail's own inputs. The guardrails reference lists them all.

Policies

A policy is the same guardrails block in a separate file, with a name and the directories it applies to. In a repository with several modules, you can give each module its own policy instead of sharing one buildnote.json across all of them.

{
  "name": "checkout",
  "moduleId": "checkout",
  "paths": [
    "services/checkout",
    "services/checkout-worker"
  ],
  "guardrails": {
    "failOn": "error",
    "checks": [
      {
        "use": "git/conventional-commits@v1"
      }
    ]
  },
  "report": {
    "github": {
      "enabled": true
    }
  }
}

buildnote guardrails --policy policies/checkout.json

Option	Type	Default	Description
name	string	the file name without its extension	The policy's name, used in its pull request comment and in the report it writes.
moduleId	string	the policy name	The module the events are submitted under. This keeps two policies in the same build apart.
paths	array	the directory the policy file is in	The directories the checks run in, relative to where you run the command.
guardrails	object	none	The same block as in buildnote.json, replacing it for this run.
report	object	the report of buildnote.json	The same block as in buildnote.json, replacing it for this run.

--policy replaces the guardrails and report sections of buildnote.json instead of adding to them. --only, --fail-on and the --slack-*, --discord-*, --github-* and --html-* reporter options narrow or override the policy exactly as they do for the file. Each command runs one policy. A job that runs several policies gets one pull request comment and one HTML report per policy, each named after it.

Every collector runs once per path, so a check sees the directory the policy applies to, not the repository root. A guardrail that runs over several paths reports one verdict with the violations from every path, each prefixed with the path where it was found. A path that isn't a directory is a configuration error: the command reports it and exits with a non zero code.

Reporting without gating

With failOn set to never, guardrails report their verdicts but never fail the build:

{
  "guardrails": {
    "failOn": "never",
    "checks": [
      {
        "use": "git/conventional-commits@v1"
      }
    ]
  }
}