Ci cd

CI/CD e Automação

Visão geral

Automatize os portões de qualidade para que nenhuma mudança chegue à produção sem passar por testes, lint, checagem de tipos e build. CI/CD é o mecanismo de imposição de todas as outras skills — pega o que humanos e agentes deixam passar, e faz isso de forma consistente em cada mudança.

Shift Left: pegue problemas o mais cedo possível no pipeline. Um bug pego no lint custa minutos; o mesmo bug em produção custa horas. Mova checagens para montante — análise estática antes dos testes, testes antes do staging, staging antes da produção.

Mais rápido é mais seguro: lotes menores e releases mais frequentes reduzem o risco, não o aumentam. Um deploy com 3 mudanças é mais fácil de depurar que um com 30.

Quando usar

• Configurando o pipeline de CI de um projeto novo
• Adicionando ou modificando checagens automatizadas
• Configurando pipelines de deploy
• Quando uma mudança deve disparar verificação automatizada
• Depurando falhas de CI

Quando NÃO usar: não gaste tempo otimizando pipeline antes de existir um pipeline — o mínimo (lint + testes + build em todo PR) vem primeiro.

O fluxo

1. Monte o pipeline de portões de qualidade

Toda mudança passa por estes portões antes do merge:

Pull Request aberto
    │
    ▼
LINT            eslint, prettier
TIPOS           tsc --noEmit
TESTES UNIT.    jest/vitest
BUILD           npm run build
INTEGRAÇÃO      testes de API/banco
E2E (opcional)  Playwright/Cypress
AUDITORIA       npm audit
BUNDLE SIZE     checagem de bundlesize
    │
    ▼
Pronto para revisão

Nenhum portão pode ser pulado. Se o lint falha, conserte o lint — não desabilite a regra. Se um teste falha, conserte o código — não pule o teste.

Os arquivos YAML completos do GitHub Actions (pipeline básico, testes de integração com Postgres, E2E com Playwright, preview deployments, workflow de rollback, Dependabot e jobs paralelos com cache) estão em referencias/pipelines-ci.md — leia somente quando for escrever a configuração.

2. Realimente as falhas de CI para os agentes

O poder do CI com agentes de IA é o ciclo de feedback. Quando o CI falha, copie a saída da falha e alimente o agente: "O pipeline falhou com este erro: [erro específico]. Corrija e verifique localmente antes de dar push de novo."

Falha de lint   → Agente roda `npm run lint --fix` e commita
Erro de tipo    → Agente lê a localização do erro e corrige o tipo
Falha de teste  → Agente segue a skill `depurar`
Erro de build   → Agente checa configuração e dependências

3. Defina a estratégia de deploy

Preview deployments: todo PR ganha um deploy de preview para teste manual.

Feature flags desacoplam deploy de release:

• Publique código sem ativá-lo. Merge na main cedo, ative quando estiver pronto.
• Rollback sem redeploy. Desative a flag em vez de reverter código.
• Canary de features. Ative para 1% dos usuários, depois 10%, depois 100%.
• Testes A/B. Compare comportamento com e sem a feature.

Ciclo de vida da flag: criar → ativar para teste → canary → rollout completo → remover a flag e o código morto. Flags eternas viram dívida técnica — defina data de limpeza ao criar.

Rollout em estágios:

PR entra na main
    ▼
Deploy em staging (automático)
    │ Verificação manual
    ▼
Deploy em produção (gatilho manual ou automático após staging)
    ▼
Monitorar erros (janela de 15 minutos)
    ├── Erros detectados → Rollback
    └── Limpo → Concluído

Todo deploy precisa ser reversível. Tenha um mecanismo de rollback pronto antes de precisar dele (workflow de exemplo em referencias/pipelines-ci.md).

4. Gerencie ambientes e segredos

.env.example        → commitado (template para desenvolvedores)
.env                → NÃO commitado (desenvolvimento local)
.env.test           → commitado (ambiente de teste, sem segredos reais)
Segredos de CI      → GitHub Secrets / vault
Segredos de prod    → plataforma de deploy / vault

O CI nunca deve ter segredos de produção. Use segredos separados para os testes do CI — mesmo para bancos de teste, use o gerenciador de segredos, nunca valores no YAML.

5. Proteja o processo

• Revisões obrigatórias: pelo menos 1 aprovação antes do merge
• Status checks obrigatórios: CI precisa passar antes do merge
• Proteção de branch: sem force-push na main
• Auto-merge: se tudo passou e foi aprovado, merge automático
• Dependabot/Renovate: atualizações semanais de dependências via PR
• Papel de Build Cop: alguém responsável por manter o CI verde. Quando o build quebra, o trabalho do Build Cop é corrigir ou reverter — isso evita que builds quebrados se acumulem enquanto todos assumem que outro vai resolver.

6. Otimize quando passar de 10 minutos

Em ordem de impacto:

Pipeline lento?
├── Cacheie dependências (actions/cache ou opção cache do setup-node)
├── Rode jobs em paralelo (lint, tipos, testes e build separados)
├── Rode só o que mudou (filtros de path; pule e2e em PRs só de docs)
├── Use matrix builds (particione a suíte de testes entre runners)
├── Otimize a suíte (tire testes lentos do caminho crítico; rode-os agendados)
└── Use runners maiores (hospedados maiores ou self-hosted para builds pesados)

Racionalizações comuns

Racionalização	Realidade
"O CI é lento demais"	Otimize o pipeline, não o pule. Um pipeline de 5 minutos evita horas de depuração.
"Mudança trivial, pula o CI"	Mudanças triviais quebram builds. E o CI é rápido para mudanças triviais.
"O teste é instável, roda de novo"	Testes instáveis mascaram bugs reais e desperdiçam o tempo de todos. Corrija a instabilidade.
"Adicionamos CI depois"	Projetos sem CI acumulam estados quebrados. Configure no primeiro dia.
"Teste manual basta"	Teste manual não escala e não é repetível. Automatize o que puder.

Sinais de alerta

• Projeto sem pipeline de CI
• Falhas de CI ignoradas ou silenciadas
• Testes desabilitados no CI para o pipeline passar
• Deploys em produção sem verificação em staging
• Sem mecanismo de rollback
• Segredos no código ou nos arquivos de configuração do CI (fora do gerenciador de segredos)
• Pipeline demorado sem esforço de otimização

Portão de aprovação

Apresente: o desenho do pipeline (portões e ordem), a estratégia de deploy (staging, canary, rollback), onde cada segredo ficará armazenado e o custo estimado de tempo do pipeline. O humano aprova: a configuração de deploy em produção, as regras de proteção de branch e qualquer acesso a segredos ou credenciais. Só avance após aprovação explícita.

Verificação

Após configurar ou modificar o CI:

• Todos os portões de qualidade presentes (lint, tipos, testes, build, auditoria)
• Pipeline roda em todo PR e push na main
• Falhas bloqueiam o merge (proteção de branch configurada)
• Resultados do CI realimentam o ciclo de desenvolvimento
• Segredos no gerenciador de segredos, não no código
• Deploy tem mecanismo de rollback
• Pipeline roda em menos de 10 minutos para a suíte de testes