Governance & audit

Every write the control plane performs — artifact changes, releases, deploys, rollbacks, task completions, tenant provisioning — is recorded as an audit entry: actor, action, and a detail string, scoped to the tenant (and usually the project).

What gets audited

Representative action names already in use: release.created, env.deployed, execution.started, task.completed, task.rejected, decision.deleted, workflow.deleted, tenant.provisioned, tenant.updated. Audit writes are best-effort — an audit-append failure never blocks or fails the operation it’s recording, the same posture usage metering takes. This trades a theoretical gap in the audit trail for never letting an observability write become an availability problem.

The actor is the caller’s email (falling back to the token subject if no email claim is present).

Reading audit

Two surfaces, both tenant-scoped:

• Per-project: GET /projects/{project}/audit — the simple list.
• Tenant-wide, filterable: GET /audit?project=&action=&actor=&from=&to=&limit= — spans every project when project is omitted. Pairs with GET /audit/summary for aggregate counts (by action, actor, day) over the same filters — built for building a compliance report without pulling every row client-side.

See Audit reference in the API section for exact request/response shapes (audit shares the artifacts/releases API page since it’s exposed alongside project governance routes).

RBAC

Within a tenant, realm roles gate specific actions:

• Deploying to, or rolling back, a protected environment (staging, prod/production) requires approver or admin.
• Completing a human task requires being the task’s assignee, or holding approver/admin, when the task has an assignee set.
• Admin-only, cross-tenant reporting routes (/admin/usage, /admin/tenants) require admin.

Roles are orthogonal to tenancy: a role never widens the tenant scope. An admin acting on their own tenant’s releases still only sees that tenant’s data — role checks gate what you may do, tenancy gates whose data you can do it to. See Tenancy & isolation.

What governance guarantees, concretely

• Reproducibility — a release is immutable, so “what ran in prod on this date” is always answerable by looking up the deployment’s release_id.
• Traceability — every governance action has an actor and a timestamp.
• Separation of duties — protected-environment deploys require a different role than the one that authors decisions, when your realm setup assigns them separately.
• Non-drift — a deployed workflow’s decision logic is frozen at deploy time (inlined from the release), so it cannot silently change underneath a running environment.