Skip to Content
GuidesPolicy as Code

Policy as Code

Commit .codestax/quality_gate.yaml to your repo’s default branch. CodeStax reads it on every scan and merges it on top of the org-level policy, giving that repo its own thresholds.

Merge Order

defaults (hardcoded) → org policy → repo override
  • Defaults — opinionated starting point (0 critical, 2 high, 3% dup, etc.)
  • Org policy — set via Settings → Policies → Quality Gates
  • Repo override — this YAML file; most specific wins

Unknown keys are silently dropped. Invalid values (e.g. rating_min: Z) are rejected and fall back to org policy for that key.

File Locations Scanned

CodeStax auto-loads from any of these paths in the repo root:

  1. .codestax/quality_gate.yaml
  2. .codestax/quality_gate.yml
  3. .codestax/quality-gate.yaml

Files larger than 64 KB are ignored. Only top-level flat key-value pairs are supported (intentional — no nested structures).

Full Schema

# .codestax/quality_gate.yaml
 
# Max new CRITICAL findings allowed in a PR vs default-branch baseline
new_critical_max: 0
 
# Max new HIGH findings allowed
new_high_max: 2
 
# Max overall duplication percent (jscpd summary)
duplication_pct_max: 3.0
 
# Max new complexity findings in the PR
complexity_new_max: 15
 
# Minimum composite quality rating (A | B | C | D | E)
rating_min: C
 
# Minimum line-coverage percent from ingested coverage reports
new_coverage_min: 80

Values accept: integers, floats, booleans (true/false/yes/no), quoted strings, unquoted strings. Comments (#...) allowed. Nested YAML ignored.

Examples

Stricter repo (security-critical service)

new_critical_max: 0
new_high_max: 0
new_coverage_min: 90
rating_min: B
duplication_pct_max: 2
complexity_new_max: 10

Looser repo (legacy monolith mid-refactor)

new_critical_max: 0     # still no new criticals
new_high_max: 10        # more lenient than org default 2
duplication_pct_max: 10 # known duplication, scheduled for extract
rating_min: D           # don't fail on the composite for now

How It’s Applied

On every scan the scanner reads the file from the cloned repo at clone_path/.codestax/quality_gate.yaml. If found, keys are merged with the org policy. The resulting effective policy is what the gate evaluates + is returned from GET /quality/gates/status/:scan_id.

If the file is malformed, partial, or uses unknown keys, those parts are dropped. A broken YAML file will not crash the scan — worst case, no override applies.

Auditing What Policy Actually Ran

Every scan stores tool_versions_json on the ScanResult, and the gate evaluation response always includes the policy that was actually applied. You can verify the override took effect:

curl -H "Authorization: Bearer $JWT" \
  https://codestax.co/api/quality/gates/status/12345 | jq '.policy'

The returned policy reflects the merged (defaults + org + repo) values.

Best Practices

  • Commit the file to the default branch. Scanner only reads from the checked-out branch on PR scans — if your override isn’t on main yet, gates will miss it.
  • Don’t override enabled, block_merge_on_fail, or applies_to_new_code_only in this file — those are org-level settings. Only thresholds are repo-scopable.
  • Pin your choices with comments describing why each value diverges from org default. Future you will thank you.
  • Review on PR — quality-gate policy changes are security-relevant. Treat the YAML like code.
New-Code DeltaManage Waivers