🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

• ❌ WRONG: D:/repos/project/file.tsx
• ✅ CORRECT: D:\repos\project\file.tsx

This applies to:

• Edit tool file_path parameter
• Write tool file_path parameter
• All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

• Priority: Update existing README.md files rather than creating new documentation
• Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
• Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
• User preference: Only create additional .md files when user specifically asks for documentation

---

Modern Automation Patterns (2025)

Overview

Production-ready patterns for DevOps automation, CI/CD pipelines, and cloud-native operations following 2025 industry standards.

Container-Aware Scripting

Docker/Kubernetes Detection

#!/usr/bin/env bash
set -euo pipefail

# Detect container environment
detect_container() {
    if [[ -f /.dockerenv ]]; then
        echo "docker"
    elif grep -q docker /proc/1/cgroup 2>/dev/null; then
        echo "docker"
    elif [[ -n "${KUBERNETES_SERVICE_HOST:-}" ]]; then
        echo "kubernetes"
    else
        echo "host"
    fi
}

# Container-aware configuration
readonly CONTAINER_ENV=$(detect_container)

case "$CONTAINER_ENV" in
    docker|kubernetes)
        # Container-specific paths
        DATA_DIR="/data"
        CONFIG_DIR="/config"
        ;;
    host)
        # Host-specific paths
        DATA_DIR="/var/lib/app"
        CONFIG_DIR="/etc/app"
        ;;
esac

Minimal Container Scripts

#!/bin/sh
# Use /bin/sh for Alpine-based containers (no bash)

set -eu  # Note: No pipefail in POSIX sh

# Check if running as PID 1
if [ $$ -eq 1 ]; then
    # PID 1 must handle signals properly
    trap 'kill -TERM $child 2>/dev/null' TERM INT

    # Start main process in background
    /app/main &
    child=$!

    # Wait for child
    wait "$child"
else
    # Not PID 1, run directly
    exec /app/main
fi

Health Check Scripts

#!/usr/bin/env bash
# healthcheck.sh - Container health probe

set -euo pipefail

# Quick health check (< 1 second)
check_health() {
    local timeout=1

    # Check process is running
    if ! pgrep -f "myapp" > /dev/null; then
        echo "Process not running" >&2
        return 1
    fi

    # Check HTTP endpoint
    if ! timeout "$timeout" curl -sf http://localhost:8080/health > /dev/null; then
        echo "Health endpoint failed" >&2
        return 1
    fi

    # Check critical files
    if [[ ! -f /app/ready ]]; then
        echo "Not ready" >&2
        return 1
    fi

    return 0
}

check_health

CI/CD Pipeline Patterns

GitHub Actions Helper

#!/usr/bin/env bash
# ci-helper.sh - GitHub Actions utilities

set -euo pipefail

# Detect GitHub Actions
is_github_actions() {
    [[ "${GITHUB_ACTIONS:-false}" == "true" ]]
}

# GitHub Actions output
gh_output() {
    local name="$1"
    local value="$2"

    if is_github_actions; then
        echo "${name}=${value}" >> "$GITHUB_OUTPUT"
    fi
}

# GitHub Actions annotations
gh_error() {
    if is_github_actions; then
        echo "::error::$*"
    else
        echo "ERROR: $*" >&2
    fi
}

gh_warning() {
    if is_github_actions; then
        echo "::warning::$*"
    else
        echo "WARN: $*" >&2
    fi
}

gh_notice() {
    if is_github_actions; then
        echo "::notice::$*"
    else
        echo "INFO: $*"
    fi
}

# Set job summary
gh_summary() {
    if is_github_actions; then
        echo "$*" >> "$GITHUB_STEP_SUMMARY"
    fi
}

# Usage example
gh_notice "Starting build"
build_result=$(make build 2>&1)
gh_output "build_result" "$build_result"
gh_summary "## Build Complete\n\nStatus: Success"

Azure DevOps Helper

#!/usr/bin/env bash
# azdo-helper.sh - Azure DevOps utilities

set -euo pipefail

# Detect Azure DevOps
is_azure_devops() {
    [[ -n "${TF_BUILD:-}" ]]
}

# Azure DevOps output variable
azdo_output() {
    local name="$1"
    local value="$2"

    if is_azure_devops; then
        echo "##vso[task.setvariable variable=$name]$value"
    fi
}

# Azure DevOps logging
azdo_error() {
    if is_azure_devops; then
        echo "##vso[task.logissue type=error]$*"
    else
        echo "ERROR: $*" >&2
    fi
}

azdo_warning() {
    if is_azure_devops; then
        echo "##vso[task.logissue type=warning]$*"
    else
        echo "WARN: $*" >&2
    fi
}

# Section grouping
azdo_section_start() {
    is_azure_devops && echo "##[section]$*"
}

azdo_section_end() {
    is_azure_devops && echo "##[endsection]"
}

# Usage
azdo_section_start "Running Tests"
test_result=$(npm test)
azdo_output "test_result" "$test_result"
azdo_section_end

Multi-Platform CI Detection

#!/usr/bin/env bash
set -euo pipefail

# Detect CI environment
detect_ci() {
    if [[ "${GITHUB_ACTIONS:-false}" == "true" ]]; then
        echo "github"
    elif [[ -n "${TF_BUILD:-}" ]]; then
        echo "azuredevops"
    elif [[ -n "${GITLAB_CI:-}" ]]; then
        echo "gitlab"
    elif [[ -n "${CIRCLECI:-}" ]]; then
        echo "circleci"
    elif [[ -n "${JENKINS_URL:-}" ]]; then
        echo "jenkins"
    else
        echo "local"
    fi
}

# Universal output
ci_output() {
    local name="$1"
    local value="$2"
    local ci_env
    ci_env=$(detect_ci)

    case "$ci_env" in
        github)
            echo "${name}=${value}" >> "$GITHUB_OUTPUT"
            ;;
        azuredevops)
            echo "##vso[task.setvariable variable=$name]$value"
            ;;
        gitlab)
            echo "${name}=${value}" >> ci_output.env
            ;;
        *)
            echo "export ${name}=\"${value}\""
            ;;
    esac
}

# Universal error
ci_error() {
    local ci_env
    ci_env=$(detect_ci)

    case "$ci_env" in
        github)
            echo "::error::$*"
            ;;
        azuredevops)
            echo "##vso[task.logissue type=error]$*"
            ;;
        *)
            echo "ERROR: $*" >&2
            ;;
    esac
}

Cloud Provider Patterns

AWS Helper Functions

#!/usr/bin/env bash
set -euo pipefail

# Check AWS CLI availability
require_aws() {
    if ! command -v aws &> /dev/null; then
        echo "Error: AWS CLI not installed" >&2
        exit 1
    fi
}

# Get AWS account ID
get_aws_account_id() {
    aws sts get-caller-identity --query Account --output text
}

# Get secret from AWS Secrets Manager
get_aws_secret() {
    local secret_name="$1"

    aws secretsmanager get-secret-value \
        --secret-id "$secret_name" \
        --query SecretString \
        --output text
}

# Upload to S3 with retry
s3_upload_retry() {
    local file="$1"
    local s3_path="$2"
    local max_attempts=3
    local attempt=1

    while ((attempt <= max_attempts)); do
        if aws s3 cp "$file" "$s3_path"; then
            return 0
        fi

        echo "Upload failed (attempt $attempt/$max_attempts)" >&2
        ((attempt++))
        sleep $((attempt * 2))
    done

    return 1
}

# Assume IAM role
assume_role() {
    local role_arn="$1"
    local session_name="${2:-bash-script}"

    local credentials
    credentials=$(aws sts assume-role \
        --role-arn "$role_arn" \
        --role-session-name "$session_name" \
        --query Credentials \
        --output json)

    export AWS_ACCESS_KEY_ID=$(echo "$credentials" | jq -r .AccessKeyId)
    export AWS_SECRET_ACCESS_KEY=$(echo "$credentials" | jq -r .SecretAccessKey)
    export AWS_SESSION_TOKEN=$(echo "$credentials" | jq -r .SessionToken)
}

Azure Helper Functions

#!/usr/bin/env bash
set -euo pipefail

# Check Azure CLI
require_az() {
    if ! command -v az &> /dev/null; then
        echo "Error: Azure CLI not installed" >&2
        exit 1
    fi
}

# Get Azure subscription ID
get_az_subscription_id() {
    az account show --query id --output tsv
}

# Get secret from Azure Key Vault
get_keyvault_secret() {
    local vault_name="$1"
    local secret_name="$2"

    az keyvault secret show \
        --vault-name "$vault_name" \
        --name "$secret_name" \
        --query value \
        --output tsv
}

# Upload to Azure Blob Storage
az_blob_upload() {
    local file="$1"
    local container="$2"
    local blob_name="${3:-$(basename "$file")}"

    az storage blob upload \
        --file "$file" \
        --container-name "$container" \
        --name "$blob_name" \
        --overwrite
}

# Get managed identity token
get_managed_identity_token() {
    local resource="${1:-https://management.azure.com/}"

    curl -sf -H Metadata:true \
        "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=$resource" \
        | jq -r .access_token
}

Parallel Processing Patterns

GNU Parallel

#!/usr/bin/env bash
set -euo pipefail

# Check for GNU parallel
if command -v parallel &> /dev/null; then
    # Process files in parallel
    export -f process_file
    find data/ -name "*.json" | parallel -j 4 process_file {}
else
    # Fallback to bash background jobs
    max_jobs=4
    job_count=0

    for file in data/*.json; do
        process_file "$file" &

        ((job_count++))
        if ((job_count >= max_jobs)); then
            wait -n
            ((job_count--))
        fi
    done

    wait  # Wait for remaining jobs
fi

Job Pool Pattern

#!/usr/bin/env bash
set -euo pipefail

# Job pool implementation
job_pool_init() {
    readonly MAX_JOBS="${1:-4}"
    JOB_POOL_PIDS=()
}

job_pool_run() {
    # Wait if pool is full
    while ((${#JOB_POOL_PIDS[@]} >= MAX_JOBS)); do
        job_pool_wait_any
    done

    # Start new job
    "$@" &
    JOB_POOL_PIDS+=($!)
}

job_pool_wait_any() {
    # Wait for any job to finish
    if ((${#JOB_POOL_PIDS[@]} > 0)); then
        local pid
        wait -n
        # Remove finished PIDs
        for i in "${!JOB_POOL_PIDS[@]}"; do
            if ! kill -0 "${JOB_POOL_PIDS[$i]}" 2>/dev/null; then
                unset 'JOB_POOL_PIDS[$i]'
            fi
        done
        JOB_POOL_PIDS=("${JOB_POOL_PIDS[@]}")  # Reindex
    fi
}

job_pool_wait_all() {
    wait
    JOB_POOL_PIDS=()
}

# Usage
job_pool_init 4
for file in data/*.txt; do
    job_pool_run process_file "$file"
done
job_pool_wait_all

Deployment Patterns

Blue-Green Deployment

#!/usr/bin/env bash
set -euo pipefail

# Blue-green deployment helper
deploy_blue_green() {
    local new_version="$1"
    local health_check_url="$2"

    echo "Starting blue-green deployment: $new_version"

    # Deploy to green (inactive) environment
    echo "Deploying to green environment..."
    deploy_to_environment "green" "$new_version"

    # Health check
    echo "Running health checks..."
    if ! check_health "$health_check_url"; then
        echo "Health check failed, rolling back" >&2
        return 1
    fi

    # Switch traffic to green
    echo "Switching traffic to green..."
    switch_traffic "green"

    # Keep blue as backup for rollback
    echo "Deployment complete. Blue environment kept for rollback."
}

check_health() {
    local url="$1"
    local max_attempts=30
    local attempt=1

    while ((attempt <= max_attempts)); do
        if curl -sf "$url" > /dev/null; then
            return 0
        fi

        echo "Health check attempt $attempt/$max_attempts failed"
        sleep 2
        ((attempt++))
    done

    return 1
}

Canary Deployment

#!/usr/bin/env bash
set -euo pipefail

# Canary deployment with gradual rollout
deploy_canary() {
    local new_version="$1"
    local stages=(5 10 25 50 100)  # Percentage stages

    echo "Starting canary deployment: $new_version"

    for percentage in "${stages[@]}"; do
        echo "Rolling out to $percentage% of traffic..."

        # Update traffic split
        update_traffic_split "$percentage" "$new_version"

        # Monitor for issues
        echo "Monitoring for 5 minutes..."
        if ! monitor_metrics 300; then
            echo "Issues detected, rolling back" >&2
            update_traffic_split 0 "$new_version"
            return 1
        fi

        echo "Stage $percentage% successful"
    done

    echo "Canary deployment complete"
}

monitor_metrics() {
    local duration="$1"
    local end_time=$((SECONDS + duration))

    while ((SECONDS < end_time)); do
        # Check error rate
        local error_rate
        error_rate=$(get_error_rate)

        if ((error_rate > 5)); then
            echo "Error rate too high: $error_rate%" >&2
            return 1
        fi

        sleep 10
    done

    return 0
}

Logging and Monitoring

Structured Logging

#!/usr/bin/env bash
set -euo pipefail

# JSON structured logging
log_json() {
    local level="$1"
    local message="$2"
    shift 2

    local timestamp
    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

    # Build JSON
    local json
    json=$(jq -n \
        --arg timestamp "$timestamp" \
        --arg level "$level" \
        --arg message "$message" \
        --arg script "$SCRIPT_NAME" \
        --argjson context "$(echo "$@" | jq -Rs .)" \
        '{
            timestamp: $timestamp,
            level: $level,
            message: $message,
            script: $script,
            context: $context
        }')

    echo "$json" >&2
}

log_info() { log_json "INFO" "$@"; }
log_error() { log_json "ERROR" "$@"; }
log_warn() { log_json "WARN" "$@"; }

# Usage
log_info "Processing file" "file=/data/input.txt" "size=1024"

Resources

• 12-Factor App Methodology
• Container Best Practices
• CI/CD Best Practices

---

Modern automation requires cloud-native patterns, container awareness, and robust CI/CD integration. These patterns ensure production-ready deployments in 2025.