Skip to main content

🚀 GitHub Actions Workflow - Quick Reference

🎯 Deployment Pipeline Overview​

Feature Branch -> PR to Beta
Beta Branch    -> Deploy Beta -> PR to Alpha
Alpha Branch   -> Deploy Alpha -> PR to Main
Main Branch    -> Deploy Production

For the AttuneLogic Service (web app) there is also an optional staging branch path that skips Beta when it is unstable:

Staging Branch (`staging/*`) → Alpha → Production
               ↓               ↓         ↓
         Auto Deploy         Auto     Auto
          to Alpha          PR/merge PR/merge

📋 Daily Developer Workflow​

1. Feature Development​

# Create feature branch
git checkout -b feature/security-improvements

# Make changes and commit
git add .
git commit -m "feat: add rate limiting protection"

# Push to trigger build validation and PR creation
git push origin feature/security-improvements

Result: Build validation runs and an automatic PR is opened to beta

2. Beta Testing​

  • Review: Auto-created PR in GitHub
  • Merge: Feature branch → beta
  • Result after merge: beta deploys to https://beta.api.{domain}/health

3. Alpha Staging​

# Merge to beta or update beta directly
# Review auto-created PR: beta → alpha
# Beta deploy URL: https://beta.api.{domain}/health
# Merge beta → alpha after validation

4. Production Release​

# Merge alpha -> main to trigger production deployment
# Auto version bump (patch/minor/major)
# Production URL: https://api.{domain}/health

🔄 Branch Strategy​

BranchPurposeTriggersAuto-deploys to
feature/*DevelopmentPush-
betaIntegration / beta deploy sourcePush or mergeBeta
alphaStaging / alpha deploy sourcePush or mergeAlpha
mainProduction deploy sourcePushProduction
staging/**Direct Alpha when Beta is unstable (UI)Push (service repo)Alpha

staging/* branches are implemented in the AttuneLogic Service (frontend) workflow to allow a Dev → Alpha → Prod path when the shared Beta environment is temporarily unstable. The API workflow continues to use the standard feature -> PR to beta -> beta -> alpha -> production path.

🎮 Manual Deployment Options​

GitHub UI Method​

  1. Go to Actions tab
  2. Select "API Multi-Stage Deploy"
  3. Click "Run workflow"
  4. Choose target environment: beta, alpha, or production

Emergency Production Deploy​

# Use the dedicated emergency workflow for urgent production fixes
gh workflow run "🚨 Emergency Production Deploy" \
  -f reason="Critical production issue" \
  -f branch="fix/urgent-production-fix"

📝 Commit Message Conventions​

TypeExampleVersion Bump
Fixfix: resolve authentication bugPatch (2.9.0 → 2.9.1)
Featurefeat: add brute force protection [MINOR]Minor (2.9.0 → 2.10.0)
Breakingfeat!: new API structure [MAJOR]Major (2.9.0 → 3.0.0)

🔍 Environment URLs​

EnvironmentURL PatternPurpose
Betahttps://beta.api.{domain}Feature testing
Alphahttps://alpha.api.{domain}Staging/UAT
Productionhttps://api.{domain}Live system

Health Check Endpoints​

curl https://beta.api.{domain}/health
curl https://alpha.api.{domain}/health
curl https://api.{domain}/health

⚡ Quick Commands​

Pre-Push Validation​

npm run type-check    # TypeScript validation
npm run build         # Build verification
npm run test:safe     # Test suite

npm run test:safe is still recommended locally, but the standard API deploy workflow is currently enforcing type-check + build and packaging the deploy artifact.

Local Development​

npm run dev           # Development server
npm run test:watch    # Watch mode testing

🚨 Common Issues & Quick Fixes​

IssueQuick Fix
Build failsRun npm run type-check locally
Tests failRun npm run test:safe locally
Deploy failsCheck SSH secrets in repo settings
PR not createdVerify GitHub token permissions

📊 Workflow Status Indicators​

✅ Success Indicators​

  • Green checkmarks in Actions tab
  • Auto-PR created with deployment details
  • Health endpoint returns 200 OK
  • Version number updated (production)

❌ Failure Indicators​

  • Red X in Actions tab
  • No auto-PR created
  • Health endpoint fails
  • Error logs in workflow details

🔄 Rollback Procedure​

Quick Rollback​

  1. Revert the problematic commit in alpha branch
  2. Push to trigger automatic production deployment
  3. Create hotfix branch for proper fix
  4. Test fix in beta → alpha → production

Emergency Rollback​

  1. Revert the bad change on a fix/* or hotfix/* branch
  2. Deploy that revert through the emergency workflow only if production cannot wait
  3. After stability is restored, promote the final fix through the normal path
  4. Avoid force-push rollback on shared release branches

🎯 Environment-Specific Testing​

Beta Environment 🧪​

  • Purpose: Feature validation
  • Data: Test data only
  • Stability: May be unstable
  • Access: Development team

Alpha Environment 🎯​

  • Purpose: Staging/UAT
  • Data: Production-like
  • Stability: Should be stable
  • Access: Extended team + stakeholders

Production Environment 🚀​

  • Purpose: Live customer system
  • Data: Real customer data
  • Stability: Must be highly available
  • Access: Restricted + monitored

📞 Quick Support​

Workflow Issues​

  1. Check Actions tab for error details
  2. Verify all required secrets are set
  3. Ensure branch protection rules are correct
  4. Check environment configurations

Deployment Issues​

  1. Verify SSH connectivity to servers
  2. Check server disk space and resources
  3. Validate environment-specific configurations
  4. Review deployment action logs

💡 Pro Tip: Always test locally with the pre-push validation commands before pushing to avoid pipeline failures!