Governance Overview

Three layers of governance ensure that only safe, approved changes reach your infrastructure.

The Three-Layer Model

When a plan run completes, Forgecroft evaluates three layers of governance in sequence:

1. OPA Policy Sets    → deny or require approval via Rego policies
2. Approval Rules     → predicate-based rules (e.g., "require approval if >5 resources destroyed")
3. External Checks    → async approval from external systems via webhook callbacks

All three layers evaluate. The results determine whether the run:

Completes (no violations, no approval needed)
Enters pending_approval (approval required)
Transitions to rejected (mandatory violation)

Layer 1: OPA Policy Sets

Policy sets contain Rego policies that evaluate the plan output. Each policy set has:

Enforcement: mandatory (violations reject the run) or advisory (violations are warnings)
Scope: org (global), project, or workspace
Profile: terraform, kubernetes, security, or custom

Policies can deny (block the run) or require_approval (trigger an approval requirement).

Layer 2: Approval Rules

Approval rules are predicate-based conditions that trigger approval requirements:

always — always require approval
destroyed_gt — require approval if more than N resources are destroyed
added_gt — require approval if more than N resources are added
changed_gt — require approval if more than N resources are changed
trigger_is — require approval for specific trigger types (e.g., pr)

Rules support multi-stage approvals with escalation on timeout.

Layer 3: External Check Providers

External check providers let you integrate custom approval systems:

Forgecroft POSTs to the provider’s callback_url with run details
The provider evaluates the run and POSTs a decision back
Forgecroft processes the decision (pass → satisfy, fail → reject)

Enforcement Modes

Mode	Behavior
`mandatory`	Violations cause the run to be rejected
`advisory`	Violations are recorded as warnings but don’t block the run

Multi-Stage Approval Flow

Approval requirements are organized into stages:

Stage 1: Platform team (min: 1)
  ↓ (all stage 1 requirements satisfied)
Stage 2: Security team (min: 2)
  ↓ (all stage 2 requirements satisfied)
Run completes → auto-apply if enabled

Each stage must be fully satisfied before the next activates.

Escalation

Approval requirements can have timeout-based escalation:

Action	Behavior
`auto_approve`	Automatically approve if timeout is reached
`escalate_to`	Escalate to a different team
`reject`	Reject the requirement (and the run)

When to Use Which Layer

Scenario	Recommended Layer
”No one should destroy production databases”	OPA Policy Set (mandatory deny)
“Changes to prod need team lead approval”	Approval Rule (predicate on environment)
“Security team must review all IAM changes”	OPA Policy Set (require_approval for IAM)
“Our custom compliance system must approve”	External Check Provider
”More than 10 changes need extra review”	Approval Rule (destroyed_gt/changed_gt)
“PR-triggered changes always need approval”	Approval Rule (trigger_is: pr)

Why Not Just Use Sentinel/OPA Directly?

Forgecroft owns the full run lifecycle, which enables capabilities that standalone policy engines can’t provide:

Contextual evaluation — policies see workspace attributes, user identity, trigger source, and plan changes together
Tied to approval workflows — require_approval rules integrate with Forgecroft’s multi-stage approval system
Post-evaluation actions — governance results directly control run status transitions and auto-apply behavior
Audit trail — every policy evaluation is recorded with timestamps and results

PR-Triggered Plans

For PR-triggered plans, policy evaluation is dry-run only. Policies are evaluated and results are shown, but no state mutations occur (no approvals created, no run status changes). This lets you see what governance would do without affecting the PR workflow.

Policy Sets — Creating and managing policy sets
Writing Rego — Writing Rego policies
Approval Rules — Predicate-based approval rules
External Checks — Integrating external approval systems
Governance Preview — Dry-run governance evaluation