Environment Promotion

AuraBoot treats DSL (models, pages, commands, permissions) as a versioned artifact that flows across environments. Promotion means lifting a known-good configuration from one environment to the next — applied per resource version — without hand-editing the destination.

Three-environment model

Tenant data does not promote. Only DSL and configuration promote. Production data stays in production.

When to use

• After a designer ships a new page or command in dev and a stakeholder needs to review it in staging.
• Before a release: cut a DSL bundle from staging and promote to prod.
• During incident response: roll back the previous DSL bundle without restoring the database.

How it works

A promotion is a four-step workflow:

1. Export a configuration snapshot from the source environment (EnvironmentExportData, readable and verifiable).
2. Diff the source against the destination to surface adds / updates / removes (GET /api/admin/environments/diff).
3. Lock the destination so concurrent edits cannot race the promotion (POST /api/admin/environments/{pid}/lock).
4. Apply: create and validate (dry-run) a promotion, then apply it; the platform writes DSL transactionally.

While the destination is locked, it rejects designer writes until it is unlocked. This prevents the classic split-brain bug where a hotfix in prod is silently overwritten by the next promotion. Lock and unlock both require a reason and are recorded in the audit trail.

API and commands

Environment promotion goes through the platform management REST API (under /api/admin/environments and /api/admin/promotions, requires an admin token).

# 0. List environments to get source/target env ids and codes
curl -sS http://localhost:6443/api/admin/environments \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# 1. Export a configuration snapshot from dev (read-only, for review)
curl -sS -X POST http://localhost:6443/api/admin/environments/dev/export \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# 2. Diff dev against staging (read-only)
curl -sS "http://localhost:6443/api/admin/environments/diff?source=dev&target=staging" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# 3. Lock the destination (reason required, recorded in audit)
curl -sS -X POST http://localhost:6443/api/admin/environments/<staging-pid>/lock \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Promote crm_lead.qualify command"}'

# 4. Create a promotion (source/target env ids + the resource units to promote)
curl -sS -X POST http://localhost:6443/api/admin/promotions \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceEnvId": 1,
    "targetEnvId": 2,
    "units": [
      { "resourceType": "PAGE_SCHEMA", "resourcePid": "<page-pid>" }
    ]
  }'

# 5. Validate (dry-run): detect conflicts; on success DRAFT -> VALIDATED
curl -sS -X POST http://localhost:6443/api/admin/promotions/<promotion-pid>/validate \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# 6. Apply: transactionally write to the destination (four-eyes when locked, reason required)
curl -sS -X POST http://localhost:6443/api/admin/promotions/<promotion-pid>/apply \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Add crm_lead.qualify command"}'

Conceptually, the diff lists added / updated / removed resources between source and destination (for example, version differences in a page schema).

Promotions are append-only in the audit log (AdminEventLogService); every apply records the operator (appliedBy), reason (appliedReason), and time (appliedAt), and records failureReason on failure.

Rollback

The platform does not have a one-click rollback endpoint today. To roll back, re-promote a previously known-good configuration version to the destination: keep the prior resource version in the source environment (or in a saved export snapshot), then create -> validate -> apply a promotion the same way, and the matching resources in the destination bump to that version. To overwrite the destination with an exported snapshot, use POST /api/admin/environments/{code}/import (the body is the EnvironmentExportData returned by export).

Verify

• After promotion, GET /api/admin/environments/diff?source=...&target=... shows no changes.
• After apply, the destination /actuator/health is UP.
• The promoted page renders end-to-end (sidebar -> list -> create -> save) in the destination.
• The promotion status is APPLIED and records appliedBy / appliedReason / appliedAt; the audit log has the corresponding event.
• After rollback, the diff returns to zero against a saved baseline.

Related

• Upgrade
• Backup and Restore
• Secrets and Variables
• CLI