⚡

部署到预发布环境Skill deploying-to-staging-environment

这是一个DevOps技能，用于协调多仓库代码同步并自动部署到预发布环境。核心功能包括：使用Git Worktrees进行分支管理、跨仓库同步、GitHub Actions自动化部署、Fly.io云平台部署、健康检查验证。关键词：多仓库部署、Git Worktrees、GitHub Actions、CI/CD流水线、预发布环境、自动化部署、DevOps工作流、分支同步、云部署、集成测试。

DevOps 0 次安装 0 次浏览 更新于 2/28/2026

name: 部署到预发布环境 description: 当需要跨relay、relay-dashboard和relay-cloud仓库部署变更到预发布环境时使用 - 使用git worktrees协调多仓库分支同步，通过GitHub Actions自动触发预发布部署

部署到预发布环境

概述

预发布环境部署是一个协调的多仓库流程，同步三个仓库（relay、relay-dashboard、relay-cloud）的代码，并通过GitHub Actions自动触发部署。预发布部署确保在生产环境前进行功能验证，同时在开发期间保持主分支的清洁。

何时使用

  • 跨仓库集成功能 - 多个组件依赖于不同仓库的变更
  • 一起测试功能分支 - 验证功能分支变更不会破坏集成
  • 将主分支提升到预发布 - 标准同步以保持预发布环境与最新主分支同步
  • 验证部署就绪性 - 测试基础设施变更或部署工作流
  • 跨团队协调 - 共享功能分支进行集成测试

何时不使用：

  • 紧急热修复（改用生产部署）
  • 仅单仓库变更（如果不阻塞其他仓库，直接推送）
  • 无部署意图的测试（改用本地环境）

架构

预发布部署系统包括：

三个仓库（relay、relay-dashboard、relay-cloud）
    ↓
预发布分支（通过git push同步）
    ↓
relay-cloud预发布推送触发GitHub Actions
    ↓
部署预发布工作流（deploy-staging.yml）
    ↓
Fly.io预发布环境（agent-relay-staging）
    ↓
自动健康检查验证

关键细节：

  • 每个仓库都有独立的预发布分支
  • relay-cloud预发布分支推送触发自动部署
  • 工作流接受可选的relay/dashboard分支覆盖
  • 如果指定分支不存在，则回退到主分支
  • 工作空间镜像构建与API部署并行进行

快速参考

标准工作流（所有仓库）

# 1. 为预发布工作创建git worktree（最佳实践）
cd /data/repos/relay
git worktree add .worktrees/staging-push main
cd .worktrees/staging-push

# 2. 推送最新主分支到预发布（获取最新）
git fetch origin main:main
git push origin main:staging

# 3. 或将当前功能分支推送到预发布（如果需要）
git fetch origin feature/your-branch:feature/your-branch
git push origin feature/your-branch:staging

# 4. 清理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（触发部署）

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
# ⚠️ 此推送触发deploy-staging.yml工作流
cd /data/repos/relay-cloud
git worktree remove .worktrees/staging-push

实现

为什么使用Git Worktrees？

Git worktrees为预发布工作流提供了几个好处：

  1. 隔离性 - 在不改变主工作目录状态的情况下处理预发布
  2. 安全性 - 在worktree中检出的功能分支不会影响当前工作
  3. 清洁性 - 推送后没有残留的状态变更
  4. 最佳实践 - 多分支操作的标准DevOps方法

分步部署流程

先决条件

  • 对所有三个仓库具有推送权限的访问权限
  • 当前工作目录：其中一个仓库
  • 没有未提交的变更阻止worktree创建

在所有仓库中执行预发布推送

步骤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

预期输出：

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

步骤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

步骤3：Relay-Cloud（触发部署）

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
# 部署自动开始！
cd /data/repos/relay-cloud
git worktree remove .worktrees/staging-push

验证部署

推送relay-cloud后，GitHub Actions自动开始：

  1. 监视工作流进度：

  2. 验证健康检查：

    • 工作流运行 curl https://agent-relay-staging.fly.dev/health
    • 预期：150秒内收到200响应
    • 以5秒间隔重试30次

  3. 检查部署摘要：

    • 点击工作流运行
    • 查看步骤摘要中的“Deployment Summary”
    • 确认部署到agent-relay-staging

推送功能分支到预发布

代替主分支，推送特定的功能分支：

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

对于具有自定义relay/dashboard分支的relay-cloud：

deploy-staging.yml工作流接受可选输入以指定确切分支：

# 推送relay-cloud预发布（将使用输入触发GitHub Actions）
cd /data/repos/relay-cloud
git worktree add .worktrees/staging-push main
cd .worktrees/staging-push
git fetch origin feature/custom-branch:feature/custom-branch
git push origin feature/custom-branch:staging
cd /data/repos/relay-cloud
git worktree remove .worktrees/staging-push

然后手动触发指定分支：

常见错误

错误 问题 修复
从脏工作树推送 Worktree创建失败并报错 在创建worktree之前提交或暂存变更
忘记移除worktree 积累worktree目录 推送后始终运行 git worktree remove .worktrees/staging-push
推送预发布而没有relay/dashboard 部署使用过时的relay/dashboard 协调所有三个仓库或使用GitHub Actions输入覆盖
未获取最新引用 推送过时的本地分支状态 推送前始终 git fetch origin branch:branch
混淆预发布分支方向 推送main→staging，而不是staging→main 记住：功能工作 → 预发布分支，用于提升/测试
假设所有仓库自动同步 relay/dashboard变更不会自动触发 只有relay-cloud预发布推送触发部署
未检查健康状态 部署可能静默失败 始终验证工作流完成且健康检查通过
在错误目录中创建worktrees 多个仓库的路径混淆 每个仓库是独立的；在该仓库的.worktrees/内创建worktrees

工作流详情

deploy-staging.yml行为

触发器：

  • 手动推送到预发布分支（自动）
  • GitHub Actions workflow_dispatch（手动，带可选输入）

可选工作流输入：

  • relay_branch - 覆盖要部署的relay分支（默认为当前预发布分支）
  • dashboard_branch - 覆盖要部署的relay-dashboard分支（默认为当前预发布分支）
  • 如果指定分支在远程不存在，则回退到主分支

部署步骤：

  1. 检出relay-cloud仓库
  2. 确定relay分支（输入或当前，回退到主分支）
  3. 确定dashboard分支（输入或当前，回退到主分支）
  4. 设置Fly CLI
  5. 使用 flyctl deploy 部署到Fly.io
  6. 验证健康检查端点
  7. 创建部署摘要

环境： staging（需要GitHub Actions环境密钥）

部署成功标准

✅ 所有检查通过：

  • [ ] “Deploy to Staging”作业完成
  • [ ] “Build Staging Workspace”作业完成
  • [ ] 健康检查成功（来自/health端点的HTTP 200）
  • [ ] 部署摘要显示所有预期值

❌ 部署失败：

  • 工作流运行显示红色X
  • 检查工作流日志中失败的步骤
  • 常见失败：身份验证（密钥）、健康检查超时、Docker构建错误

实际工作流

场景： 跨所有三个仓库的功能准备进行集成测试

# 1. 确保本地主分支是最新的
cd /data/repos/relay
git fetch origin main

cd /data/repos/relay-dashboard
git fetch origin main

cd /data/repos/relay-cloud
git fetch origin main

# 2. 推送relay主分支到预发布（使用worktree）
cd /data/repos/relay
git worktree add .worktrees/staging-push main
cd .worktrees/staging-push
git push origin main:staging
cd ..
git worktree remove .worktrees/staging-push

# 3. 推送relay-dashboard主分支到预发布
cd /data/repos/relay-dashboard
git worktree add .worktrees/staging-push main
cd .worktrees/staging-push
git push origin main:staging
cd ..
git worktree remove .worktrees/staging-push

# 4. 推送relay-cloud主分支到预发布（触发部署）
cd /data/repos/relay-cloud
git worktree add .worktrees/staging-push main
cd .worktrees/staging-push
git push origin main:staging
cd ..
git worktree remove .worktrees/staging-push

# 5. 监控部署
echo "检查：https://github.com/AgentWorkforce/relay-cloud/actions"
# 等待“Deploy (Staging)”工作流完成
# 验证健康检查通过
# 访问预发布环境：https://agent-relay-staging.fly.dev

故障排除

Worktree错误

错误：“fatal: ‘main’ already exists”

解决方案：git worktree remove .worktrees/staging-push
         （如果先前运行的worktree仍然存在）

错误：“fatal: cannot checkout branch into locked working tree”

解决方案：确保主分支未在主要工作树中检出
         git status（确认检出的是不同分支）

部署失败

健康检查150秒后超时

问题：预发布环境花费太长时间才变得健康
解决方案：- 检查Fly.io日志：flyctl logs --app agent-relay-staging
         - 重启应用：flyctl restart --app agent-relay-staging
         - 检查工作流日志中的构建错误
         - 查找部署步骤中的启动错误

Docker构建失败

问题：“Build Staging Workspace”作业失败
解决方案：- 检查docker-staging.yml工作流日志
         - 验证Dockerfile存在且有效
         - 检查资源/依赖问题
         - 本地重建以验证docker配置

分支未找到回退到主分支

问题：工作流说“using main”表示您的自定义分支
原因：指定分支在relay/relay-dashboard中不存在
解决方案：- 验证分支名称完全匹配（区分大小写）
         - 确保分支存在于远程（git ls-remote origin）
         - 使用GitHub Actions workflow_dispatch并输入正确的输入

依赖项与要求

Git： Worktree功能（Git 2.5+，所有现代系统标准）

权限： 对所有三个仓库的推送访问权限：

GitHub密钥（relay-cloud）：

  • CROSS_REPO_TOKEN - 具有跨所有三个仓库访问权限的PAT
  • FLY_API_TOKEN 或 FLY_API_TOKEN_STAGING - Fly.io部署令牌

环境： staging（在relay-cloud中配置）

关键原则： 使用git worktrees进行清洁、隔离的分支操作。跨仓库推送协调，relay-cloud预发布推送触发自动部署。