Patterns¶

Reusable design patterns for resilient automation.

Solve Once, Apply Everywhere

Good patterns solve problems once. Great patterns solve problems across technologies, languages, and platforms.

Overview¶

This section documents architecture patterns, efficiency patterns, error handling patterns, and technology-specific patterns that apply from GitHub Actions to Argo Workflows to Kubernetes operators.

These patterns are battle-tested in production environments, proven to reduce operational toil, and designed to prevent the failure modes that break automation at scale.

Pattern Categories¶

Architecture Patterns¶

System design patterns for building maintainable, scalable automation.

Separation of Concerns¶

Build scalable automation through distinct, composable modules. Reduces coupling and improves testability.

Split functionality into distinct, composable modules
Each component does one thing well
Reduces coupling, improves testability
Examples: Script-based workflow stages, modular Helm charts

Hub-and-Spoke¶

Distribute configuration from a central hub to many spokes. Enforce consistency and enable organization-wide policy updates.

Central hub distributes configuration to many spokes
Enforces consistency across repositories or clusters
Enables organization-wide policy updates
Examples: GitHub Apps distributing files, ArgoCD ApplicationSets

Strangler Fig¶

Incrementally replace legacy systems. Route traffic to new implementations, reducing risk with gradual cutovers.

Incrementally replace legacy systems without Big Bang rewrites
Route traffic to new implementation while old runs
Gradual cutover reduces risk
Examples: Feature flags, API gateway routing, Kubernetes Ingress

Three-Stage Design¶

Implement workflows using a Discovery → Execution → Summary pattern. Find, process, and aggregate results efficiently.

Discovery → Execution → Summary pattern for workflows
Discovery: Find what needs processing
Execution: Process items in parallel
Summary: Aggregate results and report
Examples: Multi-repo file distribution, vulnerability remediation

Matrix Distribution¶

Execute operations in parallel across multiple dimensions. Leverage conditional execution and template rendering for diverse scenarios.

Parallel execution across multiple dimensions
Conditional execution based on matrix values
Template rendering for each matrix combination
Examples: Multi-environment deployments, multi-arch builds

Environment Progression¶

Manage sequential deployments across environments (dev → staging → prod). Automate promotion on success and rollback on failure.

Sequential deployment through environments (dev → staging → prod)
Automated promotion on success
Rollback on failure
Examples: GitOps progressive delivery, Argo Rollouts

Efficiency Patterns¶

Patterns that reduce runtime, cost, and toil.

Idempotency¶

Ensure operations are safe to run multiple times without side effects. Critical for reliable automation and retry mechanisms.

Safe to run multiple times without side effects
Enables retries without duplication
Critical for automation reliability
Techniques: Check-before-act, upsert, tombstone markers, unique identifiers

Work Avoidance¶

Optimize automation by skipping unnecessary work when outcomes are unchanged. Use content hashes and existence checks.

Skip unnecessary work when outcomes are unchanged
Compare content hashes, not timestamps
Use existence checks before creation
Examples: Content-based PR creation, cache-based skips, path filtering

Error Handling Patterns¶

Patterns that make automation resilient to failure.

Fail Fast¶

Detect errors early and exit immediately on unrecoverable issues. Provides clear error messages and prevents expensive operations.

Detect errors early, before expensive operations
Exit immediately on unrecoverable errors
Provide clear error messages
Examples: Prerequisite checks, input validation

Prerequisite Checks¶

Verify all requirements before starting work. Ensure optimal order of checks to prevent partial execution states.

Verify all requirements before starting work
Check in optimal order (cheap first, expensive last)
Avoid partial execution states
Examples: Dependency checks, permission validation

Graceful Degradation¶

Maintain functionality with reduced capabilities when components fail. Use fallback mechanisms to preserve critical operations.

Continue with reduced functionality when components fail
Fallback to alternative implementations
Preserve critical path operations
Examples: Secondary data sources, default values

Technology-Specific Patterns¶

GitHub Actions Patterns¶

Actions Integration: Token generation, permission patterns, error handling
File Distribution: Three-stage design for cross-repo operations
Release Pipelines: Release Please integration, change detection
Work Avoidance: Matrix filtering, content comparison, cache strategies
Versioned Docs: Mike integration, version strategies

Content: 60+ pages of GitHub Actions patterns

Argo Events Patterns¶

Event Routing: Simple filtering, multi-trigger actions, transformation
Conditional Routing: Route events based on payload content
Reliability: Retry strategies, dead letter queues, backpressure handling
Setup and Operations: EventSource, EventBus, Sensor configuration

Content: 12+ pages covering event-driven workflow patterns

Argo Workflows Patterns¶

WorkflowTemplate Patterns: Basic structure, retry strategies, init containers, volumes
Concurrency Control: Mutexes, semaphores, TTL strategies
Workflow Composition: Spawning children, parallel execution, DAG orchestration
Scheduled Workflows: CronWorkflow patterns, concurrency policies, GitHub integration

Content: 20+ pages covering orchestration patterns

Cross-Cutting Concerns¶

Many patterns apply across multiple technologies:

Idempotency Across Technologies¶

GitHub Actions: Content hashing before PR creation
Argo Workflows: Check-before-act in workflow steps
Kubernetes: Declarative desired state (built-in idempotency)
Helm: --atomic flag for all-or-nothing deployments

Three-Stage Design Across Technologies¶

GitHub Actions: Discovery → Distribution → Summary for file distribution
Argo Events: EventSource → Sensor → Workflow trigger
Argo Workflows: DAG with discovery, parallel execution, aggregation
Kubernetes Operators: List resources → Reconcile → Update status

Retry Strategies Across Technologies¶

GitHub Actions: retry action with exponential backoff
Argo Events: Sensor retry configuration
Argo Workflows: WorkflowTemplate retry strategy
Kubernetes: Deployment rollout with health checks

Pattern Selection Guide¶

Quick selection:

Need cross-repo distribution? → Three-Stage Design + Hub-and-Spoke
Need to avoid duplicate work? → Idempotency + Work Avoidance
Replacing legacy system? → Strangler Fig
Need error resilience? → Fail Fast + Prerequisite Checks
Building event-driven system? → Argo Events routing patterns
Orchestrating complex workflows? → Argo Workflows composition patterns

Common Anti-Patterns¶

❌ Non-Idempotent Operations¶

# BAD: Creates duplicate issues on retry
- name: Create issue
  run: gh issue create --title "Alert" --body "Problem detected"

# GOOD: Check before creating
- name: Create issue if not exists
  run: |
    existing=$(gh issue list --search "Alert" --state all --json number -q '.[0].number')
    if [ -z "$existing" ]; then
      gh issue create --title "Alert" --body "Problem detected"
    fi

❌ Unnecessary Work¶

# BAD: Always creates PR even if no changes
- name: Create PR
  run: gh pr create --fill

# GOOD: Check if changes exist first
- name: Create PR if changes exist
  run: |
    if git diff --quiet HEAD origin/main; then
      echo "No changes, skipping PR"
    else
      gh pr create --fill
    fi

❌ Late Error Detection¶

# BAD: Deploy first, check permissions later
- name: Deploy
  run: kubectl apply -f manifests/
- name: Check RBAC
  run: kubectl auth can-i create deployments

# GOOD: Validate before deploying
- name: Prerequisite checks
  run: |
    kubectl auth can-i create deployments || exit 1
    kubectl get namespace production || exit 1
- name: Deploy
  run: kubectl apply -f manifests/

Pattern Layering¶

Patterns work best when layered:

Architecture pattern (what to build)
- Example: Hub-and-Spoke for config distribution
Efficiency pattern (how to build efficiently)
- Add: Idempotency for safe retries
- Add: Work Avoidance to skip unchanged configs
Error handling pattern (how to fail gracefully)
- Add: Fail Fast for invalid configs
- Add: Prerequisite Checks for GitHub API access

Result: Hub-and-spoke config distribution that is idempotent, skips unchanged configs, validates early, and handles errors gracefully.

Getting Started¶

Read the pattern selection guide: Understand when to use each pattern
Start with architecture patterns: Choose the right structure
Add efficiency patterns: Optimize for scale
Layer error handling: Make it resilient
Browse technology-specific patterns: See implementations

Integration with Other Sections¶

Patterns are applied throughout the other sections:

Secure: Security scanning patterns, SBOM generation patterns
Enforce: Policy enforcement patterns, admission control patterns
Build: Release automation patterns, testing patterns

Pattern Documentation Format¶

Each pattern is documented with:

Intent: What problem does this solve?
Motivation: When should you use this?
Structure: How is it organized?
Implementation: Code examples
Consequences: Trade-offs and limitations
Related patterns: What patterns complement this?

Contributing Patterns¶

See CONTRIBUTING.md in the project root for guidelines on documenting new patterns.

Pattern quality criteria:

Solves a recurring problem (not one-off solution)
Technology-agnostic (or clearly scoped to specific tech)
Production-tested (not theoretical)
Documented with real examples (not pseudocode)
Includes anti-patterns (what not to do)

Tags¶

Browse all content tagged with patterns, automation, idempotency, three-stage, and hub-and-spoke on the Tags page.