Push Guard: rules and reasoning

The reasoning behind every Push Guard rule. Configuration and operation (rule table, configuration, commands including replay) are in docs/push-guard.md; shared settings are in docs/configuration.md; credential rights are in docs/credentials.md. What the implementation settled or changed is in SPEC.md. Design of both guard posts and the risk register (risk IDs R1–R22): SPEC.md.

Focus for now: only the Push Guard, only deterministic rules. No AI at all: the Push Guard has to decide fast, pass or fail, while the push is running, and the same input must always give the same answer. No LLM, no platform API, nothing but Git. Every rule below can be decided from the pushed objects and the remote's current refs alone, with the same result every time. Testable requirements for QA are numbered as REQ-PG-* in docs/push-guard-spec.md. Open questions are in docs/push-guard-spec.md.

Assumption: one Push Guard per agent#

For now, each monitored agent gets its own Push Guard. Its configuration names the agent (agent.name), and that name goes into every log entry, warning and statistic so they can be traced back later. Everything "per agent" below therefore means "per Push Guard".

Rights#

The warden has no more rights on the platform than the agent would have. Whatever the remote refuses the agent, it refuses the warden too, so a human approval can't push past the remote's own protection; that goes through the human's own push or a merged PR. Protected branches are the remote's job; the Push Guard sticks to what Git itself offers and has no rule for them. If the remote rejects a forwarded push, the Push Guard rejects the agent's push and passes on the remote's message.

Verdict#

• Any red finding → reject without details. The response only says that the push was rejected and is waiting for a human; it doesn't name the rule. The owner is warned.
• Any yellow finding → reject with an error message the agent can use to make its change compatible: which rule fired, on which ref, path or line, and why. **yellow never goes to a human:** the agent fixes it itself. If it can't, it leaves the part out (drops the file or dependency, doesn't set the tag) and notes in its PR that this is still open. Only if it keeps getting it wrong does RATE-YELLOW-STREAK escalate to a human.
• Only green → forward exactly the checked SHAs to the remote, then accept the agent's push. Never --force: a rewrite, tag move or deletion goes out with --force-with-lease, and only if the rule's allow explicitly exempts that ref or a human approved that SHA. For an allow-list exemption the lease is against the remote state just read; for a human approval the lease base is the old OID recorded with the approval (remote tip when the overruled push was checked). If at repush the remote tip differs from that recorded old OID, the push is rejected with the fixed message Remote moved since approval (a named exception like rate limited, try later, not a silent red); the approval is invalidated and a new check plus approval are required.
• Fail-closed: a rule that errors, times out or can't read its input (scanner missing, remote unreachable, object missing) counts as red, but with the message "internal error, try again later". The next push is checked from scratch.
• Approval is per SHA: a human approves ref + new-oid. The agent's next push of exactly that SHA to that ref is forwarded without re-checking. Any other SHA (rebase, amend, extra commit) is checked from scratch.

Policy in short: red is a rule violation and goes to a human, who changes the classification only in exceptional cases. yellow is the agent's job.

Why red stays silent: a yellow message helps an honest agent fix its change, but it also teaches a manipulated agent what the rules look for. For red cases that lesson would be too valuable, so the agent only learns that the push didn't go through.

What a rule sees#

For each ref in the push (old-oid new-oid ref-name from pre-receive):

Path rules and content rules run over the cumulative diff, so splitting a change across many small commits doesn't help. Metadata rules run over each new commit.

Rules#

IDs are stable so findings, approvals and config can refer to them. Every list, pattern and limit is configuration with the default shown. Every rule is on by default and can be disabled (REQ-PG-038), and most can be narrowed with allow and deny lists (REQ-PG-040, REQ-PG-041; see Configuration). Testable requirements for each rule are in docs/push-guard-spec.md and in the Requirements column of the tables below.

Refs#

Paths#

Paths are classified generally, whatever the file is: a lockfile, a workflow or an agent config are all just entries in a list. Two rules, each with a default blocklist in the configuration:

The subject is every path that is added, modified, deleted or renamed. A rename is checked under both names (REQ-PG-014), so git mv can't move a file out of a list or into one unnoticed. A path on both lists is red (REQ-PG-015). allow and deny work as for every rule (REQ-PG-040, REQ-PG-041): allow exempts a path from the blocklist, deny keeps it in even if allow matches. Like every list, both are regex (see Configuration); paths have no leading slash, and (.*/)? means "in any directory".

Default blocklists:

PATH-RED:
  match:
    # CI configuration
    - '\.github/workflows/.*'
    - '\.github/actions/.*'
    - '\.gitlab-ci\.yml'
    - '\.(forgejo|gitea)/workflows/.*'
    - '\.circleci/.*'
    - 'Jenkinsfile'
    # Ownership and licence
    - '(.*/)?CODEOWNERS'
    - '(LICENSE|COPYING)(\..*)?'
    # Secret scanner configuration (see Scanner configuration)
    - '\.gitleaks\.toml'
    - '\.gitleaksignore'
    - '\.trufflehog.*'
    # Agent configuration
    # (?i): case-insensitive, because on macOS and Windows a tool also opens agents.md as AGENTS.md
    - '(?i)(.*/)?(AGENTS|CLAUDE|GEMINI)\.md'
    - '(?i)\.cursor/rules/.*'
    - '(?i)\.github/copilot-instructions\.md'
PATH-YELLOW:
  match:
    # Git metadata
    - '(.*/)?\.gitattributes'
    - '\.gitmodules'
    - '\.lfsconfig'
    # Hooks that run on other people's machines
    - '\.husky/.*'
    - '\.githooks/.*'
    - 'lefthook\.yml'
    - '\.pre-commit-config\.yaml'
    # Dependencies and registries
    - '(.*/)?(package\.json|package-lock\.json|pnpm-lock\.yaml|yarn\.lock|go\.mod|go\.sum|Cargo\.toml|Cargo\.lock|pyproject\.toml|uv\.lock)'
    - '(.*/)?requirements[^/]*\.txt'
    - '(.*/)?(\.npmrc|\.yarnrc[^/]*|pip\.conf)'
    # Build
    - '(.*/)?Dockerfile[^/]*'
    - '(.*/)?docker-compose[^/]*\.ya?ml'
    - '(.*/)?Makefile'
    - '(scripts/)?[^/]*\.sh'
    - '\.github/dependabot\.yml'

File modes#

These depend on the file mode in the Git tree, not on the path, so they are separate rules. The subject is the path.

Content#

Over added lines, after decoding as UTF-8 (undecodable text counts as binary — REQ-PG-024); CONTENT-SECRET scans the new commits, CONTENT-BINARY looks at whole files.

Scanner configuration#

gitleaks can be switched off from inside the repo: it skips lines with a gitleaks:allow comment, reads exceptions from a .gitleaksignore, and loads a .gitleaks.toml in the repo root as its config. An agent could push a secret together with its own exception. So the Push Guard runs the scanner only with configuration from the wall and never from the repo:

• --config <wall path> (takes precedence over a .gitleaks.toml in the repo),
• --gitleaks-ignore-path <wall path> (instead of the repo's .gitleaksignore),
• --ignore-gitleaks-allow (inline gitleaks:allow comments have no effect).

On top of that, adding such an exception is itself red (scanner files in PATH-RED, CONTENT-SCANNER-ALLOW). Real false positives are allowed by a human in the wall config, not in the repo.

Scanner configuration per repo: allowlisted paths and exceptions differ between repos, so the scanner config is per repo too, on the same principle as defaults.yaml. A shared base config on the wall, plus one file per repo that only adds paths or exceptions and pulls in the base with gitleaks' [extend] path = "…". The repo's .gitleaksignore equivalent sits next to it. All of these files live on the wall, never in the repo.

Commit metadata#

Why dates matter: a backdated commit looks old and long since reviewed in git log and on the web, and slots in between older commits; a date in the future keeps it at the top of date-sorted lists.

No author or committer rules: both are plain text the agent sets freely with git config, so checking them proves nothing and would only get in the way of rebases and cherry-picks. Which agent pushed is known from its push credential and goes into push.jsonl; that is the one identity the agent can't fake.

Size and volume#

All values are configurable per rule (defaults shown).

Configuration#

How to change these rules, try the change with replay, and a set of worked examples: Configuring the rules.

Many red and yellow rules have legitimate uses, e.g. an agent cleaning up its own branches or moving snapshot tags. So each rule has, besides its limits and patterns:

• enabled (default true): a disabled rule never fires (REQ-PG-038).
• color (red or yellow, default as in the tables): the owner decides per rule and repo what is a violation for a human and what the agent fixes itself (REQ-PG-039).
• allow: regular expressions over the rule's subject; a match means the rule doesn't fire for it (REQ-PG-040).
• deny: regular expressions over the subject; a match means the rule fires even if allow matches. deny wins over allow (REQ-PG-041).

Patterns always match the whole subject (REQ-PG-042): the Push Guard wraps each one as ^(?:…)$ itself, because Go's MatchString also accepts partial matches. Otherwise agent.* would also allow deleting refs/heads/main-agent-x.

The subject depends on the rule group (REQ-PG-043): the full ref name for REF-*, the path for PATH-*, MODE-*, CONTENT-* and SIZE-* per file, the ref name for SIZE-* totals, the branch for META-*. REF-COUNT and RATE-* have no subject. Subject-scanning rules (REF-NAMESPACE, PATH-*) look at every pushed ref or changed path and fire when deny matches, or when their match/trigger condition holds and allow doesn't match. Event rules (REF-DELETE, REF-NON-FF, REF-TAG-NEW, REF-TAG-MOVE, MODE-*, META-*, SIZE-*, CONTENT-*) are evaluated only for subjects their trigger hits; for those, deny wins over allow but does not fire the rule without the trigger. Once evaluated, a rule fires if deny matches, or if it is triggered and allow doesn't match (REQ-PG-041).

rules:
  REF-DELETE:
    allow: ['refs/heads/agent.*']          # agents may delete their own agent* branches
  REF-TAG-MOVE:
    allow: ['refs/tags/.*-SNAPSHOT']        # snapshot tags may move
  REF-NAMESPACE:
    deny: ['refs/heads/main', 'refs/heads/release/.*']   # protect branches: every push to them is red
  PATH-RED:
    match: ['scripts/release\.sh']         # this one script is red here, on top of the defaults
  PATH-YELLOW:
    allow: ['package-lock\.json']          # lockfile updates are fine in this repo
  CONTENT-BINARY:
    allow: ['docs/.*\.(png|svg)']          # images for the docs
  MODE-SYMLINK:
    color: red                             # no symlinks at all in this repo
  META-UNSIGNED:
    enabled: false                         # nobody signs here

Protecting branches works through deny on REF-NAMESPACE, because that rule subject-scans every ref name in every push. A deny on an event rule such as REF-DELETE or REF-NON-FF would only stop deleting and force-pushing: a normal fast-forward push wouldn't trigger those rules, so their deny lists would not apply.

Configuration lives on the wall, never in the repo itself. Changing it is a human's job. Each repo can have its own configuration: shared defaults, plus a file per repo that overrides individual settings (rules, enabled, color, lists, limits). A setting the repo file doesn't mention keeps the default. Lists are added to, never replaced: match, allow and deny in a repo file extend the defaults, so a default protection (e.g. deny for refs/heads/main) can't vanish unnoticed. Removing a default entry needs an explicit match_remove / deny_remove / allow_remove with the exact pattern (a pattern that isn't there is an error). There are three layers: the built-in defaults of the program, then defaults.yaml, then the repo file.

Limit bounds#

Every configurable limit has a range (REQ-PG-046). A value outside it is refused when the configuration loads, so check-config reports it; nothing is clamped silently. Zero is allowed only where the table says so.

Repos#

The Push Guard knows nothing about owners or platforms. Each repo gets a short name chosen by the owner ([a-z0-9._-]+, unique within one Push Guard) and one Git URL where its real remote lives. The name is all the agent sees: it pushes to <push guard>/<name>.git, and the Push Guard forwards to the URL. GitHub, GitLab, Gitea/Forgejo and a bare repo over SSH look the same here; owner/repo only appears inside the URL, if at all.

# warden/repos/git-warden/warden.yaml
remote: git@github.com:pihme/git-warden.git # any Git URL: ssh://, https://, git@host:path, /srv/git/x.git
credential: /etc/warden/keys/git-warden      # write credential for exactly this remote (SSH key or token file)
known_hosts: /etc/warden/known_hosts         # optional, SSH only; default: the guard user's own
default_branch: main                         # optional; otherwise read via ls-remote --symref
rules:
  REF-NAMESPACE:
    deny: ['refs/heads/main']                # every push that includes main is red

remote and credential are required per repo (credential may only be left out for a local path or file:// remote) and never come from defaults.yaml, so one repo can't accidentally push to another repo's remote. A push to a name that has no folder is rejected (red, "unknown repo"). The credential stays a file reference, never a value in the YAML, so config can be shown and diffed without leaking it. known_hosts (SSH only, optional) points to the host keys for this remote; an unknown or changed host key is refused, and ssh runs with -F none, so no ssh_config on the wall host can change where or how the guard connects.

Layout on the wall#

One file with defaults for all repos, and one folder per repo with only what differs there:

warden/
  defaults.yaml          # applies to every repo: agent.name, all rules with their defaults
  gitleaks.toml          # secret scanner rules for every repo
  repos/
    git-warden/          # folder name = repo name = the path the agent pushes to
      warden.yaml        # remote + credential, plus only what differs from defaults.yaml
      gitleaks.toml      # optional: extra scanner rules; starts with [extend] path = "/etc/warden/gitleaks.toml"
      gitleaksignore     # optional: known false positives of the scanner in this repo
    fregoli/
      warden.yaml        # a repo without its own scanner files uses the shared gitleaks.toml as is

For a push to git-warden.git, the Push Guard reads defaults.yaml, then applies repos/git-warden/warden.yaml on top; the scanner runs with that folder's gitleaks.toml (or the shared one) and gitleaksignore. Only warden.yaml with remote and credential is required in a repo folder.

Statistics#

The Push Guard keeps statistics, derived from push.jsonl, so a human can improve the configuration. Per rule and repo:

A human never confirms a rejection, they only overrule it by approving the SHA; the approval is logged with the rule IDs. A red hit nobody overrules simply stays rejected. A rule that is mostly overruled is a candidate for an allow entry, a higher limit, color: yellow or enabled: false; a yellow rule the agent rarely fixes is a candidate for allow or color: red. A red rule that is rarely overruled is doing its job. The statistics only suggest; changing the configuration stays a human's job.

Not mechanical, so not here#

Checking new dependencies against the registry (exists? how old? downloads?, R17) needs network access and a registry; it comes later as its own rule source. Anything that needs judgement (does the commit message match the code? is this a backdoor?) is not covered by Git Warden; see Coverage by Git Warden.

Human actions#

A human acts only on red, and only on the wall host where the configuration lives; being able to run the command there is the authentication. Both actions go into push.jsonl with the rule IDs, so the statistics can count them:

• push-guard approve <repo> <ref> <sha>: the agent's next push of exactly that SHA to that ref is forwarded without re-checking (and resets the streak). A short unique prefix of a rejected push is enough; an ambiguous prefix is refused.
• push-guard reset-streak <repo>: ends a RATE-YELLOW-STREAK without approving anything.

The commits of a rejected red push are kept as a bundle pending/<repo>/<id>.bundle for the human to inspect. Refs can't be written inside the push's quarantine, and its objects vanish once the push is rejected, so a ref namespace like refs/warden/pending doesn't work here.

Warnings go out through notify.command in defaults.yaml: a command that gets the warning as JSON on stdin (facts first, the agent's texts only as a marked quote). Which channel sits behind it (email, ntfy, Signal, …) is the owner's choice and not part of the Push Guard.