Policies

Define custom governance rules for your repositories

Overview

Policies let you define custom governance rules that are evaluated during PR analysis. Each policy contains rules that specify conditions and requirements. When a rule's conditions match, the requirements are checked and findings are generated.

Policies operate in advisory mode by default - they produce findings but don't block merges. This gives you visibility into policy violations before enforcing them.

Policy Structure

A policy is a JSON document with the following structure:

policy-schema.json

{
  "id": "my-policy-v1",
  "name": "My Policy",
  "version": "1.0.0",
  "description": "Optional description",
  "scope": {
    "paths": ["src/critical/**"],
    "branches": ["main", "release/*"]
  },
  "rules": [
    {
      "id": "RULE-01",
      "name": "Rule Name",
      "when": { /* conditions */ },
      "require": { /* requirements */ },
      "on_violation": "warn",
      "remediation": "How to fix"
    }
  ]
}

Scope

The optional scope object limits when a policy applies:

Field	Description
`paths`	Glob patterns for file paths the policy governs
`repos`	Repository patterns (owner/repo format)
`branches`	Target branch patterns

Conditions

Conditions determine when a rule applies. They can be simple comparisons or compound expressions using AND, OR, NOT.

Simple Condition

{
  "field": "risk.level",
  "operator": "in",
  "value": ["high", "critical"]
}

Compound Condition

{
  "AND": [
    { "field": "risk.level", "operator": "eq", "value": "high" },
    { "field": "contributor.trust_level", "operator": "eq", "value": "new" }
  ]
}

Operator	Description
`eq`	Equal to
`neq`	Not equal to
`in`	Value is in array
`contains`	Array contains value, or string contains substring
`exists`	Field has a non-empty value
`gt, gte, lt, lte`	Numeric comparisons

Available Fields

These fields can be referenced in conditions:

Field	Type	Description
`risk.level`	string	low, medium, high, critical
`risk.score`	number	0.0 to 1.0
`contributor.trust_level`	string	new, low, established, trusted, maintainer
`evidence.completeness_score`	number	0.0 to 1.0
`supply_chain.modifies_dependencies`	boolean	PR modifies dependencies
`supply_chain.modifies_ci_config`	boolean	PR modifies CI configuration
`governance.governed_paths_touched`	array	List of sensitive paths modified

Requirements

Requirements specify what must be satisfied when a rule's conditions match. Currently supported:

min_evidence_score

Require a minimum evidence completeness score.

"require": { "min_evidence_score": 0.7 }

max_risk_level

Require risk level at or below a threshold.

"require": { "max_risk_level": "medium" }

contributor_trust

Require minimum contributor trust level.

"require": {
  "contributor_trust": { "min_level": "established" }
}

Example Policy

infrastructure-governance.json

{
  "id": "infrastructure-governance-v1",
  "name": "Infrastructure Change Governance",
  "version": "1.0.0",
  "scope": {
    "paths": ["terraform/**", "k8s/**", ".github/workflows/**"]
  },
  "rules": [
    {
      "id": "INFRA-01",
      "name": "CI config changes need high evidence",
      "description": "CI changes are high-risk and need passing tests",
      "when": {
        "field": "supply_chain.modifies_ci_config",
        "operator": "eq",
        "value": true
      },
      "require": {
        "min_evidence_score": 0.8
      },
      "on_violation": "fail",
      "remediation": "Ensure CI checks pass before merging CI configuration changes"
    },
    {
      "id": "INFRA-02",
      "name": "High-risk PRs from new contributors",
      "when": {
        "AND": [
          { "field": "risk.level", "operator": "in", "value": ["high", "critical"] },
          { "field": "contributor.trust_level", "operator": "eq", "value": "new" }
        ]
      },
      "require": {
        "contributor_trust": { "min_level": "established" }
      },
      "on_violation": "warn",
      "remediation": "High-risk infrastructure changes from new contributors require extra review"
    }
  ]
}

API Access

Policies are managed via API. See the API Reference for details.

Create a Policy

curl -X POST https://axiomo.app/api/policies \
  -H "Cookie: axiomo_session=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_id": "my-policy-v1",
    "name": "My Policy",
    "version": "1.0.0",
    "policy": { "rules": [...] }
  }'

Assign Policy to Repository

curl -X POST https://axiomo.app/api/repos/github/owner/repo/config \
  -H "Cookie: axiomo_session=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "sensitive_paths": ["src/critical/**"],
    "policy_id": "my-policy-v1"
  }'

Violation Actions

When a requirement is not met, the on_violation field determines the action:

Action	Effect
`warn`	Creates a warning finding (advisory)
`fail`	Creates a failure finding
`block_merge`	Creates a failure finding (future: will block via webhook)