Configuring guardrails

The guardrails section of buildnote.json lists the policies that buildnote guardrails runs. Each entry names a guardrail from the shared library and configures it for your project.

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

Option	Type	Default	Description
failOn	string	error	Severity that fails the build when a guardrail fails. One of error, warning, never.
comment	boolean	true	Post the verdicts as a pull request comment. The other reporters are configured in the report section, the same as for buildnote report.
sources	array	[]	Libraries a reference resolves against after the one bundled with the CLI.
checks	array	[]	The guardrails to run.

A guardrail runs because it appears in checks. Delete the entry to stop running it, or narrow a single run with --only <id> without editing the file.

sources

The library bundled with the CLI is always the first place a reference resolves, and it is the only one you need for the guardrails Buildnote ships. sources adds your own libraries after it, in the order you list them: a reference that the bundled library does not declare is looked for in each of them in turn, and the first one that declares it wins.

{
  "guardrails": {
    "sources": [
      "github://acme/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 is what pins it
a path such as ./guardrails	that directory on the machine running the command, which is one version, so the version is checked against the definition's own version field

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 the bundled library and sources. Its collectors are the exception: one that repository does not ship falls back to the library bundled with the CLI, so "collect": ["git"] works in a guardrail Buildnote never shipped.

A guardrail a source declares nothing for is a configuration error rather than a skip, so a mistyped id never passes quietly. A source that cannot be reached at all is missing evidence instead, and is recorded as skipped.

What a source runs on your machine

A guardrail resolved from a source of your own downloads a check script and its collectors' scripts and runs them on the machine running the command. The CLI prints 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 its facts from, so pin the git ref rather than a branch in a github:// source you do not own.

checks

Option	Type	Default	Description
use	string	required	Guardrail reference, [github://<owner>/<repository>/]<category>/<name>@<version>, naming a guardrail of the library the CLI ships, of a sources entry, or of the repository it names 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. A mismatch skips the guardrail with a warning instead of running it.

Each shipped guardrail's page carries a ready to paste example with that guardrail's own inputs. See the guardrails reference for the list.

Reporting without gating

Guardrails report their verdicts and never fail the build:

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