Redmine GitHub Hook 插件技术文档

1. 安装指南

1.1 安装插件

1. 在 Gemfile.local 文件中添加以下内容：

   gem "redmine_github_hook"
   

2. 运行 bundle 命令安装依赖。
3. 执行数据库迁移：

   bundle exec rake redmine:plugins:migrate RAILS_ENV=production
   

4. 重启 Redmine 服务。

1.2 添加 Git 仓库到 Redmine

1. 按照 Redmine 官方文档的说明，将 Git 仓库添加到项目中。
2. 注意：不需要设置 cron 任务来同步仓库。

1.3 连接 GitHub 到 Redmine

1. 在 GitHub 仓库的设置界面中，进入 "Webhooks & Services" 部分。
2. 添加一个新的 "WebHook"，"Payload URL" 格式为：[redmine_url]/github_hook（例如 http://redmine.example.com/github_hook）。
3. 如果 GitHub 仓库名称与 Redmine 项目标识符不同，可以在 Post-Receive URL 中指定 Redmine 项目标识符，格式为：[redmine_url]/github_hook?project_id=[identifier]（例如 http://redmine.example.com/github_hook?project_id=my_project）。
4. 如果只想更新当前仓库，可以在 Post-Receive URL 中添加 repository_id 参数，格式为：[redmine_url]/github_hook?project_id=[identifier]&repository_id=[repository]（例如 http://redmine.example.com/github_hook?project_id=my_project&repository_id=my_repo）。
5. 通常只需要在 "push" 事件触发 Webhook，但可以根据需要自定义事件。

2. 项目的使用说明

2.1 功能概述

Redmine GitHub Hook 插件允许在 GitHub 上推送更改时，自动更新 Redmine 中的本地 Git 仓库。这样可以避免手动同步仓库的繁琐操作，确保 Redmine 中的代码和更改集始终保持最新。

2.2 工作流程

1. 开发者从本地机器推送代码到 GitHub。
2. GitHub 发送 HTTP POST 请求到 Redmine 的 /github_hook 端点。
3. Redmine 插件接收到请求后，从 GitHub 拉取最新的更改并更新本地仓库。
4. Redmine 数据库也会随之更新，确保代码浏览和更改集显示最新的内容。

3. 项目API使用文档

3.1 Webhook API

• URL: [redmine_url]/github_hook
• Method: POST
• Payload: GitHub 推送事件的详细信息。
• Response: 成功时返回 HTTP 200 状态码，失败时返回相应的错误信息。

3.2 参数说明

• project_id: 指定 Redmine 项目标识符。
• repository_id: 指定要更新的仓库标识符。

4. 项目安装方式

4.1 系统要求

• Redmine 运行在类 Unix 系统上。
• Redmine 版本支持：5.x, 4.x, 3.x, 2.x。
• Git 版本要求：1.5 或更高。

4.2 安装步骤

1. 按照 安装指南 中的步骤安装插件。
2. 配置 GitHub Webhook，确保 Redmine 能够接收到 GitHub 的推送通知。
3. 确保 Redmine 用户对本地仓库具有读写权限，并在 GitHub 上添加相应的 SSH 密钥。

5. 故障排除

5.1 检查日志文件

1. 查看 Redmine 日志文件，检查是否有 /github_hook 的 POST 请求记录。
2. 如果 Git 命令执行失败，日志文件中应包含相关的错误信息。

5.2 权限问题

• 确保 Redmine 用户对 GitHub 远程仓库具有读权限，对本地仓库具有读写权限。
• 在 GitHub 上添加 Redmine 用户的 SSH 密钥。

6. 工作流程图

sequenceDiagram
    participant Dev as Development Machine
    participant GH as GitHub
    participant Rm as Redmine
    Dev->>GH: git push
    GH->>Rm: POST /github_hook
    Rm->>GH: git fetch
    GH-->>Rm: commits
    Rm->>Rm: Update repository

7. 许可证

本项目基于 MIT 许可证发布。