Integration patterns

Patterns for embedding GovAI in your stack. Choose based on whether you need core-only enforcement or hosted + enterprise surfaces.

Pattern A: CI gate (most common)#

train → evaluate → approve → promote → compliance-summary → deploy

1. Emit lifecycle events to POST /evidence during the pipeline.
2. Call GET /compliance-summary?run_id=… before deploy.
3. Fail the job unless verdict == VALID.
4. Archive GET /api/export/:run_id for audit retention.

References: ../github-action.md, ../customer-quickstart.md.

Pattern B: Pre-deploy CLI check#

Use govai check with environment variables (GOVAI_RUN_ID, GOVAI_AUDIT_BASE_URL, API key). Suitable for Jenkins, GitLab CI, or local developer workflows.

Reference: ../cli-reference.md.

Pattern C: Evidence pack in PR#

Submit and verify governance evidence packs in pull requests (digest + manifest). Useful when policy requires pack shape validation before merge.

Reference: ../standards/governance_evidence_pack_standard.md.

Pattern D: Hosted audit URL + dashboard#

1. Operator provisions tenant-mapped API keys (GOVAI_API_KEYS_JSON).
2. Engineers point GOVAI_AUDIT_BASE_URL at hosted service.
3. Teams use dashboard for workflow and read-only compliance views.

Reference: ../customer-onboarding-10min.md.

Pattern E: Core-only self-host#

Run Rust audit service with file ledger; no Postgres JWT routes. Python tooling for bundle/export. Ignore dashboard/ and /api/*.

Reference: ../quickstart-5min.md, ../../OPEN_SOURCE_SCOPE.md.

Pattern F: Runtime attestation#

Emit runtime events from FastAPI, LangChain, or gateway wrappers; enforce before high-risk actions.

Reference: ../runtime/overview.md.

Pattern G: Decision intelligence (read path)#

Query flight-recorder style read APIs and the in-repo TypeScript client (@govai/client under typescript-sdk/) for executive summaries—does not replace evidence writes to the ledger.

Reference: ../govai-functions-2.md.

Authentication summary#

Tenant isolation for ledger operations is derived from API key → tenant mapping, not from optional metadata headers alone.

Anti-patterns#

• Treating missing evidence as success (bypassing BLOCKED).
• Using X-GovAI-Project as a security boundary (metadata only).
• Assuming enterprise workflow rows replace ledger appends.

Related#

• How GovAI works
• Integrations index