Skip to main content

🚀 GitHub Actions Deployment Workflow Guide

📋 Overview​

This is the current deployment guide for the API workflow and the shared release story referenced by service deployment docs.

Current promotion flow:

feature/*, fix/*, refactor/*, chore/*, hotfix/*
  -> open PR to beta
beta
  -> deploy beta
  -> open PR to alpha
alpha
  -> deploy alpha
  -> open PR to main
main
  -> deploy production

There is also an emergency production workflow for incidents that cannot wait for the normal promotion path.

🏗️ Workflow Architecture​

Pipeline Stages​

StagePurposeEnvironmentURL Pattern
Betashared internal validationbetahttps://beta.api.{domain}
Alphastaging / pre-productionalphahttps://alpha.api.{domain}
Productionlive systemproductionhttps://api.{domain}

🎯 Workflow Triggers​

Automatic Triggers​

Push Events​

on:
  push:
    branches:
      - "feature/**"   # build + open PR to beta
      - "refactor/**"  # build + open PR to beta
      - "fix/**"       # build + open PR to beta
      - "chore/**"     # build + open PR to beta
      - "hotfix/**"    # build + open PR to beta
      - "staging/**"   # build + open PR to alpha
      - "beta"         # deploy beta + open PR to alpha
      - "alpha"        # deploy alpha + open PR to main
      - "main"         # deploy production

Pull Request Events​

on:
  pull_request:
    branches:
      - "beta"
      - "alpha"
      - "main"

Merged PRs into beta or alpha are part of the deploy conditions for those target environments.

Manual Triggers​

on:
  workflow_dispatch:
    inputs:
      target_stage:
        type: choice
        options: [beta, alpha, production]

🔧 Jobs & Workflow Steps​

Job 1: Build And Package​

Purpose: validate the repo and create the deployable artifact used by every standard deploy job.

build-and-test:
  runs-on: ubuntu-latest
  steps:
    - Checkout repository
    - Setup Node.js 20.10.0
    - Install dependencies (npm ci)
    - Run type checking
    - Build TypeScript
    - Assemble deployment bundle
    - Upload deploy-package artifact

The standard workflow currently enforces type-check + build.

The test step is still commented out in api-deploy.yml, so do not describe the normal path as fully test-gated.

Job 2: Open Promotion PRs​

Feature-style branches open a PR to beta.

staging/* branches open a PR directly to alpha when beta needs to be bypassed for controlled validation.

These PR jobs do not deploy by themselves. They prepare the branch promotion step that will trigger a deploy after merge or direct branch push.

Job 3: Deploy Beta / Alpha / Production​

The normal deploy jobs now use the same shared deploy action as the emergency workflow:

  • workflow action: .github/actions/deploy
  • artifact contract: deploy-package/dist, deploy-package/package.json, deploy-package/package-lock.json
  • server runtime expectation: app starts from dist/index.js

Environment triggers:

  • beta branch or manual target_stage=beta -> deploy beta
  • alpha branch or manual target_stage=alpha -> deploy alpha
  • main branch or manual target_stage=production -> deploy production

Production also performs the version bump before deploying and runs under the GitHub production environment.

Version Bumping Logic​

  • Commit contains [MAJOR] -> major version bump
  • Commit contains [MINOR] -> minor version bump
  • Default -> patch version bump

🔐 Required Secrets & Configuration​

Repository Secrets​

secrets:
  DOMAIN_NAME: # Base domain (e.g., attunelogic.com)
  SSH_HOST: # Deployment server hostname/IP
  SSH_USER: # SSH username for deployment
  SSH_PASS: # SSH password/key for deployment
  SSH_PORT: # SSH port (usually 22)
  GITHUB_TOKEN: # Automatic (for PR creation)

GitHub Environments​

Configure in GitHub: Settings → Environments

  • beta: Beta environment configuration
  • alpha: Alpha environment configuration
  • production: Production environment (with protection rules)

Recommended Protection Rules:

  • ✅ Required reviewers for production
  • ✅ Wait timer for production deployments
  • ✅ Restrict to specific branches

📁 Custom Deploy Action​

The workflow uses a custom deploy action: .github/actions/deploy

Expected Interface:

inputs:
  environment: # beta, alpha, production
  domain: # Domain name
  ssh_host: # Server hostname
  ssh_user: # SSH username
  ssh_pass: # SSH credentials
  ssh_port: # SSH port

📦 Deployment Bundle Contract​

Current API deploys should be treated as a runnable Node app bundle, not a dist/ folder by itself.

Expected runtime bundle:

  • dist/
  • package.json
  • package-lock.json

Runtime expectation on server:

  • app starts from node dist/index.js
  • health checks verify the deployed app after startup

🚨 Emergency And Fallback Paths​

The API repo also includes an emergency workflow:

  • workflow: .github/workflows/emergency-deploy.yml
  • action used by emergency path: .github/actions/deploy

Use the emergency path only for production incidents that cannot wait for normal promotion. It still builds the app, can run tests by default, and performs production health verification after deploy.

🚀 Deployment Flow Examples​

Feature Development → Beta​

  1. Developer pushes to feature/new-security-feature
  2. Workflow triggers build-and-test + deploy-beta
  3. Auto-deployment to beta environment
  4. Auto-PR created: feature/new-security-feature → beta
  5. Testing on https://beta.api.domain.com
  6. Review & Merge PR when testing complete

Beta → Alpha Promotion​

  1. Team merges feature PR into beta branch
  2. Workflow triggers build-and-test + deploy-alpha
  3. Auto-deployment to alpha environment
  4. Auto-PR created: beta → alpha
  5. Staging validation on https://alpha.api.domain.com
  6. Approve & Merge for production release

Alpha → Production Release​

  1. Release Manager merges alpha PR into alpha branch
  2. Workflow triggers build-and-test + deploy-production
  3. Version bump based on commit message
  4. Auto-deployment to production environment
  5. Auto-PR created: alpha → main (with version tag)
  6. Merge to keep main in sync with production

🔄 Branch Strategy & GitOps​

Branch Hierarchy​

main (production sync)
├── alpha (production candidate)
│   ├── beta (staging)
│   │   ├── feature/security-features
│   │   ├── feature/ui-improvements
│   │   └── feature/bug-fixes

GitOps Principles​

  • 🔄 Declarative: Infrastructure as code
  • 🔍 Version Controlled: All changes tracked in Git
  • 🤖 Automated: No manual deployment steps
  • 🛡️ Auditable: Complete deployment history
  • 🔒 Secure: Environment-based access controls

📊 Monitoring & Validation​

Health Check Endpoints​

Each deployment includes automatic health check validation:

# Beta Environment
GET https://beta.api.{domain}/health

# Alpha Environment
GET https://alpha.api.{domain}/health

# Production Environment
GET https://api.{domain}/health

Expected Response:

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "uptime": 1234567,
  "environment": "beta|alpha|production",
  "version": "2.9.0"
}

Deployment Verification​

  • ✅ HTTP 200 response from health endpoint
  • ✅ Correct environment in response
  • ✅ Service uptime > 0
  • ✅ Expected version number

⚠️ Best Practices & Guidelines​

Commit Message Conventions​

# Patch version bump (default)
git commit -m "fix: resolve rate limiting bug"

# Minor version bump
git commit -m "feat: add brute force protection [MINOR]"

# Major version bump
git commit -m "feat!: breaking API changes [MAJOR]"

Branch Naming Conventions​

# Feature development
feature/security-rate-limiting
feature/ui-dashboard-improvements
feature/user-management-system

# Code refactoring
refactor/optimize-database-queries
refactor/restructure-auth-middleware
refactor/cleanup-legacy-code

# Bug fixes
fix/user-authentication-bug
fix/database-connection-issue
fix/api-response-formatting

# Staging branches (service, optional direct-to-Alpha)
staging/critical-security-patch
staging/quick-alpha-validation

For critical, time-sensitive UI fixes in the AttuneLogic Service, prefer a staging/* branch that deploys directly to Alpha over introducing a separate hotfix/* naming scheme. The API workflow itself still follows the standard feature → beta → alpha → production promotion path.

Environment Usage Guidelines​

Beta Environment 🧪​

  • Purpose: Feature testing and integration
  • Data: Test data only
  • Access: Development team
  • Stability: May be unstable during active development

Alpha Environment 🎯​

  • Purpose: Staging and user acceptance testing
  • Data: Production-like test data
  • Access: Extended team, stakeholders
  • Stability: Should be stable and production-ready

Production Environment 🚀​

  • Purpose: Live customer-facing system
  • Data: Real customer data
  • Access: Restricted, monitored
  • Stability: Must be highly available and stable

🚨 Troubleshooting​

Common Issues​

Build Failures​

# Check these locally before pushing:
npm run type-check  # TypeScript errors
npm run build       # Compilation issues
npm run test:safe   # Test failures

Deployment Failures​

  • ✅ Verify SSH credentials in repository secrets
  • ✅ Check server accessibility and ports
  • ✅ Validate environment configurations
  • ✅ Review deploy action logs

PR Creation Failures​

  • ✅ Ensure GITHUB_TOKEN has proper permissions
  • ✅ Check branch protection rules
  • ✅ Verify repository permissions for actions

Manual Intervention​

Emergency Production Deployment​

  1. Use workflow_dispatch with production target
  2. Monitor deployment carefully
  3. Create manual PR for alpha → main sync

Rollback Procedure​

  1. Revert commits in alpha branch
  2. Trigger automatic deployment to production
  3. Create hotfix branch for proper fix

📈 Workflow Metrics & Analytics​

Deployment Frequency​

  • Beta: Multiple times per day
  • Alpha: Daily to weekly
  • Production: Weekly to monthly

Success Rate Targets​

  • Build Success: >95%
  • Beta Deployment: >98%
  • Alpha Deployment: >99%
  • Production Deployment: >99.9%

Performance Metrics​

  • Build Time: <10 minutes
  • Deployment Time: <5 minutes per environment
  • Health Check Response: <30 seconds

🔧 Customization & Extensions​

Adding New Environments​

  1. Create new environment in GitHub settings
  2. Add new job in workflow file
  3. Configure secrets and protection rules
  4. Update custom deploy action

Custom Validation Steps​

- name: Security Scan
  run: npm audit --audit-level high

- name: Performance Test
  run: npm run test:performance

- name: Integration Test
  run: npm run test:integration

Notification Integration​

- name: Slack Notification
  if: failure()
  uses: 8398a7/action-slack@v3
  with:
    status: failure
    webhook_url: ${{ secrets.SLACK_WEBHOOK }}

📚 Related Documentation​

  • Security Implementation Guide
  • Multi-Industry Testing Guide (Coming Soon)
  • Deployment Readiness Report (Coming Soon)
  • GitHub Actions Deploy Action (Coming Soon)

🎯 Summary​

This workflow provides:

✅ Automated 3-stage deployment pipeline
✅ Built-in testing and validation
✅ Automatic PR creation and tracking
✅ Semantic versioning for releases
✅ Environment-specific configurations
✅ Security and access controls
✅ Health checks and monitoring
✅ GitOps best practices

The workflow ensures safe, reliable deployments while maintaining fast development velocity and complete audit trails for your multi-tenant, multi-industry SaaS platform. 🚀