Gating & policy

A scan that can’t block is a suggestion. This page covers the structural gate — when shipmoor scan exits non-zero — and the policy knobs that tune it: the --fail-on threshold, per-rule severity overrides, and scoping the gate to what the change actually introduced.

The threshold: --fail-on

shipmoor scan --changed --fail-on critical
shipmoor scan --changed --fail-on high      # the default
shipmoor scan --changed --fail-on medium
shipmoor scan --changed --fail-on none      # never block; report only

A finding at or above the threshold makes the scan exit 1 (the gate firing — not an error; the report is still written). Everything below the threshold is reported as informational. See Output formats & exit codes for the full contract.

Set the default once in .shipmoor.yaml instead of repeating the flag:

thresholds:
  fail_on: high

Tuning severities per project

The shipped severities follow a cross-language policy — a phantom import is high in every language, debug output is low everywhere (see Findings & rules for the full table). When your project disagrees, override per rule in .shipmoor.yaml:

rules:
  disabled:
    - python.placeholder.empty_body        # interface-heavy codebase; stubs are intentional
  severity_overrides:
    python.quality.mutable_default: high   # bitten before; make it block

An override changes what the gate does in your repo without forking the rule. Disabling a rule removes its findings entirely.

Gate the change, not the history

The most important policy decision in a brownfield repo: scope the gate to what the change introduces. With diff-aware scans, every finding carries a change_status, and by default only findings the change introduced count against the gate:

diff:
  only_introduced: true   # the default

shipmoor scan --diff origin/main...HEAD --fail-on high

The three-dot range pins the gate to “what this branch adds relative to the merge base” — a PR is never blocked on legacy findings it didn’t create.

Community vs Team

Everything above is Community — local, per-repo, in your .shipmoor.yaml.

Two .shipmoor.yaml extension points are reserved for the Team tier, which is coming soon:

policy:
  mode: local        # team-managed rulesets land here
  rulesets: []

baselines:
  shared: []         # shared finding baselines across a team
  ignore_fingerprints: []

In the current release these keys are accepted but inert: Team features report their availability through entitlements and do not change scan behavior. Today, the practical “baseline” mechanisms are diff scoping (only_introduced), rule disabling, and severity overrides — all local and reviewable in your repo.

The gate on this page is the structural gate — findings against the code itself. The Claim Check verdict has its own, separately configured gate with a floor that can’t be loosened. See Turning on the gate.

Next

• Output formats & exit codes — what exit 1 means downstream.
• GitHub Actions — putting the gate in front of merges.
• Configuration — the full .shipmoor.yaml surface.