A CI job that pushes an automated run's outcomes into a case repository times out and is retried, and the cycle ends up holding the same outcomes twice. What mechanism prevents that, and how do you choose its key?

## Why a retry duplicates in the first place A failed push has three possible truths behind it, and the client can only distinguish two of them: 1. **The request never arrived.** Nothing was written. Retrying is correct and necessary. 2. **The request arrived and was rejected.** Nothing was written, and the response said so. Retrying is pointless until the cause is fixed. 3. **The request arrived, was written, and the response was lost.** The write happened. Retrying writes it again. A connection timeout, a dropped socket, a proxy cutting a long bulk call, a runner evicted between send and receive — all of these look identical from the client and all of them are case 1 or case 3. Because a CI job that fails is retried, either by an operator clicking the button or by an automatic policy, case 3 is not a rare edge; it is a routine event on any pipeline that pushes results. The visible symptom is a cycle holding two rows for the same item in the same round, which corrupts every count computed over that cycle. ## The mechanism An **idempotency key** is a caller-supplied value that identifies *the write*, not the attempt. The receiving side keeps a record of the keys it has already applied and, on seeing one again, returns the original result instead of performing the work a second time. That converts an at-least-once delivery channel into effectively-once recording, which is the strongest guarantee available when the network can lose responses. The key sits alongside the payload's three handles — the cycle, the item, the outcome — and answers a fourth question: *is this the same write I already accepted?* ## Choosing the key The format hardly matters; the derivation is everything. A workable key satisfies both halves of one rule: - **Stable across retries of the same work.** Re-running the failed job must produce the same key, or the mechanism does nothing. - **Distinct for genuinely different work.** A deliberate re-execution of the suite must produce a different key, or the second run's outcomes are silently swallowed as duplicates — a much worse failure, because it looks like everything worked. | Key derived from | Stable on retry? | Distinct per real run? | Verdict | |---|---|---|---| | A random value per call | No | Yes | Useless — every attempt is a new write | | A timestamp taken at call time | No | Yes | Same defect, harder to spot | | Pipeline run identifier plus shard index | Yes | Yes | The workable choice | | Pipeline run identifier plus attempt number | No | Yes | Retries look like new writes | | The commit SHA alone | Yes | No | Two deliberate runs of one commit collapse into one | | A hash of the payload contents | Yes | Mostly | Works until a message or duration differs by a byte | The practical answer in almost every pipeline is a stable run identity the platform already provides, combined with whatever partitions the work (shard index, job name, chunk sequence number when a bulk push is chunked). Each chunk needs its own key, or a retry of chunk five will be mistaken for chunk one. ## When the repository does not offer the mechanism Not every product exposes idempotent result recording, so you need fallbacks that achieve the same outcome with the guarantees you do have: - **Reconcile instead of append.** Read what the cycle already holds for the items in this batch, and push only the difference. This costs an extra read and races if two writers push at once, but it is simple and needs nothing from the vendor. - **Make the write itself replace rather than add.** Where a repository records at most one outcome per item per cycle, a repeat is naturally harmless; verify this rather than assuming it, since many products deliberately append every submission as history. - **Give each pipeline attempt its own container.** If a retry writes into a fresh cycle, a duplicate is impossible by construction. The cost is a proliferation of near-identical cycles and a reporting layer that must know which one is authoritative. - **Put the dedupe in your own ingest step.** A small wrapper that owns the key table gives you the guarantee regardless of what the product supports, at the cost of a component to run. ## The habit to keep Treat every push as retryable and every timeout as *possibly written*. Never respond to an ambiguous failure by skipping the retry to be safe — that trades duplicate rows for missing ones, which is the same corruption pointing the other way. Retry with the same key, and let the key decide. Where a suite is retried in whole or in part, the placement of that retry and what a pass on a second attempt conceals are separate concerns with their own answers; what matters here is only that repeated delivery of the same outcomes must record once.