Saltar al contenido principal

Deployment Workflow Guide

This guide explains the single-branch deployment workflow used in this project.

Overview​

The deployment workflow uses a simplified single-branch approach:

  • Feature branches → PR to main → Automatic staging deployment → Manual production promotion (with approval)

This eliminates the need for the intermediate develop branch while maintaining all safety checks and validation.

Workflow Diagram​

Feature Branch
    ↓
PR to main
    ↓
Pre-merge Validation (TypeScript, Docker builds)
    ↓
Merge to main
    ↓
Automatic Staging Deployment
    ↓
Test in Staging
    ↓
Manual Production Deployment (requires approval)
    ↓
Production

Step-by-Step Process​

1. Create Feature Branch​

# Create feature branch from main
git checkout main
git pull origin main
git checkout -b feature/your-feature-name

# Work on your feature...
git add .
git commit -m "feat: add new feature"
git push origin feature/your-feature-name

2. Create Pull Request to Main​

  1. Go to GitHub and create a pull request targeting main branch
  2. Pre-merge validation will automatically run:
    • TypeScript checks (for frontend-pwa)
    • Docker builds for all changed applications
    • Change detection to identify which apps need deployment
  3. Wait for validation to pass
  4. Get code review approval
  5. Merge the PR

3. Automatic Staging Deployment​

When you merge a PR to main:

  • The staging deployment workflow automatically triggers
  • Only changed applications are deployed (backend, web-app, landing-page, frontend-pwa)
  • Deployment uses staging environment secrets
  • All validation steps run (Firebase config, database connection, etc.)

What gets deployed:

  • Applications with changes in their directories or Dockerfiles
  • Uses commit SHA for image tagging
  • Deploys to staging Cloud Run services

4. Test in Staging​

After staging deployment completes:

  1. Verify the application works correctly in staging
  2. Test the new feature thoroughly
  3. Check logs for any issues
  4. Verify all integrations work

5. Deploy to Production​

Once staging is verified:

  1. Go to GitHub Actions → Deploy to Production workflow
  2. Click Run workflow
  3. Optionally specify a commit SHA (defaults to latest main)
  4. Click Run workflow button
  5. Approval required: A team member with approval permissions must approve
  6. After approval, production deployment proceeds
  7. Monitor the deployment in GitHub Actions

Production Deployment Details:

  • Uses production environment secrets
  • Requires explicit approval through GitHub Environments
  • Only deploys changed applications
  • Uses the same validation steps as staging

Change Detection​

The workflow automatically detects which applications changed:

  • Backend: Changes in apps/backend/** or deploy/gcp/backend.Dockerfile
  • Web App: Changes in apps/web-app/** or deploy/gcp/web-app.Dockerfile
  • Landing Page: Changes in apps/landing-page/** or deploy/gcp/landing-page.Dockerfile
  • Frontend PWA: Changes in apps/frontend-pwa/** or deploy/gcp/frontend-pwa.Dockerfile

Only changed applications are built and deployed, saving time and resources.

Environments​

Staging Environment​

  • Purpose: Test changes before production
  • Deployment: Automatic on merge to main
  • Approval: Not required
  • Secrets: Staging-specific secrets from GitHub Environment
  • Database: Staging database instance
  • URLs: Staging-specific API and frontend URLs

Production Environment​

  • Purpose: Live production environment
  • Deployment: Manual trigger with approval
  • Approval: Required (at least 1 reviewer)
  • Secrets: Production-specific secrets from GitHub Environment
  • Database: Production database instance
  • URLs: Production API and frontend URLs

GitHub Environments​

Secrets are managed through GitHub Environments:

  • Staging Environment: Contains all staging-specific secrets
  • Production Environment: Contains all production-specific secrets with approval protection

See GitHub Environments Setup Guide for configuration details.

Workflow Files​

Pre-Merge Validation​

  • File: .github/workflows/premerge-validate.yml
  • Triggers: PRs to main branch
  • Purpose: Validate code before merging
  • Actions: TypeScript checks, Docker builds (no push)

Staging Deployment​

  • File: .github/workflows/deploy-staging-from-main.yml
  • Triggers: Merge to main branch
  • Purpose: Deploy to staging automatically
  • Environment: staging

Production Deployment​

  • File: .github/workflows/deploy-production.yml
  • Triggers: Manual (workflow_dispatch)
  • Purpose: Deploy to production with approval
  • Environment: production

Rollback Process​

If you need to rollback to a previous version:

  1. Find the commit SHA of the previous working version
  2. Go to GitHub Actions → Deploy to Production workflow
  3. Click Run workflow
  4. Enter the previous commit SHA in the commit_sha input
  5. Click Run workflow
  6. Approve the deployment
  7. The previous version will be deployed

Note: Docker images are retained in Artifact Registry, so previous versions can always be redeployed.

Troubleshooting​

Staging Deployment Not Triggering​

Check:

  • PR was actually merged (not just closed)
  • Changes were made to application directories or Dockerfiles
  • Workflow file exists and is correct
  • GitHub Actions are enabled for the repository

Production Deployment Requires Approval​

This is expected behavior! Production deployments require approval through GitHub Environments. The approver will receive a notification and can approve in the GitHub Actions UI.

Secrets Not Found​

Check:

  • Secrets are added to the correct GitHub Environment (staging or production)
  • Environment name matches exactly in the workflow file
  • Secrets are not in repository secrets (should be in environment secrets)

Change Detection Not Working​

Check:

  • Changes are in the correct directories (apps/backend/**, etc.)
  • Dockerfile changes are in deploy/gcp/ directory
  • Path-based filter is working correctly (check workflow logs)

Best Practices​

  1. Always test in staging first: Never deploy to production without testing in staging
  2. Small, frequent deployments: Smaller changes are easier to test and rollback
  3. Monitor deployments: Watch GitHub Actions logs during deployment
  4. Verify after deployment: Check that applications are accessible and working
  5. Use descriptive commit messages: Helps track what was deployed
  6. Keep feature branches focused: One feature per branch makes testing easier
  7. Delete merged branches: Keeps repository clean

Quick Reference​

Daily Workflow​

# 1. Create feature branch
git checkout main && git pull && git checkout -b feature/my-feature

# 2. Make changes and commit
git add . && git commit -m "feat: my feature"

# 3. Push and create PR
git push origin feature/my-feature
# Create PR to main on GitHub

# 4. After merge, staging deploys automatically
# Test in staging, then manually trigger production deployment

Production Deployment​

  1. GitHub → Actions → Deploy to Production
  2. Run workflow (optionally specify commit SHA)
  3. Wait for approval
  4. Approve deployment
  5. Monitor deployment

Rollback​

  1. GitHub → Actions → Deploy to Production
  2. Run workflow with previous commit SHA
  3. Approve deployment

Last Updated: 2024-12-19 Related: Git Workflow Guide, Migration Guide