Deployment Automation Guide

May 10, 2026 · View on GitHub

Overview

This guide describes the automated deployment workflows for the GXQ Studio platform, including Vercel and Railway deployments with health checks and automatic rollback.

Deployment Workflows

1. Vercel Deployment (`.github/workflows/deploy-vercel.yml`)

Triggers:

Push to main branch (automatic)
Manual workflow dispatch with environment selection

Features:

✅ Automatic build and deployment
✅ Health check after deployment
✅ Automatic rollback on failure
✅ Deployment status tracking
✅ PR comments with preview URLs

Required Secrets:

VERCEL_TOKEN         # Vercel API token
VERCEL_ORG_ID        # Vercel organization ID
VERCEL_PROJECT_ID    # Vercel project ID

Manual Deployment:

# Trigger via GitHub CLI
gh workflow run deploy-vercel.yml -f environment=production

# Or via GitHub UI
# Actions → Deploy to Vercel → Run workflow

Deployment Steps:

Checkout code
Install Vercel CLI
Pull Vercel environment configuration
Build project artifacts
Deploy to Vercel
Create GitHub deployment record
Run health check
Comment on PR (if applicable)
Rollback on failure

2. Railway Deployment (`.github/workflows/deploy-railway.yml`)

Triggers:

Push to main branch (automatic)
Manual workflow dispatch

Features:

✅ Automatic build and deployment
✅ Health check with retries
✅ Endpoint validation tests
✅ Deployment status tracking
✅ Error reporting via GitHub issues

Required Secrets:

RAILWAY_TOKEN        # Railway API token
RAILWAY_PROJECT_ID   # Railway project ID

Manual Deployment:

# Trigger via GitHub CLI
gh workflow run deploy-railway.yml

# Or via Railway CLI
railway up

Deployment Steps:

Checkout code
Install dependencies
Run tests
Build project
Install Railway CLI
Deploy to Railway
Wait for deployment to be ready
Run health check with retries
Test all endpoints
Create deployment record

Health Check System

Health Check Endpoint

URL: /api/health

Response:

{
  "status": "healthy",
  "rpcLatency": 150,
  "walletBalance": 1.5,
  "walletAddress": "...",
  "jupiterApiStatus": "online",
  "uptime": 3600,
  "errorRate": 0.5,
  "timestamp": 1703001234567
}

Status Codes:

200 - Healthy
503 - Unhealthy (degraded)

Health Check Process

RPC Connection Check
- Connect to Solana RPC
- Measure latency
- Verify connectivity
Wallet Check
- Load wallet from private key
- Check balance
- Warn if balance < 0.01 SOL
Jupiter API Check
- Test Jupiter quote API
- Verify availability
- 5-second timeout
Error Rate Check
- Calculate error rate
- Status degraded if > 20%
- Status unhealthy if > 50%

Automatic Rollback

Trigger Conditions:

Health check fails after deployment
Deployment build fails
Critical error detected

Rollback Process:

Detect failure via health check
Trigger rollback job
Revert to previous deployment
Notify via GitHub
Create incident issue

Manual Rollback:

# Vercel
vercel rollback --token=$VERCEL_TOKEN

# Railway
railway rollback

Deployment Environments

Production (Vercel)

URL: https://TradeOS.app
Branch: main
Auto-deploy: Yes
Rollback: Automatic on failure

Production (Railway)

URL: Auto-generated
Branch: main
Auto-deploy: Yes
Health checks: 5 retries with 10s delay

Preview (Vercel)

URL: Auto-generated per PR
Branch: Any PR branch
Auto-deploy: On PR sync
Comments: Automatic PR comments

Required Environment Variables

All Environments

# Solana Configuration
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
WALLET_PRIVATE_KEY=your_base58_private_key

# Admin Panel
ADMIN_USERNAME=admin
ADMIN_PASSWORD=strong_password
JWT_SECRET=your_32_character_secret

# Trading Configuration
MINIMUM_PROFIT_SOL=0.01
MAX_SLIPPAGE=0.01

# Optional: Cron security
CRON_SECRET=your_cron_secret

Vercel-Specific

# For webapp builds
NEXT_PUBLIC_RPC_URL=https://api.mainnet-beta.solana.com

Setting Environment Variables

Vercel:

vercel env add SOLANA_RPC_URL production
vercel env add WALLET_PRIVATE_KEY production

Railway:

railway variables set SOLANA_RPC_URL=your_value
railway variables set WALLET_PRIVATE_KEY=your_value

GitHub Actions (Secrets):

Go to repository Settings
Click Secrets and variables → Actions
Click New repository secret
Add each secret

Deployment Checklist

Pre-Deployment

Deployment

Post-Deployment

Monitoring Deployments

View Deployment Status

GitHub:

# List deployments
gh api repos/:owner/:repo/deployments

# View specific deployment
gh api repos/:owner/:repo/deployments/:id

# View deployment statuses
gh api repos/:owner/:repo/deployments/:id/statuses

Vercel:

# View deployments
vercel ls

# View logs
vercel logs [deployment-url]

Railway:

# View deployments
railway status

# View logs
railway logs

Monitor Health

# Production health check
curl https://your-domain.vercel.app/api/health

# Watch health continuously
watch -n 5 'curl -s https://your-domain.vercel.app/api/health | jq'

Alert Configuration

Set up alerts for:

Deployment failures
Health check failures
High error rates
Low wallet balance
RPC connectivity issues

Troubleshooting

Deployment Fails to Build

Check:

Build logs in GitHub Actions
Dependencies installed correctly
TypeScript compilation errors
Environment variables set

Solution:

# Test build locally
npm run build

# Check for errors
npm run lint

Health Check Fails

Check:

RPC URL accessible
Wallet private key valid
Environment variables set
Jupiter API accessible

Solution:

# Test RPC connection
curl -X POST $SOLANA_RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'

# Test health endpoint
curl https://your-domain.vercel.app/api/health

Rollback Doesn't Work

Check:

Previous deployment exists
Deployment permissions
API tokens valid

Solution:

# List previous deployments
vercel ls

# Manual rollback to specific deployment
vercel rollback [deployment-url]

Environment Variables Not Set

Check:

Variables configured in platform
Variable names match exactly
Deployment refreshed after changes

Solution:

# Vercel: List variables
vercel env ls

# Railway: List variables
railway variables

Auto-Merge Integration

The auto-merge workflow now includes deployment checks:

Requirements:

✅ All CI checks passed
✅ At least 1 approval
✅ No changes requested
✅ Deployment successful (if triggered)
✅ Health checks passing

Labels:

auto-merge - Enable auto-merge for PR
skip-deployment - Skip deployment checks

Best Practices

1. Test Before Deploying

# Run full test suite
npm test

# Build locally
npm run build

# Lint code
npm run lint

# Validate endpoints
npm run validate-endpoints http://localhost:3000