Governance Timeline

What Is the Governance Timeline?

The governance timeline aggregates all governance-related events for a run into a single chronological view. It pulls from five data sources:

1. policy_results — Policy evaluation events
2. run_approval_requirements — Approval requirement activations
3. external_checks — External check provider callbacks
4. run_approvals — User approval/rejection decisions
5. governance_events — System governance events

Viewing the Timeline

GET /runs/{id}/governance-timeline

Response:

[
  {
    "id": "uuid",
    "occurred_at": "2026-01-15T10:00:00Z",
    "event_type": "policy_evaluated",
    "actor_type": "system",
    "actor_id": null,
    "details": {
      "policy_set_name": "production-safety",
      "passed": false,
      "violations": ["..."]
    }
  },
  {
    "id": "uuid",
    "occurred_at": "2026-01-15T10:00:01Z",
    "event_type": "requirement_active",
    "actor_type": "system",
    "actor_id": null,
    "details": {
      "stage": 1,
      "reason": "Production destroy requires approval"
    }
  },
  {
    "id": "uuid",
    "occurred_at": "2026-01-15T10:05:00Z",
    "event_type": "approval_received",
    "actor_type": "user",
    "actor_id": "user-uuid",
    "details": {
      "decision": "approved",
      "comment": "Reviewed and approved"
    }
  }
]

Event Types

Actor Types

Use Cases

• Audit — Show the complete governance history for compliance
• Debugging — Understand why a run was rejected or is pending
• Reporting — Track governance effectiveness over time

Related

• Governance Preview — Dry-run evaluation
• Approvals — Approval workflow details