Policies

Policies define your organization’s security standards. They control scan behavior, quality gates, notification rules, and enforcement across all repositories.

Policy Levels

Policies are configured at two levels:

Organization policies — apply to every repository in the org
Repository overrides — override specific fields for a single repo

When a repository has an override, that value takes precedence. All other fields fall back to the organization default.

Configuration

Navigate to Settings → Policies to manage policies.

Scan Settings

Field	Type	Default	Description
`default_scan_type`	`smart` / `deep`	`smart`	Default scan type for manual and scheduled scans
`auto_scan_on_push`	boolean	`false`	Trigger a scan automatically when code is pushed
`scan_on_pr`	boolean	`true`	Trigger PR review on pull request events
`scan_branches`	string[]	`["main"]`	Branches that trigger auto-scans
`exclude_paths`	string[]	`[]`	Glob patterns to exclude from scanning (e.g., `test/`, `vendor/`)
`scanners_enabled`	string[]	all	Which scanners to run: `sast`, `sca`, `secrets`, `iac`, `container`

Quality Gate

Field	Type	Default	Description
`gate_enabled`	boolean	`true`	Whether the quality gate is enforced
`max_critical`	integer	`0`	Maximum critical findings allowed to pass
`max_high`	integer	`5`	Maximum high findings allowed to pass
`max_risk_score`	integer	`50`	Maximum PR risk score allowed to pass
`require_no_secrets`	boolean	`true`	Block if any secrets are detected
`require_no_new_critical_cves`	boolean	`true`	Block if new critical CVEs are introduced

Notifications

Field	Type	Default	Description
`notify_on_critical`	boolean	`true`	Send email/Slack on critical findings
`notify_on_gate_fail`	boolean	`true`	Notify when a quality gate fails
`notify_on_scan_complete`	boolean	`false`	Notify on every scan completion
`notification_channels`	string[]	`["email"]`	Channels: `email`, `slack`
`notification_recipients`	string[]	org admins	Email addresses or Slack channels

Compliance & Retention

Field	Type	Default	Description
`compliance_frameworks`	string[]	`[]`	Enabled frameworks: `soc2`, `iso27001`
`retention_days`	integer	plan default	Days to retain scan results
`require_sbom`	boolean	`false`	Generate SBOM on every deep scan
`auto_remediation`	boolean	`false`	Automatically create fix PRs for critical issues

Inheritance Model


Organization Policy (base)
    └── Repository Override (specific fields only)
         └── Effective Policy (merged result)

When evaluating a policy for a repository:

Start with the organization policy as the base
Apply any repository-level overrides on top
The merged result is the effective policy

Only fields explicitly set at the repository level override the org default. Unset fields inherit from the org.

Viewing Effective Policy

On any repository’s settings page, the Effective Policy section shows the merged result with indicators showing which values are inherited vs. overridden.

API Access

Retrieve or update policies via the API:


# Get org policy
curl -H "X-API-Key: $CODESTAX_API_KEY" \
  https://codestax.co/api/v1/policies/org
 
# Update org policy
curl -X PATCH -H "X-API-Key: $CODESTAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_critical": 0, "auto_scan_on_push": true}' \
  https://codestax.co/api/v1/policies/org
 
# Set repo override
curl -X PATCH -H "X-API-Key: $CODESTAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"default_scan_type": "deep", "exclude_paths": ["docs/**"]}' \
  https://codestax.co/api/v1/policies/repo/123

Permissions

Action	Required Role
View org policy	MEMBER or above
Edit org policy	ORG_ADMIN or above
View repo override	MEMBER or above
Edit repo override	ORG_ADMIN or above