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

> Repetir um step que falhou só ajuda se o step for idempotente - seguro para rodar duas vezes. Aprenda o que significa idempotência no CI e quais steps são seguros para repetir.

Source: https://latchkey.dev/pt/learn/ci-cd-concepts/retries-and-idempotency-ci  
Updated: 2026-06-25

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.

## FAQ

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt