CI/CD Pipeline Blueprint with GitHub Actions

## ROLE
You are a DevOps engineer and CI/CD specialist with deep expertise in GitHub Actions, having designed and maintained pipelines for organizations ranging from 5-person startups to 500+ engineer enterprises. You understand workflow optimization, caching strategies, matrix builds, reusable workflows, and security best practices for CI/CD. You have experience deploying to AWS, GCP, Azure, Vercel, and bare-metal environments through GitHub Actions, and you prioritize fast feedback loops, cost efficiency, and pipeline reliability.

## OBJECTIVE
Design a complete CI/CD pipeline using GitHub Actions for [PROJECT NAME] — a [TECH STACK DESCRIPTION] application. The pipeline should handle the full software delivery lifecycle from code push to production deployment across [ENVIRONMENTS: dev/staging/production]. The pipeline must enforce quality gates, security checks, and approval workflows while keeping build times under [TARGET BUILD TIME] minutes.

## TASK

### Section 1: Workflow Architecture & Trigger Strategy
- Design the overall workflow architecture: which workflows trigger on which events (push, PR, release, schedule, manual dispatch)
- Create a branching strategy integration: how the pipeline maps to your Git flow (feature branches → dev → staging → main/production)
- Plan workflow composition: monolithic vs. modular workflows, reusable workflow strategy, and composite actions
- Define concurrency controls: cancel in-progress runs for the same branch, queue production deployments
- Establish workflow permissions: least-privilege GITHUB_TOKEN permissions for each job

### Section 2: Build & Test Stage
- Design the build job: checkout, dependency installation with caching (node_modules, pip cache, Go modules, etc.), compilation, and artifact generation
- Create a matrix build strategy for multi-version or multi-platform testing
- Implement test parallelization: splitting test suites across runners for faster feedback
- Configure test reporting: JUnit/XML report parsing, coverage report generation, and PR comment integration
- Design the artifact strategy: what to build once and reuse across stages (Docker images, compiled binaries, static assets)
- Implement build caching: dependency caching, layer caching for Docker builds, and incremental compilation

### Section 3: Quality & Security Gates
- Integrate linting and code formatting checks: ESLint, Prettier, Black, golangci-lint, etc.
- Add static analysis: SonarQube/SonarCloud integration, CodeQL analysis, or Semgrep
- Implement dependency vulnerability scanning: Dependabot, Snyk, or Trivy for container images
- Add secret scanning and credential leak detection
- Design license compliance checking for open-source dependencies
- Configure SAST and DAST integration appropriate for [TECH STACK DESCRIPTION]
- Set quality gate thresholds: minimum code coverage, maximum critical vulnerabilities, linting error tolerance

### Section 4: Container & Artifact Publishing
- Design the Docker build workflow: multi-stage builds, build arguments, layer caching with BuildKit
- Implement image tagging strategy: semantic versioning, git SHA, branch-based tags, and latest tag management
- Configure container registry push: GitHub Container Registry (ghcr.io), AWS ECR, Docker Hub, or GCP Artifact Registry
- Add image signing and provenance attestation (Sigstore/Cosign)
- Design artifact versioning and retention policies
- Implement image scanning before publishing (Trivy, Grype)

### Section 5: Deployment Stages
- Design the deployment workflow for each environment:
  - Development: automatic deployment on merge to dev branch, ephemeral preview environments for PRs
  - Staging: automatic deployment on merge to staging branch, full integration test suite execution
  - Production: manual approval gate, deployment with health checks, automatic rollback on failure
- Implement deployment strategies: rolling update, blue-green, or canary with traffic shifting
- Configure environment secrets and variables management (GitHub Environments)
- Add smoke tests and health checks post-deployment
- Design database migration handling within the deployment pipeline
- Create rollback workflows: manual trigger and automatic rollback on health check failure

### Section 6: Notifications, Monitoring & Maintenance
- Configure notifications: Slack/Discord/Teams alerts for pipeline failures, deployment completions, and security findings
- Design pipeline metrics collection: build times, success rates, deployment frequency, and lead time
- Create scheduled maintenance workflows: dependency updates (Dependabot), infrastructure drift detection, and cleanup jobs
- Implement cost optimization: self-hosted runners strategy, spot instance usage, and runner right-sizing
- Design a workflow debugging and troubleshooting guide with common failure patterns and resolutions

## OUTPUT FORMAT
Provide complete, copy-paste ready YAML workflow files for each pipeline stage with inline comments explaining each step. Include a workflow dependency diagram described in text showing the relationship between workflows. Provide a README-style setup guide covering required secrets, environment configuration, and initial setup steps. Include performance optimization tips and cost estimates for GitHub Actions minutes.

## CONSTRAINTS
- All secrets must be managed through GitHub Environments or encrypted secrets — never hardcoded
- Pipeline must be idempotent — safe to re-run at any point without side effects
- Build times must target under [TARGET BUILD TIME] minutes for the full pipeline
- Workflows must be maintainable by developers, not just DevOps specialists
- Include error handling and retry logic for flaky steps (network calls, external services)
- All third-party actions must be pinned to specific SHA commits for supply chain security