Anyone building a dashboard wants to test before showing it. The product separates this into
three environments — dev, test and prod — and provides a promotion
flow that moves the definition of a dashboard from one environment to the next without copying
data, without copying credentials and without manual editing at the destination.
What an environment is here#
There is no separate registry of "environment". An environment is a convention on the
workspace: a label [dev], [test] or [prod] in the workspace name (or
the entire name being dev/test/prod). Sibling workspaces belong to the same
organização — it is what determines which dev/test/prod
form a set.
| Environment | Label | Purpose |
|---|---|---|
dev | Development | build and break at will |
test | Test | validate with intended users before exposing |
prod | Production | what the company consumes and shares |
Without a label, the workspace is treated as no declared environment and does not enter the promotion flow.
The order rule#
Promotion is always forward and never skips a step without record:
dev → testandtest → prodare the normal transitions.dev → prodonly with explicit force, and this is recorded in the audit.- Reverting (
prod → test) or promoting to the same environment is not allowed — to go back there is rollback (below).
The flow: diff → approve → apply → rollback#
The promotion is built on top of BI-as-code: the diff is the same dry-run as import; apply is the same additive merge.
1. Gerar o plano (diff)
No painel de origem, abra Promoção e escolha o workspace de destino. O produto exporta a definição, remove qualquer referência local do ambiente de origem (como o vínculo com o modelo semântico daquele workspace) e calcula, entidade por entidade, o que é
novo,inalteradoouconflito.2. Aprovar (outra pessoa)
Quem aprova não pode ser quem promove — segregação de funções. Conflitos exigem estratégia explícita (
manter_meu/usar_deles); sem escolha, a promoção não aplica nada.3. Aplicar
O merge é aditivo e idempotente: aplicar a mesma promoção duas vezes não muda nada na segunda (tudo vira
inalterado). O estado do destino antes de aplicar fica guardado no plano.4. Rollback
Voltar é reescrever o snapshot capturado no passo 3. Também fica na auditoria.
Golden rule: credentials never travel#
The export is already created without secrets (it reads only the definition of the dashboard). Even so, before applying, the product scans the content and removes any sensitive key (password, token, API key, service account credential…) that may have been injected into some configuration. Connections, keys and data do not migrate; at the destination you use the destination's own connections and run the refresh.
What gets recorded#
Each promotion generates events in the audit: who requested it, who approved it, origin, destination, whether it was forced, a summary of the plan applied and, if any, the rollback.
Current limits#
- Promotion covers dashboards and model (the definition). Pipelines have their own versioning (publicar e versionar) and are not promoted by this flow.
- The three environments are separate workspaces: each has its own datalake, its own connections and its own credits.
Related: BI-as-code · Organização e workspaces · Papéis (RBAC) · Auditoria.