Skip to content
TesseraQLTesseraQL

Environments and promotion

How an edit made in dev Studio reaches production: it travels through git, passes the CI gates, and lands as the same artifact configured per environment by a profile. Nothing here is new machinery — it composes the pieces the framework already ships.

The loop

Section titled “The loop”
  1. Edit in dev. Studio is writable to holders of the tql.studio.edit.<name> atom — the bootstrap administrator carries the wildcard: route form, source editor, scaffolds, migrations, policy edits — everything lands as files in the app tree, and applying serves immediately (the hot reload).
  2. Branch and PR. The app tree is a git repository; Studio edits are ordinary diffs. Open a PR from the dev branch. The Studio audit trail (work/studio/audit/) tells you who changed what if the diff needs context — work/ itself is never committed.
  3. CI governance gate. The PR pipeline runs the machine checks the framework provides:
    • tesseraql lint (or tesseraql:lint) — structure, security, references; findings carry source:line.
    • tesseraql test + coverage kinds (tesseraql:report) — the declarative suites, with per-kind thresholds (see testing).
    • tesseraql release-diff --app . --baseline <deployed-tree> — what does this deploy change: routes, API contract, the migrations it will run, policy changes, schema delta. The baseline is a checkout of the previously released tag. Post the Markdown to the PR; a reviewer approves the change, not a prose description of it.
    • tesseraql:release-evidence — the SBOM, OpenAPI, and htmx-contract artifacts.
  4. Tag and package. On merge, CI builds the immutable artifact — tesseraql package (.tqlapp) or the container image — stamped with the tag. Run artifacts under .tesseraql/ stay out of the package by design; spec.json (byte-stable) rides along.
  5. Promote by config, not edits. Staging and prod run the SAME artifact with a different environment profile: --env staging / --env prod selects config/env/<profile>.yml (datasources, pool sizing, metrics/audit switches — see environment profiles). Secrets stay in the environment or the secret provider — never in the tree.
  6. Prod grants no edit atoms. Production principals simply do not hold tql.studio.edit.<name>, so the explorer, docs portal, ops console and release diff page stay available for inspection while every write path refuses. An edit gets to prod exactly one way — back through steps 1-5.
  7. Capture the next baseline. After the deploy, capture the baselines the documentation portal’s Release diff page reads from the app home: copy the released openapi.json (the API spec tesseraql generate writes, also a release-evidence artifact) to .tesseraql/docs/openapi.baseline.json, and the schema sidecar .tesseraql/docs/schema.json to .tesseraql/docs/schema.baseline.json. Keep the deployed tree/tag available as the release-diff baseline for the next cycle.

Rollback

Section titled “Rollback”

Redeploy the previous tag with the same profile. Migrations are fix-forward (Flyway free edition has no undo): roll back code freely, roll schema forward with a follow-up migration.

Next

Section titled “Next”