/deploying-to-staging-environment

name: deploying-to-staging-environment
description: Use when deploying changes to staging across relay, relay-dashboard, and relay-cloud repos - coordinates multi-repo branch syncing using git worktrees, automatically triggers staging deployments via GitHub Actions

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

Relay-Dashboard

cd /data/repos/relay-dashboard
git worktree add .worktrees/staging-push main
cd .worktrees/staging-push
git fetch origin main:main
git push origin main:staging
cd /data/repos/relay-dashboard
git worktree remove .worktrees/staging-push

Relay-Cloud (Triggers Deployment)

cd /data/repos/relay-cloud
git worktree add .worktrees/staging-push main
cd .worktrees/staging-push
git fetch origin main:main
git push origin main:staging
# ⚠️ This push triggers deploy-staging.yml workflow
cd /data/repos/relay-cloud
git worktree remove .worktrees/staging-push

Implementation

Why Git Worktrees?

Git worktrees provide several benefits for staging workflows:

1. **Isolation** - Work on staging without changing main working directory state 2. **Safety** - Feature branch checked out in worktree won't affect your current work 3. **Cleanliness** - No lingering state changes after pushing 4. **Best practice** - Standard DevOps approach for multi-branch operations

Step-by-Step Deployment Process

Prerequisites

• Access to all three repos with push permission
• Current working directory: one of the repos
• No uncommitted changes blocking worktree creation

Execute Staging Push Across All Repos

**Step 1: Relay**

cd /data/repos/relay
git worktree add .worktrees/staging-push main
cd .worktrees/staging-push
git fetch origin main:main
git push origin main:staging
cd /data/repos/relay
git worktree remove .worktrees/staging-push

Expected output:

Updated 'main' to 'origin/main'
remote: Create pull request for staging...
To github.com:AgentWorkforce/relay.git
 [new branch]      main -> staging
or
 * [up-to-date]    main -> staging

**Step 2: Relay-Dashboard**

cd /data/repos/relay-dashboard
git worktree add .worktrees/staging-push main
cd .worktrees/staging-push
git fetch origin main:main
git push origin main:staging
cd /data/repos/relay-dashboard
git worktree remove .worktrees/staging-push

**Step 3: Relay-Cloud (Triggers Deployment)**

cd /data/repos/relay-cloud
git worktree add .worktrees/staging-push main
cd .worktrees/staging-push
git fetch origin main:main
git push origin main:staging
# Deployment starts automatically!
cd /data/repos/relay-cloud
git worktree remove .worktrees/staging-push

Verify Deployment

After pushing relay-cloud, GitHub Actions starts automatically:

1. **Watch workflow progress:**

• Go to: https://github.com/AgentWorkforce/relay-cloud/actions
• Find "Deploy (Staging)" workflow run
• Check that both jobs pass:
• "Deploy to Staging" (Fly.io deployment)
• "Build Staging Workspace" (Docker image build)

2. **Verify health check:**

• Workflow runs `curl https://agent-relay-staging.fly.dev/health`
• Expected: 200 response within 150 seconds
• Retries 30 times with 5-second intervals

3. **Check deployment summary:**

• Click workflow run
• View "Deployment Summary" in step summary
• Confirms deployment to agent-relay-staging

Pushing Feature Branches to Staging

Instead of main, push a specific feature branch:

cd /data/repos/relay
git worktree add .worktrees/staging-push main
cd .worktrees/staging-push
git fetch origin feature/your-feature:feature/your-feature
git push origin feature/your-feature:staging
cd /data/repos/relay
git worktree remove .worktrees/staging-push

**For relay-