Workflow 4: Env Promotion and Safe Rollback

Last validated: 2026-05-14

Goal

Promote configuration and versions across environments while maintaining reproducibility and fast rollback options.

When To Use

Staging to production promotion
Secret rotation combined with release updates
Controlled rollback under incident pressure

A) CLI Path (Tenant Env + Version Ops)


# 1) Import tenant env baseline
dodil scriptum env import ./.env.prod
 
# 2) Validate critical keys
dodil scriptum env get OPENAI_API_KEY
dodil scriptum env get DB_HOST
 
# 3) Publish candidate draft
dodil scriptum draft publish invoice-parser
 
# 4) Pin-run smoke test
dodil scriptum thread run invoice-parser \
  --version 4 \
  --input @./smoke/prod_smoke.json \
  --env \
  --result
 
# 5) Roll back if needed
dodil scriptum version rollback invoice-parser --to 3

Argument guidance:

Use explicit --version in smoke runs to avoid accidental active-version drift.
Keep --env enabled in smoke tests so runtime resolves actual effective config.

B) gRPC Path (Script Overlay Promotion)

CLI currently has no script env overlay command, so manage overlays via API.


# Read current script overlay
grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{"name":"invoice-parser"}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/GetScriptEnv
 
# Apply overlay updates
grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{
    "name":"invoice-parser",
    "set":{"MODEL":"gpt-4.1","TEMPERATURE":"0.0"},
    "delete":["LEGACY_MODEL"]
  }' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/UpdateScriptEnv

C) HTTP Path

Management verification


curl -sS https://api.dev.dodil.io:443/ready
curl -sS https://api.dev.dodil.io:443/health

Business API via gateway (if deployed)


curl -sS "https://api.dev.dodil.io:443/v1/scriptum/scripts/invoice-parser/env" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID"

Promotion Checklist

Tenant env imported and validated.
Script overlay updated and reviewed.
Candidate version published.
Pinned smoke run succeeds.
Rollback command and target version verified before change window.

Rollback Checklist

Record incident/ticket ID in runbook.
Run version rollback to known good version.
Execute smoke thread on rolled-back version.
Archive output and step details for postmortem.