sjafferali/portainer-github-webhook-relay

GitHub Webhooks to Portainer 转发服务

镜像概述

本镜像是一个轻量级Web应用，核心功能为接收GitHub发送的Webhooks事件，并将其转发至Portainer实例，实现GitHub事件与Portainer操作的自动化联动。通过该服务，用户可基于GitHub仓库活动（如代码推送、PR合并等）触发Portainer的部署、更新等管理操作。

核心功能与特性

• GitHub Webhooks接收：支持标准GitHub Webhooks协议，可接收各类事件（push、pull_request、release等）
• Portainer请求转发：将处理后的Webhooks事件转换为Portainer API请求，支持调用Portainer的部署、更新、重启等接口
• 轻量级设计：基于简约架构，资源占用低，部署便捷
• 灵活配置：通过环境变量或配置文件自定义转发规则、目标Portainer实例及认证信息

使用场景与适用范围

• 自动化部署：GitHub仓库代码推送后，自动触发Portainer部署对应服务
• 持续集成/持续部署(CI/CD)：配合GitHub Actions或其他CI工具，实现代码合并后通过Portainer完成服务更新
• 事件驱动管理：基于GitHub特定事件（如release发布）自动执行Portainer中的服务扩缩容、配置更新等操作

使用方法与配置说明

基本部署（Docker Run）

bash
docker run -d \
  --name github-webhook-relay \
  -p 3000:3000 \
  -e PORT=3000 \
  -e PORTAINER_URL="https://portainer.example.com/api" \
  -e PORTAINER_TOKEN="your-portainer-api-token" \
  -e GITHUB_SECRET="your-github-webhook-secret" \
  [镜像名称]:[标签]

环境变量配置

详细使用步骤

1. 配置GitHub Webhooks
   在GitHub仓库的「Settings > Webhooks」中添加webhook，设置Payload URL为该服务的访问地址（如http://your-relay-service:3000/webhook），Content type选择application/json，填写与环境变量GITHUB_SECRET一致的密钥。

2. 启动转发服务
   使用上述docker run命令启动容器，确保环境变量正确配置（尤其是Portainer URL和Token需具备操作权限）。

3. 验证联动效果
   触发GitHub事件（如推送代码），检查服务日志确认Webhooks接收与转发状态，同时在Portainer中验证目标操作是否执行（如堆栈部署）。

高级配置（可选）

• 自定义转发规则：通过挂载配置文件（如/app/config.json）定义事件与Portainer接口的映射关系，支持按事件类型、仓库名称等条件路由请求。
• 日志与监控：添加LOG_LEVEL环境变量（如debug）开启详细日志，便于问题排查；可结合Prometheus等工具监控服务运行状态。

注意事项

• 确保服务与GitHub、Portainer之间网络互通，防火墙规则需允许对应端口通信。
• Portainer Token需具备足够权限（如堆栈管理、服务部署等），建议使用最小权限原则创建专用Token。
• 高可用场景下，可部署多个实例并通过负载均衡器分发请求。