# CIにおけるretryと冪等性: 副作用なく安全にretryする

> 失敗したstepのretryが役立つのは、そのstepが冪等 - 2回実行しても安全 - な場合だけです。CIにおける冪等性の意味と、どのstepがretryして安全かを学びます。

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

不安定なstepのretryが安全なのは、2回実行しても害がない場合だけです。その性質が冪等性であり - どのstepがそれを持つかを知ることが、クリーンな回復と重複したdeployとの分かれ目になります。

retryは一時的なCI障害に対する最もシンプルな対処法ですが、stepに副作用があった場合、盲目的なretryは実害を及ぼしかねません。冪等性はretryを安全にする性質です。

## 冪等性の意味

ある操作が冪等であるとは、1回実行しても何度実行しても同じ最終状態になることです。`npm ci` は冪等です - 1回でも3回でも同じ `node_modules` に収束します。支払いを送信したり行をappendしたりするstepは*冪等ではありません* - 実行のたびに世界が再び変化します。

## retryして安全 vs 安全でない

- 安全: 依存関係のinstall、checkout、読み取り専用のテスト、build。
- 安全: 冪等になるよう設計されたdeploy(宣言的なapply、upsert)。
- 安全でない: レコードのappend、通知の送信、カウンタのインクリメント。
- 安全でない: 実行のたびに新しい外部リソースを作成するあらゆるstep。

## stepをretry可能にする

副作用のあるstepは冪等になるよう設計しましょう: 安定したidをキーにしたupsert、命令的なcreateではなく宣言的なapply、そしてAPI呼び出しには冪等性キーを使い、retryされたリクエストがサーバー側で重複排除されるようにします。そうすれば、retryは二重に作用するのではなく再収束します。

## ノイズをretryし、シグナルはretryしない

自動retryは、一時的で冪等なstep(ネットワークfetch、依存関係のinstall、既知だが不安定なテスト)に、小さく制限された回数で限定しましょう。非冪等なstepを含むpipeline全体を一律にretryしてはならず、決定論的なロジックの失敗を決してretryしてはいけません - それは本当のバグを隠すだけです。

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