# Deploying To Staging Environment

Use when deploying changes to staging across relay, relay-dashboard, and relay-cloud...

- Repository: https://github.com/AgentWorkforce/relay (1088 stars)
- Category: Git and review
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add AgentWorkforce/relay --skill deploying-to-staging-environment -g -a claude-code -y`
Codex: `npx skills add AgentWorkforce/relay --skill deploying-to-staging-environment -g -a codex -y`
Cursor: `npx skills add AgentWorkforce/relay --skill deploying-to-staging-environment -g -a cursor -y`
Gemini CLI: `npx skills add AgentWorkforce/relay --skill deploying-to-staging-environment -g -a gemini-cli -y`

## 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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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)

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

The rest: https://github.com/AgentWorkforce/relay/blob/HEAD/.claude/skills/deploying-to-staging-environment/SKILL.md