Docs

Customer CI quickstart

Customer and CI quickstart#

This page is the canonical integration overview for the hosted audit API and the aigov CLI. For a step-by-step hosted console walkthrough (~10 minutes), use customer-onboarding-10min.md (also mirrored under Help → Getting started on govbase.dev). For a local developer loop with Docker/Rust/Postgres on loopback, use quickstart-5min.md.

The legacy govai command remains available as a deprecated alias for existing integrations.

Public documentation for readers is rendered on govbase.dev from this docs/ tree (for example /docs/quickstart, /docs/api-reference). The canonical prose remains in GitHub so CI link checks and contributors edit one source.

What is AIGov#

AIGov is an audit-backed decision service: you append structured evidence for a run_id, and the hosted API returns a single authoritative verdict (VALID / INVALID / BLOCKED) from GET /compliance-summary. Semantics are defined in trust-model.md.

CI often calls aigov check against the same run_id so merges or deploys fail unless the server verdict is VALID. Production-style release gates should use aigov submit-evidence-pack followed by aigov verify-evidence-pack (digest + optional export cross-check) as documented in github-action.md—check alone does not prove artefact continuity.

Use one value for GOVAI_RUN_ID end to end: evidence submission → decision readout (check and/or workflow) → aigov export-run.

Preview runtime: POST /v1/runtime/evaluate exists as a preview namespace (see api-reference.md and OpenAPI). It does not replace GET /compliance-summary as the authoritative gate for promotion verdicts.

Billing: if your operator enables Stripe on the hosted endpoint, see billing.md for checkout, status, usage reporting, and enforcement.

Evidence lifecycle

How an evidence event moves from emission to an auditable ledger record.

Record evidence

Emit a lifecycle event to the audit ledger (read-only preview — no live call).

Preview
AIGov try console
local
Try thisCopy and run in your environment

POST /evidence

Command
curl -sS -X POST "$GOVAI_AUDIT_BASE_URL/evidence" \
  -H "Authorization: Bearer $GOVAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"evaluation_reported","run_id":"demo-run","payload":{"passed":true}}'
Expected output
View expected output
{ "status": "recorded", "event_id": "…" }

Prerequisites#

  • Python 3.10+
  • GOVAI_AUDIT_BASE_URL — base URL of your AIGov audit service
  • Optional: GOVAI_API_KEY if your endpoint requires a Bearer token

Install pin must match version in python/pyproject.toml for the release you use.

Ledger tenant: which ledger you read/write is determined only by your API key (GOVAI_API_KEYS_JSON on the server). The optional X-GovAI-Project header (and aigov --project) is metadata for usage labels and does not isolate ledger data.

Hosted billing (Stripe)#

If you use a hosted AIGov audit endpoint with Stripe, see billing.md for:

  • Checkout (POST /billing/checkout-session)
  • Billing status (GET /billing/status)
  • Usage reporting (POST /billing/report-usage)
  • Billing portal (POST /billing/portal-session)
  • Invoices (GET /billing/invoices)
  • Reconciliation (GET /billing/reconciliation)
  • Webhooks and enforcement behavior

Billing identity is always the ledger tenant derived from your API key, not X-GovAI-Project.

Step by step integration#

Hosted CI integration

  1. 1Install CLI

    Pin must match python/pyproject.toml for your release tag.

    python -m pip install --upgrade pip
    python -m pip install "aigov-py==0.2.1"
    aigov --help >/dev/null && echo "AIGov CLI OK"
  2. 2Configure endpoint

    Omit GOVAI_API_KEY only for legacy unauthenticated dev endpoints.

    export GOVAI_AUDIT_BASE_URL="https://YOUR_GOVAI_AUDIT_SERVICE"
    export GOVAI_API_KEY="YOUR_API_KEY"
  3. 3Create run_id
    export GOVAI_RUN_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
    echo "$GOVAI_RUN_ID"
  4. 4POST evidence

    See full payload example in repository customer-quickstart history or quickstart-5min.md.

    export EVENT_ID="evt_${GOVAI_RUN_ID}"
    curl -sS "$GOVAI_AUDIT_BASE_URL/evidence" \
      -H "content-type: application/json" \
      -H "authorization: Bearer $GOVAI_API_KEY" \
      -d @event.json
  5. 5Gate on verdict
    aigov check --run-id "$GOVAI_RUN_ID"
    Expected output
    "VALID → exit 0; INVALID → exit 2; BLOCKED → exit 3"

After only the minimal event, aigov check usually returns BLOCKED until the full promotion sequence is recorded. Export when ready:

aigov export-run --run-id "$GOVAI_RUN_ID" > "aigov-export-${GOVAI_RUN_ID}.json"

Expected results#

  • CLI runs without error
  • Evidence endpoint returns 200
  • aigov check returns a verdict
  • export-run produces JSON

Troubleshooting#

aigov command not found
Reinstall CLI and ensure PATH is correct (legacy govai alias uses the same package)

401 or 403
Check GOVAI_API_KEY

BLOCKED
Missing evidence or approval

VALID locally but fails in CI
Ensure same GOVAI_RUN_ID, API base URL, and API key

← Back to home