deploying-to-staging-environment

Deploying to Staging Environment

Overview

The staging environment deployment is a coordinated multi-repo process that synchronizes code across three repositories (relay, relay-dashboard, relay-cloud) and automatically triggers deployment via GitHub Actions. Staging deployments ensure feature verification before production while keeping main branch clean during development.

When to Use

• Integrating features across repos - Multiple components depend on changes in different repos
• Testing feature branches together - Verify feature branch changes don't break integration
• Promoting main to staging - Standard sync to keep staging up-to-date with latest main
• Verifying deployment readiness - Test infrastructure changes or deployment workflows
• Cross-team coordination - Share feature branches for integration testing

When NOT to use:

• Emergency hotfixes (use production deployment instead)
• Single-repo changes only (push directly if not blocking other repos)
• Testing without intent to deploy (use local environment instead)

Architecture

The staging deployment system consists of:

Three Repos (relay, relay-dashboard, relay-cloud)
    ↓
Staging Branches (synced via git push)
    ↓
relay-cloud staging push triggers GitHub Actions
    ↓
Deploy-Staging Workflow (deploy-staging.yml)
    ↓
Fly.io Staging Environment (agent-relay-staging)
    ↓
Automatic health check verification

Key details:

• Each repo has independent staging branch
• relay-cloud staging branch push triggers automatic deployment
• Workflow accepts optional relay/dashboard branch overrides
• Falls back to main if specified branch doesn't exist
• Workspace image builds in parallel with API deployment

Quick Reference

Standard Workflow (All Repos)

# 1. Create git worktree for staging work (BEST PRACTICE)
cd /data/repos/relay
git worktree add .worktrees/staging-push main
cd .worktrees/staging-push

# 2. Push latest main to staging (fetch fresh)
git fetch origin main:main
git push origin main:staging

# 3. Or push current feature branch to staging (if desired)
git fetch origin feature/your-branch:feature/your-branch
git push origin feature/your-branch:staging

# 4. Clean up worktree
cd /data/repos/relay
git worktree remove .worktrees/staging-push