Status: Approved · v3 · SPEC-DELIVERY-CI-001

depends_on: SPEC-ARCH-QUALITY-001, SPEC-ARCH-ENV-001, SPEC-ARCH-CONTAINER-001, SPEC-ARCH-SECURITY-001

used_by: IS-ZERO-00.4, IS-MVP-18.1, IS-MVP-18.2

CI/CD seletivo e automação

O monorepo economiza build e deploy por impacto, mas qualidade é um gate global: nenhum alvo publica se qualquer check obrigatório falhar.

Objetivos

• detectar alvos afetados pelo diff e pelo grafo de dependências;
• validar somente o necessário sem deixar dependentes sem cobertura;
• promover develop → homol → master exclusivamente por PR;
• publicar web/API apenas depois de todos os gates aplicáveis ficarem verdes;
• operar inicialmente dentro dos free tiers, falhando de forma segura quando a cota acabar.

Eventos

Evento	Validação	Deploy
PR para develop, homol ou master	classificação + gates globais + gates dos afetados	preview efêmero opcional do web; nunca produção
merge/push protegido em develop	gates no SHA mergeado	targets afetados em desenvolvimento
merge/push protegido em homol	gates no SHA mergeado	targets afetados em homologação
merge/push protegido em master	gates no SHA mergeado + production guard	targets afetados em produção
execução manual	mesmos gates, ambiente e SHA explícitos	permitido para recuperação; sem pular qualidade

Classificador de impacto

O primeiro job produz uma matriz explícita com web, mobile, api, contracts, shared, ui, mocks, infra e docs. A decisão considera diff base...head, dependências workspace:* e o grafo Turborepo.

Matriz mínima

Mudança	Gates/builds afetados	Deploy após merge
somente apps/web/**	web + dependências necessárias	somente web
somente apps/mobile/**	mobile + dependências necessárias	nenhum deploy Vercel/API; store release fica pós-MVP
somente services/api/**	API + contracts consumidos	somente API
packages/ui/**	UI, web e mobile	web; mobile valida, mas não publica em store
packages/shared/**	consumidores declarados, normalmente web/mobile	web se afetado; mobile só valida
packages/mocks/**	clientes que usam mocks e contract parity	web/mobile conforme impacto; nunca API só por fixture
packages/contracts/**	web + mobile + API + mocks + parity	web e API; mobile valida; todos os consumidores precisam ficar verdes
lockfile, workspace, Turbo, TS base ou infra global	todos os alvos	somente targets cujo artefato mudou, após full gates
somente docs/specs	repository validation, links e policy checks	nenhum deploy, salvo mudança de configuração executável detectada

O classificador é conservador: dúvida ou arquivo global desconhecido resulta em todos os alvos afetados. Um job ignorado por “não afetado” deve aparecer como sucesso neutro, para não bloquear checks requeridos da branch.

Gate global antes do CD

O pipeline separa classify, quality e deploy. Nenhum job de deploy depende diretamente de um job parcial; todos dependem de um agregador quality-gate que falha se qualquer gate obrigatório falhar ou for cancelado.

Ordem mínima:

1. checkout com histórico suficiente para calcular base/head;
2. pnpm frozen install e cache;
3. validação de repository/docs/env/secrets;
4. typecheck, lint/boundaries, testes e builds dos alvos afetados;
5. contract parity sempre que contracts, mocks, API ou clientes integrados mudarem;
6. Docker build/scan/smoke quando alvo containerizado ou infra mudar;
7. agregador quality-gate;
8. deploy seletivo por ambiente;
9. smoke pós-deploy e registro de SHA/URL.

Retry automático não converte teste flaky em verde. Reexecução manual preserva SHA e evidências.

Branch protection

develop, homol e master exigem:

• pull request;
• branch atualizada ou merge-base validada;
• quality-gate obrigatório e único;
• conversas resolvidas;
• sem force push/deleção;
• pelo menos uma aprovação quando houver outro revisor disponível; para operação solo, o owner pode realizar o merge após checks, sem push direto.

Configuração GitHub é manual e documentada. Se o plano gratuito do repositório privado não oferecer proteção obrigatória, a limitação é registrada e o owner aplica o fluxo de PR manualmente; não se cria falsa proteção apenas no YAML.

Deploy web seletivo

• Vercel Git Integration ou CLI pode executar o deploy, mas deve estar subordinada ao quality-gate.
• Para impedir deploy antecipado pela integração Git, usar configuração de deployment/ignored build compatível ou CD explícito por CLI após qualidade.
• master é Production Branch; develop e homol usam domínio e env de Preview específicos.
• Mudança exclusiva de API não dispara build/deploy web.
• Mudança em contracts/UI/shared dispara web conforme a matriz.
• Cada deployment registra commit URL, branch e environment.

Deploy API seletivo

• Publicar imagem Docker identificada por SHA e promover exatamente essa imagem.
• develop, homol e master usam serviços/vars/CORS separados.
• Mudança exclusiva de web/mobile não publica API.
• Mudança em contracts ou config global publica API após todos os consumers passarem.
• Smoke GET /api/v1/health e contract parity do ambiente bloqueiam promoção.

Mobile

No escopo atual, CI executa gates e export quando afetado. O pipeline já deve expor um job reutilizável de build mobile, mas não armazena credenciais nem submete builds. IS-POST-13.1 evoluirá o mesmo classificador para gerar releases Google Play/Apple App Store apenas quando mobile ou dependências forem afetados.

Custo zero e cotas

• GitHub Actions usa runners Linux padrão, cache limitado e cancelamento de execução superseded; repositório privado deve permanecer dentro da franquia mensal.
• Vercel Hobby usa previews/production e branch-specific env/domains, sem depender de Custom Environments pagos.
• Render Free pode hospedar API de teste, com cold start e 750 horas compartilhadas; não é target produtivo com SLA.
• Nenhuma cota excedida autoriza fallback inseguro, deploy sem teste ou reutilização de secrets entre ambientes.
• O pipeline deve reduzir builds redundantes, retenção de artifacts e previews obsoletos.

Segurança

• Tokens Vercel/provider e credentials de registry ficam em GitHub Environments/Secrets.
• PR de fork ou código não confiável nunca recebe secrets/deploy permission.
• Environments homol e master podem exigir aprovação manual antes do job com secrets.
• Actions são fixadas por major ou SHA conforme política; permissões do GITHUB_TOKEN começam read-only e ampliam por job.
• Logs e artifacts não contêm .env, tokens, certificates ou payload privado.

Rollback e observabilidade

• Web reatribui domínio ao deployment saudável anterior ou faz revert por PR.
• API promove imagem SHA anterior; nunca reconstrói código diferente com a mesma tag.
• Falha de smoke marca deployment como falho e impede a próxima promoção.
• Handoff registra ambiente, SHA, alvo, URL, duração, gates e rollback disponível.

Critérios de aceite

• PR é o único caminho normal para develop, homol e master.
• Um único quality-gate agrega todos os checks e é pré-condição de qualquer deploy.
• Mudança somente de API não publica web/mobile; mudança somente de web não publica API/mobile.
• Mudança em contracts executa gates de web, mobile, API e mocks e publica todos os targets deployáveis afetados.
• Lockfile/config global cai no modo conservador full validation.
• Web mapeia branches aos três ambientes; API usa serviços separados por ambiente.
• Mobile valida seletivamente e não publica nas lojas neste incremento.
• Docs-only não consome deploy, mas continua validando repositório.
• Secrets, forks, manual dispatch, rollback e cotas possuem testes/policy checks.
• Pipeline e runbooks funcionam sem recurso pago obrigatório.

Histórico

• 3.0 — CI/CD seletivo por grafo, quality gate global, branches protegidas, Vercel/containers e custo zero.
• 2.0 — pipeline mínimo de PR, preview e proteção de contracts.