Devops Workflow Engineer

DevOps Workflow Engineer

Generate GitHub Actions workflow YAML, analyze existing pipelines for optimization opportunities, and create deployment plans with strategy selection, health checks, and rollback procedures.

Core Capabilities

• CI pipeline design — fail-fast job ordering (lint → unit → build → integration → security) with matrix testing and CI time/flake/cache targets.
• CD & multi-environment — dev/staging/prod promotion flows, build-once-deploy-everywhere, environment protection rules, and rollback at every stage.
• Pipeline optimization — detect missing caching, missing timeouts, serial chains, deprecated actions, leaked secrets, and oversized runners; apply path filtering and concurrency cancellation.
• Deployment strategies — choose blue-green, canary, or rolling via decision tree; canary traffic-split schedule with promotion gates.
• GitHub Actions patterns — reusable workflows, OIDC auth, secrets hierarchy, and runner cost estimation.

When to Use

• Designing a new CI or CD workflow from scratch.
• Planning a multi-environment (dev/staging/prod) deployment.
• Optimizing an existing pipeline's cost or runtime.
• Implementing a blue-green, canary, or rolling deployment strategy.

Clarify First

Before generating the workflow, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• [ ] Workflow type — CI, CD, release, or security-scan (sets workflow_generator.py --type)
• [ ] Stack — language and test framework (e.g. python/pytest) (drives the generated YAML steps via --language/--test-framework)
• [ ] Deployment strategy & environments — blue-green, canary, or rolling, and which of dev/staging/prod (drives the deployment_planner.py plan)

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Tools

All tools support --format json and --output/-o for file writing.

References

Load the reference that matches the task — keep this file lean and pull detail on demand:

• [references/workflows-and-optimization.md](references/workflows-and-optimization.md) — the CI / CD / optimization workflows with full YAML, deployment-strategy decision tree and canary schedule, GitHub Actions patterns, runner cost table, anti-patterns, and troubleshooting. Read when building or tuning a pipeline.
• [references/github-actions-patterns.md](references/github-actions-patterns.md) — deep GitHub Actions pattern library. Read when authoring advanced workflow YAML.
• [references/deployment-strategies.md](references/deployment-strategies.md) — deep deployment strategy guide (blue-green, canary, rolling). Read when planning a release rollout.
• [references/agentic-workflows-guide.md](references/agentic-workflows-guide.md) — agentic/automated workflow patterns. Read when wiring up AI-driven or autonomous pipeline steps.

Integration Points

GitHub Agentic Workflows Guide

Reference for GitHub's agentic workflow system (2026): markdown-based AI automation definitions, safe-outputs, tool permissions, continuous automation categories, and setup with the gh-aw CLI.

---

Table of Contents

• Overview
• What Are Agentic Workflows?
• Markdown-Based Workflow Format
• Frontmatter Schema
• Safe-Outputs Concept
• Tool Permissions
• Six Continuous Automation Categories
• Setup with gh-aw CLI
• Examples
• Integration with Traditional GitHub Actions
• Best Practices
• Limitations and Considerations

---

Overview

GitHub agentic workflows are a new automation layer that enables AI-driven tasks within GitHub repositories. Unlike traditional GitHub Actions (which use YAML-based declarative definitions), agentic workflows are defined in markdown files with YAML frontmatter, written in natural language, and executed by an AI agent with access to repository tools.

Agentic workflows complement, rather than replace, GitHub Actions. They are best suited for tasks that benefit from AI reasoning: code review, documentation generation, triage, and security analysis.

---

What Are Agentic Workflows?

Agentic workflows are:

• Markdown files stored in .github/agents/ within a repository.
• Triggered by GitHub events (pull_request, push, issues, schedule, etc.).
• Executed by an AI agent that reads the markdown instructions and uses declared tools.
• Permission-scoped to limit what the agent can access.
• Safe by default -- outputs are labeled as AI-generated and require human review.

Key Differences from GitHub Actions

---

Markdown-Based Workflow Format

Agentic workflows are stored as markdown files in .github/agents/:

.github/
  agents/
    code-review.md
    triage-issues.md
    update-docs.md
    security-scan.md

Structure

Each file has two parts:

1. YAML frontmatter -- Metadata, triggers, tools, and permissions. 2. Markdown body -- Natural language instructions for the AI agent.

Minimal Example

---
name: code-review-agent
description: Reviews pull requests for quality, security, and conventions
triggers:
  - pull_request
tools:
  - code-search
  - file-read
  - comment-create
permissions:
  contents: read
  pull-requests: write
safe-outputs: true
---

# Code Review Agent

Review every pull request for:

1. Security vulnerabilities and credential leaks
2. Performance regressions
3. Test coverage gaps
4. Adherence to project coding conventions

## Process

- Read the pull request diff and understand the context
- Search the codebase for related files that might be affected
- Post inline comments for specific issues found
- Post a summary comment with an overall assessment

---

Frontmatter Schema

The YAML frontmatter defines the workflow's identity, triggers, capabilities, and constraints.

Required Fields

Optional Fields

Triggers

Agentic workflows support the same event triggers as GitHub Actions:

triggers:
  - pull_request           # Fires on PR open, sync, reopen
  - push                   # Fires on push to branches
  - issues                 # Fires on issue open, edit, label
  - issue_comment          # Fires on new comments
  - schedule               # Cron-based scheduling
  - workflow_dispatch      # Manual trigger
  - release                # Fires on release events

Trigger with Filters

triggers:
  - type: pull_request
    branches: [main, release/*]
    paths: ['src/**', 'tests/**']
  - type: schedule
    cron: '0 9 * * 1'     # Mondays at 9 AM UTC

---

Safe-Outputs Concept

The safe-outputs: true flag (enabled by default) ensures that everything the agent produces is:

1. Labeled as AI-generated -- Comments, commits, and issues include an AI attribution badge. 2. Not auto-merged -- PR changes created by the agent require human approval. 3. Not auto-deployed -- Deployment triggers are suppressed for agent-created artifacts. 4. Fully auditable -- Every action is logged with the agent's reasoning chain.

Why Safe-Outputs Matters

• Prevents AI hallucinations from reaching production unreviewed.
• Maintains human accountability for all deployed changes.
• Provides an audit trail for compliance.
• Builds trust incrementally as teams gain confidence in AI outputs.

Disabling Safe-Outputs

For low-risk automation (like labeling or triage), you can disable safe-outputs:

safe-outputs: false   # Outputs are applied directly without AI labeling

Use with caution. Only disable for:

• Read-only operations (search, analysis)
• Low-risk write operations (adding labels, assigning reviewers)
• Internal tooling where all outputs are reviewed by other processes

---

Tool Permissions

Agentic workflows declare which tools the agent can use. Each tool maps to a specific capability and required permission.

Available Tools

Permission Scoping

Follow the principle of least privilege:

# Good: minimal permissions
permissions:
  contents: read
  pull-requests: write

# Avoid: overly broad
permissions:
  contents: write     # Only needed if the agent creates/modifies files
  actions: write      # Only needed if the agent triggers workflows

Tool + Permission Matrix

# Read-only agent (code review)
tools: [code-search, file-read, comment-create]
permissions:
  contents: read
  pull-requests: write

# Write agent (auto-fix)
tools: [code-search, file-read, file-write, comment-create]
permissions:
  contents: write
  pull-requests: write

# Triage agent (issue management)
tools: [issue-update, comment-create]
permissions:
  issues: write

---

Six Continuous Automation Categories

GitHub organizes agentic workflows into six categories of continuous automation:

1. Code Quality

Automated code review, style enforcement, and quality checks.

Triggers: pull_request Tools: code-search, file-read, comment-create, pr-review Examples:

• Review PRs for security vulnerabilities
• Check adherence to coding conventions
• Identify performance anti-patterns
• Suggest refactoring opportunities

2. Documentation

Automated documentation generation, updates, and verification.

Triggers: push (to main), pull_request Tools: code-search, file-read, file-write, comment-create Examples:

• Generate changelog entries from PR titles
• Update API documentation when endpoints change
• Verify README accuracy
• Generate code documentation

3. Security

Automated security scanning, vulnerability detection, and remediation.

Triggers: push, schedule, pull_request Tools: code-search, file-read, comment-create, issue-create Examples:

• Scan for hardcoded secrets
• Detect dependency vulnerabilities
• Review infrastructure-as-code for misconfigurations
• Generate security advisories

4. Release Management

Automated versioning, release notes, and publishing.

Triggers: release, workflow_dispatch, push (tags) Tools: code-search, file-read, file-write, comment-create Examples:

• Draft release notes from merged PRs
• Bump version numbers
• Validate release checklists
• Generate migration guides

5. Issue Triage

Automated issue labeling, assignment, and prioritization.

Triggers: issues, issue_comment Tools: issue-update, comment-create, code-search Examples:

• Label issues by type (bug, feature, question)
• Assign issues to relevant team members
• Detect duplicate issues
• Prioritize based on severity

6. Maintenance

Automated dependency updates, cleanup, and housekeeping.

Triggers: schedule Tools: code-search, file-read, file-write, issue-create Examples:

• Check for outdated dependencies
• Clean up stale branches
• Archive old issues
• Verify CI configuration health

---

Setup with gh-aw CLI

The gh-aw CLI extension manages agentic workflows from the command line.

Installation

# Install the gh-aw extension
gh extension install github/gh-aw

Commands

# List all agentic workflows in the repository
gh aw list

# Create a new agentic workflow from a template
gh aw create --name code-review --category code-quality

# Validate workflow files
gh aw validate

# Run a workflow manually (for testing)
gh aw run code-review --event pull_request --pr 42

# View workflow execution logs
gh aw logs code-review --run 12345

# Disable a workflow
gh aw disable code-review

# Enable a workflow
gh aw enable code-review

Creating from Templates

# List available templates
gh aw templates

# Create from template
gh aw create --template security-scanner
gh aw create --template pr-reviewer
gh aw create --template issue-triager
gh aw create --template doc-generator
gh aw create --template release-drafter
gh aw create --template dependency-checker

Validation

# Validate all workflow files
gh aw validate

# Output:
# .github/agents/code-review.md     [VALID]
# .github/agents/triage-issues.md   [VALID]
# .github/agents/update-docs.md     [WARNING] Missing description
# .github/agents/security-scan.md   [ERROR] Invalid tool: 'deploy-trigger'

---

Examples

Example 1: PR Code Reviewer

---
name: pr-code-reviewer
description: Reviews pull requests for quality, security, and best practices
triggers:
  - pull_request
tools:
  - code-search
  - file-read
  - comment-create
  - pr-review
permissions:
  contents: read
  pull-requests: write
safe-outputs: true
timeout-minutes: 10
---

# PR Code Reviewer

## Instructions

Review the pull request thoroughly:

1. Read the complete diff to understand what changed
2. Search for related files that might be affected by the changes
3. Check for security issues: SQL injection, XSS, credential exposure
4. Check for performance issues: N+1 queries, unbounded loops, large allocations
5. Verify test coverage: new code should have corresponding tests
6. Check code style: consistent with project conventions

## Output

Post inline comments for specific issues with severity labels:
- [CRITICAL] Security vulnerabilities or data loss risks
- [WARNING] Performance issues or potential bugs
- [SUGGESTION] Style improvements or refactoring opportunities

Post a summary comment with:
- Overall assessment (approve, request changes, or comment)
- Risk level (low/medium/high)
- List of findings grouped by severity

Example 2: Issue Triager

---
name: issue-triager
description: Automatically labels and assigns new issues
triggers:
  - issues
tools:
  - code-search
  - issue-update
  - comment-create
permissions:
  issues: write
  contents: read
safe-outputs: false
---

# Issue Triager

When a new issue is created:

1. Read the issue title and body
2. Classify the issue type: bug, feature-request, question, documentation
3. Determine the affected component by searching the codebase for related files
4. Apply appropriate labels
5. If the issue is a bug, add priority label based on severity
6. Post a welcome comment acknowledging the issue and explaining next steps

Example 3: Documentation Updater

---
name: doc-updater
description: Updates documentation when code changes
triggers:
  - type: push
    branches: [main]
    paths: ['src/api/**']
tools:
  - code-search
  - file-read
  - file-write
  - comment-create
permissions:
  contents: write
  pull-requests: write
safe-outputs: true
---

# Documentation Updater

When API code changes are pushed to main:

1. Identify which API endpoints were modified
2. Read the current documentation in docs/api/
3. Compare code with documentation to find discrepancies
4. Create a PR with documentation updates
5. Include a summary of what changed and why

## Rules

- Only update documentation that is directly affected by code changes
- Preserve existing documentation style and formatting
- Add examples for new endpoints
- Mark deprecated endpoints clearly

---

Integration with Traditional GitHub Actions

Agentic workflows coexist with GitHub Actions. Common integration patterns:

Pattern 1: Agent Triggered by Action

# .github/workflows/on-pr.yml
on:
  pull_request:
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - run: make lint
  # The agentic workflow in .github/agents/code-review.md
  # fires on the same pull_request event independently

Pattern 2: Agent Triggers an Action

---
tools:
  - workflow-trigger
permissions:
  actions: write
---

If the review finds critical security issues, trigger the
security-alert workflow to notify the security team.

Pattern 3: Action Passes Context to Agent

GitHub Actions can create comments or artifacts that agentic workflows read as context for more informed analysis.

---

Best Practices

1. Start with safe-outputs enabled. Disable only after building trust with a specific workflow. 2. Scope permissions minimally. Give each workflow only the tools and permissions it needs. 3. Write clear, structured instructions. Use numbered steps and explicit criteria. 4. Test with `gh aw run` before enabling triggers. Validate behavior on real PRs/issues. 5. Set reasonable timeouts. Default 15 minutes is good for most tasks; reduce for simple triage. 6. Monitor execution logs. Review gh aw logs regularly to catch unexpected behavior. 7. Version your workflows. Track changes to .github/agents/ in version control like any other config. 8. Combine with Actions for deterministic gates. Use Actions for build/test/deploy; use agents for review/triage/documentation. 9. Keep instructions focused. One workflow per task. Do not create a single workflow that tries to do everything. 10. Document the expected behavior. Include a "## Rules" section in the markdown to set explicit boundaries.

---

Limitations and Considerations

• Non-deterministic: Agentic workflows may produce different outputs for the same input. Use safe-outputs and human review.
• Token costs: Each execution consumes AI model tokens. Monitor usage for cost control.
• Rate limits: Frequent triggers (every push, every comment) can hit rate limits. Use path filters and concurrency groups.
• Not a replacement for Actions: Deterministic tasks (build, test, deploy) should remain in GitHub Actions.
• Model availability: Execution depends on AI model availability. Plan for occasional delays or failures.
• Repository access: Agentic workflows can only access the repository they are defined in (no cross-repo access by default).

Deployment Strategies

Comprehensive guide to deployment strategies for production systems. Covers blue-green, canary, rolling, A/B testing, feature flags, and database migration handling during deployments.

---

Table of Contents

1. Strategy Comparison 2. Blue-Green Deployment 3. Canary Deployment 4. Rolling Deployment 5. A/B Testing Deployments 6. Feature Flags 7. Database Migrations During Deploy 8. Choosing the Right Strategy

---

Strategy Comparison

---

Blue-Green Deployment

Overview

Blue-green deployment maintains two identical production environments. At any time, only one (say "blue") serves live traffic. New versions are deployed to the inactive environment ("green"), validated, and then traffic is switched.

Architecture

                    Load Balancer
                    /           \
                   /             \
            [Blue - v1.2]    [Green - v1.3]
            (ACTIVE)         (STAGING)
                   \             /
                    \           /
                  Shared Database

Implementation Steps

1. Deploy to green environment

   # Deploy new version to green
   kubectl apply -f deployment-green.yaml
   kubectl rollout status deployment/app-green --timeout=300s

2. Run validation on green

   # Health checks
   curl -sf https://green.internal.example.com/health || exit 1

   # Smoke tests against green
   SMOKE_URL=https://green.internal.example.com pytest tests/smoke/

3. Switch traffic

   # Update load balancer to point to green
   # AWS ALB example:
   aws elbv2 modify-listener --listener-arn $LISTENER_ARN \
     --default-actions Type=forward,TargetGroupArn=$GREEN_TG_ARN

   # Or Kubernetes service selector:
   kubectl patch service app-service -p '{"spec":{"selector":{"version":"green"}}}'

4. Monitor

• Watch error rates for 15-30 minutes.
• Compare latency baselines.
• Verify business metrics (conversion, API success rate).

5. Finalize or rollback

   # If healthy: decommission blue (or keep as rollback)
   # If unhealthy: switch back to blue
   kubectl patch service app-service -p '{"spec":{"selector":{"version":"blue"}}}'

GitHub Actions Integration

jobs:
  deploy-green:
    environment: production-green
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to green
        run: ./scripts/deploy.sh green ${{ github.sha }}
      - name: Validate green
        run: ./scripts/validate.sh green

  switch-traffic:
    needs: deploy-green
    environment: production
    runs-on: ubuntu-latest
    steps:
      - name: Switch traffic to green
        run: ./scripts/switch-traffic.sh green
      - name: Monitor (5 min)
        run: ./scripts/monitor.sh --duration 300 --threshold 0.01

When to Use

• Applications where instant rollback is critical.
• Systems that can afford 2x infrastructure during deployments.
• When you need to validate the full environment before exposing to users.

When to Avoid

• Very large infrastructure (cost doubles during deploy).
• Stateful services with data that diverges between environments.
• When database schema changes require both versions to coexist.

---

Canary Deployment

Overview

Canary deployment routes a small fraction of traffic to the new version while the majority continues on the stable version. Traffic percentage increases gradually based on success metrics.

Architecture

            Load Balancer / Service Mesh
              /        |         \
            95%        |         5%
           /           |           \
    [Stable v1.2]     |     [Canary v1.3]
    (10 replicas)     |     (1 replica)
                       |
               Metric Collection
               (errors, latency)

Traffic Split Schedule

Implementation with Kubernetes

Using Argo Rollouts:

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: my-app
spec:
  replicas: 10
  strategy:
    canary:
      steps:
        - setWeight: 5
        - pause: { duration: 15m }
        - setWeight: 25
        - pause: { duration: 30m }
        - setWeight: 50
        - pause: { duration: 60m }
        - setWeight: 100
      canaryMetadata:
        labels:
          role: canary
      stableMetadata:
        labels:
          role: stable
      analysis:
        templates:
          - templateName: success-rate
        startingStep: 1
        args:
          - name: service-name
            value: my-app

Analysis Template

apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata:
  name: success-rate
spec:
  args:
    - name: service-name
  metrics:
    - name: success-rate
      interval: 1m
      successCondition: result[0] >= 0.99
      failureCondition: result[0] < 0.95
      failureLimit: 3
      provider:
        prometheus:
          address: http://prometheus:9090
          query: |
            sum(rate(http_requests_total{service="{{args.service-name}}",status!~"5.."}[5m]))
            /
            sum(rate(http_requests_total{service="{{args.service-name}}"}[5m]))

Implementation with Istio

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: my-app
spec:
  hosts:
    - my-app
  http:
    - route:
        - destination:
            host: my-app
            subset: stable
          weight: 95
        - destination:
            host: my-app
            subset: canary
          weight: 5

When to Use

• High-traffic services where a bad deploy affects many users.
• When you have good observability and can detect issues at low traffic percentages.
• Services where you want real production validation before full rollout.

When to Avoid

• Low-traffic services (not enough signal at 5%).
• Services without good metrics/monitoring.
• When speed of deployment is more important than safety.

---

Rolling Deployment

Overview

Rolling deployment replaces instances of the old version with the new version one at a time (or in configured batch sizes). At least some instances are always available.

Architecture

Time T0: [v1] [v1] [v1] [v1]  (all old)
Time T1: [v2] [v1] [v1] [v1]  (1 updated)
Time T2: [v2] [v2] [v1] [v1]  (2 updated)
Time T3: [v2] [v2] [v2] [v1]  (3 updated)
Time T4: [v2] [v2] [v2] [v2]  (all new)

Kubernetes Configuration

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 4
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1          # Max extra pods during update
      maxUnavailable: 0     # Always maintain full capacity
  template:
    spec:
      containers:
        - name: app
          image: my-app:v2
          readinessProbe:
            httpGet:
              path: /ready
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 5
          livenessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 15
            periodSeconds: 10

Key Parameters

Rollback

# Automatic rollback on failure
kubectl rollout undo deployment/my-app

# Rollback to specific revision
kubectl rollout undo deployment/my-app --to-revision=3

# Check rollout history
kubectl rollout history deployment/my-app

When to Use

• Stateless services with multiple replicas.
• Kubernetes-native deployments.
• When infrastructure cost must stay flat (no extra environment).

When to Avoid

• When both versions cannot serve traffic simultaneously (breaking API changes).
• Single-instance deployments (no redundancy during update).
• When instant rollback is required (rolling back is another rolling update).

---

A/B Testing Deployments

Overview

A/B testing deployments route traffic to different versions based on user attributes (not random traffic splitting). This enables data-driven decisions about which version performs better.

Difference from Canary

Routing Strategies

Header-based:

# Istio VirtualService
http:
  - match:
      - headers:
          x-experiment-group:
            exact: "variant-b"
    route:
      - destination:
          host: my-app
          subset: variant-b
  - route:
      - destination:
          host: my-app
          subset: variant-a

Cookie-based:

http:
  - match:
      - headers:
          cookie:
            regex: ".*ab_group=B.*"
    route:
      - destination:
          host: my-app
          subset: variant-b

User-segment based (application level):

def get_variant(user):
    """Determine which variant to show based on user attributes."""
    if user.id % 100 < 50:
        return "A"
    return "B"

Metrics to Track

• Primary metric: Conversion rate, revenue per user, engagement time.
• Guardrail metrics: Error rate, latency, bounce rate (must not degrade).
• Statistical significance: Typically need p < 0.05 with adequate sample size.

When to Use

• Validating new UI/UX against existing.
• Testing pricing changes.
• Comparing different recommendation algorithms.

---

Feature Flags

Overview

Feature flags decouple deployment from release. Code is deployed but features are toggled on/off independently, enabling gradual rollout, instant kill switches, and A/B testing without redeployment.

Flag Types

Implementation Patterns

Simple boolean flag:

def checkout(request):
    if flags.is_enabled("new-checkout-v2"):
        return new_checkout(request)
    return legacy_checkout(request)

Percentage rollout:

def checkout(request):
    if flags.is_enabled("new-checkout-v2", percentage=10):
        return new_checkout(request)
    return legacy_checkout(request)

User-targeted flag:

def checkout(request):
    if flags.is_enabled("new-checkout-v2", user=request.user,
                         rules={"plan": "premium", "country": "US"}):
        return new_checkout(request)
    return legacy_checkout(request)

Flag Lifecycle

1. Create flag (disabled) -----> Code deploys with flag check
2. Enable for internal users --> Test in production
3. Enable for 5% of users ----> Monitor metrics
4. Increase to 25%, 50% ------> Gradual rollout
5. Enable for 100% -----------> Full release
6. Remove flag from code ------> Clean up (critical step!)

Best Practices

• Name flags clearly: enable-new-checkout-flow not flag-123.
• Set expiration dates: Stale flags are tech debt.
• Log flag evaluations: Know which users see which variant.
• Have a kill switch process: Document how to disable a flag in an emergency.
• Clean up after rollout: Remove flag code once fully launched.
• Limit active flags: More than 10-15 active flags creates combinatorial complexity.

Feature Flag in GitHub Actions

jobs:
  deploy:
    steps:
      - name: Set feature flags for environment
        run: |
          # Using a hypothetical flag management CLI
          flag-ctl set new-checkout-v2 \
            --env ${{ inputs.environment }} \
            --percentage 5 \
            --description "Gradual rollout of new checkout"

Services

---

Database Migrations During Deploy

The Challenge

Database schema changes during deployment create risk because:

• Old code may not work with new schema.
• New code may not work with old schema.
• Both versions run simultaneously during rolling/canary/blue-green deployments.

Golden Rule: Backward-Compatible Migrations

Every migration must be compatible with both the current and previous version of the application code.

Safe Migration Patterns

1. Add a column (safe)

-- Migration: Add column with default
ALTER TABLE users ADD COLUMN email_verified BOOLEAN DEFAULT FALSE;
-- Old code ignores the new column. New code uses it.

2. Remove a column (two-phase)

Phase 1 (deploy v2): Stop reading the column in code. Deploy.
Phase 2 (deploy v3): Drop the column in migration. Deploy.

3. Rename a column (three-phase)

Phase 1: Add new column, write to both old and new.
Phase 2: Migrate data, read from new column.
Phase 3: Drop old column.

4. Add an index (safe, but watch performance)

-- Use CONCURRENTLY to avoid locking the table
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);

5. Change column type (two-phase)

Phase 1: Add new column with new type, dual-write.
Phase 2: Migrate data, switch reads to new column.
Phase 3: Drop old column.

Unsafe Migration Patterns (Avoid)

Migration Execution in CI/CD

jobs:
  migrate:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v4

      - name: Backup database
        run: ./scripts/db-backup.sh ${{ inputs.environment }}

      - name: Run migration (dry run)
        run: ./scripts/db-migrate.sh --dry-run --env ${{ inputs.environment }}

      - name: Run migration
        run: ./scripts/db-migrate.sh --env ${{ inputs.environment }}

      - name: Verify migration
        run: ./scripts/db-verify.sh --env ${{ inputs.environment }}

  deploy:
    needs: migrate
    # ... deploy application code

Migration Rollback

• Always write a corresponding down migration.
• Test rollback in staging before deploying to production.
• If a migration is not reversible, document it and plan accordingly.

# Example: Django migration with reverse
class Migration(migrations.Migration):
    operations = [
        migrations.AddField(
            model_name='user',
            name='email_verified',
            field=models.BooleanField(default=False),
        ),
    ]

    # Django auto-generates reverse: RemoveField

---

Choosing the Right Strategy

Decision Tree

Start
  |
  v
Is zero-downtime required?
  |
  No --> Simple deployment (stop old, start new)
  |
  Yes
  |
  v
Is instant rollback critical?
  |
  No --> Rolling deployment
  |
  Yes
  |
  v
Can you afford 2x infrastructure?
  |
  Yes --> Blue-green deployment
  |
  No
  |
  v
Do you have good observability (metrics, alerting)?
  |
  No --> Blue-green (simpler to manage)
  |
  Yes
  |
  v
Is traffic high enough for meaningful canary signal?
  |
  No --> Blue-green
  |
  Yes --> Canary deployment

Strategy Selection by Service Type

Combining Strategies

Production deployments often combine multiple strategies:

1. Feature flags + Canary: Deploy with feature hidden behind flag, canary the deployment, then gradually enable the flag. 2. Blue-green + Database migration: Run backward-compatible migration first, then blue-green switch the application. 3. Rolling + Health checks: Standard Kubernetes rolling update with readiness probes acting as automatic gates. 4. Canary + A/B test: Use canary for risk mitigation during deploy, then A/B test the feature over days.

GitHub Actions Patterns

30+ proven patterns for production GitHub Actions workflows. Each pattern includes a working example and guidance on when to apply it.

---

Table of Contents

1. Trigger Patterns 2. Job Structure Patterns 3. Matrix Patterns 4. Caching Patterns 5. Artifact Patterns 6. Security Patterns 7. Reusable Workflow Patterns 8. Composite Action Patterns 9. Environment Patterns 10. Advanced Patterns

---

Trigger Patterns

Pattern 1: Path-Filtered Push

Run the workflow only when relevant files change.

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'tests/**'
      - 'Dockerfile'
      - 'requirements*.txt'
    paths-ignore:
      - '**.md'
      - 'docs/**'

When to use: Reduce unnecessary CI runs on documentation-only or config-only changes.

Pattern 2: Manual Dispatch with Inputs

Allow manual triggering with parameters.

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        type: choice
        options: [dev, staging, production]
      dry_run:
        description: 'Dry run (no actual deploy)'
        required: false
        type: boolean
        default: true
      version:
        description: 'Version to deploy (leave empty for latest)'
        required: false
        type: string

When to use: On-demand deployments, maintenance tasks, or any workflow that needs human-supplied parameters.

Pattern 3: Scheduled with Conditional Skip

Run on schedule but skip if there are no new changes.

on:
  schedule:
    - cron: '0 6 * * 1-5'  # Weekdays at 6 AM UTC

jobs:
  check:
    runs-on: ubuntu-latest
    outputs:
      should_run: ${{ steps.check.outputs.should_run }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - id: check
        run: |
          if git diff --quiet HEAD~1; then
            echo "should_run=false" >> "$GITHUB_OUTPUT"
          else
            echo "should_run=true" >> "$GITHUB_OUTPUT"
          fi

  build:
    needs: check
    if: needs.check.outputs.should_run == 'true'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Building..."

When to use: Nightly dependency checks or security scans that should skip if nothing changed.

Pattern 4: PR Target Branch Filter

Run different checks depending on the target branch of a PR.

on:
  pull_request:
    branches:
      - main
      - 'release/**'

jobs:
  basic-checks:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Run on all PRs"

  release-checks:
    if: startsWith(github.base_ref, 'release/')
    runs-on: ubuntu-latest
    steps:
      - run: echo "Extra checks for release branches"

When to use: Enforce stricter validation for release branch PRs.

Pattern 5: Multi-Event Trigger with Conditional Logic

Handle multiple triggers with event-specific behavior.

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  release:
    types: [published]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: make build

      - name: Publish (release only)
        if: github.event_name == 'release'
        run: make publish

---

Job Structure Patterns

Pattern 6: Fan-Out / Fan-In

Run independent checks in parallel, then merge results.

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: make lint

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: make test

  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: make security-scan

  gate:
    needs: [lint, test, security]
    runs-on: ubuntu-latest
    steps:
      - run: echo "All checks passed"

When to use: Always. This is the default pattern for CI pipelines.

Pattern 7: Conditional Job Execution

Skip jobs based on commit message or labels.

jobs:
  test:
    if: "!contains(github.event.head_commit.message, '[skip ci]')"
    runs-on: ubuntu-latest
    steps:
      - run: make test

  deploy:
    if: contains(github.event.pull_request.labels.*.name, 'deploy-preview')
    runs-on: ubuntu-latest
    steps:
      - run: make deploy-preview

Pattern 8: Job Output Passing

Pass data from one job to another.

jobs:
  prepare:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.version.outputs.version }}
      sha_short: ${{ steps.sha.outputs.sha_short }}
    steps:
      - uses: actions/checkout@v4
      - id: version
        run: echo "version=$(cat VERSION)" >> "$GITHUB_OUTPUT"
      - id: sha
        run: echo "sha_short=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"

  build:
    needs: prepare
    runs-on: ubuntu-latest
    steps:
      - run: echo "Building version ${{ needs.prepare.outputs.version }}"

Pattern 9: Timeout and Retry

Protect against hung processes and handle transient failures.

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - name: Run flaky integration test (with retry)
        uses: nick-fields/retry@v3
        with:
          timeout_minutes: 5
          max_attempts: 3
          command: make integration-test

---

Matrix Patterns

Pattern 10: Basic Cross-Platform Matrix

Test across operating systems and language versions.

jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ['3.10', '3.11', '3.12']
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - run: python -m pytest

Pattern 11: Matrix with Include/Exclude

Fine-tune matrix combinations.

strategy:
  matrix:
    os: [ubuntu-latest, macos-latest]
    node: [18, 20, 22]
    exclude:
      - os: macos-latest
        node: 18
    include:
      - os: ubuntu-latest
        node: 22
        coverage: true

When to use: Skip combinations that are not supported or add extra configuration to specific combinations.

Pattern 12: Dynamic Matrix from JSON

Generate matrix values dynamically.

jobs:
  generate-matrix:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set.outputs.matrix }}
    steps:
      - uses: actions/checkout@v4
      - id: set
        run: |
          # Read from file, API, or compute dynamically
          MATRIX=$(python generate_matrix.py)
          echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT"

  build:
    needs: generate-matrix
    strategy:
      matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
    runs-on: ${{ matrix.runner }}
    steps:
      - run: echo "Building ${{ matrix.name }}"

Pattern 13: Matrix with Shared Setup

Factor out common setup into a composite action or reusable step.

jobs:
  test:
    strategy:
      matrix:
        shard: [1, 2, 3, 4]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup-project
      - name: Run test shard
        run: pytest --shard-id=${{ matrix.shard }} --num-shards=4

---

Caching Patterns

Pattern 14: Language-Native Cache

Use built-in cache support in setup actions.

# Python
- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    cache: pip

# Node.js
- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: npm

# Go
- uses: actions/setup-go@v5
  with:
    go-version: '1.22'
    cache: true

Pattern 15: Multi-Path Cache

Cache multiple directories with a composite key.

- uses: actions/cache@v4
  with:
    path: |
      ~/.cache/pip
      ~/.local/share/virtualenvs
      .mypy_cache
      .pytest_cache
    key: ${{ runner.os }}-full-${{ hashFiles('**/requirements*.txt', 'setup.cfg') }}
    restore-keys: |
      ${{ runner.os }}-full-
      ${{ runner.os }}-

Pattern 16: Docker Layer Cache with BuildKit

Cache Docker build layers using GitHub Actions cache backend.

- uses: docker/build-push-action@v5
  with:
    context: .
    push: true
    tags: ${{ env.REGISTRY }}/${{ env.IMAGE }}:${{ github.sha }}
    cache-from: type=gha
    cache-to: type=gha,mode=max

Pattern 17: Turbo/Nx Build Cache

Cache build outputs for monorepo build systems.

- uses: actions/cache@v4
  with:
    path: node_modules/.cache/turbo
    key: turbo-${{ runner.os }}-${{ hashFiles('**/turbo.json', '**/package-lock.json') }}
    restore-keys: turbo-${{ runner.os }}-

---

Artifact Patterns

Pattern 18: Build Once, Deploy Everywhere

Build an artifact in one job, use it across deployment jobs.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/
          retention-days: 1

  deploy-staging:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/
      - run: ./deploy.sh staging dist/

  deploy-prod:
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/
      - run: ./deploy.sh production dist/

Pattern 19: Test Report Artifacts

Aggregate test results across matrix jobs.

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: test-results-${{ matrix.os }}-${{ matrix.version }}
    path: |
      **/junit-*.xml
      **/coverage-*.xml
    retention-days: 7

---

Security Patterns

Pattern 20: OIDC Authentication (AWS)

Use short-lived tokens instead of stored credentials.

permissions:
  id-token: write
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789012:role/github-actions
      aws-region: us-east-1

Pattern 21: OIDC Authentication (GCP)

permissions:
  id-token: write
  contents: read

steps:
  - uses: google-github-actions/auth@v2
    with:
      workload_identity_provider: projects/123456/locations/global/workloadIdentityPools/github/providers/my-repo
      service_account: github-actions@my-project.iam.gserviceaccount.com

Pattern 22: Minimal Permissions

Always declare the minimum permissions needed.

# Top-level: restrict all
permissions:
  contents: read

jobs:
  deploy:
    permissions:
      contents: read
      packages: write      # Only this job needs package write
      id-token: write      # Only this job needs OIDC

Pattern 23: Secret Masking for Dynamic Values

Mask dynamically generated sensitive values.

steps:
  - name: Generate token
    id: token
    run: |
      TOKEN=$(curl -s https://auth.example.com/token)
      echo "::add-mask::$TOKEN"
      echo "token=$TOKEN" >> "$GITHUB_OUTPUT"

Pattern 24: Dependency Review on PRs

Block PRs that introduce vulnerable dependencies.

on:
  pull_request:

jobs:
  dependency-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/dependency-review-action@v4
        with:
          fail-on-severity: high
          deny-licenses: GPL-3.0, AGPL-3.0

---

Reusable Workflow Patterns

Pattern 25: Parameterized Reusable Workflow

Define a workflow that can be called with different parameters.

# .github/workflows/reusable-test.yml
on:
  workflow_call:
    inputs:
      python-version:
        type: string
        default: '3.12'
      test-command:
        type: string
        default: 'pytest'
    secrets:
      CODECOV_TOKEN:
        required: false

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ inputs.python-version }}
          cache: pip
      - run: pip install -r requirements.txt
      - run: ${{ inputs.test-command }}

Pattern 26: Chained Reusable Workflows

Call reusable workflows in sequence.

jobs:
  test:
    uses: ./.github/workflows/reusable-test.yml
    with:
      python-version: '3.12'

  build:
    needs: test
    uses: ./.github/workflows/reusable-build.yml
    with:
      push_image: true
    secrets: inherit

  deploy:
    needs: build
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: staging
    secrets: inherit

Pattern 27: Cross-Repository Reusable Workflow

Call a workflow from another repository.

jobs:
  deploy:
    uses: my-org/shared-workflows/.github/workflows/deploy.yml@v2
    with:
      environment: production
    secrets:
      DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}

---

Composite Action Patterns

Pattern 28: Project Setup Composite

Bundle common setup steps.

# .github/actions/setup-project/action.yml
name: Setup Project
description: Install all dependencies and configure environment

inputs:
  python-version:
    default: '3.12'

runs:
  using: composite
  steps:
    - uses: actions/setup-python@v5
      with:
        python-version: ${{ inputs.python-version }}
        cache: pip
    - run: pip install -r requirements.txt -r requirements-dev.txt
      shell: bash
    - run: pre-commit install
      shell: bash

Pattern 29: Deploy Composite with Outputs

A composite action that deploys and returns the deployment URL.

# .github/actions/deploy/action.yml
name: Deploy
description: Deploy to environment and return URL

inputs:
  environment:
    required: true
  image_tag:
    required: true

outputs:
  url:
    description: Deployment URL
    value: ${{ steps.deploy.outputs.url }}

runs:
  using: composite
  steps:
    - id: deploy
      run: |
        URL=$(./deploy.sh ${{ inputs.environment }} ${{ inputs.image_tag }})
        echo "url=$URL" >> "$GITHUB_OUTPUT"
      shell: bash

---

Environment Patterns

Pattern 30: Environment Protection Rules

Use GitHub environments with required reviewers and wait timers.

jobs:
  deploy-prod:
    environment:
      name: production
      url: https://myapp.example.com
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh production

Configure in Settings > Environments > production:

• Required reviewers: team leads
• Wait timer: 5 minutes
• Deployment branches: only main

Pattern 31: Environment-Specific Secrets and Variables

Use environment-scoped configuration.

jobs:
  deploy:
    environment: ${{ inputs.environment }}
    runs-on: ubuntu-latest
    steps:
      - run: |
          curl -X POST ${{ vars.DEPLOY_URL }} \
            -H "Authorization: Bearer ${{ secrets.DEPLOY_TOKEN }}" \
            -d '{"version": "${{ github.sha }}"}'

Each environment (dev, staging, production) has its own DEPLOY_URL variable and DEPLOY_TOKEN secret.

---

Advanced Patterns

Pattern 32: Concurrency Groups

Prevent concurrent runs and cancel outdated ones.

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

For production deployments, do NOT cancel in progress:

concurrency:
  group: deploy-production
  cancel-in-progress: false

Pattern 33: Step Summary

Write rich markdown summaries visible in the Actions UI.

- name: Generate summary
  run: |
    echo "## Build Results" >> "$GITHUB_STEP_SUMMARY"
    echo "| Metric | Value |" >> "$GITHUB_STEP_SUMMARY"
    echo "|--------|-------|" >> "$GITHUB_STEP_SUMMARY"
    echo "| Tests | 142 passed |" >> "$GITHUB_STEP_SUMMARY"
    echo "| Coverage | 87.3% |" >> "$GITHUB_STEP_SUMMARY"
    echo "| Build time | 3m 12s |" >> "$GITHUB_STEP_SUMMARY"

Pattern 34: PR Comment with Results

Post CI results as a PR comment.

- uses: marocchino/sticky-pull-request-comment@v2
  with:
    header: ci-results
    message: |
      ## CI Results
      - Tests: ${{ steps.test.outputs.result }}
      - Coverage: ${{ steps.coverage.outputs.percentage }}%
      - Build: ${{ steps.build.outputs.status }}

Pattern 35: Monorepo Path-Based Jobs

Run only the jobs relevant to changed packages.

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      frontend: ${{ steps.filter.outputs.frontend }}
      backend: ${{ steps.filter.outputs.backend }}
      infra: ${{ steps.filter.outputs.infra }}
    steps:
      - uses: actions/checkout@v4
      - uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            frontend:
              - 'packages/frontend/**'
            backend:
              - 'packages/backend/**'
            infra:
              - 'terraform/**'

  test-frontend:
    needs: changes
    if: needs.changes.outputs.frontend == 'true'
    runs-on: ubuntu-latest
    steps:
      - run: cd packages/frontend && npm test

  test-backend:
    needs: changes
    if: needs.changes.outputs.backend == 'true'
    runs-on: ubuntu-latest
    steps:
      - run: cd packages/backend && pytest

Pattern 36: Automatic PR Labeling

Label PRs based on changed files.

on:
  pull_request:

jobs:
  label:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/labeler@v5
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

With .github/labeler.yml:

frontend:
  - changed-files:
    - any-glob-to-any-file: 'src/frontend/**'
backend:
  - changed-files:
    - any-glob-to-any-file: 'src/backend/**'
documentation:
  - changed-files:
    - any-glob-to-any-file: '**/*.md'

Pattern 37: Release Drafter

Automatically draft release notes from PR titles.

on:
  push:
    branches: [main]
  pull_request:
    types: [opened, reopened, synchronize]

permissions:
  contents: read
  pull-requests: write

jobs:
  draft:
    runs-on: ubuntu-latest
    steps:
      - uses: release-drafter/release-drafter@v6
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CI/CD Workflows, Strategies, and Optimization

Read this when designing a CI or CD pipeline, choosing a deployment strategy, optimizing pipeline cost/runtime, applying GitHub Actions patterns, or troubleshooting workflows.

Workflow 1: CI Pipeline Design

The agent generates pipelines following fail-fast ordering:

1. Lint and format (~30s) -- cheapest gate first 2. Unit tests (~2-5m) -- matrix across versions 3. Build verification (~3-8m) 4. Integration tests (~5-15m, parallel with build) 5. Security scanning (~2-5m)

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: make lint

  test:
    needs: lint
    strategy:
      matrix:
        python-version: ['3.10', '3.11', '3.12']
    steps:
      - uses: actions/setup-python@v5
        with: { python-version: "${{ matrix.python-version }}", cache: pip }
      - run: pip install -r requirements.txt
      - run: pytest --junitxml=results.xml

  security:
    needs: lint
    steps:
      - run: pip-audit -r requirements.txt

CI targets:

Workflow 2: CD Pipeline and Multi-Environment Deployment

python scripts/deployment_planner.py --type webapp --environments dev,staging,prod --format json

Environment promotion flow:

Build -> Dev (auto) -> Staging (auto) -> Production (manual approval)
                                              |
                                        Canary (10%) -> Full rollout

Key CD rules:

• Build once, deploy the same artifact everywhere
• Tag artifacts with commit SHA for traceability
• Use environment protection rules for production gates
• Maintain rollback capability at every stage

Workflow 3: Pipeline Optimization

python scripts/pipeline_analyzer.py .github/workflows/ --format json -o report.json

The agent checks for:

1. Missing caching -- dependencies reinstalled every run 2. No timeouts -- stuck jobs burn budget 3. Sequential chains that could parallelize 4. Deprecated actions with newer versions available 5. Security issues -- secrets in logs, missing permissions scoping 6. Cost inefficiency -- oversized runners, no path filtering

Optimization techniques:

Path-based filtering -- skip CI for docs-only changes:

on:
  push:
    paths: ['src/**', 'tests/**', 'requirements*.txt']
    paths-ignore: ['docs/**', '*.md']

Concurrency cancellation -- cancel superseded runs:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Dependency caching:

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-deps-${{ hashFiles('**/requirements.txt') }}

Deployment Strategies

Decision tree:

Zero-downtime required?
  No  -> Rolling deployment
  Yes -> Need instant rollback?
    No  -> Rolling with health checks
    Yes -> Budget for 2x infrastructure?
      Yes -> Blue-green
      No  -> Canary

Canary traffic split schedule:

GitHub Actions Patterns

Reusable workflows -- define once, call everywhere:

# .github/workflows/reusable-deploy.yml
on:
  workflow_call:
    inputs:
      environment: { required: true, type: string }
      image_tag: { required: true, type: string }
    secrets:
      DEPLOY_KEY: { required: true }

OIDC authentication -- no long-lived credentials:

permissions:
  id-token: write
  contents: read
steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789:role/github-actions
      aws-region: us-east-1

Secrets hierarchy: Organization > Repository > Environment. Never echo secrets; use add-mask for dynamic values. Prefer OIDC for cloud auth.

Runner Cost Optimization

Monthly estimate: (runs/day) x (avg min/run) x 30 x (cost/min) Example: 50 pushes/day x 8 min x 30 = 12,000 min x $0.008 = $96/month.

Anti-Patterns

Troubleshooting