Skip to content

Automatic translation — the Portuguese version is the reference. View in Portuguese

Updated on 2026-10-04

Environments (dev/test/prod) and versioned promotion

How to separate development, testing, and production into sibling workspaces and promote a dashboard between them with diff, approval by another person, idempotent apply, and rollback.

On this page (6)

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.

EnvironmentLabelPurpose
devDevelopmentbuild and break at will
testTestvalidate with intended users before exposing
prodProductionwhat 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 → test and test → prod are the normal transitions.
  • dev → prod only 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. 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, inalterado ou conflito.

  2. 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. 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. 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.

Related links