CI/CD para backends Go: build, test, migrate, deploy

Por que CI/CD importa para backends Go\n\nDeploys manuais falham de maneiras chatas e repetitivas. Alguém faz o build no laptop com outra versão do Go, esquece uma variável de ambiente, pula uma migração ou reinicia o serviço errado. O release “funciona pra mim”, mas não em produção — e você só descobre isso depois que os usuários sentem o impacto.\n\nCódigo gerado não elimina a necessidade de disciplina de release. Quando você regenera um backend após atualizar requisitos, pode introduzir novos endpoints, novos formatos de dados ou novas dependências mesmo sem tocar o código manualmente. É exatamente aí que você quer um pipeline como grade de segurança: cada mudança passa pelos mesmos cheques, todas as vezes.\n\nAmbientes previsíveis significam que passos de build e deploy rodam em condições que você pode nomear e repetir. Algumas regras cobrem a maior parte do problema:\n\n- Trave versões (toolchain do Go, imagens base, pacotes OS).\n- Build uma vez, deploy o mesmo artefato em todo lugar.\n- Mantenha configuração fora do binário (vars de ambiente ou arquivos por ambiente).\n- Use a mesma ferramenta de migração e processo em cada ambiente.\n- Faça rollbacks reais: mantenha o artefato anterior e saiba o que acontece com o banco de dados.\n\nO objetivo do CI/CD para backends Go não é automação por si só. É releases repetíveis com menos estresse: regenere, rode o pipeline e confie que o que sai é deployável.\n\nSe você usa um gerador como AppMaster que produz backends Go, isso importa ainda mais. Regeneração é um recurso, mas só parece segura quando o caminho da mudança até produção é consistente, testado e previsível.\n\n## Escolha seu runtime e defina “previsível” desde o início\n\n"Previsível" significa que a mesma entrada produz o mesmo resultado, não importa onde rode. Para CI/CD de backends Go, isso começa por concordar o que deve permanecer idêntico entre dev, staging e prod.\n\nOs não-negociáveis comuns são a versão do Go, a imagem base do SO, flags de build e como a configuração é carregada. Se algum desses muda por ambiente, você terá surpresas como comportamento TLS diferente, pacotes de sistema faltando ou bugs que só aparecem em produção.\n\nA maior parte do drift de ambiente aparece nos mesmos lugares:\n\n- SO e bibliotecas do sistema (versões distintas de distro, CA certs faltando, diferenças de fuso horário)\n- Valores de configuração (feature flags, timeouts, origens permitidas, URLs de serviços externos)\n- Forma e settings do banco (migrações, extensões, collation, limites de conexão)\n- Tratamento de segredos (onde vivem, como rotacionam, quem pode ler)\n- Suposições de rede (DNS, firewalls, descoberta de serviços)\n\nEscolher entre Kubernetes e VMs é menos sobre o que é “melhor” e mais sobre o que seu time consegue operar com calma.\n\nKubernetes encaixa bem quando você precisa de autoscaling, rolling updates e uma forma padrão de rodar muitos serviços. Ele também ajuda a impor consistência porque os pods rodam a partir das mesmas imagens. VMs podem ser a escolha certa quando você tem um ou poucos serviços, um time pequeno e quer menos peças em movimento.\n\nVocê pode manter o pipeline igual mesmo que os runtimes sejam diferentes padronizando o artefato e o contrato ao redor dele. Por exemplo: sempre construa a mesma imagem de container no CI, rode os mesmos passos de teste e publique o mesmo bundle de migração. Só a etapa de deploy muda: Kubernetes aplica uma nova tag de imagem, enquanto VMs puxam a imagem e reiniciam um serviço.\n\nUm exemplo prático: um time regenera um backend Go com AppMaster e faz deploy para staging no Kubernetes, mas usa uma VM em produção por enquanto. Se ambos puxam a mesma imagem exata e carregam configuração do mesmo tipo de cofre de segredos, “runtime diferente” vira detalhe de deploy, não causa de bugs. Se você usa AppMaster (appmaster.io), esse modelo também se encaixa bem porque dá para fazer deploy em alvos gerenciados ou exportar o código-fonte e rodar o mesmo pipeline na sua infraestrutura.\n\n## Um mapa simples de pipeline que qualquer um consegue explicar\n\nUm pipeline previsível é fácil de descrever: verifique o código, construa, prove que funciona, envie exatamente o que foi testado e então faça o deploy da mesma forma toda vez. Essa clareza importa ainda mais quando seu backend é regenerado (por exemplo, pelo AppMaster), porque mudanças podem tocar muitos arquivos ao mesmo tempo e você quer feedback rápido e consistente.\n\nUm fluxo direto de CI/CD para backends Go se parece com isto:\n\n- Lint e cheques básicos\n- Build\n- Testes unitários\n- Cheques de integração\n- Empacotar (artefatos imutáveis)\n- Migrar (etapa controlada)\n- Deploy\n\nEstruture para que falhas parem cedo. Se o lint falha, nada mais deve rodar. Se o build falha, não perca tempo iniciando bancos para cheques de integração. Isso mantém custos baixos e faz o pipeline parecer rápido.\n\nNem todo passo precisa rodar em todo commit. Uma divisão comum é:\n\n- Cada commit/PR: lint, build, testes unitários\n- Branch main: cheques de integração, empacotamento\n- Tags de release: migrar, deploy\n\nDecida o que manter como artefatos. Normalmente é o binário compilado ou imagem de container (o que você deploya), além de logs de migração e relatórios de teste. Guardar isso facilita rollbacks e auditorias porque você pode apontar exatamente o que foi testado e promovido.\n\n## Passo a passo: etapa de build estável e repetível\n\nA etapa de build deve responder a uma pergunta: conseguimos produzir o mesmo binário hoje, amanhã e em outro runner? Se isso não for verdade, cada passo posterior (testes, migrações, deploy) fica difícil de confiar.\n\nComece travando o ambiente. Use uma versão fixa do Go (por exemplo, 1.22.x) e uma imagem runner fixa (distro Linux e versões de pacotes). Evite tags “latest”. Pequenas mudanças em libc, Git ou toolchain do Go podem criar falhas “funciona na minha máquina” que são dolorosas de depurar.\n\nCache de módulos ajuda, mas só quando é visto como ganho de velocidade, não fonte de verdade. Faça cache do build cache do Go e do cache de download de módulos, mas claveie pelo go.sum (ou limpe no main quando deps mudam) para que novas dependências acionem download limpo.\n\nAdicione um portão rápido antes da compilação. Mantenha-o rápido para que desenvolvedores não o ignorem. Um conjunto típico é checar gofmt, go vet e (se for rápido) staticcheck. Também falhe em arquivos gerados faltando ou desatualizados, problema comum em codebases regeneradas.\n\nCompile de forma reprodutível e embuta infos de versão. Flags como -trimpath ajudam, e você pode usar -ldflags para injetar SHA do commit e hora do build. Produza um artefato nomeado por serviço. Isso facilita traçar o que está rodando no Kubernetes ou numa VM, especialmente quando o backend é regenerado.\n\n## Passo a passo: testes que pegam problemas antes do deploy\n\nTestes só ajudam se rodarem do mesmo jeito toda vez. Mire primeiro em feedback rápido e depois adicione cheques mais profundos que ainda terminem em tempo previsível.\n\nComece com testes unitários em cada commit. Defina timeout rígido para que um teste travado falhe alto em vez de pendurar todo o pipeline. Também decida o que significa cobertura “suficiente” para seu time. Cobertura não é troféu, mas um patamar mínimo ajuda a evitar erosão de qualidade.\n\nUma etapa de testes estável inclui tipicamente:\n\n- Rode go test ./... com timeout por pacote e timeout global do job.\n- Trate qualquer teste que atinja timeout como bug real a ser corrigido, não como “CI instável”.\n- Defina expectativas de cobertura para pacotes críticos (auth, billing, permissions), não necessariamente para todo o repositório.\n- Adicione o race detector para código que lida com concorrência (filas, caches, workers).\n\nO race detector é valioso, mas pode deixar builds bem mais lentos. Um bom compromisso é rodá-lo em pull requests e builds noturnos, ou apenas em pacotes selecionados, em vez de em todo push.\n\nTestes flaky devem falhar o build. Se precisar isolar um teste, mantenha-o visível: mova para um job separado que ainda rode e reporte vermelho, exigindo um dono e prazo para correção.\n\nArmazene a saída dos testes para que depurar não exija rerodar tudo. Salve logs brutos mais um relatório simples (pass/fail, duração e testes mais lentos). Isso facilita identificar regressões, especialmente quando mudanças regeneradas tocam muitos arquivos.\n\n## Cheques de integração com dependências reais, sem builds lentos\n\nTestes unitários dizem que seu código funciona isoladamente. Cheques de integração dizem que o serviço inteiro ainda se comporta quando sobe, conecta a serviços reais e atende requisições. Essa é a rede de segurança que pega problemas só visíveis quando tudo está ligado.\n\nUse dependências efêmeras quando seu código precisar delas para iniciar ou responder requisições chave. Um PostgreSQL temporário (e Redis, se usado) rodando só para o job costuma ser suficiente. Mantenha versões próximas da produção, mas não tente copiar todos os detalhes de produção.\n\nUma boa etapa de integração é propositalmente pequena:\n\n- Inicie o serviço com vars de ambiente parecidas com produção (mas segredos de teste)\n- Verifique um health check (por exemplo, /health retorna 200)\n- Chame um ou dois endpoints críticos e verifique códigos de status e formato da resposta\n- Confirme que consegue alcançar o PostgreSQL (e o Redis, se necessário)\n\nPara cheques de contrato de API, foque nos endpoints que mais causariam dano se quebrassem. Você não precisa de uma suíte end-to-end completa. Algumas verdades de requisição/resposta bastam: campos obrigatórios rejeitados com 400, autenticação exigida retorna 401, e um caminho feliz retorna 200 com as chaves JSON esperadas.\n\nPara manter integrações rápidas o suficiente para rodar com frequência, limite o escopo e controle o tempo. Prefira um banco com dataset minúsculo. Execute só algumas requisições. Defina timeouts rígidos para que um boot travado falhe em segundos, não minutos.\n\nSe você regenera seu backend (por exemplo com AppMaster), esses cheques têm peso extra. Eles confirmam que o serviço regenerado ainda sobe limpo e fala a API que seu app web ou mobile espera.\n\n## Migrações de banco: ordenação segura, gates e a realidade do rollback\n\nComece escolhendo onde as migrações rodam. Rodá-las no CI é bom para pegar erros cedo, mas CI geralmente não deve tocar produção. A maioria das equipes roda migrações durante o deploy (como uma etapa dedicada) ou como um job de “migrate” separado que deve terminar antes da nova versão iniciar.\n\nUma regra prática: construa e teste no CI, depois rode migrações o mais próximo possível da produção, com credenciais e limites parecidos com os de produção. No Kubernetes, isso costuma ser um Job one-off. Em VMs, pode ser um comando scriptado na etapa de release.\n\nA ordem importa mais do que se espera. Use arquivos com timestamp (ou números sequenciais) e imponha “aplicar em ordem, exatamente uma vez”. Faça migrações idempotentes quando possível, para que uma tentativa de retry não crie duplicados ou trave no meio.\n\nMantenha a estratégia de migração simples:\n\n- Prefira mudanças aditivas primeiro (novas tabelas/colunas, colunas nullable, novos índices).\n- Faça deploy do código que consegue lidar tanto com o esquema antigo quanto com o novo por uma release.\n- Só então remova ou aperte constraints (dropar colunas, tornar colunas NOT NULL).\n- Torne operações longas seguras (por exemplo, crie índices concurrentemente quando suportado).\n\nAdicione um gate de segurança antes de qualquer execução. Pode ser um lock no banco para que só uma migração rode por vez, mais uma política como “sem mudanças destrutivas sem aprovação”. Por exemplo, falhe o pipeline se uma migração contiver DROP TABLE ou DROP COLUMN a menos que um gate manual seja aprovado.\n\nRollback é a verdade dura: muitas mudanças no esquema não são reversíveis. Se você droppa uma coluna, os dados não voltam. Planeje rollbacks pensando em correções pra frente: mantenha um down migration somente quando for realmente seguro, e confie em backups mais uma migração corretiva quando não for.\n\nAcompanhe cada migração com um plano de recuperação: o que fazer se falhar no meio, e o que fazer se a aplicação precisar reverter. Se você gera backends Go (por exemplo, com AppMaster), trate migrações como parte do contrato de release para que código regenerado e esquema permaneçam sincronizados.\n\n## Empacotamento e configuração: artefatos em que se pode confiar\n\nUm pipeline só parece previsível quando o que você deploya é sempre o que testou. Isso depende de empacotamento e configuração. Trate o output do build como um artefato selado e mantenha todas as diferenças de ambiente fora dele.\n\nEmpacotamento normalmente segue dois caminhos. Imagem de container é o padrão se você faz deploy em Kubernetes, porque prende a camada do SO e torna rollouts consistentes. Um bundle para VM pode ser igualmente confiável quando necessário, desde que inclua o binário compilado mais o pequeno conjunto de arquivos necessários em runtime (por exemplo: CA certs, templates ou assets estáticos), e você faça o deploy do mesmo jeito cada vez.\n\nConfiguração deve ser externa, não embutida no binário. Use variáveis de ambiente para a maioria das configurações (portas, host do DB, feature flags). Use arquivo de configuração apenas quando valores forem longos ou estruturados, e mantenha-o específico por ambiente. Se usar um serviço de configuração, trate-o como uma dependência: permissões travadas, logs de auditoria e plano de fallback claro.\n\nSegredos são a linha que você não cruza. Não vão no repo, na imagem ou nos logs do CI. Evite imprimir connection strings no startup. Guarde segredos no cofre do CI e injete-os no deploy.\n\nPara tornar artefatos rastreáveis, embuta identidade em cada build: tagueie artefatos com versão + commit hash, inclua metadados do build (versão, commit, hora do build) em um endpoint de info e registre a tag do artefato no log de deploy. Facilite responder “o que está rodando” com um comando ou dashboard.\n\nSe você gera backends Go (por exemplo com AppMaster), essa disciplina importa ainda mais: regeneração é segura quando suas regras de nomeação de artefatos e configuração tornam cada release fácil de reproduzir.\n\n## Deploy para Kubernetes ou VMs sem surpresas\n\nA maioria das falhas de deploy não é “código ruim”. São ambientes desencontrados: configuração diferente, segredos faltando ou um serviço que inicia mas não está pronto. O objetivo é simples: deployar o mesmo artefato em todo lugar e mudar apenas a configuração.\n\n### Kubernetes: trate deploys como rollouts controlados\n\nNo Kubernetes, mire em rollout controlado. Use rolling updates para substituir pods gradualmente e adicione readiness e liveness checks para que a plataforma saiba quando enviar tráfego e quando reiniciar um container travado. Requests e limits importam também, porque um serviço Go que funciona num runner grande pode ser OOM-killed num nó pequeno.\n\nMantenha config e segredos fora da imagem. Construa uma imagem por commit e injete configurações específicas do ambiente no deploy (ConfigMaps, Secrets ou seu secret manager). Assim, staging e produção rodam os mesmos bits.\n\n### VMs: systemd dá o que você precisa na maioria dos casos\n\nSe você faz deploy em máquinas virtuais, o systemd pode ser seu “mini-orquestrador”. Crie um unit file com diretório de trabalho claro, arquivo de ambiente e política de restart. Torne logs previsíveis enviando stdout/stderr para seu coletor de logs ou journald, para que incidentes não virem caçadas por SSH.\n\nVocê ainda pode fazer rollouts seguros sem cluster. Um setup simples blue/green funciona: mantenha dois diretórios (ou duas VMs), troque o load balancer e mantenha a versão anterior pronta para rollback rápido. Canary é similar: envie uma pequena fatia de tráfego para a nova versão antes de confirmar.\n\nAntes de marcar um deploy como “feito”, rode o mesmo smoke check pós-deploy em todo lugar:\n\n- Confirme que o endpoint de health retorna OK e que dependências são alcançáveis\n- Execute uma pequena ação real (por exemplo, criar e ler um registro de teste)\n- Verifique que a versão/build ID do serviço bate com o commit\n- Se o cheque falhar, reverta e alerte\n\nSe você regenera backends (por exemplo, um backend Go do AppMaster), essa abordagem se mantém estável: construa uma vez, deploy o artefato e deixe a configuração de ambiente guiar diferenças, não scripts ad-hoc.\n\n## Erros comuns que tornam pipelines não confiáveis\n\nA maioria dos releases quebrados não vem de “código ruim”. Acontecem quando o pipeline se comporta de forma diferente a cada execução. Se você quer CI/CD para backends Go calmo e previsível, cuidado com esses padrões.\n\n### Padrões de erro que causam surpresas\n\nRodar migrações automaticamente em cada deploy sem guardrails é clássico. Uma migração que tranca uma tabela pode derrubar um serviço movimentado. Coloque migrações atrás de uma etapa explícita, exija aprovação para produção e assegure que dá para rerodar com segurança.\n\nUsar tags latest ou imagens base sem pinagem é outra forma fácil de criar falhas misteriosas. Prenda imagens Docker e versões do Go para que seu ambiente de build não drifte.\n\nCompartilhar um banco entre ambientes “temporariamente” tende a virar permanente, e é assim que dados de teste vazam para staging e scripts de staging atingem produção. Separe bancos (e credenciais) por ambiente, mesmo que o esquema seja o mesmo.\n\nCheques de health e readiness faltando permitem que um deploy “suceda” enquanto o serviço está quebrado, e o tráfego é roteado cedo demais. Adicione cheques que reflitam comportamento real: o app inicia, conecta ao banco e serve uma requisição.\n\nPor fim, propriedade obscura de segredos, configuração e acesso transforma releases em adivinhação. Alguém precisa ser dono de como segredos são criados, rotacionados e injetados.\n\nUm fracasso realístico: um time faz merge, o pipeline deploya e uma migração automática roda primeiro. Ela completa em staging (poucos dados), mas dá timeout em produção (dados grandes). Com imagens pinadas, separação de ambientes e um passo de migração gateado, o deploy teria parado com segurança.\n\nSe você gera backends Go (por exemplo, com AppMaster), essas regras importam ainda mais porque a regeneração pode tocar muitos arquivos ao mesmo tempo. Entradas previsíveis e gates explícitos evitam que mudanças grandes virem releases arriscados.\n\n## Checklist rápido para um CI/CD previsível\n\nUse isto como checagem intuitiva para CI/CD de backends Go. Se você consegue responder cada ponto com um “sim” claro, os releases ficam mais fáceis.\n\n- Trave o ambiente, não só o código. Prenda a versão do Go e a imagem do container de build, e use a mesma configuração local e no CI.\n- Faça o pipeline rodar com 3 comandos simples. Um comando builda, outro roda testes, outro produz o artefato deployável.\n- Trate migrações como código de produção. Exija logs para cada execução de migração e documente o que “rollback” significa para sua app.\n- Produza artefatos imutáveis e rastreáveis. Construa uma vez, tagueie com o commit SHA e promova entre ambientes sem rebuild.\n- Faça deploys com cheques que falhem rápido. Adicione readiness/liveness e um pequeno smoke test que rode em cada deploy.\n\nLimite e audite acesso a produção. O CI deve deployar usando uma service account dedicada, segredos devem ser gerenciados centralmente e qualquer ação manual em produção deve deixar rastro claro (quem, o quê, quando).\n\n## Exemplo realista e próximos passos que você pode começar esta semana\n\nUm pequeno time de ops de quatro pessoas envia releases uma vez por semana. Eles frequentemente regeneram o backend Go porque o time de produto refina fluxos. O objetivo é simples: menos consertos à noite e releases que não pegam ninguém de surpresa.\n\nUma mudança típica de sexta: adicionam um novo campo em customers (mudança de esquema) e atualizam a API que grava esse campo (mudança de código). O pipeline trata isso como um único release. Ele builda um artefato, roda testes contra esse exato artefato e só então aplica migrações e faz o deploy. Assim, o banco nunca fica à frente do código que espera o esquema, e o código não é deployado sem seu esquema correspondente.\n\nQuando há mudança de esquema, o pipeline adiciona um gate de segurança. Verifica que a migração é aditiva (como adicionar coluna nullable) e sinaliza ações arriscadas (dropar coluna ou reescrever tabela grande). Se a migração for arriscada, o release para antes da produção. O time reescreve a migração para ficar mais segura ou agenda uma janela planejada.\n\nSe os testes falham, nada segue adiante. O mesmo vale se migrações falham em ambiente pré-produção. O pipeline não deve tentar “empurrar isso só dessa vez”.\n\nUm conjunto simples de próximos passos que funciona para a maioria dos times:\n\n- Comece com um ambiente (um deploy dev que você pode resetar com segurança).\n- Faça o pipeline sempre produzir um artefato versionado.\n- Rode migrações automaticamente em dev, mas exija aprovação em produção.\n- Adicione staging só depois que dev estiver estável por algumas semanas.\n- Adicione um gate de produção que exija testes verdes e um deploy bem-sucedido em staging.\n\nSe você gera backends com AppMaster, mantenha a regeneração nas mesmas etapas do pipeline: regenere, build, teste, migre em um ambiente seguro e então deploy. Trate o código gerado como qualquer outro source. Todo release deve ser reproduzível a partir de uma versão tagueada, com os mesmos passos sempre.