Env Promotion & Rollback

Goal. Promote configuration and a new version into an environment with a reproducible smoke test and a fast rollback path.

When to use. Staging-to-production promotion, secret rotation alongside a release, and controlled rollback under incident pressure.

1. Promote the tenant environment

Import the environment baseline, then verify the keys that matter:


dodil scriptum env import ./.env.prod
dodil scriptum env get LLM_MODEL
dodil scriptum env get DB_HOST

env import overwrites existing keys; blank lines and # comments are ignored.

Security note. env get and env list currently return values. Treat the output as sensitive and keep it out of tickets and screenshots.

2. Promote the version


dodil scriptum draft publish invoice-parser
dodil scriptum version list invoice-parser

3. Pinned smoke test

Always pin --version in a smoke run so you test exactly what you promoted, and keep --env on so the runtime resolves the real effective configuration:


dodil scriptum thread run invoice-parser \
  --version 4 \
  --input @./smoke/prod_smoke.json \
  --env \
  --result

4. Roll back if needed


dodil scriptum version rollback invoice-parser --to 3

--to 0 rolls back to the previous active version. After a rollback, re-run the smoke test against the restored version and archive the output.

Per-script env overlays (API)

The CLI manages only the tenant store. Per-script overlays — which override tenant values for one script at runtime — are API-only:


# Apply an overlay for this script
grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{
    "name":"invoice-parser",
    "set":{"LLM_MODEL":"gpt-4o","TEMPERATURE":"0.0"},
    "delete":["LEGACY_MODEL"]
  }' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/UpdateScriptEnv

Promotion checklist

Tenant env imported and the critical keys verified.
Script overlay updated and reviewed (if used).
Candidate version published.
Pinned smoke run succeeds.
Rollback target version confirmed before the change window.

Rollback checklist

Record the incident/ticket ID in the runbook.
Run version rollback to the known-good version.
Smoke-test the rolled-back version.
Archive output and step detail for the postmortem.