deploying-to-staging-environment
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
AgentWorkforce · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add AgentWorkforce/relay --skill 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:
- Isolation - Work on staging without changing main working directory state
- Safety - Feature branch checked out in worktree won't affect your current work
- Cleanliness - No lingering state changes after pushing
- 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:
-
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)
-
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
- Workflow runs
-
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-
阅读完整来源 ↗