mcpField
G
git-multibranch

git-multibranch

github.com/letta-ai云与 DevOps15237 次安装4 周前更新
代码仓库

关于 git-multibranch

Git Multi-Branch Deployment 是一项配置指南型 skill，用于通过 Git post-receive hook 将不同分支部署到不同 Web 服务器目录。内容涵盖 SSH、裸仓库、Web 服务器配置及部署验证，面向搭建分支式自动部署流程的场景。

主要功能

  1. 01配置专用 Git 用户与 SSH
  2. 02创建裸仓库并初始化分支
  3. 03按分支配置 Web 部署目录
  4. 04用 post-receive hook 执行部署
  5. 05验证推送、部署与页面访问

适用场景

  1. 01将 main 与 dev 部署到不同目录
  2. 02搭建通过 SSH 推送的 Web 部署
  3. 03排查 hook 未执行或权限问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/letta-ai/skills --skill git-multibranch

安装后在 Claude Code 中输入/git-multibranch确认已加载。

详细介绍

Git 多分支部署

概述

本技能介绍如何设置基于 Git 的部署系统，让多个分支（例如 main、dev）通过 post-receive 钩子自动部署到不同的 Web 服务器位置。内容涵盖 SSH 配置、Git 仓库设置、Web 服务器配置和自动化部署工作流。

前置条件验证

开始之前，请验证所有必需的工具和配置：

  • 检查必需的软件包：git、openssh-server、sshpass（用于测试）、Web 服务器（nginx/apache）
  • 确认 SSH（22）和 HTTP/HTTPS（80/443）端口可用
  • 确认拥有创建用户的权限
  • 提前设置 Git 默认分支名称：git config --global init.defaultBranch main

实施步骤

1. 用户和 SSH 设置

操作：

  • 创建专用的 Git 用户，并为其设置主目录
  • 设置用于 SSH 身份验证的密码
  • 配置 SSH 以允许密码身份验证

SSH 配置注意事项：

  • 修改 /etc/ssh/sshd_config 设置：PasswordAuthentication yes、ChallengeResponseAuthentication yes
  • 考虑可能造成干扰的其他设置：UsePAM、KbdInteractiveAuthentication
  • 更改配置后重启 SSH 服务
  • 规划测试中的 SSH 主机密钥验证（可预先接受密钥，或处理 StrictHostKeyChecking）
2. 创建 Git 仓库

操作：

  • 在 Git 用户的主目录中创建一个裸 Git 仓库
  • 使用适当的权限进行初始化
  • 创建包含内容的初始分支

分支设置模式：

1. Clone the bare repo to a temp location
2. Create initial commit on main branch
3. Create and populate additional branches (e.g., dev)
4. Push all branches to the bare repo
3. Web 服务器配置

操作：

  • 为每个分支创建部署目录（例如 /var/www/main、/var/www/dev）
  • 为 Git 用户设置适当的所有权和权限
  • 为每个部署目标配置虚拟主机或服务器块
  • 如需 HTTPS，则处理 SSL 证书

SSL 证书生成（自签名）：

  • 使用带有适当主题和 SAN 扩展的 openssl req
  • 配置 Web 服务器使用这些证书和现代 TLS 协议
4. 创建 Post-Receive 钩子

操作：

  • 在裸仓库的 hooks/ 目录中创建可执行的 post-receive 钩子
  • 解析 ref 更新，以确定推送的是哪个分支
  • 将相应分支检出到对应的部署目录

钩子结构：

1. Read stdin for ref updates (oldrev newrev refname)
2. Parse branch name from refname
3. For each target branch, checkout to deployment directory using GIT_WORK_TREE
5. 服务配置

操作：

  • 启动并启用所需服务（SSH、Web 服务器）
  • 如需持久运行，则配置服务在启动时自动运行
  • 确认服务正在运行且可访问

验证策略

SSH 访问验证
  • 使用密码测试 SSH 连接：sshpass -p <password> ssh -o StrictHostKeyChecking=no <user>@<host>
  • 验证通过 SSH 执行 Git 操作是否正常
Git 操作验证
  • 通过 SSH 克隆仓库
  • 创建测试提交并推送到每个分支
  • 确认推送顺利完成，没有错误
部署验证
  • 每次推送后，确认内容出现在正确的部署目录中
  • 测试 Web 服务器是否为每个分支/端点提供正确的内容
  • 确认部署在规定的时间限制内完成
端到端测试模式
1. Clone repository to fresh test directory
2. Make changes to branch content
3. Push changes
4. Immediately verify web endpoint reflects changes
5. Time the deployment if latency requirements exist

常见问题和错误

分支命名混淆
  • 问题： Git 可能默认使用 master 而不是 main
  • 解决方案： 创建仓库前设置 git config --global init.defaultBranch main
  • 恢复方法： 如果分支已创建，可使用 git branch -m master main 重命名分支
SSH 配置不完整
  • 问题： 即使更改了配置，SSH 连接仍然失败
  • 原因： 缺少 UsePAM、KbdInteractiveAuthentication 等设置，或服务未重启
  • 解决方案： 检查所有相关的 SSH 设置，并在更改后重启 sshd
主机密钥验证失败
  • 问题： SSH 命令因主机密钥验证错误而失败
  • 解决方案：
    • 预先接受主机密钥：ssh-keyscan -H <host> >> ~/.ssh/known_hosts
    • 测试时使用 StrictHostKeyChecking=no（说明相关安全影响）
测试期间的推送冲突
  • 问题： 重新测试时出现非快进错误
  • 原因： 先前的测试数据与新的推送发生冲突
  • 解决方案：
    • 每次测试都使用新的测试目录
    • 视情况强制推送：git push --force
    • 在测试之间重置仓库状态
Post-Receive Hook 问题
  • 问题： Hook 未执行，或部署失败但没有提示
  • 原因： Hook 不可执行、shebang 错误、缺少 GIT_WORK_TREE
  • 验证： 在 Hook 中添加日志，使用 ls -la hooks/ 检查权限
服务状态问题
  • 问题： 服务未运行或未能在启动时运行
  • 解决方案： 使用 systemctl enable 确保服务在启动时运行，并在测试前验证状态
缺少前置条件
  • 问题： 因未安装所需工具而导致命令失败
  • 解决方案： 在开始时检查所有前置条件，并在开始设置前安装缺少的软件包

需要考虑的边缘情况

未处理的分支推送
  • 确定推送其他非已配置分支时的处理方式
  • 说明应静默忽略、发出警告还是报错
部署失败
  • 考虑在 post-receive Hook 中添加错误处理
  • 确定部署失败时的通知机制
并发推送
  • 注意同时推送可能引发的竞态条件
  • 考虑在生产环境中添加锁定机制
权限问题
  • 确保 Git 用户对所有部署目录都有写入权限
  • 创建目录后验证所有权

效率建议

减少重复操作
  • 为重复使用的 SSH 命令设置环境变量：export GIT_SSH_COMMAND='sshpass -p password ssh -o StrictHostKeyChecking=no'
  • 将相关操作批量合并到单次 Shell 调用中
清理测试
  • 使用相互隔离的测试目录，避免累积临时文件
  • 在每次运行之间清理测试仓库
命令可用性
  • 使用命令前验证其是否存在（例如，计时操作前运行 command -v time）
  • 准备好备用方案（例如，使用 date +%s%3N 代替 time）

评论

支持 Markdown