Deployment Workflow Migration Guide

This guide helps you migrate from the old develop → main workflow to the new single-branch workflow.

What Changed

Old Workflow

• Feature branch → PR to develop → Auto-deploy to staging
• develop → PR to main → Auto-deploy to production
• Two merges required for production deployment

New Workflow

• Feature branch → PR to main → Auto-deploy to staging
• Manual trigger → Approve → Deploy to production
• One merge required for staging, manual trigger for production

Migration Steps

Step 1: Configure GitHub Environments

⚠️ REQUIRED BEFORE USING NEW WORKFLOW

1. Follow the GitHub Environments Setup Guide
2. Create staging and production environments
3. Migrate all secrets to appropriate environments
4. Configure production environment with approval requirement

Time Required: 1-2 hours

Step 2: Update Your Workflow

For Developers:

1. Update your local workflow:

   git checkout main
   git pull origin main

2. Create feature branches from main instead of develop:

   # Old way (don't use anymore)
   # git checkout develop && git checkout -b feature/my-feature
   
   # New way
   git checkout main && git checkout -b feature/my-feature

3. Create PRs to main instead of develop:

   • Target branch: main
   • Pre-merge validation will run automatically
   • After merge, staging deploys automatically

Step 3: Test the New Workflow

1. Create a test feature branch:

   git checkout main
   git pull origin main
   git checkout -b test/new-workflow

2. Make a small, safe change (e.g., update a comment or README)

3. Create PR to main:

   • Verify pre-merge validation runs
   • Verify it passes

4. Merge the PR:

   • Verify staging deployment triggers automatically
   • Verify staging deployment completes successfully

5. Test production deployment:

   • Go to GitHub Actions → Deploy to Production
   • Click "Run workflow"
   • Verify approval is required
   • Approve and verify deployment works

Step 4: Update Team Documentation

1. Update any internal documentation
2. Share the new workflow with team members
3. Update onboarding materials if applicable

Step 5: Archive Old Workflow (Optional)

After confirming the new workflow works:

1. The old deploy-staging.yml workflow can be disabled
2. Keep it for reference for a period (e.g., 1 month)
3. Eventually remove or archive it

Note: The develop branch can remain for reference but is no longer used for deployments.

Key Differences

Branch Strategy

Aspect	Old Workflow	New Workflow
Feature branch from	develop	main
PR target	develop	main
Staging deploy	Auto on merge to develop	Auto on merge to main
Production deploy	Auto on merge to main	Manual trigger with approval
Merges to production	2 (develop → main)	1 (feature → main)

Deployment Triggers

Environment	Old Workflow	New Workflow
Staging	Auto on develop merge	Auto on main merge
Production	Auto on main merge	Manual trigger + approval

Approval Process

Environment	Old Workflow	New Workflow
Staging	None	None (same)
Production	None (automatic)	Required (GitHub Environments)

Benefits of New Workflow

1. Fewer merges: One merge instead of two
2. Faster feedback: Direct merge to main, immediate staging deployment
3. Better control: Production requires explicit approval
4. Simpler process: Single branch to manage
5. Same safety: All validation and checks preserved

Common Questions

Q: What happens to the develop branch?

A: The develop branch is no longer used for deployments. You can:

• Keep it for reference
• Delete it if not needed
• Use it for other purposes if desired

Q: Can I still use the old workflow?

A: The old workflows (deploy-staging.yml targeting develop) will continue to work until disabled. However, we recommend migrating to the new workflow for consistency.

Q: What if I need to deploy a hotfix?

A: Hotfixes follow the same process:

1. Create hotfix branch from main
2. Create PR to main
3. Merge → Auto-deploy to staging
4. Test in staging
5. Manually trigger production deployment

Q: How do I know which apps will deploy?

A: The workflow automatically detects changes:

• Check the GitHub Actions logs
• Only changed apps are built and deployed
• Change detection is based on file paths

Q: What if staging deployment fails?

A:

1. Check the GitHub Actions logs for errors
2. Fix the issue in your feature branch
3. Create a new PR or push fixes to existing PR
4. Merge again when fixed
5. Production deployment should wait until staging is stable

Rollback Plan

If you need to revert to the old workflow:

1. The old deploy-staging.yml workflow still exists
2. You can re-enable it if needed
3. Create PRs to develop instead of main
4. Note: This requires reverting the workflow file changes

Checklist

Use this checklist to ensure a smooth migration:

• GitHub Environments configured (staging and production)
• All secrets migrated to environments
• Production environment has approval configured
• Team members understand new workflow
• Tested staging deployment with new workflow
• Tested production deployment with new workflow
• Updated internal documentation
• Team trained on new process
• Old workflow documented/archived

Support

If you encounter issues during migration:

1. Check the GitHub Environments Setup Guide
2. Review workflow logs in GitHub Actions
3. Verify environment configuration
4. Check that secrets are correctly migrated

---

Created: 2024-12-19 Last Updated: 2024-12-19