deployment-sop

bybren-llc's avatarfrom bybren-llc

Deployment workflows, pre-deploy validation, and smoke testing patterns. Use when deploying to staging or production, running smoke tests, or validating deployments.

⭐11stars🔀4forks📁View on GitHub🕐Updated Dec 25, 2025
[CI and CD]

When & Why to Use This Skill

The Deployment SOP skill streamlines software release cycles by providing standardized workflows for pre-deployment validation, smoke testing, and rollback procedures. It acts as a central hub for navigating authoritative deployment documentation, ensuring that every release to staging or production follows rigorous safety protocols and 'Stop-the-Line' conditions to maintain system stability.

Use Cases

  • Executing standardized deployment workflows for staging and production environments to ensure consistency across teams.
  • Performing pre-deployment validation checks, including CI status verification, PR audits, and database migration testing.
  • Conducting post-deployment smoke tests and health checks to verify core functionality and system uptime.
  • Managing emergency rollback procedures and documenting deployment evidence for Linear tickets or audit trails.
  • Enforcing safety guardrails and 'Stop-the-Line' conditions to prevent the deployment of unstable code during active incidents.
namedeployment-sop
descriptionDeployment workflows, pre-deploy validation, and smoke testing patterns. Use when deploying to staging or production, running smoke tests, or validating deployments.

Deployment SOP Skill

Purpose

Route to existing deployment SOPs and provide checklists for safe, validated deployments. This skill does NOT duplicate SOP content—it links to authoritative sources.

When This Skill Applies

Invoke this skill when:

  • Deploying to staging or production
  • Running pre-deploy validation
  • Executing post-deploy smoke tests
  • Accessing Linux dev machine for deployment
  • Coordinating release activities

Authoritative References (MUST READ)

Document Location Purpose
Semantic Release SOP docs/ci-cd/Semantic-Release-Deployment-SOP.md Release automation workflow
Staging/UAT Release SOP docs/sop/STAGING-UAT-RELEASE-SOP.md UAT validation process
Linux Dev Machine Access docs/deployment/LINUX-DEV-MACHINE-ACCESS-SOP.md Pop OS dev server access
Production Server Access docs/deployment/PRODUCTION-SERVER-ACCESS-SOP.md Production deployment

Pre-Deployment Checklist

Before ANY deployment:

  • All CI checks pass (GitHub Actions green)
  • PR merged to target branch (dev for staging, master for prod)
  • No unresolved blockers in Linear
  • Database migrations tested locally
  • Environment variables verified
# Validate before deploy
yarn ci:validate
yarn build

Post-Deployment Smoke Test

After deployment completes:

  • Health endpoint responds: curl https://{domain}/api/health
  • Database connection verified (check health response)
  • Authentication flow works (sign-in/sign-up)
  • Critical user flows functional
  • No new errors in logs (PostHog/Coolify)
# Smoke test commands
curl -s https://{domain}/api/health | jq .
# Expected: {"status":"healthy","timestamp":"..."}

Deployment Evidence Template

For Linear ticket attachment:

## Deployment Evidence - {TICKET_PREFIX}-XXX

### Environment

- **Target**: Staging / Production
- **Branch**: `{branch_name}`
- **Commit**: `{commit_sha}`

### Pre-Deployment

- [x] CI checks passed
- [x] PR merged
- [x] Migrations verified

### Post-Deployment

- [x] Health check: PASSED
- [x] Auth flow: PASSED
- [x] Smoke tests: PASSED

### Verification

curl -s https://{domain}/api/health
{"status":"healthy","timestamp":"2025-XX-XXTXX:XX:XX.XXXZ"}

Rollback Procedure

If deployment fails:

  1. Identify failure - Check Coolify logs, PostHog errors
  2. Revert commit - git revert {commit_sha}
  3. Push revert - Triggers automatic rollback deployment
  4. Verify rollback - Run smoke tests again
  5. Document incident - Update Linear ticket with evidence

Stop-the-Line Conditions

FORBIDDEN

  • Deploying with failing CI checks
  • Skipping smoke tests on production
  • Deploying database migrations without local testing
  • Force-deploying over active incidents

REQUIRED

  • Health check MUST pass within 5 minutes
  • Production deployments MUST have staging validation first
  • Rollback plan MUST be documented before production deploy

Branch → Environment Mapping

Branch Environment Auto-Deploy
dev Staging (Pop OS) Manual pull
master Production (Coolify) Automatic

Note: Merging to dev builds Docker image but requires manual ./scripts/dev-docker.sh pull on Pop OS.