🔧 Technical Documentation
Deployment
Code Promotion Workflow

Code Promotion Workflow

Complete guide to the MyNATCA code promotion process, from development through staging to production deployment.

Overview

The MyNATCA platform uses a structured branch strategy with automated quality checks and version management:

  • Feature branches → Development work
  • dev → Integration testing (optional)
  • staging → Pre-production testing
  • main → Production

All changes flow through Pull Requests with required approvals and automated checks.

Branch Strategy

Branch Protection

Direct commits to main and staging are blocked by pre-commit hooks:

main     ← Production (protected)
  ↑
staging  ← Pre-production (protected)
  ↑
dev      ← Integration (optional)
  ↑
feature/* ← Development work

Enforcement:

  • Pre-commit hooks installed by setup-git-hooks.sh
  • Attempts to commit to main/staging are rejected
  • All changes must go through Pull Requests
  • Can be overridden with --no-verify (not recommended)

Branch Naming

Feature branches:

  • feature/add-new-feature
  • feature/improve-performance
  • fix/bug-description
  • chore/update-dependencies

Format: type/short-description

Types:

  • feature/ - New features
  • fix/ - Bug fixes
  • chore/ - Maintenance tasks
  • docs/ - Documentation changes
  • refactor/ - Code refactoring
  • test/ - Test additions/changes

Development Workflow

1. Create Feature Branch

cd ~/dev/mynatca/platform
 
# Ensure you're starting from latest main
git checkout main
git pull origin main
 
# Create feature branch
git checkout -b feature/add-new-capability
 
# Or for bug fixes
git checkout -b fix/resolve-issue-123

2. Make Changes

# Make your code changes
# ... edit files ...
 
# Test locally
npm run dev
 
# Run quality checks (optional - will run automatically during bump)
npx prettier --check "**/*.{js,mjs,json,md,yaml,yml}"
npx eslint "**/*.{js,mjs}"
npm run type-check  # If TypeScript

3. Commit Changes

# Stage files
git add .
 
# Commit with descriptive message
git commit -m "Add new capability for feature X
 
- Implement core functionality
- Add tests
- Update documentation"
 
# Pre-commit hook runs automatically:
# - Checks you're not on main/staging
# - Validates YAML/JSON
# - Checks for merge conflicts
# - Trims trailing whitespace

Commit message format:

type: short description

Longer explanation if needed:
- Bullet point 1
- Bullet point 2
- Bullet point 3

4. Push Feature Branch

git push origin feature/add-new-capability

Preparing for Deployment

Quality Checks and Version Bumping

Before merging to staging or main, run the deployment preparation workflow:

cd ~/dev/mynatca/platform
 
# For patch version bump (bug fixes, small changes)
npm run bump:patch   # 1.0.0 → 1.0.1
 
# For minor version bump (new features, backwards compatible)
npm run bump:minor   # 1.0.0 → 1.1.0
 
# For major version bump (breaking changes)
npm run bump:major   # 1.0.0 → 2.0.0
 
# Alias for bump:patch
npm run bump

This runs scripts/prepare-deployment.sh which:

  1. Prettier format - Auto-formats all code
  2. ESLint lint - Lints and auto-fixes code issues
  3. TypeScript check - Validates types (if applicable)
  4. Version bump - Updates VERSION and package.json
  5. Summary - Shows what changed and next steps

Output example:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  MyNATCA Platform - Deployment Preparation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Current version: 1.0.0
Bump type: patch

[1/4] Running Prettier format...
✓ Prettier format passed

[2/4] Running ESLint...
✓ ESLint passed

[3/4] Running TypeScript check...
✓ TypeScript check passed

[4/4] Bumping version...
✓ Version bumped

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ All checks passed! Ready for deployment
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Version: 1.0.0 → 1.0.1

Modified files:
  - VERSION
  - package.json
  - (any formatted/linted files)

Next steps:
  1. Review changes: git diff
  2. Stage files: git add .
  3. Commit: git commit -m "chore: bump version to 1.0.1"
  4. Tag: git tag v1.0.1
  5. Push: git push && git push --tags

Review and Commit Version Bump

# Review all changes (code formatting + version bump)
git diff
 
# Stage all changes
git add .
 
# Commit with version bump message
git commit -m "chore: bump version to 1.0.1"
 
# Tag the release
git tag v1.0.1
 
# Push to remote
git push origin feature/add-new-capability --tags

Pull Request Process

1. Create Pull Request

Create a PR on GitHub from your feature branch to staging:

Title: Clear, descriptive title

Add new capability for feature X

Description template:

## Summary
Brief description of what this PR does
 
## Changes
- Change 1
- Change 2
- Change 3
 
## Testing
- [x] Local testing completed
- [x] Quality checks passed (prettier, eslint, typescript)
- [x] Version bumped
- [ ] Tested in staging (will test after merge)
 
## Database Changes
- [ ] Migrations included
- [ ] Seed data updated
- [ ] Schema documentation updated
 
## Breaking Changes
- [ ] None
- [ ] Yes (describe below)
 
## Related Issues
Closes #123
Related to #456

2. Code Review

Team members review the PR:

Reviewers check:

  • Code quality and standards
  • Test coverage
  • Documentation updates
  • Migration safety
  • Breaking changes impact
  • Security concerns

Author responsibilities:

  • Respond to feedback
  • Make requested changes
  • Update PR with additional commits
  • Re-request review after changes

3. Approval and Merge

Once approved:

# Merge via GitHub UI (Squash and merge recommended)
# Or via command line:
 
# Ensure you're up to date
git checkout staging
git pull origin staging
 
# Merge feature branch
git merge feature/add-new-capability
 
# Push to staging
git push origin staging

Staging Deployment

Automatic Deployment

When code is pushed to staging branch:

  1. CI/CD automatically deploys to staging environment
  2. Migrations are applied automatically
  3. Environment-specific variables are used

Manual Deployment (If needed)

# From staging branch
git checkout staging
git pull origin staging
 
# Deploy to staging (deployment method varies by project)
# Platform (Digital Ocean)
git push digitalocean-staging staging:main
 
# Verify deployment
curl https://staging-api.mynatca.org/api/health

Staging Verification

Test thoroughly in staging:

# Health check
curl https://staging-api.mynatca.org/api/health
 
# Test endpoints
curl https://staging-api.mynatca.org/api/members
 
# Run integration tests
npm run test:integration
 
# Manual testing
# - Test new features
# - Test existing features (regression)
# - Test database migrations
# - Test authentication flows

Staging checklist:

  • Application starts successfully
  • Health checks pass
  • New features work as expected
  • Existing features still work (no regressions)
  • Database migrations applied successfully
  • Authentication/authorization works
  • API endpoints respond correctly
  • Error handling works properly

Production Deployment

1. Merge Staging to Main

After successful staging verification:

# Checkout main
git checkout main
git pull origin main
 
# Merge staging
git merge staging
 
# Push to main
git push origin main

2. Create Production Release

# Tag production release
git tag v1.0.1
git push origin v1.0.1
 
# Create GitHub Release (optional but recommended)
# - Go to GitHub Releases
# - Create new release from tag v1.0.1
# - Document changes and migration notes

3. Deploy to Production

# Automatic deployment (recommended)
# Push to main triggers CI/CD
 
# Manual deployment (if needed)
git push digitalocean-production main
 
# Verify deployment
curl https://api.mynatca.org/api/health

4. Post-Deployment Verification

# Health checks
curl https://api.mynatca.org/api/health
curl https://platform.mynatca.org/api/health
 
# Smoke tests
# - Test critical user flows
# - Verify authentication
# - Check database connectivity
# - Test key features
 
# Monitor logs
# - Check for errors
# - Monitor performance
# - Watch for anomalies
 
# Database verification
# - Check migration status
# - Verify data integrity
# - Check query performance

Production checklist:

  • Application deployed successfully
  • Health checks pass
  • Critical features tested
  • Database migrations applied
  • No errors in logs
  • Performance acceptable
  • Monitoring shows normal metrics
  • Team notified of deployment

Version Management

VERSION File

The VERSION file is the single source of truth for platform version:

# View current version
cat VERSION
# 1.0.1
 
# Version is also updated in package.json automatically

Version Display

The version appears on the platform landing page footer:

URL: http://localhost:1300/ (or production URL) Format: Version 1.0.1

Semantic Versioning

Format: MAJOR.MINOR.PATCH

MAJOR version (1.0.0 → 2.0.0)

  • Breaking changes
  • Incompatible API changes
  • Major feature overhauls

MINOR version (1.0.0 → 1.1.0)

  • New features
  • Backwards-compatible functionality
  • Enhancements to existing features

PATCH version (1.0.0 → 1.0.1)

  • Bug fixes
  • Security patches
  • Documentation updates
  • Performance improvements

Manual Version Bump (Not Recommended)

Use npm scripts instead, but if needed:

# Manual bump using script
./scripts/bump-version.js patch   # 1.0.0 → 1.0.1
./scripts/bump-version.js minor   # 1.0.0 → 1.1.0
./scripts/bump-version.js major   # 1.0.0 → 2.0.0

Git Hooks

Pre-Commit Hooks

Automatically run on every commit:

Branch Protection:

  • Blocks commits to main and staging branches
  • Requires Pull Request workflow
  • Can override with --no-verify (not recommended)

Basic Quality Checks:

  • Trim trailing whitespace
  • Fix end of files
  • Validate YAML syntax
  • Validate JSON syntax
  • Check for merge conflicts

Note: Prettier and ESLint do NOT run on every commit. They run when you use npm run bump:* commands.

Post-Checkout/Post-Merge Hooks

  • Update migration symlinks automatically
  • Keep platform synchronized with subproject migrations

Installing Hooks

cd ~/dev/mynatca/platform
./scripts/setup-git-hooks.sh
 
# For subprojects
cd ~/dev/mynatca/pay
./scripts/setup-git-hooks.sh

Rollback Procedures

Rolling Back a Deployment

If issues are found in production:

Option 1: Revert the merge

git checkout main
git revert HEAD
git push origin main

Option 2: Deploy previous tag

# Find previous working version
git tag --sort=-v:refname | head -5
 
# Deploy previous version
git checkout v1.0.0
git push digitalocean-production HEAD:main --force

Option 3: Hotfix

# Create hotfix branch from main
git checkout -b hotfix/critical-fix main
 
# Make minimal fix
# ... edit files ...
 
# Test thoroughly
npm run dev
 
# Bump patch version
npm run bump:patch
 
# Commit and push
git commit -am "hotfix: critical fix for production issue"
git push origin hotfix/critical-fix
 
# Create PR to main (bypass staging for critical fixes)
# After approval, merge and deploy

Database Rollback

If migrations cause issues:

Option 1: Rollback migration

-- Create rollback migration
-- supabase/migrations/YYYYMMDDHHmmss_rollback_previous_change.sql
 
-- Reverse the previous migration changes
ALTER TABLE ... DROP COLUMN ...;

Option 2: Restore from backup

# Restore database from latest backup
# (Consult Supabase/database documentation)

Emergency Procedures

Hotfix Process

For critical production bugs:

# 1. Create hotfix branch from main
git checkout -b hotfix/critical-security-fix main
 
# 2. Make minimal fix
# ... fix the critical issue ...
 
# 3. Test thoroughly
npm run dev
npm test
 
# 4. Bump patch version
npm run bump:patch
 
# 5. Commit
git add .
git commit -m "hotfix: fix critical security vulnerability
 
CVE-2025-XXXX: Description of fix"
git tag v1.0.2
 
# 6. Push to remote
git push origin hotfix/critical-security-fix --tags
 
# 7. Deploy directly to production (skip staging for critical fixes)
git checkout main
git merge hotfix/critical-security-fix
git push origin main
 
# 8. Backport to staging
git checkout staging
git merge main
git push origin staging
 
# 9. Verify fix
curl https://api.mynatca.org/api/health
 
# 10. Document incident
# - Create incident report
# - Document root cause
# - Document fix
# - Update runbooks if needed

Skip Pre-Commit Hooks (Emergency Only)

# Override branch protection (use with caution!)
git commit --no-verify -m "Emergency fix"
 
# Or set environment variable
SKIP=1 git commit -m "Emergency fix"

Warning: Only use for emergencies. Always prefer the standard PR workflow.

Best Practices

DO ✅

  • Create feature branches from latest main
  • Write descriptive commit messages
  • Run npm run bump:* before creating PRs
  • Test thoroughly in staging before production
  • Tag all production releases
  • Document breaking changes
  • Update CHANGELOG.md
  • Follow semantic versioning
  • Keep commits focused and atomic
  • Squash commits when merging to keep history clean

DON'T ❌

  • Commit directly to main or staging
  • Skip quality checks (npm run bump)
  • Deploy to production without staging testing
  • Skip version bumping
  • Force push to protected branches (except emergency rollbacks)
  • Commit secrets or sensitive data
  • Skip code review
  • Deploy breaking changes without coordination
  • Merge untested code
  • Skip documentation updates

Troubleshooting

Pre-Commit Hook Blocks Commit

Issue: Can't commit because on main/staging branch

Solution:

# Switch to feature branch
git checkout -b feature/my-changes
 
# Or if you want to keep changes on current branch
git stash
git checkout -b feature/my-changes
git stash pop

Version Bump Fails

Issue: npm run bump fails with errors

Solution:

# Check what's failing
npm run bump:patch
 
# Fix Prettier issues manually
npx prettier --write "**/*.{js,mjs,json,md,yaml,yml}"
 
# Fix ESLint issues manually
npx eslint --fix "**/*.{js,mjs}"
 
# Fix TypeScript issues
npm run type-check
# Then fix reported issues
 
# Try bump again
npm run bump:patch

Git Hooks Not Working

Issue: Hooks don't run automatically

Solution:

# Reinstall hooks
./scripts/setup-git-hooks.sh
 
# Verify hooks are installed
ls -la .git/hooks/pre-commit
ls -la .git/hooks/post-checkout

Merge Conflicts

Issue: Conflicts when merging

Solution:

# Update your branch with latest staging
git checkout feature/my-changes
git fetch origin
git merge origin/staging
 
# Resolve conflicts
# ... edit conflicted files ...
 
git add .
git commit -m "Merge staging into feature branch"

Quick Reference

Commands

# Development
git checkout -b feature/name              # Create feature branch
npm run bump:patch                        # Prepare for deployment
git commit -m "message"                   # Commit changes
git push origin feature/name              # Push to remote
 
# Deployment Preparation
npm run bump:patch   # Bug fixes (1.0.0 → 1.0.1)
npm run bump:minor   # New features (1.0.0 → 1.1.0)
npm run bump:major   # Breaking changes (1.0.0 → 2.0.0)
npm run bump         # Alias for bump:patch
 
# Promotion
# Feature → Staging: Create PR, merge after approval
# Staging → Main: Merge via PR after staging verification
# Main → Production: Automatic deployment or manual push
 
# Git Hooks
./scripts/setup-git-hooks.sh             # Install hooks
git commit --no-verify                   # Skip hooks (emergency only)
 
# Rollback
git revert HEAD                          # Revert last commit
git checkout v1.0.0                      # Deploy previous version

Branch Flow

feature/name → staging → main → production
     ↓            ↓        ↓
   develop    staging   production
   on local   testing   deployment

Related Documentation

Deployment GuideVersion Management