---
name: ci-cd-and-automation
description: Set up and enforce CI/CD pipelines: quality gates, test runners in CI, deployment strategies, rollback. Use when creating or modifying build and deploy pipelines, adding automated checks, or debugging CI failures. Not for writing the tests themselves: use test-driven-development. Not for diagnosing an app bug CI surfaced: use systematic-debugging. Not for branch and merge mechanics: use git-workflow-and-versioning.
license: MIT
metadata:
  author: TechTide AI (Alex Cinovoj)
  provenance: rewritten from patterns in addyosmani/agent-skills (MIT)
  category: Delivery & Handoff
---

# CI/CD and Automation

CI is the enforcement mechanism for every other engineering rule: no change reaches production without passing lint, types, tests, and build. Two principles drive everything here. Shift left: a bug caught in lint costs minutes, the same bug in production costs hours. Faster is safer: a deploy with 3 changes debugs easier than one with 30.

## The quality gate pipeline

Every PR passes these gates, in order, before merge:

| Gate | Tool (typical JS/TS) | Blocks merge |
|---|---|---|
| Lint + format | eslint, prettier | yes |
| Type check | tsc --noEmit | yes |
| Unit tests | vitest / jest, with coverage | yes |
| Build | npm run build | yes |
| Integration tests | API/DB tests against a service container | yes |
| E2E (golden paths) | Playwright | yes where present |
| Security audit | npm audit --audit-level=high | yes |
| Bundle size | size check against budget | yes where present |

No gate is skippable. Lint fails: fix the code, not the rule. Test fails: fix the code, not the test. Read references/github-actions.md when writing the actual workflow YAML (basic pipeline, DB service containers, E2E jobs, caching, parallel jobs).

## Setup workflow

1. Add the basic pipeline on day one of the project. Not later.
2. Wire branch protection: required status checks, at least one review, no force-push to main.
3. Add integration and E2E jobs as the surfaces appear.
4. Separate secrets: CI gets test credentials from the secrets manager, never production secrets, never values in code or workflow files.
5. Keep the whole suite under 10 minutes. Over that, optimize in this order: cache dependencies, parallelize jobs, path-filter unrelated work, shard tests with a matrix, move slow tests to a schedule, buy bigger runners.

## The feedback loop

CI's value with agents is the loop: CI fails, the exact failure output goes back to the agent, the agent fixes and verifies locally, pushes again. Patterns: lint failure gets autofix and commit; type error gets read-location-and-fix; test failure goes to systematic-debugging; build error gets a config and dependency check. Never push "hoping CI passes" twice in a row; reproduce the failure locally first.

## Deployment

- **Preview deployments:** every PR gets one for manual verification.
- **Staged rollout:** merge deploys to staging automatically; production deploys after staging verification; monitor errors for a fixed window (15 minutes is a sane default); errors trigger rollback, clean window means done.
- **Feature flags:** decouple deploy from release. Ship dark, enable when ready, canary 1% then 10% then 100%, roll back by flipping the flag instead of redeploying. Every flag gets a cleanup date at creation; immortal flags are tech debt.
- **Rollback:** every deploy must be reversible with one manual workflow taking a version input. If you cannot name the rollback command, you are not ready to deploy.

## Environment hygiene

```
.env.example   committed (template)
.env           never committed (local)
.env.test      committed, no real secrets
CI secrets     GitHub Secrets / vault
Prod secrets   deploy platform / vault
```

## Good vs bad

**Bad:** A flaky E2E test fails one run in five, so the team adds `continue-on-error: true` and merges anyway. Three weeks later a real checkout regression ships through the same green checkmark.

**Good:** The flaky test is quarantined the same day with an issue and an owner, the flake root cause (a race on a network stub) is fixed within the sprint, and the gate stays blocking the whole time.

## Verification

Open a throwaway PR that deliberately breaks one gate (introduce a type error). Expect: CI fails on the type-check job, and the merge button is blocked by branch protection. If the merge is not blocked, required status checks are not configured; fix branch protection before trusting the pipeline. Revert the throwaway change.

## Completion checklist

- [ ] Lint, type check, tests, build, and audit gates all present
- [ ] Pipeline runs on every PR and push to main
- [ ] Branch protection blocks merge on failure
- [ ] Secrets in the secrets manager, none in code or workflow files
- [ ] Rollback mechanism exists and is documented
- [ ] Suite runs in under 10 minutes
- [ ] Flag cleanup dates set for any feature flags introduced

Any box unchecked: not done. Fix or say so.

## Red flags

Verbatim excuses, all invalid:

- "CI is too slow, skip it this once"
- "This change is trivial, it doesn't need checks"
- "The test is flaky, just re-run until green"
- "We'll add CI later, after the MVP"
- "Manual testing covers it"
- "Disable that rule so the pipeline passes"

Closure rule: any change that reaches main without passing every configured gate is a broken process, regardless of whether the change itself was fine. Fix the process the same day: re-enable the gate, and revert or re-verify the change through it.

## Footguns

- **Tests disabled to make CI green.** A skipped test suite is a lie the dashboard tells. Fix: skips require an issue link and an owner; audit for `skip`/`only` markers in CI itself.
- **Production secrets in CI.** One compromised PR workflow exfiltrates them. Fix: CI gets dedicated test credentials; production secrets live only in the deploy platform.
- **Broken main with no owner.** Everyone assumes someone else will fix the build, and breakage compounds. Fix: designate a build cop whose job is fix-or-revert, independent of who broke it.
- **The 45-minute pipeline.** Slow CI trains people to batch changes and bypass checks. Fix: treat pipeline time as a budget; apply the optimization ladder before anyone asks to skip gates.