devops

DevOps & CI/CD — pnpm / GitHub Actions

Staff Engineer standard: CI is the contract with main — green is mandatory, automation enforces it.

---

1. Core Principles

✅ Every PR runs the full pipeline before merge
✅ Cache dependencies — slow CI loses signal
✅ Fail fast: lint → test → build → audit
✅ Pin action versions (e.g. @v4), avoid @latest
✅ Secrets in GitHub Secrets, never in workflow YAML
✅ Required status checks on protected branches
❌ Never merge red. Never disable failing checks to ship

---

2. CI Pipeline (Minimum Standard)

1. Lint      → Code style + ESLint rules
2. Typecheck → tsc --noEmit
3. Test      → Unit + integration (Vitest)
4. Build     → Verify compilation
5. Audit     → Security vulnerabilities (pnpm audit)

Order matters: cheap checks first, expensive last. Lint catches 80% of issues in seconds.

---

3. GitHub Actions — Reference Workflow

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

on:
  push:
    branches: [main]
  pull_request:

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

      - uses: pnpm/action-setup@v4
        with:
          version: 9
          run_install: false

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm typecheck
      - run: pnpm test
      - run: pnpm build
      - run: pnpm audit --audit-level=high

Rules:

• --frozen-lockfile — fail if pnpm-lock.yaml drifts (CI must match lockfile exactly)
• cache: "pnpm" — speeds up subsequent runs ~10x
• Pin pnpm/action-setup@v4 and actions/setup-node@v4 to majors

---

4. Branch Naming (mirrors code-git skill)

feature/user-authentication    # New features
fix/api-timeout-error          # Bug fixes
hotfix/security-patch          # Critical production fixes
refactor/database-queries      # Internal cleanup
docs/update-readme             # Documentation only
chore/update-eslint            # Maintenance

Lowercase, hyphens, 3-5 words. Branch name should explain the change, not the ticket.

---

5. When CI Fails

NEVER:  Merge when CI is red
NEVER:  Disable a failing check to unblock yourself
NEVER:  Add `if: always()` to skip a step you don't understand
ALWAYS: Reproduce locally first — `pnpm <step>` with same Node version
ALWAYS: Push the fix, wait for green, then merge

Common failure patterns:

Symptom	Likely cause	Fix
frozen-lockfile error	Lockfile out of sync	Run pnpm install locally, commit pnpm-lock.yaml
Test passes local, fails CI	Timezone / locale / flaky timing	Pin TZ=UTC in workflow env, mock dates
Build OOM	Memory-heavy bundler step	Add NODE_OPTIONS=--max-old-space-size=4096
Audit fails on transitive dep	Upstream advisory	Override via pnpm.overrides in package.json

---

6. Secrets & Environment

# Reference, never inline
- run: pnpm deploy
  env:
    SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}

Rules:

• Secrets live in Settings → Secrets and variables → Actions
• Never echo $SECRET — masked in logs but leaks via set -x or error dumps
• Use Environments for prod secrets — adds required reviewers + deploy gates
• Rotate any secret accidentally committed (assume compromise)

---

7. Required Status Checks

Configure in Settings → Branches → Branch protection rules for main:

[ ] Require pull request before merging
[ ] Require approvals: 1+
[ ] Require status checks to pass: ci / ci
[ ] Require branches to be up to date before merging
[ ] Do not allow bypassing the above settings

No bypass — not even for admins. The whole point is automated enforcement.

---

8. Quick Checklist

[ ] Workflow runs on push to main + all PRs
[ ] pnpm cache enabled (cache: "pnpm")
[ ] --frozen-lockfile in install step
[ ] Lint, typecheck, test, build, audit all run
[ ] Secrets via ${{ secrets.X }} — never inline
[ ] Action versions pinned (@v4, not @latest)
[ ] Main protected: PR required, CI required, no bypass
[ ] Failure modes documented in README or runbook