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.

Local policy vs Team

Everything above is available locally with Shipmoor Scan.

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.