Skip to content

Implementation Patterns

Five patterns for making operations idempotent. Each has tradeoffs; choose based on your constraints.

Pattern Overview

Pattern Best For Tradeoff
Check-Before-Act Creating resources Race conditions possible
Upsert APIs with atomic operations Not universally available
Force Overwrite Content that can be safely replaced Destructive if misused
Unique Identifiers Natural deduplication ID logic can be complex
Tombstone Markers Multi-step operations Markers need cleanup

Quick Reference

Check-Before-Act

The most common pattern. Check if the target state exists before attempting to create it.

if git ls-remote --heads origin "$BRANCH" | grep -q "$BRANCH"; then
  git checkout -B "$BRANCH" "origin/$BRANCH"
else
  git checkout -b "$BRANCH"
fi

Create-or-Update (Upsert)

Use APIs or commands that handle both cases atomically.

gh release create v1.0.0 --notes "Release" || gh release edit v1.0.0 --notes "Release"

Force Overwrite

Don't check, just overwrite. Safe when overwriting with identical content is acceptable.

git push --force-with-lease origin "$BRANCH"

Unique Identifiers

Generate deterministic IDs so duplicate operations target the same resource.

BRANCH="update-$(sha256sum file.txt | cut -c1-8)"

Tombstone/Marker Files

Leave markers indicating operations completed.

MARKER=".completed-$RUN_ID"
[ -f "$MARKER" ] && exit 0
# Do work...
touch "$MARKER"

Choosing a Pattern

flowchart TD
    A[Need idempotency] --> B{API has upsert?}
    B -->|Yes| C[Use Upsert]
    B -->|No| D{Safe to overwrite?}
    D -->|Yes| E[Use Force Overwrite]
    D -->|No| F{Natural unique key?}
    F -->|Yes| G[Use Unique Identifiers]
    F -->|No| H{Multi-step operation?}
    H -->|Yes| I[Use Tombstone Markers]
    H -->|No| J[Use Check-Before-Act]

    %% Ghostty Hardcore Theme
    style A fill:#5e7175,color:#f8f8f3
    style B fill:#fd971e,color:#1b1d1e
    style C fill:#a7e22e,color:#1b1d1e
    style D fill:#fd971e,color:#1b1d1e
    style E fill:#e6db74,color:#1b1d1e
    style F fill:#fd971e,color:#1b1d1e
    style G fill:#65d9ef,color:#1b1d1e
    style H fill:#fd971e,color:#1b1d1e
    style I fill:#9e6ffe,color:#1b1d1e
    style J fill:#65d9ef,color:#1b1d1e
Scenario Recommended Pattern
Creating resources (PRs, branches, files) Check-Before-Act
Updating existing resources Upsert or Force Overwrite
Operations with natural keys Unique Identifiers
Complex multi-step operations Tombstone Markers
API supports atomic operations Upsert

Combine Patterns

Real-world automation often combines multiple patterns. A workflow might use Check-Before-Act for PR creation, Force Overwrite for branch updates, and Unique Identifiers for naming.

Comments