cicd-deployment

name	cicd-deployment
description	Manage CI/CD pipelines, build processes, deployment configurations, and release workflows. Use when the user says 'set up CI', 'create a pipeline', 'deploy this', 'fix the build', 'GitHub Actions', 'deployment failed', 'create release workflow', 'add a build step', 'configure staging', or 'set up preview deployments'. Also triggers on 'CI/CD', 'continuous integration', 'continuous deployment', 'pipeline configuration', 'build process', 'release management', 'deploy to production', or 'workflow automation'.
version	1.0.0

CI/CD Deployment Skill

Purpose

CI/CD automates the path from code to production. Well-configured pipelines catch bugs before users, enforce quality gates, and make deploys boring. This skill covers pipeline creation, optimization, debugging, deployment strategies, and release management across platforms.

When to Activate

• Setting up CI/CD for a new or existing project
• Debugging failed builds or deployments
• Adding or modifying pipeline stages (lint, test, deploy)
• Configuring deployment targets (staging, preview, production)
• Optimizing build times and reducing CI costs
• Designing release workflows (semantic versioning, changelogs)
• Setting up preview/ephemeral environments per PR
• Implementing rollback procedures

Core Workflow

Step 1: Detect Existing CI/CD

Search the repository for existing configuration:

.github/workflows/*.yml    # GitHub Actions
.circleci/config.yml       # CircleCI
Jenkinsfile                # Jenkins
.gitlab-ci.yml             # GitLab CI
bitbucket-pipelines.yml    # Bitbucket Pipelines
Dockerfile                 # Container builds
docker-compose.yml         # Multi-container orchestration
vercel.json                # Vercel
netlify.toml               # Netlify
fly.toml                   # Fly.io
render.yaml                # Render
railway.json               # Railway
appspec.yml                # AWS CodeDeploy
buildspec.yml              # AWS CodeBuild
cloudbuild.yaml            # Google Cloud Build
azure-pipelines.yml        # Azure DevOps

Also check package.json scripts, Makefile, and Taskfile.yml for build/deploy commands the pipeline may reference.

Step 2: Understand the Stack

Before writing any pipeline config, identify:

• Language & runtime: Node.js, Python, Go, Rust, Java, etc.
• Package manager: npm, pnpm, yarn, pip, poetry, go modules, cargo
• Build tool: webpack, vite, esbuild, tsc, gradle, make
• Test runner: jest, vitest, pytest, go test, cargo test
• Linter/formatter: eslint, prettier, ruff, golangci-lint, clippy
• Deployment target: Vercel, AWS, GCP, Fly.io, Kubernetes, static hosting
• Monorepo tooling: turborepo, nx, lerna, pnpm workspaces

Step 3: Apply or Modify Pipeline Configuration

Generate or modify pipeline config following these principles:

1. Match project conventions -- use the same scripts from package.json/Makefile
2. Fail fast -- run cheapest checks first (lint before full test suite)
3. Cache aggressively -- dependencies, build artifacts, Docker layers
4. Minimize secrets -- use OIDC where possible, scope secrets to environments
5. Pin versions -- actions, Docker images, runtime versions
6. Set timeouts -- every job and long-running step needs an explicit timeout

Step 4: Validate

Before committing pipeline changes:

1. Syntax check -- use actionlint for GitHub Actions, circleci config validate, etc.
2. Verify secret references -- confirm every ${{ secrets.X }} has a corresponding secret configured
3. Confirm scripts exist -- every npm run X or make Y must resolve to a real command
4. Test locally -- use act for GitHub Actions, circleci local execute for CircleCI
5. Dry run -- push to a feature branch first, never modify the default branch pipeline blindly

Pipeline Architecture

A production-grade pipeline has five stages. Not every project needs all of them -- start simple and add stages as the project matures.

Stage 1: Build

• Install dependencies with lockfile (npm ci, pip install -r requirements.txt)
• Enable dependency caching keyed on lockfile hash
• Compile/transpile source code
• Generate build artifacts and pass to downstream jobs

Stage 2: Quality Gate

• Lint source code (eslint, ruff, clippy)
• Type-check (tsc --noEmit, mypy, pyright)
• Run unit tests with coverage reporting
• Security scan dependencies (npm audit, trivy, snyk)
• Check for secrets in code (gitleaks, trufflehog)

Stage 3: Integration

• Run integration tests against real services (database, API)
• Execute database migrations in test environment
• Run E2E tests (Playwright, Cypress) against preview deployment
• Contract testing for microservices

Stage 4: Deploy

• Deploy to preview/staging environment on PR
• Run smoke tests against staging
• Deploy to production on merge to default branch
• Use deployment strategy appropriate to risk (see references/deployment-strategies.md)

Stage 5: Post-Deploy

• Run smoke tests against production
• Health check endpoints
• Notify team (Slack, Discord, email)
• Tag release, generate changelog
• Monitor error rates for regression

Build Optimization

Dependency Caching

Cache dependencies to avoid re-downloading on every build:

• npm/pnpm/yarn: Cache based on lockfile hash
• pip: Cache ~/.cache/pip with requirements hash
• Go: Cache ~/go/pkg/mod with go.sum hash
• Docker: Layer caching, BuildKit cache mounts
• Turborepo/Nx: Remote caching for monorepo builds

See references/github-actions-patterns.md for platform-specific examples.

Parallel Execution

Run independent stages concurrently:

• Lint, type-check, and unit tests can run in parallel
• Different test suites (unit, integration, e2e) can run in parallel
• Multi-platform builds (linux/amd64, linux/arm64) can run in parallel

Conditional Execution

Skip unnecessary work:

• Path filters: Only run frontend tests when frontend code changes
• Skip patterns: [skip ci] in commit message for docs-only changes
• Branch filters: Only deploy from default branch
• Changed file detection: Use tools like dorny/paths-filter or tj-actions/changed-files

Artifact Management

• Upload build artifacts for downstream jobs instead of rebuilding
• Set retention policies to control storage costs
• Use artifact checksums to verify integrity across jobs

Platform-Specific Patterns

Detailed patterns and examples are in the reference documents:

• references/github-actions-patterns.md -- Reusable workflows, caching, matrix builds, environment protection
• references/deployment-strategies.md -- Rolling, blue-green, canary, feature flags, preview environments
• references/rollback-procedures.md -- Platform-specific rollback, post-rollback checklist, when not to rollback

Pipeline Health Checks

Use scripts/check_pipeline_health.sh to audit an existing pipeline configuration for common issues. It checks for:

• Detected CI system and config files
• Referenced scripts that may not exist
• Hardcoded secrets or tokens in pipeline files
• Dockerfile best practices
• Missing lockfiles or .gitignore

Gotchas

Secrets

Never hardcode secrets in pipeline files. Use the platform's secret store (GitHub Secrets, CircleCI Contexts, etc.). Verify that every referenced secret actually exists in the target environment before merging. Use OIDC federation for cloud providers instead of long-lived credentials where possible.

Branch Protection

Pipeline changes on the default branch may require admin review. Always test pipeline changes in a feature branch first. Be aware that some CI platforms only read workflow files from the default branch for certain trigger types.

Build Matrix Explosion

A matrix of 3 OS versions x 3 runtime versions = 9 jobs. Constrain matrices to what you actually deploy. Use include/exclude to target specific combinations. Consider running the full matrix only on release branches.

Docker Cache Invalidation

Order Dockerfile instructions from least to most frequently changing. Copy package.json AND the lockfile before running npm install. Source code copies should come after dependency installation. Use .dockerignore to exclude node_modules, .git, and test fixtures.

Flaky Tests in CI

Investigate environment differences before adding retry logic. Common causes: timing-dependent assertions, shared test state, missing environment variables, DNS resolution differences, file system ordering. Fix the root cause -- retries mask bugs.

CI Cost Management

GitHub Actions minutes are finite on private repos. Use path filters to skip unnecessary runs. Cancel in-progress runs when a new commit is pushed to the same branch. Use self-hosted runners for heavy workloads. Monitor usage regularly.

Timeout Defaults

Set explicit timeouts on every job and long-running step. Platform defaults (6 hours on GitHub Actions) are far too generous. A hanging build that consumes 6 hours of compute is expensive and blocks the pipeline. Typical timeouts: build (15 min), unit tests (10 min), e2e tests (20 min), deploy (10 min).

Environment Parity

CI environments differ from local: different OS, different file system (case sensitivity), different network access, different available tools. Pin tool versions explicitly. Use Docker for reproducibility. Document required environment variables.