ci-cd-and-automation

name	ci-cd-and-automation
description	Automates GitHub Actions quality gates (lint, tsc, test, build, audit), preview deploys, staged rollouts, rollback workflows, and Dependabot. Use when adding or repairing CI pipelines, required PR checks, or deployment automation. Never treat workflow YAML as the place to author the test suite; not for Kubernetes Helm or Argo CD cluster operations.
version	1.0.1

CI/CD and Automation

Overview

Automate quality gates so that no change reaches production without passing tests, lint, type checking, and build. CI/CD is the enforcement mechanism for every other skill — it catches what humans and agents miss, and it does so consistently on every single change.

Shift Left: Catch problems as early in the pipeline as possible. A bug caught in linting costs minutes; the same bug caught in production costs hours. Move checks upstream — static analysis before tests, tests before staging, staging before production.

Faster is Safer: Smaller batches and more frequent releases reduce risk, not increase it. A deployment with 3 changes is easier to debug than one with 30. Frequent releases build confidence in the release process itself.

When to Use

• Setting up a new project's CI pipeline
• Adding or modifying automated checks (lint, type-check, test, build, audit)
• Configuring deployment pipelines (preview, staging, production)
• When a change should trigger automated verification
• Debugging CI failures and feeding errors back to agents
• Establishing rollback mechanisms or feature-flag strategies

Prerequisites

• A repository hosted on GitHub (or equivalent CI platform)
• Node.js 22+ and npm available locally for verifying pipeline steps before pushing
• On Windows host (primary), use PowerShell for local verification commands
• GitHub Secrets (or platform vault) configured for any CI credentials — never hardcode secrets in workflow files
• Branch protection rules available on the repository (requires admin access)

Procedure

1. Define the Quality Gate Pipeline

Every change goes through these gates before merge. No gate can be skipped. If lint fails, fix lint — don't disable the rule. If a test fails, fix the code — don't skip the test.

Pull Request Opened
    │
    ▼
┌─────────────────┐
│   LINT CHECK     │  eslint, prettier
│   ↓ pass         │
│   TYPE CHECK     │  tsc --noEmit
│   ↓ pass         │
│   UNIT TESTS     │  jest/vitest
│   ↓ pass         │
│   BUILD          │  npm run build
│   ↓ pass         │
│   INTEGRATION    │  API/DB tests
│   ↓ pass         │
│   E2E (optional) │  Playwright/Cypress
│   ↓ pass         │
│   SECURITY AUDIT │  npm audit
│   ↓ pass         │
│   BUNDLE SIZE    │  bundlesize check
└─────────────────┘
    │
    ▼
  Ready for review

2. Create the Basic CI Workflow

Create .github/workflows/ci.yml:

# .github/workflows/ci.yml
name: CI

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

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

      - name: Test
        run: npm test -- --coverage

      -  
           

         
           

3. Add Database Integration Tests (if applicable)

Add a separate integration job with a Postgres service container:

  integration:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_DB: testdb
          POSTGRES_USER: ci_user
          POSTGRES_PASSWORD: ${{ secrets.CI_DB_PASSWORD }}
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - run: npm ci
      - name: Run migrations
        run: npx prisma migrate deploy
        env:
          DATABASE_URL: postgresql://ci_user:${{ secrets.CI_DB_PASSWORD }}@localhost:5432/testdb
         
           
        
             

Note: Even for CI-only test databases, use GitHub Secrets for credentials rather than hardcoding values. This builds good habits and prevents accidental reuse of test credentials in other contexts.

4. Add E2E Tests (optional)

  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - run: npm ci
      - name: Install Playwright
        run: npx playwright install --with-deps chromium
      - name: Build
        run: npm run build
      - name: Run E2E tests
        run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

5. Verify Locally Before Pushing (Windows / PowerShell)

Run the same gate sequence locally to catch issues before CI:

npm run lint
npx tsc --noEmit
npm test -- --coverage
npm run build
npm audit --audit-level=high

All commands must exit with code 0 before committing.

6. Configure Preview Deployments

Every PR gets a preview deployment for manual testing:

# Deploy preview on PR (Vercel/Netlify/etc.)
deploy-preview:
  runs-on: ubuntu-latest
  if: github.event_name == 'pull_request'
  steps:
    - uses: actions/checkout@v4
    - name: Deploy preview
      run: npx vercel --token=${{ secrets.VERCEL_TOKEN }}

7. Set Up Staged Rollouts

PR merged to main
    │
    ▼
  Staging deployment (auto)
    │ Manual verification
    ▼
  Production deployment (manual trigger or auto after staging)
    │
    ▼
  Monitor for errors (15-minute window)
    │
    ├── Errors detected → Rollback
    └── Clean → Done

8. Create a Rollback Workflow

Every deployment should be reversible:

# Manual rollback workflow
name: Rollback
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to rollback to'
        required: true

jobs:
  rollback:
    runs-on: ubuntu-latest
    steps:
      - name: Rollback deployment
        run: |
          # Deploy the specified previous version
          npx vercel rollback ${{ inputs.version }}

9. Configure Environment Management

.env.example       → Committed (template for developers)
.env                → NOT committed (local development)
.env.test           → Committed (test environment, no real secrets)
CI secrets          → Stored in GitHub Secrets / vault
Production secrets  → Stored in deployment platform / vault

CI should never have production secrets. Use separate secrets for CI testing.

10. Add Dependabot / Renovate

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: npm
    directory: /
    schedule:
      interval: weekly
    open-pull-requests-limit: 5

11. Configure Branch Protection and PR Checks

• Required reviews: At least 1 approval before merge
• Required status checks: CI must pass before merge
• Branch protection: No force-pushes to main
• Auto-merge: If all checks pass and approved, merge automatically

12. Feed CI Failures Back to Agents

When CI fails, copy the failure output and feed it to the agent:

"The CI pipeline failed with this error:
[paste specific error]
Fix the issue and verify locally before pushing again."

Key patterns:

Lint failure → Agent runs `npm run lint --fix` and commits
Type error  → Agent reads the error location and fixes the type
Test failure → Agent follows debugging-and-error-recovery skill
Build error → Agent checks config and dependencies

13. Optimize the Pipeline (when CI exceeds 10 minutes)

Apply these strategies in order of impact:

Slow CI pipeline?
├── Cache dependencies
│   └── Use actions/cache or setup-node cache option for node_modules
├── Run jobs in parallel
│   └── Split lint, typecheck, test, build into separate parallel jobs
├── Only run what changed
│   └── Use path filters to skip unrelated jobs (e.g., skip e2e for docs-only PRs)
├── Use matrix builds
│   └── Shard test suites across multiple runners
├── Optimize the test suite
│   └── Remove slow tests from the critical path, run them on a schedule instead
└── Use larger runners
    └── GitHub-hosted larger runners or self-hosted for CPU-heavy builds

Example with caching and parallelism:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '22', cache: 'npm' }
      - run: npm ci
      - run: npm run lint

  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '22', cache: 'npm' }
      - run: npm ci
      - run: npx tsc --noEmit

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      -  
         {  ,   }
         
           

14. Feature Flags (decouple deployment from release)

// Simple feature flag pattern
if (featureFlags.isEnabled('new-checkout-flow', { userId })) {
  return renderNewCheckout();
}
return renderLegacyCheckout();

Flag lifecycle: Create → Enable for testing → Canary → Full rollout → Remove the flag and dead code. Flags that live forever become technical debt — set a cleanup date when you create them.

Pitfalls

Rationalization	Reality
"CI is too slow"	Optimize the pipeline (see step 13), don't skip it. A 5-minute pipeline prevents hours of debugging.
"This change is trivial, skip CI"	Trivial changes break builds. CI is fast for trivial changes anyway.
"The test is flaky, just re-run"	Flaky tests mask real bugs and waste everyone's time. Fix the flakiness.
"We'll add CI later"	Projects without CI accumulate broken states. Set it up on day one.
"Manual testing is enough"	Manual testing doesn't scale and isn't repeatable. Automate what you can.

Red flags to watch for:

• No CI pipeline in the project
• CI failures ignored or silenced
• Tests disabled in CI to make the pipeline pass
• Production deploys without staging verification
• No rollback mechanism
• Secrets stored in code or CI config files (not secrets manager)
• Long CI times with no optimization effort

Build Cop role: Designate someone responsible for keeping CI green. When the build breaks, the Build Cop's job is to fix or revert — not the person whose change caused the break. This prevents broken builds from accumulating while everyone assumes someone else will fix it.

Verification

After setting up or modifying CI, verify each item:

• All quality gates are present (lint, types, tests, build, audit)
• Pipeline runs on every PR and push to main
• Failures block merge (branch protection configured)
• CI results feed back into the development loop
• Secrets are stored in the secrets manager, not in code
• Deployment has a rollback mechanism
• Pipeline runs in under 10 minutes for the test suite

Checkable commands (run locally on Windows / PowerShell before pushing):

# Verify all gates pass locally
npm run lint; if ($LASTEXITCODE -ne 0) { Write-Error "Lint failed"; exit 1 }
npx tsc --noEmit; if ($LASTEXITCODE -ne 0) { Write-Error "Type check failed"; exit 1 }
npm test -- --coverage; if ($LASTEXITCODE -ne 0) { Write-Error "Tests failed"; exit 1 }
npm run build; if ($LASTEXITCODE -ne 0) { Write-Error "Build failed"; exit 1 }
npm audit --audit-level=high; if ($LASTEXITCODE -ne 0) { Write-Error "Security audit failed"; exit 1 }
Write-Host "All quality gates passed locally."

Post-push verification:

1. Open a PR and confirm the CI workflow triggers automatically.
2. Confirm all jobs report green (lint, typecheck, test, build, audit).
3. Confirm the PR cannot be merged while any status check is failing.
4. Confirm preview deployment is available (if configured).
5. Confirm rollback workflow is dispatchable (if configured).

Related skills

• debugging-and-error-recovery — Use when CI test failures need root-cause analysis.
• testing-and-validation — Use when writing or expanding the test suite that CI runs.
• code-quality-and-linting — Use when configuring lint and format rules enforced by CI.