name	patterns
description	Battle-tested automation patterns for GitHub Actions, Argo, and Kubernetes. Build resilient, idempotent workflows that scale with hub-and-spoke design.

Patterns

When to Use This Skill

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.

Implementation

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

Techniques

Overview

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

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

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

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

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

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

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

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, 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
Check in optimal order (cheap first, expensive last)
Avoid partial execution states
Examples: Dependency checks, permission validation

Graceful Degradation

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/

See reference.md for additional techniques and detailed examples.

Anti-Patterns to Avoid

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

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

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

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

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

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

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

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

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, 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
Check in optimal order (cheap first, expensive last)
Avoid partial execution states
Examples: Dependency checks, permission validation

Graceful Degradation

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.

Overview

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

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

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

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

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

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

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

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, 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
Check in optimal order (cheap first, expensive last)
Avoid partial execution states
Examples: Dependency checks, permission validation

Graceful Degradation

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)

Examples

See examples.md for code examples.

Full Reference

See reference.md for complete documentation.

Related Patterns

0
-z "$existing"
Secure
Enforce
Build
Secure
Enforce
Build
Tags

Install Skill

SKILL.md

Patterns

When to Use This Skill

Implementation

Techniques

Overview

Pattern Categories

Architecture Patterns

Separation of Concerns

Hub-and-Spoke

Strangler Fig

Three-Stage Design

Matrix Distribution

Environment Progression

Efficiency Patterns

Idempotency

Work Avoidance

Error Handling Patterns

Fail Fast

Prerequisite Checks

Graceful Degradation

Technology-Specific Patterns

GitHub Actions Patterns

Argo Events Patterns

Argo Workflows Patterns

Cross-Cutting Concerns

Idempotency Across Technologies

Three-Stage Design Across Technologies

Retry Strategies Across Technologies

Pattern Selection Guide

Common Anti-Patterns

❌ Non-Idempotent Operations

❌ Unnecessary Work

❌ Late Error Detection

Anti-Patterns to Avoid

Overview

Pattern Categories

Architecture Patterns

Separation of Concerns

Hub-and-Spoke

Strangler Fig

Three-Stage Design

Matrix Distribution

Environment Progression

Efficiency Patterns

Idempotency

Work Avoidance

Error Handling Patterns

Fail Fast

Prerequisite Checks

Graceful Degradation

Technology-Specific Patterns

GitHub Actions Patterns

Argo Events Patterns

Argo Workflows Patterns

Cross-Cutting Concerns

Idempotency Across Technologies

Three-Stage Design Across Technologies

Retry Strategies Across Technologies

Pattern Selection Guide

Common Anti-Patterns

❌ Non-Idempotent Operations

❌ Unnecessary Work

❌ Late Error Detection

Pattern Layering

Getting Started

Integration with Other Sections

Pattern Documentation Format

Contributing Patterns

Related Content

Tags

Overview

Pattern Categories

Architecture Patterns

Separation of Concerns

Hub-and-Spoke

Strangler Fig

Three-Stage Design

Matrix Distribution