alexelcu/github-webhook-listener

github-webhook-listener

镜像概述和主要用途

一个简单的Web应用，可注册为GitHub Webhook，响应事件并触发shell命令。主要用于通过Travis-CI作业安全触发自有服务器上的网站刷新，无需暴露服务器凭据或SSH密钥。服务器进程资源占用低，在64位Ubuntu机器上内存使用不超过20MB，适合低配置服务器。

核心功能和特性

• 响应GitHub Webhook事件并执行配置的shell命令
• 轻量级设计，内存占用低（<20MB），适合资源有限的服务器
• 支持通过配置文件定义多个项目及对应的触发条件和命令
• 内置git支持，便于执行git pull等更新操作
• 可通过Docker快速部署，支持docker-compose编排

使用场景和适用范围

适用于需要通过GitHub事件（如代码推送、合并请求等）自动触发服务器操作的场景，例如：

• 静态网站（如基于gh-pages分支）的自动更新
• 服务器上代码仓库的自动拉取和部署
• 基于GitHub事件的自动化任务触发

特别适合个人服务器、低配置服务器或需要安全部署流程的环境。

使用方法和配置说明

快速启动

镜像已发布到Docker Hub，可通过以下命令快速运行：

sh
docker run \
  -p 8080:8080 \
  -ti alexelcu/github-webhook-listener

服务器配置

上述命令仅启动服务器，需通过配置文件定义具体行为。创建./config.yaml配置文件：

yaml
http:
  path: "/"
  port: 8080

runtime:
  workers: 2
  output: stdout

projects:
  myproject:  # 项目名称，可自定义
    ref: "refs/heads/gh-pages"  # 仅响应推送到gh-pages分支的事件
    directory: "/var/www/myproject"  # 命令执行目录
    command: "git pull"  # 要执行的命令（镜像已内置git）
    secret: "xxxxxxxxxxxxxxxxxxxxxxxxxx"  # Webhook密钥（与GitHub配置一致）

配置说明

1. projects下的项目名称（如myproject）可自定义，用于标识不同项目
2. ref：指定触发事件的分支，如refs/heads/main表示main分支
3. directory：命令执行的工作目录
4. command：触发时执行的shell命令，常用git pull更新代码
5. secret：可选，用于验证GitHub Webhook请求的密钥，需与GitHub配置一致

权限配置

为确保命令以指定用户执行，建议在主机创建专用用户：

sh
sudo adduser synchronize  # 创建用户
sudo adduser synchronize www-data  # 添加到www-data组（根据需求调整）
sudo chown -R synchronize:www-data /var/www/myproject  # 设置目录权限

使用指定用户运行容器：

sh
docker run \
  -p 8080:8080 \
  -v "$(pwd)/config.yaml:/opt/app/config/config.yaml" \  # 挂载配置文件
  -u "$(id -u synchronize):$(id -g synchronize)" \  # 指定用户ID和组ID
  -ti alexelcu/github-webhook-listener

docker-compose配置

推荐使用docker-compose管理服务，示例配置：

yaml
version: '3.3'

services:
  github-webhook-listener:
    container_name: github-webhook-listener
    image: 'alexelcu/github-webhook-listener:latest'
    restart: unless-stopped  # 自动重启
    ports:
      - "8080:8080"  # 端口映射
    tty: true
    networks:
      - main  # 使用外部网络（需提前创建）
    volumes:
      - /var/www:/var/www  # 挂载网站目录
      - /etc/github-webhook-listener/config.yaml:/opt/app/config/config.yaml  # 挂载配置文件
    user: "${SYNC_UID}:${SYNC_GID}"  # 通过环境变量指定用户ID和组ID

networks:
  main:
    external:
      name: main  # 外部网络名称

Nginx反向代理配置

若需通过域名访问，可配置Nginx反向代理：

conf
location / {
  proxy_pass http://127.0.0.1:8080;  # 代理到容器端口
  proxy_set_header    Host            $host;
  proxy_set_header    X-Real-IP       $remote_addr;
  proxy_set_header    X-Forwarded-for $remote_addr;
  proxy_connect_timeout 300;  # 连接超时时间
}

GitHub项目Webhook配置

1. 进入GitHub项目设置页面，打开“Webhooks”部分（URL格式：https://github.com/<用户>/<项目>/settings/hooks）
2. 点击“Add webhook”，配置以下信息：
   • Payload URL：服务器访问地址（如https://your-domain.com，路径需与配置文件http.path一致）
   • Content type：选择application/json
   • Secret：输入配置文件中secret字段的值（若配置了secret）
   • Which events would you like to trigger this webhook?：选择“Just the push event.”或根据需求选择
3. 点击“Add webhook”完成配置

手动安装（非Docker）

详见https://github.com/alexandru/github-webhook-listener/wiki/Setup

许可证

Copyright © 2018-2020 Alexandru Nedelcu，保留部分权利。

基于3-Clause BSD许可证。详见https://github.com/alexandru/github-webhook-listener/blob/master/LICENSE%E3%80%82