✅ GitHub Actions Workflow Setup Checklist

📋 Pre-Setup Requirements

Repository Structure

.github/workflows/api-deploy.yml file exists
.github/actions/deploy/ custom action exists
package.json includes required scripts
tsconfig.json configured for TypeScript
Health check endpoint implemented

Required Package.json Scripts

{
  "scripts": {
    "type-check": "tsc --noEmit",
    "build": "tsc",
    "test:safe": "NODE_ENV=test jest --detectOpenHandles --forceExit",
    "release:major": "npm version major",
    "release:minor": "npm version minor",
    "release:patch": "npm version patch"
  }
}

🔐 Repository Configuration

1. GitHub Repository Secrets

Navigate to: Repository → Settings → Secrets and variables → Actions

DOMAIN_NAME - Base domain (e.g., attunelogic.com)
SSH_HOST - Deployment server IP/hostname
SSH_USER - SSH username for deployment
SSH_PASS - SSH password or private key
SSH_PORT - SSH port (usually 22)

Note: GITHUB_TOKEN is automatically provided

2. GitHub Environments

Navigate to: Repository → Settings → Environments

Create Beta Environment

Name: beta
Protection rules: None (development environment)
Environment secrets: None required

Create Alpha Environment

Name: alpha
Protection rules:
- Required reviewers (optional)
- Wait timer: 5 minutes (optional)

Create Production Environment

3. Repository Permissions

Navigate to: Repository → Settings → Actions → General

Allow all actions and reusable workflows
Allow GitHub Actions to create and approve pull requests
Workflow permissions: Read and write permissions

🌿 Branch Protection Setup

Main Branch Protection

Navigate to: Repository → Settings → Branches → Add rule for main

Require pull request reviews before merging
Require status checks to pass before merging
Require linear history
Include administrators in restrictions

Alpha Branch Protection

Require pull request reviews before merging
Require status checks: build-and-test

Beta Branch Protection

Require status checks: build-and-test
Allow force pushes (for development)

🔧 Custom Deploy Action Setup

Create Deploy Action Directory

mkdir -p .github/actions/deploy

Required Deploy Action Files

.github/actions/deploy/action.yml - Action definition
.github/actions/deploy/deploy.sh - Deployment script
.github/actions/deploy/README.md - Documentation

Sample Action Definition

# .github/actions/deploy/action.yml
name: "Deploy AttuneLogic API"
description: "Deploy API to specified environment"
inputs:
  environment:
    description: "Target environment (beta, alpha, production)"
    required: true
  domain:
    description: "Domain name"
    required: true
  ssh_host:
    description: "SSH host"
    required: true
  ssh_user:
    description: "SSH user"
    required: true
  ssh_pass:
    description: "SSH password/key"
    required: true
  ssh_port:
    description: "SSH port"
    required: true
    default: "22"
runs:
  using: "composite"
  steps:
    - name: Deploy
      shell: bash
      run: |
        chmod +x ${{ github.action_path }}/deploy.sh
        ${{ github.action_path }}/deploy.sh
      env:
        ENVIRONMENT: ${{ inputs.environment }}
        DOMAIN: ${{ inputs.domain }}
        SSH_HOST: ${{ inputs.ssh_host }}
        SSH_USER: ${{ inputs.ssh_user }}
        SSH_PASS: ${{ inputs.ssh_pass }}
        SSH_PORT: ${{ inputs.ssh_port }}

🖥️ Server Infrastructure Setup

Server Requirements

Server Directory Structure

/var/www/
├── beta.api.domain.com/
├── alpha.api.domain.com/
└── api.domain.com/

Environment Variables on Server

Each environment should have its own .env file:

PM2 Configuration

# Install PM2
npm install -g pm2

# Create ecosystem file for each environment
# ecosystem.config.js
module.exports = {
  apps: [
    {
      name: 'api-beta',
      script: './dist/index.js',
      cwd: '/var/www/beta.api.domain.com',
      env: { NODE_ENV: 'beta', PORT: 3001 }
    },
    {
      name: 'api-alpha',
      script: './dist/index.js',
      cwd: '/var/www/alpha.api.domain.com',
      env: { NODE_ENV: 'alpha', PORT: 3002 }
    },
    {
      name: 'api-production',
      script: './dist/index.js',
      cwd: '/var/www/api.domain.com',
      env: { NODE_ENV: 'production', PORT: 3000 }
    }
  ]
};

🌐 DNS & SSL Configuration

DNS Records

api.domain.com → Production server
alpha.api.domain.com → Alpha server (or same with different port)
beta.api.domain.com → Beta server (or same with different port)

SSL Certificates

Wildcard certificate for *.api.domain.com
Or individual certificates for each subdomain
Auto-renewal configured (Let's Encrypt recommended)

Nginx Configuration

# /etc/nginx/sites-available/api-environments

# Production
server {
    listen 80;
    listen 443 ssl;
    server_name api.domain.com;

    ssl_certificate /path/to/ssl/cert;
    ssl_certificate_key /path/to/ssl/key;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# Alpha
server {
    listen 80;
    listen 443 ssl;
    server_name alpha.api.domain.com;

    location / {
        proxy_pass http://localhost:3002;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# Beta
server {
    listen 80;
    listen 443 ssl;
    server_name beta.api.domain.com;

    location / {
        proxy_pass http://localhost:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

✅ Health Check Implementation

Required Health Endpoint

// src/routes/health.js
app.get("/health", (req, res) => {
  res.json({
    status: "ok",
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
    environment: process.env.NODE_ENV,
    version: require("../package.json").version,
  });
});

Health Check Validation

Returns HTTP 200 status
Includes environment name
Includes version number
Includes uptime information

🧪 Testing the Workflow

Initial Test Setup

Create test feature branch

git checkout -b feature/test-deployment
echo "test" > test.txt
git add test.txt
git commit -m "test: workflow validation"
git push origin feature/test-deployment

Verify Beta deployment triggers
Check auto-PR creation
Test health endpoints

End-to-End Test

Feature → Beta deployment works
Beta → Alpha promotion works
Alpha → Production deployment works
Version bumping works correctly
All auto-PRs created successfully

Rollback Test

Revert commit in alpha
Verify production rollback
Confirm health checks pass

📊 Monitoring Setup

GitHub Actions Monitoring

Email notifications enabled for failed workflows
Slack/Teams integration (optional)
Action usage monitoring

Application Monitoring

Server monitoring (CPU, memory, disk)
Application performance monitoring
Error tracking (Sentry, etc.)
Uptime monitoring for health endpoints

🚨 Security Checklist

GitHub Security

Secrets are properly secured (never logged)
Limited scope GitHub tokens
Environment-specific protection rules
Regular audit of repository access

Server Security

SSH key-based authentication (preferred over passwords)
Firewall configured properly
Regular security updates
Non-root deployment user

Application Security

Environment variables properly secured
Database connections encrypted
API rate limiting enabled
HTTPS enforced

📝 Documentation Requirements

Team Documentation

Workflow guide for developers
Deployment procedures documented
Emergency contact information
Rollback procedures documented

Runbooks

Deployment failure recovery
Server maintenance procedures
Database backup/restore procedures
Performance issue troubleshooting

🎯 Final Validation

Pre-Production Checklist

All tests passing in CI/CD
Security features implemented and tested
Performance benchmarks met
Documentation complete and up-to-date
Team trained on new workflow

Go-Live Checklist

Production environment fully configured
Monitoring and alerting active
Emergency procedures tested
Stakeholders notified of new process

🎉 Success Criteria

Operational Goals

Deployment frequency: Daily to weekly
Deployment time: < 10 minutes
Failure rate: < 5%
Recovery time: < 30 minutes

Team Goals

Developer confidence: High comfort with new process
Release velocity: Faster feature delivery
Quality: Fewer production issues
Visibility: Clear deployment status

🎊 Congratulations! Your GitHub Actions deployment workflow is now fully configured and ready for production use!

📋 Pre-Setup Requirements​

Repository Structure​

Required Package.json Scripts​

🔐 Repository Configuration​

1. GitHub Repository Secrets​

2. GitHub Environments​

Create Beta Environment​

Create Alpha Environment​

Create Production Environment​

3. Repository Permissions​

🌿 Branch Protection Setup​

Main Branch Protection​

Alpha Branch Protection​

Beta Branch Protection​

🔧 Custom Deploy Action Setup​

Create Deploy Action Directory​

Required Deploy Action Files​

Sample Action Definition​

🖥️ Server Infrastructure Setup​

Server Requirements​

Server Directory Structure​

Environment Variables on Server​

PM2 Configuration​

🌐 DNS & SSL Configuration​

DNS Records​

SSL Certificates​

Nginx Configuration​

✅ Health Check Implementation​

Required Health Endpoint​

Health Check Validation​

🧪 Testing the Workflow​

Initial Test Setup​

End-to-End Test​

Rollback Test​

📊 Monitoring Setup​

GitHub Actions Monitoring​

Application Monitoring​

🚨 Security Checklist​

GitHub Security​

Server Security​

Application Security​

📝 Documentation Requirements​

Team Documentation​

Runbooks​

🎯 Final Validation​

Pre-Production Checklist​

Go-Live Checklist​

🎉 Success Criteria​

Operational Goals​

Team Goals​