Prévias: um ambiente para cada merge request

Uma prévia é uma cópia efêmera de um produto, implantada para um merge request para que as pessoas que revisam uma mudança possam testá-la em um navegador antes do merge. O Airframe só a implanta depois que as pessoas certas aprovaram a mudança, dá a ela um endereço próprio e a destrói quando o merge request é integrado ou fechado. Esta página explica o que uma prévia contém, quem a implanta, quando ela some e quanto custa.

O que um merge request recebe

Um merge request aprovado de um produto recebe três coisas.

Seu próprio nome de host. O endereço é <product>-eph-<iid>.<domain>.<journey>.projectairframe.dev, em que <iid> é o número do merge request. O merge request 42 de um produto chamado invoicing no domínio billing da jornada settle ficaria em invoicing-eph-42.billing.settle.projectairframe.dev. Como uma prévia tem um nome de host, e não um caminho sob outro, os cookies, os redirecionamentos e os links funcionam como em produção. Como todo nome de host de um produto, ela fica atrás do login único, e só o grupo de usuários do produto entra. O certificado e o registro curinga do domínio já cobrem toda prévia, então nada é emitido para cada uma.

O roteador de prévias. Cada produto tem um pequeno serviço no seu projeto de não produção, criado pelo módulo preview-substrate do golden path. Ele lê o número do merge request no nome de host e encaminha cada requisição para os serviços daquela prévia. Cada serviço de uma prévia aceita chamadas só do roteador, então o nome de host, com o seu login, é a única entrada.

Um banco de dados. O campo preview_db da entrada do catálogo escolhe como uma prévia recebe um:

sidecar, o padrão: um contêiner de PostgreSQL que roda ao lado do serviço da prévia na mesma revisão do Cloud Run, carregado na partida com os arquivos .airframe/eph/ do produto. Ele não custa nada enquanto está ocioso e esquece seus dados quando sua instância some. O módulo de Cloud Run do golden path roda o serviço de uma prévia em uma instância no máximo, porque os dados vivem nessa instância, e o pacote de políticas avisa sobre um serviço com um banco assim que possa rodar mais.
shared: uma instância do Cloud SQL por produto, dimensionada pelo campo preview_concurrency da entrada, na qual cada prévia recebe um banco de dados próprio. Ela exige que o projeto de não produção do produto esteja na rede compartilhada da plataforma; até lá, uma prévia compartilhada não pode ser aplicada.

O que uma prévia contém é escolha do produto, na sua raiz de Terraform infra/eph, composta com os mesmos módulos da produção. O ciclo de vida em volta dela é da plataforma.

Quem a implanta, e quando

O pipeline do próprio merge request nunca implanta uma prévia: ele roda código que ninguém revisou ainda, então não tem nenhuma credencial da nuvem. A prévia vem do executor, na aprovação.

Quando o controle de aprovação aprova o merge request de um produto, ele inicia as execuções do executor para aquele commit: os planos, a compilação das imagens e a prévia. A execução da prévia espera a compilação do último commit do merge request, por até 25 minutos, e para se a compilação falhou. Depois, com a identidade de apply de não produção do produto, ela planeja infra/eph, passa o pacote de políticas sobre o plano, calcula o preço e o aplica. Ela publica uma nota no merge request com o endereço da prévia e a hora em que ela expira.

Um novo push zera as aprovações do merge request. A aprovação seguinte aplica a mesma prévia de novo com o novo commit, e é assim que a prévia acompanha a mudança. A identidade de produção nunca é usada, então uma prévia não pode tocar a produção. Um produto cujo status no catálogo é retiring não recebe prévia, já que não serve nada.

Quando ela é destruída

Uma prévia é destruída no primeiro de três momentos:

O merge. O controle de aprovação fica sabendo do merge pelo GitLab e inicia a execução de destruição do executor. O executor confere por conta própria que o merge request foi integrado ou fechado, destrói os recursos da prévia com a mesma identidade de não produção e publica uma nota. O estado do Terraform da prévia é mantido, vazio, como registro.
O fechamento. Um merge request fechado é tratado da mesma forma.
O tempo de vida. O campo preview_ttl_hours da entrada, 72 horas a menos que a entrada diga outra coisa e no máximo 168, contadas a partir do último apply da prévia.

O tempo de vida, uma notificação perdida e uma destruição que falhou são pegos pelo coletor: preview:collect, um job do pipeline agendado diário do repositório control-plane. Ele lista toda prévia que, segundo os registros do executor, ainda está de pé, confere o estado e a expiração de cada merge request, e destrói as integradas, as fechadas e as expiradas, com uma nota em cada merge request.

Cada prévia tem um registro que guarda o que foi aplicado, e uma trava, para que um apply e uma destruição nunca rodem ao mesmo tempo. Um merge request fechado e reaberto inicia uma nova geração do registro, então uma destruição atrasada não consegue remover a nova prévia.

Quanto custa

O roteador e os serviços da prévia vão a zero, e um banco sidecar não custa nada enquanto está ocioso; um serviço de prévia em execução carrega cerca de 512 MiB a mais de memória para o seu banco. Uma instância compartilhada custa cerca de USD 9 por mês por produto enquanto existe.

O executor calcula o preço do plano de cada prévia e mostra o valor na sua nota. A verificação de custo que mantém o merge fechado acima do orçamento do produto deixa a prévia de fora, então uma prévia nunca bloqueia uma mudança. E como só uma mudança aprovada recebe uma prévia, alguém que só pode abrir merge requests não consegue inflar a conta.

Como uma prévia difere da sandbox

Uma sandbox é uma cópia opcional e duradoura de um produto na versão da sua branch main, com sua própria instância do Cloud SQL e um serviço sempre aquecido, em <product>-sandbox.<domain>.<journey>.projectairframe.dev. Outros produtos testam contra ela, e ela custa dinheiro o mês inteiro. Uma prévia contém a mudança de um merge request, vive horas ou dias, e some depois do merge.

Ver o que uma prévia faz

Os logs, as métricas e os traces de uma prévia levam o rótulo de ambiente eph-<iid>, para que os painéis do produto a mostrem quando se escolhe esse valor. O golden path define deployment.environment com esse valor no serviço da prévia, e o gateway OTLP o toma como env, enquanto o agente da plataforma e o gateway de logs o derivam do nome do serviço. As regras de alerta selecionam só a produção, então uma prévia nunca acorda ninguém. Observabilidade explica os rótulos.

Projetado, não construído

O teste de fumaça (projetado). O arquivo .airframe/preview.yaml do produto nomeia um teste de fumaça e comandos para rodar depois da criação, e nada os executa ainda. Hoje o apply espera até que a nova revisão esteja pronta, e a aplicação prepara seu próprio esquema de banco de dados e seus dados iniciais na partida.
Os painéis no merge request (projetados). A nota teria um link para os painéis do produto filtrados pela prévia, e os erros de uma prévia chegariam como comentário no merge request.
O agente de auditoria (projetado). Ele encontraria uma prévia sem registro, ou uma cuja destruição falhou.

As prévias funcionaram nos ensaios da plataforma em setembro de 2026. Uma prévia exige que os projetos do produto estejam vinculados ao faturamento, e hoje nenhum produto de demonstração está, então nenhum tem uma prévia agora.

Este site também roda na plataforma, mas não tem prévias: o mantenedor decidiu que um merge request para o site não recebe nenhuma.

Onde fica

No repositório control-plane:

No repositório golden-path: