Guardrails / Collectors

Git repository and commit range

The repository, HEAD, the remotes, and every commit between the base ref and HEAD with its message, author, parents and the files the range changed.

Facts key	git
Version	v1
Script	git.py
Timeout	60 seconds

Inputs

Input	Description	Default	Environment
baseRef	Ref the collected range starts at. The commits collected are <baseRef>..HEAD.	origin/main	GUARDRAIL_INPUT_BASEREF

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": ["git"]
}

git = guardrail.facts("git")

Facts

The document git 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
repository	Whether the CLI is running inside a git repository. Nothing else is collected when it is not.
root	Absolute path of the working tree root, or null when git could not report it.
head.sha	Full SHA of the commit checked out.
head.short	First seven characters of that SHA.
head.branch	Branch name checked out, or null when HEAD is detached.
head.detached	Whether HEAD is detached rather than on a branch.
head.tags	Tags pointing at HEAD.
remotes	Remote name to fetch URL, as git remote -v reports them.
dirty	Whether the working tree carries uncommitted changes, or null when git could not report it.
baseRef	The baseRef input, as the guardrail configured it.
resolved	Whether baseRef resolves in this checkout. A shallow clone is the usual reason it does not, and every guardrail over a range skips rather than failing when it is false.
baseSha	SHA baseRef resolved to.
commits	Every commit in <baseRef>..HEAD, newest first. Empty for a range with no commits, which is a pass rather than a skip.
commits[].sha	Full SHA of the commit.
commits[].short	First seven characters of that SHA.
commits[].parents	SHAs of the commit's parents.
commits[].merge	Whether the commit has more than one parent.
commits[].subject	First line of the commit message.
commits[].message	The whole commit message, trailing newlines removed.
commits[].body	The message below the subject line.
commits[].author.name	Author name.
commits[].author.email	Author email.
commits[].author.date	Author date, ISO 8601.
commits[].committer.name	Committer name.
commits[].committer.email	Committer email.
commits[].committer.date	Commit date, ISO 8601.
changedFiles	Paths <baseRef>...HEAD changed, relative to the working tree root.

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 git collector:

{
  "repository": true,
  "root": "/home/dana/widget",
  "head": {
    "sha": "b6b5c4e277f7ddb042ec2ce1aa1349fc278d0cdc",
    "short": "b6b5c4e",
    "branch": "bound-the-queue",
    "detached": false,
    "tags": [
      "v1.1.0"
    ]
  },
  "remotes": {
    "origin": "https://github.com/acme/widget.git"
  },
  "dirty": false,
  "baseRef": "main",
  "commits": [
    {
      "sha": "b6b5c4e277f7ddb042ec2ce1aa1349fc278d0cdc",
      "short": "b6b5c4e",
      "parents": [
        "fa702e9abd742bd1cf39376f8959a4c113e99759"
      ],
      "merge": false,
      "subject": "feat(service): bound the widget queue",
      "message": "feat(service): bound the widget queue\n\nA queue nobody bounds is a queue that fills.",
      "body": "A queue nobody bounds is a queue that fills.",
      "author": {
        "name": "Dana Scott",
        "email": "dana@example.com",
        "date": "2026-03-02T14:40:00+00:00"
      },
      "committer": {
        "name": "Dana Scott",
        "email": "dana@example.com",
        "date": "2026-03-02T14:40:00+00:00"
      }
    }
  ],
  "changedFiles": [
    "service/src/main/kotlin/Queue.kt"
  ],
  "resolved": true,
  "baseSha": "fa702e9abd742bd1cf39376f8959a4c113e99759"
}

Collected for

Guardrail	Category	Inputs
git/author-identity-domain	git	baseRef
git/changed-files-budget	git	baseRef
git/conventional-commits	git	baseRef
git/no-merge-commits	git	baseRef
git/no-wip-commits	git	baseRef
git/work-item-reference	git	baseRef

All collectors