Ambientes de pré-visualização explicados: uma cópia nova da sua aplicação para cada pull request

Um ambiente de pré-visualização (preview) é uma cópia temporária da sua aplicação, criada a partir de um pull request ou de um branch e disponível num URL próprio. Os revisores abrem um link e experimentam a alteração no browser, em vez de se limitarem a ler um diff. Quando o trabalho termina, o ambiente desaparece.

Este guia explica para que servem os ambientes de pré-visualização, o que os torna difíceis de gerir e como funcionam na Nodion.

O que é um ambiente de pré-visualização?

Pense nele como um ambiente de staging temporário para uma única alteração. Cada pull request, ou cada branch que escolher, recebe:

• um build próprio do código desse branch,
• uma aplicação própria em execução, com URL próprio,
• cópias próprias dos serviços de que depende, normalmente pelo menos uma base de dados nova,
• um tempo de vida limitado.

A diferença em relação a um servidor de staging partilhado clássico: ninguém espera que o staging fique livre, e uma funcionalidade ainda em desenvolvimento não pode estragar o teste de outra. Para a mesma ideia, também vai encontrar os termos review apps, deploy previews ou ephemeral environments.

Porque é que as equipas os usam

• Rever software em execução, não só código. Um layout partido, um fluxo confuso ou uma página lenta saltam à vista no browser e passam facilmente despercebidos num diff.
• QA por alteração. As pessoas responsáveis pelos testes verificam uma alteração isolada antes do merge, pelo que cada bug que encontram corresponde a um único pull request.
• Partes interessadas sem ambiente de desenvolvimento. Designers, product managers ou um cliente abrem um link. Sem checkout local, sem partilha de ecrã.
• Testar migrações. Uma migração de esquema tem de correr numa base de dados real antes de a preview funcionar. Uma migração que só funciona num portátil falha aqui, não em produção.
• Trabalho em paralelo. Cinco pull requests abertos significam cinco previews em vez de uma fila à espera de um único servidor de staging.

O que os torna difíceis

Fazer o build da aplicação é a parte fácil. A parte difícil é tudo o que está à volta.

Bases de dados

Uma aplicação sem dados é difícil de rever, por isso a maioria das previews precisa de uma base de dados. Há três escolhas comuns: uma base de dados vazia, uma base de dados vazia com dados iniciais (seed) ou uma cópia da produção. Copiar a produção é tentador, mas coloca dados reais de clientes, incluindo dados pessoais, em muitos ambientes temporários a que mais pessoas têm acesso. Além disso, é lento quando a base de dados é grande. Para a maioria das equipas, uma base de dados vazia com um script de seed que cria dados de demonstração realistas é a opção mais segura por omissão.

Segredos

Uma preview executa código que ainda não foi revisto. As credenciais de produção não têm lugar ali. Dê às previews chaves de teste ou de sandbox para fornecedores de pagamentos, e-mail e APIs de terceiros, para que um bug num branch não possa cobrar um cartão real nem enviar e-mails a clientes reais.

URLs e callbacks

Cada preview tem um hostname diferente. Os URLs de redirecionamento OAuth, os endpoints de webhooks, as regras CORS e os cookies associados ao seu domínio de produção podem deixar de funcionar. As aplicações que leem o seu URL base a partir da configuração, em vez de terem o domínio de produção escrito no código, têm aqui muito menos problemas.

Custos e limpeza

Cada preview aberta executa uma aplicação, mais uma base de dados nova por cada base de dados associada à aplicação principal. Dez pull requests abertos podem significar dez ambientes extra, e uma preview esquecida continua a correr até alguém a fechar. A limpeza tem de acontecer automaticamente, e é por isso que as previews devem expirar sozinhas.

Como funcionam os ambientes de pré-visualização na Nodion

Na Nodion, as previews fazem parte de todas as aplicações com deploy a partir de um repositório Git:

• Ative-as nas Settings da aplicação.
• Uma preview por pull request ou branch. Cada preview é uma aplicação efémera com URL próprio.
• Manual ou automática. Crie uma preview manualmente ou deixe a Nodion criar uma automaticamente para os pull requests.
• Uma base de dados nova. Por cada base de dados associada à aplicação, a preview recebe uma base de dados própria, vazia, nunca um clone dos seus dados de produção. Os volumes, os buckets e as zonas de e-mail não são copiados.
• As definições da aplicação são copiadas. Uma preview arranca com uma cópia das variáveis de ambiente da aplicação, incluindo os segredos. As variáveis das bases de dados associadas apontam para as bases de dados novas da preview; tudo o resto, incluindo chaves e URLs de outros serviços, é copiado tal como está, por isso reveja-o. A Nodion acrescenta NODION_PREVIEW=1, NODION_PR_NUMBER, NODION_BRANCH e NODION_PARENT_APP.
• As previews expiram após um número de dias sem deploy (7 por omissão, configurável nas definições da aplicação). Até lá, pode voltar a fazer deploy de cada uma ou fechá-la no separador Previews da aplicação.
• Apenas aplicações Git. As aplicações com deploy a partir de uma imagem pré-construída não têm previews.

A base de dados nova é uma escolha deliberada: as bases de dados de preview associadas começam vazias, por isso não contêm dados de produção. Reveja também as chaves e os URLs copiados, para que o código da preview não consiga chegar aos sistemas de produção através deles. O reverso da medalha é que a sua aplicação tem de conseguir arrancar a partir de uma base de dados vazia, algo que convém garantir em qualquer caso.

Para começar, ligue o seu repositório em integrações Git, crie a aplicação a partir dele e ative as previews nas definições. Os detalhes estão na documentação das aplicações.

Um ciclo de revisão típico

1. Um programador abre um pull request. Com as previews automáticas ativas, arranca uma preview para esse pull request, com URL próprio e uma base de dados vazia.
2. O programador publica o link da preview no pull request. Os revisores, a equipa de QA e o product owner experimentam a alteração no browser.
3. O feedback transforma-se em novos commits. Volte a fazer deploy da preview a partir do separador Previews para mostrar o código mais recente aos revisores.
4. Depois de a alteração ser aprovada e integrada, feche a preview ou deixe-a expirar sozinha.

Ninguém teve de pedir uma vaga no staging, e a Nodion criou uma base de dados nova para a preview. Reveja todas as outras chaves e URLs copiados antes de executar código da preview, porque continuam a apontar para onde apontam as definições da aplicação.

Prepare a sua aplicação para previews

• Execute as migrações automaticamente quando a aplicação faz deploy ou arranca, para que uma base de dados nova receba o esquema atual sem passos manuais.
• Adicione um script de seed que crie um login de teste e algum conteúdo de demonstração. Os revisores devem ver algo útil logo no primeiro clique.
• Leia o URL base de uma variável de ambiente em vez de escrever o domínio de produção diretamente no código.
• Passe os efeitos secundários para modo de teste quando NODION_PREVIEW estiver definida: pagamentos, e-mails e tudo o que escreva noutros sistemas. As previews herdam os segredos da aplicação, por isso, sem essa verificação, uma preview usa as suas chaves de produção.
• Mantenha os pull requests pequenos. Uma preview para uma alteração focada é muito mais fácil de rever do que uma para uma semana de trabalho.

Quando pode dispensá-los

Para um projeto individual com poucas alterações por semana, um ambiente local e a produção podem bastar. As previews compensam quando há mais de uma pessoa a rever, testar ou aprovar alterações, ou quando as migrações de base de dados fazem parte do seu trabalho habitual.

As previews vêm com todas as aplicações Git na Nodion, juntamente com processos, logs, métricas e deploy automático. Consulte Aplicações para ter a visão completa.