Building a Modern CI/CD Pipeline: From Code to Production

A CI/CD pipeline isn't a YAML file. It's the backbone of your engineering organization's ability to ship software reliably. A well-designed pipeline catches bugs before they reach production, enforces code quality standards automatically, and gives the team confidence that any commit on main can be deployed safely.

This guide walks through building a production-grade CI/CD pipeline using GitHub Actions for orchestration, Docker for containerization, and Kubernetes for deployment. We'll cover the architecture decisions that matter, the testing strategies that provide actual safety, and the monitoring practices that close the feedback loop.

Pipeline Architecture

A modern CI/CD pipeline has five stages. Each stage gates the next — a failure at any point stops the pipeline and notifies the team.

1. Build — Compile code, install dependencies, generate artifacts
2. Test — Unit tests, integration tests, security scans
3. Package — Build container images, tag with commit SHA
4. Deploy — Roll out to staging, then production
5. Verify — Health checks, smoke tests, metric validation

The key principle is immutable artifacts. The Docker image built in stage 3 is the exact image that runs in staging and production. You never rebuild for different environments — you change configuration, not code.

GitHub Actions: Workflow Structure

Here is the complete workflow file for a Node.js application. We'll break down each section.

name: CI/CD Pipeline
on:
 push:
 branches: [main]
 pull_request:
 branches: [main]

env:
 REGISTRY: ghcr.io
 IMAGE_NAME: ${{ github.repository }}

jobs:
 test:
 runs-on: ubuntu-latest
 strategy:
 matrix:
 node-version: [20, 22]
 steps:
 - uses: actions/checkout@v4

 - uses: actions/setup-node@v4
 with:
 node-version: ${{ matrix.node-version }}
 cache: 'npm'

 - run: npm ci

 - name: Type check
 run: npx tsc --noEmit

 - name: Lint
 run: npm run lint

 - name: Unit tests
 run: npm test -- --coverage
 env:
 CI: true

 - name: Upload coverage
 if: matrix.node-version == 22
 uses: actions/upload-artifact@v4
 with:
 name: coverage
 path: coverage/

 integration-test:
 runs-on: ubuntu-latest
 needs: test
 services:
 postgres:
 image: postgres:16
 env:
 POSTGRES_DB: testdb
 POSTGRES_USER: test
 POSTGRES_PASSWORD: test
 ports:
 - 5432:5432
 options: >-
 --health-cmd pg_isready
 --health-interval 10s
 --health-timeout 5s
 --health-retries 5
 redis:
 image: redis:7
 ports:
 - 6379:6379
 steps:
 - uses: actions/checkout@v4
 - uses: actions/setup-node@v4
 with:
 node-version: 22
 cache: 'npm'
 - run: npm ci
 - name: Run integration tests
 run: npm run test:integration
 env:
 DATABASE_URL: postgresql://test:test@localhost:5432/testdb
 REDIS_URL: redis://localhost:6379

 build-and-push:
 runs-on: ubuntu-latest
 needs: [test, integration-test]
 if: github.event_name == 'push' && github.ref == 'refs/heads/main'
 permissions:
 contents: read
 packages: write
 outputs:
 image-tag: ${{ steps.meta.outputs.tags }}
 steps:
 - uses: actions/checkout@v4

 - uses: docker/login-action@v3
 with:
 registry: ${{ env.REGISTRY }}
 username: ${{ github.actor }}
 password: ${{ secrets.GITHUB_TOKEN }}

 - id: meta
 uses: docker/metadata-action@v5
 with:
 images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
 tags: |
 type=sha,prefix=

 - uses: docker/build-push-action@v5
 with:
 context: .
 push: true
 tags: ${{ steps.meta.outputs.tags }}
 cache-from: type=gha
 cache-to: type=gha,mode=max

Several design decisions in this workflow are worth highlighting:

Matrix testing: Running tests against Node 20 and 22 catches compatibility issues before they bite you in production upgrades. The cost is minimal — GitHub Actions runs matrix jobs in parallel.

Service containers: Integration tests run against real PostgreSQL and Redis instances, not mocks. Service containers start automatically and are health-checked before tests run. This catches issues that mocks silently pass, such as incorrect SQL syntax, missing indexes, or Redis data structure mismatches.

This connects to the ideas in Clean Architecture in Practice: Hexagonal, Onion, and Ports-.

SHA-based tags: Images are tagged with the Git commit SHA, not latest or version numbers. This makes every deployment traceable to an exact commit and eliminates tag mutation issues.

Docker: Production-Ready Images

Container image quality directly affects deployment speed, security posture, and runtime performance. Here is a multi-stage Dockerfile that produces a minimal production image.

FROM node:22-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --ignore-scripts
COPY .
RUN npm run build
RUN npm prune --production

FROM gcr.io/distroless/nodejs22-debian12
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

EXPOSE 3000
USER nonroot
CMD ["dist/server.js"]

The multi-stage build separates build dependencies from runtime dependencies. The final image uses Google's distroless base, which contains only the Node.js runtime — no shell, no package manager, no utilities an attacker could exploit. The resulting image is typically 80-120 MB compared to 400+ MB for a standard node:22 image.

Running as nonroot prevents privilege escalation attacks inside the container. This is a security baseline, not an option.

Kubernetes: Deployment Strategy

The deployment configuration determines how your application rolls out and how it recovers from failures. Here is a production deployment manifest.

apiVersion: apps/v1
kind: Deployment
metadata:
 name: api-server
spec:
 replicas: 3
 strategy:
 type: RollingUpdate
 rollingUpdate:
 maxSurge: 1
 maxUnavailable: 0
 selector:
 matchLabels:
 app: api-server
 template:
 spec:
 containers:
 - name: api
 image: ghcr.io/org/api:abc123f
 ports:
 - containerPort: 3000
 resources:
 requests:
 cpu: 250m
 memory: 256Mi
 limits:
 cpu: 500m
 memory: 512Mi
 readinessProbe:
 httpGet:
 path: /health
 port: 3000
 initialDelaySeconds: 5
 periodSeconds: 10
 livenessProbe:
 httpGet:
 path: /health
 port: 3000
 initialDelaySeconds: 15
 periodSeconds: 20
 env:
 - name: NODE_ENV
 value: production
 - name: DATABASE_URL
 valueFrom:
 secretKeyRef:
 name: api-secrets
 key: database-url

maxUnavailable: 0 ensures zero downtime during deployments. Kubernetes brings up a new pod before terminating an old one. Combined with readiness probes, traffic only routes to pods that have confirmed they can serve requests.

Resource requests and limits prevent noisy-neighbor problems and enable the Kubernetes scheduler to make intelligent placement decisions. Set requests based on observed P50 usage and limits based on P99 peaks, with headroom.

Related reading: Developer Experience Metrics: Lead Time, DORA Metrics, and E.

Testing Strategy

The testing pyramid is still the right model, but the ratio has shifted. Modern applications benefit from more integration tests and fewer unit tests than the traditional pyramid suggests.

The critical insight is that integration tests with real databases catch an entire class of bugs that unit tests can't: schema mismatches, transaction isolation issues, query performance problems, and constraint violations. The CI workflow above provisions real PostgreSQL and Redis containers specifically for this reason.

Security scanning runs in parallel with other test jobs using tools like Trivy for container scanning and npm audit for dependency vulnerabilities. These should block deployment, not just warn.

Deployment Patterns

Three deployment patterns cover the majority of production needs:

Rolling deployments (shown above) are the default. They work well for stateless services where any version can handle any request. The maxSurge/maxUnavailable settings control the rollout speed.

Blue-green deployments maintain two identical environments. Traffic switches atomically from the old version (blue) to the new version (green) after verification. This enables instant rollback by switching back to blue. The cost is double the infrastructure during the transition.

Canary deployments route a small percentage of traffic (typically 1-5%) to the new version first. If error rates and latency remain stable after an observation period, traffic gradually shifts to the new version. This catches issues that only manifest under production load patterns.

Related reading: Secrets Management: HashiCorp Vault, AWS Secrets Manager, an.

# Canary with Argo Rollouts
apiVersion: argoproj.io/v1alpha1
kind: Rollout
spec:
 strategy:
 canary:
 steps:
 - setWeight: 5
 - pause: { duration: 5m }
 - setWeight: 25
 - pause: { duration: 10m }
 - setWeight: 75
 - pause: { duration: 10m }
 analysis:
 templates:
 - templateName: success-rate
 startingStep: 2

Production Monitoring

A deployment without monitoring is a deployment you can't learn from. The monitoring stack should answer three questions: Is the service healthy? Is it performing well? What changed?

Health endpoints report application readiness. A health check should verify database connectivity, cache availability, and critical dependency access — not just return 200 OK.

Metrics track the four golden signals: latency (P50, P95, P99), traffic (requests/second), error rate (5xx percentage), and saturation (CPU, memory, connection pool utilization). Prometheus plus Grafana is the standard open-source stack. Set alerts on P99 latency and error rate, not averages.

Structured logging makes debugging possible. Every log entry should include a request ID, timestamp, service name, and severity level. Use JSON format for machine parsing. Correlate logs across services using distributed tracing (OpenTelemetry).

Pipeline Anti-Patterns

These patterns consistently cause pipeline failures and deployment incidents:

• Building different artifacts per environment. — If your staging build is different from your production build, staging isn't actually testing what ships.
• Skipping integration tests to speed up the pipeline. — The time saved is borrowed against incident response time later.
• Using latest tags. — Tag mutation makes deployments non-deterministic and rollbacks impossible.
• Manual approval gates for every deployment. — These create bottlenecks and incentivize batching changes, which increases deployment risk.
• Not monitoring after deployment. — A deploy without automated verification is a hope-driven process.

The goal of CI/CD isn't automation. It's confidence. Every stage of the pipeline should increase your confidence that this code is safe to run in production.

Start with the simplest pipeline that provides real safety — build, test, deploy — and add complexity only when you have evidence that the current pipeline is insufficient. An overengineered pipeline that nobody maintains is worse than a simple one that actually runs.