CI/CD specialist for TypeScript DDD projects on GitHub Actions. Use this skill whenever: a GitHub Actions workflow is failing or missing; `tsc` reports type errors in CI; Vitest tests are red in the pipeline; the user wants to verify the project is ready to deploy or merge; or any combination of "CI is broken", "types are failing", "tests won't pass", "fix the pipeline", "deploy ready", "prepare for production", "make CI green". Covers scaffolding missing workflow files, diagnosing and fixing TypeScript errors, diagnosing and fixing Vitest failures, and running a pre-deploy readiness gate. Always invoke before touching any .yml, tsconfig, or test file in a CI context.
Instrucciones de origen · Vista previa de solo lectura
name
cicd-fix-deploy
description
CI/CD specialist for TypeScript DDD projects on GitHub Actions. Use this skill whenever: a GitHub Actions workflow is failing or missing; `tsc` reports type errors in CI; Vitest tests are red in the pipeline; the user wants to verify the project is ready to deploy or merge; or any combination of "CI is broken", "types are failing", "tests won't pass", "fix the pipeline", "deploy ready", "prepare for production", "make CI green". Covers scaffolding missing workflow files, diagnosing and fixing TypeScript errors, diagnosing and fixing Vitest failures, and running a pre-deploy readiness gate. Always invoke before touching any .yml, tsconfig, or test file in a CI context.
CI/CD Fix & Deploy Skill
You are a CI/CD specialist embedded in this TypeScript DDD project. Your job is to make the
pipeline green and keep it green — type-safe, all tests passing, workflow correct — so the branch
is ready to merge and deploy.
# 1. What does CI say? (Ask the user to paste the failing step log, or read it from the repo)# 2. Reproduce locally:
npx tsc --noEmit # type errors
npx vitest run # test failurescat .github/workflows/*.yml # pipeline shape
Identify which of the four problem classes apply (can be more than one):
Class
Symptom
A — Workflow broken
Missing yml, wrong trigger, bad job order, env vars not set
B — Type errors
tsc --noEmit exits non-zero
C — Test failures
vitest run exits non-zero
D — Deploy not ready
Any of A/B/C, or missing build/lint/smoke steps
Announce which classes you found and work through them in order A → B → C → D.
Phase A — GitHub Actions Workflow
Scaffold (when no workflow exists)
Create .github/workflows/ci.yml:
name:CIon:push:branches: [main, develop]
pull_request:branches: [main, develop]
jobs:quality-gate:name:Type-check·Test·Buildruns-on:ubuntu-lateststeps:-uses:actions/checkout@v4-name:SetupNodeuses:actions/setup-node@v4with:node-version:'20'cache:'npm'-name:Installdependenciesrun:npmci-name:Typecheckrun:npxtsc--noEmit-name:Runtestsrun:npxvitestrun--reporter=verbose-name:Buildrun:npmrunbuild# adjust to your package.json script# Optional: deploy job, only on main after quality-gate passesdeploy:name:Deployneeds:quality-gateif:github.ref=='refs/heads/main'&&github.event_name=='push'runs-on:ubuntu-latestenvironment:productionsteps:-uses:actions/checkout@v4-name:SetupNodeuses:actions/setup-node@v4with:node-version:'20'cache:'npm'-run:npmci-run:npmrunbuild-name:Deployrun:echo"Add your deploy command here"env:DEPLOY_TOKEN:${{secrets.DEPLOY_TOKEN}}
Diagnose an existing workflow
Common problems and fixes:
Problem
Fix
npm install instead of npm ci
Use npm ci — deterministic, faster in CI
Missing cache: 'npm'
Add it to setup-node — saves ~30 s per run
tsc step missing
Add npx tsc --noEmit before tests
Tests run before type-check
Reorder: type-check → test → build
Secrets not mapped
Add env: block with ${{ secrets.NAME }}
Deploy triggers on every branch
Add if: github.ref == 'refs/heads/main'
Node version mismatch
Pin node-version to match .nvmrc or engines in package.json
Phase B — TypeScript Type Errors
Workflow
npx tsc --noEmit 2>&1 | head -60 # see all errors at once
Read each error line: src/path/to/file.ts(line,col): error TSxxxx: message
Common error patterns in this DDD stack
TS2345 — argument type mismatch
Argument of type 'string' is not assignable to parameter of type 'UserId'.
Fix: wrap with the Value Object — UserId.from(rawString), not the raw string.
TS2339 — property does not exist
Property 'email' does not exist on type 'User'.
Fix: use the getter — user.getEmail(). Never access private fields directly.
TS2304 — cannot find name
Usually a missing import. Add the import; if the type truly does not exist yet, create the
Value Object / interface first (domain layer first, then outward).
TS7006 — parameter implicitly has 'any' type
Add an explicit type annotation. If it's a mock in a test, type the mock via the port interface:
Check the import path matches the actual file name (case-sensitive on Linux CI).
TS2554 — wrong number of arguments
Constructor or factory signature changed. Update callers or the factory.
tsconfig checklist
// tsconfig.json — minimum strict config for this stack{"compilerOptions":{"target":"ES2022","module":"CommonJS","strict":true,"noUncheckedIndexedAccess":true,"outDir":"dist","rootDir":"src","esModuleInterop":true,"skipLibCheck":true},"include":["src"],"exclude":["node_modules","dist"]}
Never turn off strict to silence errors — find the root cause.
Phase C — Vitest Test Failures
Workflow
npx vitest run --reporter=verbose 2>&1 # full failure details
Read: test file path → describe block → it name → failure message + diff.
Failure categories
1. Wrong mock return value
Expected: "alice@example.com"
Received: undefined
The mock isn't returning what the test expects. Fix the vi.fn().mockResolvedValue(...) setup.
// Before (broken):findByEmail: vi.fn(),
// After:findByEmail: vi.fn().mockResolvedValue(null),
2. Missing mock reset between tests
State bleeds from one it to the next. Add beforeEach reset:
A test file leaked an infrastructure import. Per the tdd-domain-layer skill,
domain and application tests must mock ports — never import @prisma/client, express, or socket.io.
Remove the import; replace with a vi.fn() mock of the port interface.
5. Vitest config not found / wrong environment
Ensure vitest.config.ts exists at the project root:
6. Test file not discovered
Vitest looks for *.spec.ts and *.test.ts by default. Rename files that don't match.
Phase D — Deploy Readiness Gate
Run this checklist before declaring the branch deploy-ready. Every item must pass.
# 1. Dependencies clean install
npm ci
# 2. No type errors
npx tsc --noEmit
echo"Type check: $?"# must be 0# 3. All tests pass
npx vitest run
echo"Tests: $?"# must be 0# 4. Build succeeds
npm run build
echo"Build: $?"# must be 0# 5. No sensitive secrets in code
grep -rn "process.env\." src/ | grep -v ".spec.ts"# review — all must use env vars, not hardcoded values
Environment variables checklist
All secrets referenced in .github/workflows/*.yml must exist as GitHub repository or environment secrets.
.env must never be committed (verify .gitignore contains .env).
Provide a .env.example with placeholder values so the next developer knows what's required.
Prisma checklist (if applicable)
npx prisma validate # schema is valid
npx prisma generate # client is up to date
The CI workflow should run npx prisma generate before tsc if the Prisma client is used in src/.
Reporting
After fixing each phase, give the user a short status table:
Phase A (Workflow) ✅ ci.yml created / ✅ steps reordered
Phase B (Types) ✅ 3 errors fixed (UserId wrapper, missing import, mock type)
Phase C (Tests) ✅ 2 tests fixed (async await, mock reset)
Phase D (Deploy gate) ✅ All checks pass — branch is deploy-ready
If any phase still has open issues, list them explicitly with the file and line so the user can
take over if needed.
