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
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
- 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
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
- 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)
Related Content
Tags
Browse all content tagged with patterns, automation, idempotency, three-stage, and hub-and-spoke on the Tags page.
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
- 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)
Related Content
Tags
Browse all content tagged with patterns, automation, idempotency, three-stage, and hub-and-spoke on the Tags page.
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
References