claude-code-hub/.github/CI_CD_SETUP.md

GitHub Actions CI/CD 配置说明

📋 工作流概览

本项目包含两个独立的 GitHub Actions 工作流：

1. PR 构建检查 (pr-check.yml)

• 触发条件：向 dev 或 main 分支提交 Pull Request
• 功能：构建 Docker 镜像但不推送，用于验证代码可构建性
• 作用：作为合并前的质量门控

2. 版本发布 (release.yml)

• 触发条件：在 main 分支上创建符合 x.x.x 格式的标签
• 功能：构建并推送 Docker 镜像到 DockerHub
• 推送标签：版本标签 + latest 标签

🔐 必需的 GitHub Secrets

在仓库设置中配置以下 Secrets：

DOCKERHUB_USERNAME = ding113
DOCKERHUB_TOKEN = <your-dockerhub-access-token>

获取 DockerHub Token

1. 登录 Docker Hub
2. Account Settings → Security
3. New Access Token → 创建具有 Read & Write 权限的 Token

🛡️ 分支保护规则配置

为 dev 分支设置保护规则

1. 进入仓库 Settings → Branches
2. Add rule → Branch name pattern: dev
3. 配置以下选项：

必选项：

• Require a pull request before merging
• Require status checks to pass before merging
  • 搜索并选择：Docker Build Test
• Require branches to be up to date before merging

可选项（根据团队需求）：

• Require approvals (需要审核批准)
• Dismiss stale pull request approvals when new commits are pushed
• Require review from CODEOWNERS

1. Create 保存规则

为 main 分支设置保护规则

1. Add rule → Branch name pattern: main
2. 配置以下选项：

必选项：

• Require a pull request before merging
• Require status checks to pass before merging
  • 搜索并选择：Docker Build Test
• Require branches to be up to date before merging
• Include administrators (管理员也需要遵守规则)

推荐选项：

• Require approvals (数量：1-2)
• Require conversation resolution before merging
• Do not allow bypassing the above settings

1. Create 保存规则

🔄 工作流程示例

1. 功能开发流程

# 1. 创建功能分支
git checkout -b feature/new-feature

# 2. 开发并提交代码
git add .
git commit -m "feat: add new feature"
git push origin feature/new-feature

# 3. 创建 PR 到 dev 分支
# GitHub 会自动运行构建检查

# 4. 构建通过后，合并到 dev

2. 发布流程

# 1. 从 dev 合并到 main
git checkout main
git merge dev
git push origin main

# 2. 创建版本标签
git tag 1.0.0
git push origin 1.0.0

# 3. GitHub Actions 自动：
#    - 验证标签在 main 分支上
#    - 构建 Docker 镜像
#    - 推送到 DockerHub (1.0.0 + latest)
#    - 创建 GitHub Release

🐳 Docker 镜像使用

发布后，可以使用以下命令拉取镜像：

# 最新版本
docker pull ding113/claude-code-hub:latest

# 特定版本
docker pull ding113/claude-code-hub:1.0.0

# 运行容器
docker run -d \
  -p 3000:3000 \
  --env-file .env \
  ding113/claude-code-hub:latest

⚠️ 注意事项

1. 版本标签格式：必须是 x.x.x 格式（如 1.0.0），可选 v 前缀（如 v1.0.0）
2. 分支策略：
   • feature/* → dev (通过 PR)
   • dev → main (通过 PR)
   • 标签只在 main 分支创建
3. 缓存优化：工作流使用 GitHub Actions 缓存加速构建
4. 多平台支持：自动构建 linux/amd64 和 linux/arm64 架构

🚨 故障排除

PR 构建失败

• 检查 Dockerfile 语法
• 查看 Actions 日志中的错误信息
• 确保所有依赖正确安装

无法推送到 DockerHub

• 验证 Secrets 配置正确
• 检查 DockerHub Token 权限
• 确认 DockerHub 仓库名称正确

标签发布未触发

• 确保标签格式正确（x.x.x）
• 确认标签在 main 分支上创建
• 检查 Actions 是否被禁用