Configure organization policies

Open Settings → Policies to manage the canonical organization policy. The same policy is consumed by manual scans, provider-triggered pull-request reviews, quality-gate decisions, and provider status delivery.

Use the dedicated Settings → Quality Gates page for new-code thresholds, quality-gate waivers, and the quality policy-as-code workflow.

Policy inheritance

CodeStax starts with the organization policy, then applies fields explicitly set in a repository override. Deleting an override restores full organization inheritance.


Organization policy
└── Repository override
    └── Effective policy

Repository overrides can narrow or relax supported controls, but cannot change the organization-only default scan type, scan timeout, or notification preferences.

Available controls

Quality gate

Field	Default	Purpose
`risk_threshold`	`75`	Maximum review risk score before the gate fails
`block_merge_on_fail`	`false`	Publish a provider failure signal when the gate fails
`gate_reliability`	`A,B`	Accepted reliability grades
`gate_security`	`A`	Accepted security grades
`gate_maintainability`	`A,B,C`	Accepted maintainability grades
`gate_max_complexity`	`60`	Maximum allowed complexity signal
`max_critical_issues`	`0`	Maximum critical findings
`max_high_issues`	`-1`	Maximum high findings; `-1` disables the limit
`fail_on_dead_code`	`false`	Fail when dead-code findings are present
`fail_on_duplicates_pct`	`-1`	Maximum duplication percentage; `-1` disables the limit

Scans and reviews

Field	Default	Purpose
`auto_scan_on_push`	`true`	Allow supported push webhooks to trigger scans
`auto_review_enabled`	`true`	Master switch for provider-triggered reviews
`auto_review_on_pr_open`	`true`	Review newly opened pull or merge requests
`auto_review_on_pr_update`	`false`	Review new commits on an existing request
`auto_review_on_pr_reopen`	`true`	Review reopened requests
`default_scan_type`	`smart`	Organization default for manual and scheduled scans
`scan_timeout_minutes`	`30`	Maximum scan time, from 1 to 1,440 minutes
`review_target_branches`	`main,develop`	Comma-separated target-branch patterns
`excluded_paths`	empty	Comma-separated repository-relative path patterns

Code quality analyzers

The policy can enable or disable the Python complexity, Python dead-code, and duplication analyzers; set complexity and confidence thresholds; set duplication minimum lines and tokens; and add repository-relative exclusion patterns. The Quality Profiles and Rule Catalog pages provide the customer-facing configuration workflow.

Notifications

Organization policy includes notify_critical, notify_gate_fail, and notify_weekly_digest. User delivery preferences live under Settings → Notifications.

API


# Read the organization policy
$ curl -H "X-API-Key: $CODESTAX_API_KEY" \
  https://codestax.co/api/policies/org
 
# Update selected organization fields
$ curl -X PUT \
  -H "X-API-Key: $CODESTAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"risk_threshold":70,"auto_review_on_pr_update":true}' \
  https://codestax.co/api/policies/org
 
# Read a repository override and effective policy
$ curl -H "X-API-Key: $CODESTAX_API_KEY" \
  https://codestax.co/api/policies/repo/<repo_id>
 
# Update a repository override
$ curl -X PUT \
  -H "X-API-Key: $CODESTAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"risk_threshold":60}' \
  https://codestax.co/api/policies/repo/<repo_id>

Use DELETE /api/policies/repo/{repo_id} to remove the override. GET /api/policies/gate-conditions returns the current supported gate-condition catalog.

Policy updates reject unknown fields and explicit null values. Read the current policy before updating it, and send only fields you intend to change.

Permissions and enforcement

Viewers can read policy through tenant-scoped product views. Organization admins and owners can change organization and repository policy. API keys must carry the scopes required by the endpoint.

block_merge_on_fail publishes a failure result; the SCM provider blocks merging only when you also require the CodeStax signal in branch protection, merge checks, or branch restrictions. See Set up quality gates.