Trystpilot - DevOps & Infrastructure Governance

Trystpilot — DevOps & Infrastructure Governance

Version: 0.5.0 · Last updated: 2026-02-28 See also: design/devops/cicd.md for pipeline diagram

---

Repository Structure

trystpilot/
├── .github/
│   └── workflows/
│       ├── pr-commit-comments.yml   ✅ active
│       ├── lint.yml                 ❌ planned
│       ├── typecheck.yml            ❌ planned
│       ├── tests.yml                ❌ planned
│       ├── deps.yml                 ❌ planned
│       └── release.yml              ❌ planned
├── app/                             Next.js App Router
├── design/                          Mermaid architecture diagrams
│   ├── architecture/
│   ├── business/
│   ├── devops/
│   ├── governance/
│   └── product/
├── docs/                            Documentation hub
│   ├── CHANGELOG.md
│   ├── ARCHITECTURE.md
│   ├── DEVOPS.md                    (this file)
│   ├── SECURITY.md
│   └── index.md
├── .env.example                     Canonical env var reference
├── CLAUDE.md                        AI context (updated each commit)
├── ROADMAP.md                       Milestone-driven roadmap
└── README.md                        Quick-start

---

Branching Model

Branch	Role	Deploy target
main	Production	trystpilot.xyz
development	Integration / staging	Preview URL
claude/<name>-<id>	Agent feature branches	Preview URL
hotfix/<name>	Emergency prod fixes	→ main directly

Rules:

• No direct push to main or development.
• All changes via PR.
• claude/* branches merge into development; development merges into main on release.
• Hotfixes branch from main and merge back to both main and development.

---

CI/CD Workflow

Currently Active

Workflow	File	Trigger
PR commit summary comment	pr-commit-comments.yml	push on any open PR

Planned (Phase 1)

Workflow	Purpose	Blocking?
lint.yml	ESLint + Prettier check	Yes — PR gate
typecheck.yml	tsc --noEmit	Yes — PR gate
tests.yml	vitest run	Yes — PR gate
deps.yml	npm audit --audit-level=high	Yes — PR gate
secrets.yml	git-secrets / Gitleaks scan	Yes — push gate
changelog.yml	Enforce docs/CHANGELOG.md entry on PRs to main	Yes — PR gate
release.yml	Auto-tag + GitHub release on main merge	No — informational

---

Environment Separation

Variable	development	production
DATABASE_URL	Dev/test DB	Prod DB
ADMIN_SECRET	Not required locally	Required
NEXT_PUBLIC_CF_ANALYTICS_TOKEN	Optional	Required
UPSTASH_REDIS_REST_URL	Optional	Required
UPSTASH_REDIS_REST_TOKEN	Optional	Required
HCAPTCHA_SECRET	Optional	Required

All secrets set in Vercel Project Settings → Environment Variables. Never in code. Never in .env files committed to git (.gitignore excludes .env* except .env.example).

---

Secret Management

1. .env.example — canonical list of every required variable. Updated whenever a new env var is introduced. No values, only keys + comments.
2. Vercel Environment Variables — production and preview scoped separately.
3. Local development — cp .env.example .env.local, fill in dev credentials.
4. CI secrets — stored as GitHub Actions Secrets, referenced via ${{ secrets.VAR_NAME }}.

Gitleaks / git-secrets scan planned to block accidental commits of secrets.

---

Semantic Versioning Policy

Format: MAJOR.MINOR.PATCH — current: 0.5.0

Bump	Trigger
PATCH (x.x.+1)	Bug fix, dependency update, copy/doc change
MINOR (x.+1.0)	New feature, non-breaking API addition, schema additive migration
MAJOR (+1.0.0)	Breaking change, destructive DB migration, major UX redesign

All releases tagged vMAJOR.MINOR.PATCH on main. GitHub Release created automatically by release.yml (planned).

---

Database Migration Governance

Current: Manual SQL applied directly to production. Risky — must change before v1.0.

Target approach (Phase 1):

1. Migrations stored in lib/db/migrations/ as numbered SQL files (001_initial.sql, 002_add_respect_weight.sql).
2. Applied via node-pg-migrate or db-migrate in a npm run migrate script.
3. CI runs npm run migrate:dry-run on PRs to detect schema conflicts.
4. Production migrations run as a Vercel Build step or manual deploy step (not auto-applied on deploy).

---

Monitoring Stack

Tool	Monitors	Status
Vercel Analytics	Page views, Core Web Vitals	✅ Active
Cloudflare Analytics	CDN hits, request geography	✅ Active
Vercel Function logs	API errors, cold starts	✅ Basic
Sentry	Runtime errors, stack traces	❌ Planned Phase 1
Checkly / Better Uptime	Uptime checks, synthetic monitoring	❌ Planned Phase 1
Railway Metrics	DB CPU, memory, connections	✅ Basic

---

Governance Checklist

Per-PR Requirements (current)

• Commit message follows format: type(scope): description
• CLAUDE.md updated if implementation state changes
• No secrets in diff
• No console.log left in production code paths

Per-PR Requirements (Phase 1, after CI gates added)

• All lint checks pass
• TypeScript compiles without errors
• Tests pass (when test framework added)
• npm audit shows no high/critical vulnerabilities
• docs/CHANGELOG.md has an entry (PRs targeting main only)

Per-Release Requirements

• Version bumped in package.json
• docs/CHANGELOG.md updated with release notes
• CLAUDE.md updated (version + date)
• Git tag pushed (vMAJOR.MINOR.PATCH)
• GitHub Release created with changelog