Retries e Idempotência no CI: Repita com Segurança Sem Efeitos Colaterais

Por Daniel Zoghalchali·Latchkey

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.

Perguntas frequentes

What is Retries and idempotency in CI: retry safely without side effects?

Retries are the simplest cure for transient CI failures, but a blind retry can do real damage if the step had side effects. Idempotency is the property that makes retries safe.

What idempotency means?

An operation is idempotent if running it once or many times produces the same end state. npm ci is idempotent - it converges to the same node_modules whether run once or three times. A step that posts a payment or appends a row is *not* - each run changes the world again.

Making steps retry-safe?

Design side-effecting steps to be idempotent: use upserts keyed on a stable id, declarative apply instead of imperative create, and idempotency keys for API calls so a retried request is deduplicated server-side. Then a retry re-converges instead of double-acting.

Retry the noise, not the signal?

Limit automatic retries to transient, idempotent steps (network fetches, dependency installs, flaky-but-known tests) with a small bounded count. Never blanket-retry a whole pipeline that contains non-idempotent steps, and never retry a deterministic logic failure - that just hides a real bug.

Guias relacionados

Fail-Fast vs Continue-on-Error: Controlling How CI StopsFail-fast stops the pipeline at the first failure; continue-on-error lets it press on. How to Quarantine Flaky Tests Without Hiding Real BugsQuarantining moves known-flaky tests out of the blocking path so they stop failing builds, while keeping them What Is a Lockfile and Why Should You Commit It?A lockfile pins the exact versions of every dependency so builds are reproducible.