Retries e Idempotência no CI: Repita com Segurança Sem Efeitos Colaterais
Repetir um step instável só é seguro se rodá-lo duas vezes não causar dano. Essa propriedade é a idempotência - e saber quais steps a possuem é a diferença entre uma recuperação limpa e um deploy duplicado.
Retries são a cura mais simples para falhas transitórias de CI, mas uma repetição cega pode causar dano real se o step tiver efeitos colaterais. Idempotência é a propriedade que torna os retries seguros.
O que significa idempotência
Uma operação é idempotente se rodá-la uma vez ou muitas vezes produz o mesmo estado final. npm ci é idempotente - ele converge para o mesmo node_modules seja rodado uma ou três vezes. Um step que registra um pagamento ou faz append de uma linha *não* é - cada execução muda o mundo de novo.
Seguro vs inseguro para repetir
- Seguro: installs de dependências, checkouts, testes somente leitura, builds.
- Seguro: deploys projetados para serem idempotentes (apply declarativo, upsert).
- Inseguro: fazer append de registros, enviar notificações, incrementar contadores.
- Inseguro: qualquer step que cria um novo recurso externo a cada execução.
Tornando steps seguros para retry
Projete steps com efeitos colaterais para serem idempotentes: use upserts com chave em um id estável, apply declarativo em vez de create imperativo e chaves de idempotência para chamadas de API, de modo que uma requisição repetida seja deduplicada no lado do servidor. Assim um retry reconverge em vez de agir em dobro.
Repita o ruído, não o sinal
Limite os retries automáticos a steps transitórios e idempotentes (fetches de rede, installs de dependências, testes instáveis porém conhecidos) com uma contagem pequena e limitada. Nunca repita indiscriminadamente um pipeline inteiro que contém steps não idempotentes, e nunca repita uma falha de lógica determinística - isso apenas esconde um bug real.
Principais conclusões
- Idempotente = rodar várias vezes produz o mesmo estado final.
- Installs, checkouts e deploys declarativos são seguros para repetir; appends e envios não são.
- Use upserts e chaves de idempotência para tornar steps com efeitos colaterais seguros para retry.
- Limite os retries a steps transitórios e idempotentes - nunca mascare uma falha real.