DevOps Guidelines

When to Use

Use for DevOps, platform, container, pipeline, or release tasks - any work that touches infrastructure, deployment, CI/CD, Docker, Kubernetes, health checks, rollback, feature flags, production readiness, or mobile release workflows.

Numbered Workflow

1. Assess - identify workload type, target provider/environment, acceptance criteria, and risk level.
2. Classify - select applicable sections (deployment strategy, Docker, K8s, CI/CD, health, config, rollback, feature flags, mobile) based on workload/provider/environment.
3. Plan - for each selected section, define concrete steps, validation checks, and rollback triggers.
4. Apply - execute the plan, running validation at each gate (lint -> typecheck -> unit -> integration -> preview -> smoke).
5. Verify - confirm health endpoints, monitoring, rollback capability, and documented outcome.
6. Rollback-ready - ensure a tested rollback path exists before declaring success.

Edge Cases

• Idempotent re-run: workflow must be safe to execute multiple times without side effects.
• Missing credentials: fail fast with clear error; never proceed with partial auth.
• Workload without health endpoint: deploy but flag as incomplete; require health endpoint before production promotion.
• Image digest pinning: always pin by digest (image@sha256:...) not tag for production.
• Phased rollout rollback: if canary/blue-green rollout fails, revert traffic split instantly; do not wait for full rollback.

Apply only sections relevant to workload/provider/environment/acceptance criteria. Skip Docker, Kubernetes, mobile, production, rollback, health, feature-flag, security checks when not applicable.

Deployment strategy

• Rolling (default): gradual, zero-downtime replacement.
• Blue-green: duplicate environments, atomic cutover, instant rollback, 2x infra.
• Canary: route small % first; requires traffic splitting.

Docker

• Pin base-image tags (node:22-alpine); NEVER :latest.
• Multi-stage builds + non-root user. Copy deps first for caching.
• .dockerignore: node_modules, .git, tests. Define HEALTHCHECK + resource limits.

Kubernetes

Configure startup, readiness, liveness probes with workload-appropriate initial delays/thresholds.

CI/CD

• PR: lint -> typecheck -> unit -> integration -> preview.
• Main: build -> staging -> smoke -> production.

Health and shutdown

• Simple: GET /health -> { "status": "ok" }.
• Detailed: dependencies, uptime, version.
• Services MUST expose meaningful health + gracefully handle SIGTERM when workload requires it.

Configuration

Use environment variables (Twelve-Factor), separated by environment. Validate at startup + fail fast. NEVER commit secrets or hard-code NODE_ENV=production.

Rollback

• Kubernetes: kubectl rollout undo.
• Vercel: vercel rollback.
• Docker: redeploy previous pinned image.

Feature Flags

• Lifecycle: create -> enable -> 5% -> 25% -> 50% -> 100% -> remove flag + dead code.
• Every flag MUST have owner, expiration, rollback trigger. Remove within two weeks.

Checklists

• Pre-deploy: passing tests, code review, env vars, migrations, rollback plan.
• Post-deploy: healthy, monitored, old pods terminated, outcome documented.
• Production: passing tests; no hardcoded secrets; JSON logs; meaningful health; pinned versions; validated env vars; resource limits; TLS; CVE scan; CORS; rate limiting; CSP/HSTS/X-Frame-Options; tested rollback; runbook; on-call.
• Apply security/CVE checks to executable or security-sensitive workloads.

Mobile Deployment

• EAS: eas build:configure; eas build -p ios|android --profile preview; eas update --branch production; --auto-submit.
• Fastlane: iOS match/cert/sigh/pilot; Android Gradle/supply.
• Credentials in env/secret storage, never Git. Automate iOS signing with fastlane match; use keytool + Google Play App Signing for Android.
• TestFlight: internal instant; external 90 days/100 testers. Google Play: internal/beta/production. Expect 1-7 days review.
• Rollback: EAS eas update:rollback; native release -> revert build; store release -> reduce phased rollout.