GitPull
GitPull 1.4 是一款基于 Git 的 Spigot/Paper 数据包更新工具。玩家可以拉取代码仓库、在聊天窗口中查看进度,并在更新完成后点击消息以重新加载数据包。GitHub 推送通知通过独立的 Webhook 服务和本地事件文件进行集成。
功能特性
- 对配置好的 URL 执行
git pull 或 git clone,无需配置 origin。
- 支持多个仓库、分支、HTTP 代理以及执行超时设置。
- 异步运行 Git 命令,并显示仓库信息、Git 阶段、百分比和已用时间。
- 区分更新成功、已是最新、失败和超时的结果。
- 提供可配置的完成音效和可点击的数据包重新加载操作。
- 在 Webhook 拉取成功后,向拥有
gitpull.notify 权限的在线操作员或玩家发送通知。
安装与升级
要求:Java 21 或更高版本、支持 api-version: 1.21 的 Spigot/Paper 服务器,且服务器上已安装 Git。该项目基于 Spigot API 1.21.11 编译。
从项目目录构建:
.\gradlew.bat build
在 Linux/macOS 上,请使用 ./gradlew build。生成的工件位于 build/libs/gitpull-1.4.jar。
- 将 JAR 文件复制到服务器的
plugins 目录并启动服务器。
- 编辑生成的
plugins/gitpull/config.yml,替换示例中的仓库 URL、目录和分支。
- 运行
/pull reload 应用配置,然后运行 /pull <repository-name>。
如需升级,请停止服务器并替换旧的 JAR 文件,保留配置目录。如果服务器配置了 settings.update-folder: update,你也可以将新 JAR 放入 plugins/update/ 下,文件名需与旧 JAR 相同。它将在下次启动时替换旧文件。插件目录中仅保留一个 GitPull JAR。
/pull reload 会重新读取配置文件。正在运行的 Git 任务会保留其启动时的仓库设置。JAR 升级需要重启服务器。
命令与权限
| 命令 |
用途 |
权限 |
/pull |
按配置顺序拉取所有有效的仓库 |
gitpull.pull |
/pull <name> |
拉取单个仓库;仓库名称支持 Tab 补全 |
gitpull.pull |
/pull reload |
重新加载配置和通知监听器 |
gitpull.pull, gitpull.reload |
这些权限默认授予操作员。控制台也可以运行这些命令。仓库名称 reload 为保留字。
| 通知权限 |
用途 |
gitpull.notify |
接收 Webhook 通知;默认授予操作员 |
minecraft.command.reload |
显示并执行数据包重新加载操作;操作员也能看到该操作 |
该操作会以玩家身份运行 /minecraft:reload,服务器仍会检查命令权限。它重新加载的是数据包,而非插件 JAR。游戏内的链接当前标记为 重载数据包 (Reload datapacks);插件消息均为中文。
配置
git-command: git
http-proxy: ""
clone-if-missing: true
timeout-seconds: 300
notifications:
sound:
enabled: true
id: "minecraft:entity.experience_orb.pickup"
volume: 0.8
pitch: 1.2
webhook-notifications:
enabled: true
directory: "webhook-events"
max-age-seconds: 300
repositories:
pack:
repository: "https://github.com/OWNER/REPO.git"
directory: "world/datapacks/my-pack"
branch: "main"
| 设置项 |
含义 |
git-command |
Git 可执行文件的名称或完整路径,例如 /usr/bin/git |
http-proxy |
为 Git 子进程设置大小写敏感的 HTTP/HTTPS 代理环境变量。空值表示不添加任何覆盖;继承的环境变量和 Git 配置可能仍然生效。SSH URL 不使用此 HTTP 代理 |
clone-if-missing |
允许在目标不存在,或为空且没有 Git 仓库时进行克隆 |
timeout-seconds |
每个仓库的 Git 操作超时时间,最小值为 1 秒 |
repositories.<name>.repository |
用于克隆和拉取的 HTTPS 或 SSH URL;现有的远程配置将被保留 |
repositories.<name>.directory |
绝对路径,或相对于服务器世界容器(通常是服务器根目录)的路径 |
repositories.<name>.branch |
要克隆或拉取的远程分支。留空表示使用远程默认分支;拉取操作不会切换本地分支 |
webhook-notifications.enabled |
监听本地事件文件;可以禁用以仅支持手动使用 |
webhook-notifications.directory |
事件目录;相对路径相对于 plugins/gitpull 解析,也支持绝对路径 |
webhook-notifications.max-age-seconds |
通知的最大有效时长,默认 300 秒,可配置范围为 1 到 86400 秒 |
私有仓库使用运行游戏服务器的操作系统账户的 SSH 密钥或 HTTPS 凭据。请确认该账户能够无需交互式提示即可访问该仓库。
进度、音效与数据包重新加载
当 Git 输出阶段和百分比信息时,聊天窗口的进度更新频率最多每秒一次。如果没有新的进度,插件每 10 秒报告一次当前状态和已用时间。百分比描述的是当前的 Git 阶段,而非整体任务的完成度。
- 手动拉取:当所有仓库都成功且至少有一个仓库被更新或克隆时,请求者会收到一次音效,最终消息提供重新加载操作。
- Webhook 拉取:每次修订变更都会为通知接收者播放音效,并为拥有重新加载权限的玩家提供重新加载操作。
- “已是最新”的结果仅显示文本。失败和超时不会播放成功音效。
notifications.sound 控制启用标志、命名空间声音 ID、音量(范围 0.0–1.0)和音调(范围 0.5–2.0)。默认是经验球拾取音效。另一个有效的选择是 minecraft:entity.ender_dragon.death。客户端必须拥有所选音效;播放使用“玩家”音效类别。应用更改请使用 /pull reload。
GitHub Webhook 设置
工作原理
GitHub push → HTTPS 端点 → webhook 服务 → pull-script.sh
↓ 成功的 Git 拉取
gitpull-notify.py
↓ 事件文件
plugins/gitpull/webhook-events
↓ 每 40 ticks 轮询一次
chat, sound, reload action
GitPull 不暴露 HTTP 端点。设置 webhook-notifications.enabled: true 启用文件监控;您还必须部署一个服务来接收 GitHub 请求,并配置一个脚本来发布通知。手动 /pull 命令会直接启动 Git,而不使用 Webhook。
本示例使用 Linux、adnanh/webhook 2.8+、Nginx 和 systemd。它假设已存在一个名为 minecraft 的游戏服务器操作系统账户,服务器根目录为 /srv/minecraft,仓库名称为 pack,分支为 main。请替换为您实际的值。Webhook 和游戏服务器使用相同的账户和文件系统。
1. 安装依赖项和脚本
在 Debian/Ubuntu 上,安装依赖项,然后从本项目的目录中复制脚本:
sudo apt install git python3 webhook nginx util-linux coreutils
sudo install -d -o minecraft -g minecraft /srv/gitpull
sudo install -d -o minecraft -g minecraft /srv/minecraft/plugins/gitpull/webhook-events
sudo install -o minecraft -g minecraft -m 750 deploy/pull-script.sh /srv/gitpull/pull-script.sh
sudo install -o minecraft -g minecraft -m 640 deploy/gitpull-notify.py /srv/gitpull/gitpull-notify.py
sudo sed -i 's/\r$//' /srv/gitpull/pull-script.sh /srv/gitpull/gitpull-notify.py
需要 Python 3.8 或更高版本。util-linux 提供 flock;coreutils 提供 timeout。事件文件仅对所有者可读和可写,因此此设置将 Webhook 和游戏服务器作为同一账户运行。
捆绑的 pull-script.sh 和 config-tokumei.yml 包含特定于 tokumei 部署的路径。对于其他环境,请编辑 /srv/gitpull/pull-script.sh:
| 脚本位置 |
此示例的值 |
exec 9> 后的锁文件 |
/srv/gitpull/pull.lock |
cd 后的目录 |
/srv/minecraft/world/datapacks/my-pack |
传递给 git pull 的 URL 和分支 |
https://github.com/OWNER/REPO.git main |
-c http.proxy=... |
设置您的代理,如果不需要代理则移除此参数 |
python3 后的脚本路径 |
/srv/gitpull/gitpull-notify.py |
| 通知目录参数 |
/srv/minecraft/plugins/gitpull/webhook-events |
通知仓库名称参数 tokumei |
pack,与插件配置匹配以在聊天中显示。通知名称必须包含 1–80 个 ASCII 字母、数字、_、. 或 - |
最终的通知调用应为:
python3 /srv/gitpull/gitpull-notify.py /srv/minecraft/plugins/gitpull/webhook-events pack "$status" "$before" "$after"
拉取脚本需要一个现有的 Git 仓库。使用插件或手动将仓库克隆到目标目录中(作为 minecraft 用户)。捆绑的脚本使用代理 192.168.6.2:7890 和 120 秒超时。插件的 http-proxy 和 timeout-seconds 设置不会更改此脚本。
2. 配置 Webhook 端点
将其保存为 /srv/gitpull/hooks.json,并将 REPLACE_WITH_YOUR_SECRET 替换为您自己的随机密钥。此配置接受对 main 的签名推送:
[
{
"id": "gitpull",
"execute-command": "/srv/gitpull/pull-script.sh",
"command-working-directory": "/srv/gitpull",
"http-methods": ["POST"],
"trigger-rule": {
"and": [
{"match": {"type": "payload-hmac-sha256", "secret": "REPLACE_WITH_YOUR_SECRET", "parameter": {"source": "header", "name": "X-Hub-Signature-256"}}},
{"match": {"type": "value", "value": "push", "parameter": {"source": "header", "name": "X-GitHub-Event"}}},
{"match": {"type": "value", "value": "refs/heads/main", "parameter": {"source": "payload", "name": "ref"}}},
{"match": {"type": "value", "value": "false", "parameter": {"source": "payload", "name": "deleted"}}}
]
}
}
]
使该文件对 minecraft 用户可读,例如使用 sudo chown minecraft:minecraft /srv/gitpull/hooks.json 和 sudo chmod 600 /srv/gitpull/hooks.json。
此示例在接受请求后立即响应。Git 结果将记录到服务日志和事件文件中。请参阅 官方 Webhook 字段参考。
创建 /etc/systemd/system/gitpull-webhook.service:
[Unit]
Description=GitPull Webhook
After=network-online.target
Wants=network-online.target
[Service]
User=minecraft
Group=minecraft
WorkingDirectory=/srv/gitpull
ExecStart=/usr/bin/webhook -ip 127.0.0.1 -port 9000 -hooks /srv/gitpull/hooks.json -hotreload -verbose
Restart=on-failure
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now gitpull-webhook
如果您已经在运行 Webhook,请将钩子添加到其现有的 hooks 数组中,而不是在同一端口上启动另一个进程。如果更改了其 systemd 启动参数,请重启该服务。
3. 设置 HTTPS
将您的域名指向服务器并获得有效的 TLS 证书。添加并启用 Nginx 站点,替换域名和证书路径:
server {
listen 443 ssl;
server_name hooks.example.com;
ssl_certificate /etc/letsencrypt/live/hooks.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/hooks.example.com/privkey.pem;
location = /hooks/gitpull {
proxy_pass http://127.0.0.1:9000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
sudo nginx -t
sudo systemctl reload nginx
允许在 443 端口接收传入的 HTTPS 流量。Webhook 仅监听本地回环地址(localhost)的 9000 端口。
4. 配置 GitHub 仓库
在仓库中打开 Settings → Webhooks → Add webhook:
| 字段 |
值 |
| Payload URL |
https://hooks.example.com/hooks/gitpull |
| Content type |
application/json |
| Secret |
与 hooks.json 中相同的密钥 |
| SSL verification |
Enabled |
| Events |
Just the push event |
| Active |
Enabled |
你需要拥有管理仓库 Webhook 的权限。请确保在 GitHub 和 Nginx 中一致使用 gitpull 作为 hook ID 和端点后缀。如果你更改了分支,请同时更新脚本、插件配置以及 refs/heads/main 过滤器。
5. 启用游戏内通知并验证
将插件配置设置为:
webhook-notifications:
enabled: true
directory: "webhook-events"
max-age-seconds: 300
这将解析为 /srv/minecraft/plugins/gitpull/webhook-events,并且必须与 Python 编写器的目录匹配。运行 /pull reload,以操作员身份加入游戏,并将一个文本文件(非数据包资源)推送到 main。
检查服务日志:
sudo journalctl -u gitpull-webhook -n 50 --no-pager
更新时会产生 AUTOPULL_RESULT UPDATED <旧版本> <新版本>;若无变化则产生 AUTOPULL_RESULT UNCHANGED <版本>。插件通常在约 2 秒内发送通知,随后删除事件文件。验证完成后,请删除并推送测试文件以检查第二次通知。
已知限制和故障排除
- 并发 Webhook 和手动拉取: 脚本中的
flock 仅协调 Webhook 脚本。插件会防止并发的插件任务,但两条路径不共享锁。避免同时对同一仓库运行两者;否则可能出现 Git 锁冲突或拉取失败。
- Webhook 故障通知: 只有成功的更新和已经是最新的结果才会生成事件文件。请检查 Webhook 日志以查看故障、超时和忙(busy)结果。HTTP 200 仅表示请求已确认。
- 无游戏内通知: 请检查插件是否已加载、事件路径是否匹配、服务账户是否有读写权限,以及玩家是否为操作员或拥有
gitpull.notify 权限。过期的事件会被删除;格式错误的事件文件会被重命名为 .invalid。如果没有符合条件的玩家在线,事件将被记录并消耗,不会在玩家登录时重放。
- 无声音或重载动作: “已是最新”的结果不会触发任何操作。该动作需要重载权限;手动批量操作也要求所有仓库都成功。客户端音频设置和声音资源决定了播放是否可闻。
- 文件已更新但游戏玩法未改变: GitPull 不会自动重载数据包。请点击重载动作或运行
/minecraft:reload。这将重载启用的数据包,而不仅仅是更新的仓库。
- 目录或认证错误: 克隆操作不会覆盖非空且非 Git 仓库的目录。请为实际运行脚本或游戏服务器的账户配置私有仓库凭据。
- 其他部署限制: 捆绑的 Webhook 脚本针对 Linux 和单个仓库。GitPull 的监听器消费的是文件,而非远程 HTTP 回调。单独的部署需要一个写入者和插件均可访问的通知目录。
开发检查
gradlew build 会编译插件并运行 Java 测试。在 Linux 上,可分别使用以下命令测试 Webhook 脚本和事件写入器:
python3 deploy/test_webhook.py "$(pwd)/deploy/pull-script.sh" "$(pwd)/deploy/gitpull-notify.py"
该测试使用临时 Git 仓库和一个独立的本地 Webhook 进程。它涵盖了更新、未更改的仓库、繁忙执行、失败、超时以及成功的事件发布等场景。
GitPull
GitPull 1.4 is a Git-based datapack updater for Spigot/Paper. Players can pull repositories, follow progress in chat, and click a message to reload datapacks after an update. GitHub push notifications are integrated through a separate Webhook service and local event files.
Features
- Run
git pull or git clone against the configured URL, without configuring origin.
- Support multiple repositories, branches, HTTP proxies, and execution timeouts.
- Run Git asynchronously and show the repository, Git stage, percentage, and elapsed time.
- Distinguish updates, already-up-to-date results, failures, and timeouts.
- Provide a configurable success sound and a clickable datapack reload action.
- Notify online operators or players with
gitpull.notify after a successful Webhook pull.
Installation and upgrades
Requirements: Java 21 or later, a Spigot/Paper server supporting api-version: 1.21, and Git installed on the server. The project compiles against Spigot API 1.21.11.
Build from the project directory:
.\gradlew.bat build
On Linux/macOS, use ./gradlew build. The artifact is build/libs/gitpull-1.4.jar.
- Copy the JAR into the server's
plugins directory and start the server.
- Edit the generated
plugins/gitpull/config.yml, replacing the example repository URL, directory, and branch.
- Run
/pull reload to apply the configuration, then /pull <repository-name>.
To upgrade, stop the server and replace the old JAR, keeping the configuration directory. If the server has settings.update-folder: update configured, you can instead place the new JAR in plugins/update/ under the same filename as the old JAR. It will replace the old file on the next startup. Keep only one GitPull JAR in the plugin directory.
/pull reload rereads configuration. Running Git tasks retain the repository settings they started with. A JAR upgrade requires a server restart.
Commands and permissions
| Command |
Purpose |
Permission |
/pull |
Pull all valid repositories in configuration order |
gitpull.pull |
/pull <name> |
Pull one repository; repository names support tab completion |
gitpull.pull |
/pull reload |
Reload configuration and the notification listener |
gitpull.pull, gitpull.reload |
These permissions default to operators. The console can also run the commands. The repository name reload is reserved.
| Notification permission |
Purpose |
gitpull.notify |
Receive Webhook notifications; granted to operators by default |
minecraft.command.reload |
Display and execute the datapack reload action; operators also see the action |
The action runs /minecraft:reload as the player, and the server still checks command permissions. It reloads datapacks, not plugin JARs. The in-game link is currently labeled 重载数据包 (Reload datapacks); plugin messages are in Chinese.
Configuration
git-command: git
http-proxy: ""
clone-if-missing: true
timeout-seconds: 300
notifications:
sound:
enabled: true
id: "minecraft:entity.experience_orb.pickup"
volume: 0.8
pitch: 1.2
webhook-notifications:
enabled: true
directory: "webhook-events"
max-age-seconds: 300
repositories:
pack:
repository: "https://github.com/OWNER/REPO.git"
directory: "world/datapacks/my-pack"
branch: "main"
| Setting |
Meaning |
git-command |
Git executable name or full path, such as /usr/bin/git |
http-proxy |
Sets uppercase and lowercase HTTP/HTTPS proxy environment variables for Git subprocesses. An empty value adds no overrides; inherited environment variables and Git configuration may still apply. SSH URLs do not use this HTTP proxy |
clone-if-missing |
Allow cloning when the target does not exist, or is empty and has no Git repository |
timeout-seconds |
Git operation timeout per repository, with a minimum of 1 second |
repositories.<name>.repository |
HTTPS or SSH URL used for both cloning and pulling; existing remote configuration is preserved |
repositories.<name>.directory |
Absolute path, or a path relative to the server's world container, normally the server root |
repositories.<name>.branch |
Remote branch to clone or pull. Empty means the remote default branch; pulling does not switch the local branch |
webhook-notifications.enabled |
Listen for local event files; can be disabled for manual-only use |
webhook-notifications.directory |
Event directory; relative paths resolve against plugins/gitpull, and absolute paths are supported |
webhook-notifications.max-age-seconds |
Maximum notification age, default 300 seconds, configurable from 1 to 86400 seconds |
Private repositories use the SSH keys or HTTPS credentials of the OS account running the game server. Confirm that this account can access the repository without interactive prompts.
Progress, sound, and datapack reload
When Git emits stage and percentage information, chat progress updates at most once per second. With no new progress, the plugin reports the current status and elapsed time every 10 seconds. Percentages describe the current Git stage, not overall task completion.
- Manual pulls: when every repository succeeds and at least one repository is updated or cloned, the requester receives one sound and the final message offers the reload action.
- Webhook pulls: each revision change plays a sound for notification recipients and offers the reload action to players with reload permission.
- Already-up-to-date results display text only. Failures and timeouts do not play a success sound.
notifications.sound controls the enabled flag, namespaced sound ID, volume from 0.0–1.0, and pitch from 0.5–2.0. The default is the experience orb pickup sound. Another valid choice is minecraft:entity.ender_dragon.death. The client must have the selected sound; playback uses the Players sound category. Apply changes with /pull reload.
GitHub Webhook setup
How it works
GitHub push → HTTPS endpoint → webhook service → pull-script.sh
↓ successful Git pull
gitpull-notify.py
↓ event file
plugins/gitpull/webhook-events
↓ polled every 40 ticks
chat, sound, reload action
GitPull does not expose an HTTP endpoint. Setting webhook-notifications.enabled: true enables file monitoring; you must also deploy a service to receive GitHub requests and a script to publish notifications. Manual /pull commands launch Git directly and do not use Webhook.
This example uses Linux, adnanh/webhook 2.8+, Nginx, and systemd. It assumes an existing game-server OS account named minecraft, a server root of /srv/minecraft, repository name pack, and branch main. Substitute your actual values. Webhook and the game server use the same account and filesystem.
1. Install dependencies and scripts
On Debian/Ubuntu, install the dependencies, then copy the scripts from this project's directory:
sudo apt install git python3 webhook nginx util-linux coreutils
sudo install -d -o minecraft -g minecraft /srv/gitpull
sudo install -d -o minecraft -g minecraft /srv/minecraft/plugins/gitpull/webhook-events
sudo install -o minecraft -g minecraft -m 750 deploy/pull-script.sh /srv/gitpull/pull-script.sh
sudo install -o minecraft -g minecraft -m 640 deploy/gitpull-notify.py /srv/gitpull/gitpull-notify.py
sudo sed -i 's/\r$//' /srv/gitpull/pull-script.sh /srv/gitpull/gitpull-notify.py
Python 3.8 or later is required. util-linux provides flock; coreutils provides timeout. Event files are readable and writable only by their owner, so this setup runs Webhook and the game server as the same account.
The bundled pull-script.sh and config-tokumei.yml contain paths specific to the tokumei deployment. For another environment, edit /srv/gitpull/pull-script.sh:
| Script location |
Value for this example |
Lock file after exec 9> |
/srv/gitpull/pull.lock |
Directory after cd |
/srv/minecraft/world/datapacks/my-pack |
URL and branch passed to git pull |
https://github.com/OWNER/REPO.git main |
-c http.proxy=... |
Set your proxy, or remove this argument if no proxy is needed |
Script path after python3 |
/srv/gitpull/gitpull-notify.py |
| Notification directory argument |
/srv/minecraft/plugins/gitpull/webhook-events |
Notification repository-name argument tokumei |
pack, matching the plugin configuration for display in chat. Notification names must contain 1–80 ASCII letters, digits, _, ., or - |
The resulting notification call should be:
python3 /srv/gitpull/gitpull-notify.py /srv/minecraft/plugins/gitpull/webhook-events pack "$status" "$before" "$after"
The pull script requires an existing Git repository. Clone it using the plugin or manually as minecraft into the target directory. The bundled script uses proxy 192.168.6.2:7890 and a 120-second timeout. The plugin's http-proxy and timeout-seconds settings do not change this script.
2. Configure the Webhook endpoint
Save this as /srv/gitpull/hooks.json, replacing REPLACE_WITH_YOUR_SECRET with your own random secret. This configuration accepts signed pushes to main:
[
{
"id": "gitpull",
"execute-command": "/srv/gitpull/pull-script.sh",
"command-working-directory": "/srv/gitpull",
"http-methods": ["POST"],
"trigger-rule": {
"and": [
{"match": {"type": "payload-hmac-sha256", "secret": "REPLACE_WITH_YOUR_SECRET", "parameter": {"source": "header", "name": "X-Hub-Signature-256"}}},
{"match": {"type": "value", "value": "push", "parameter": {"source": "header", "name": "X-GitHub-Event"}}},
{"match": {"type": "value", "value": "refs/heads/main", "parameter": {"source": "payload", "name": "ref"}}},
{"match": {"type": "value", "value": "false", "parameter": {"source": "payload", "name": "deleted"}}}
]
}
}
]
Make the file readable by minecraft, for example with sudo chown minecraft:minecraft /srv/gitpull/hooks.json and sudo chmod 600 /srv/gitpull/hooks.json.
This example responds immediately after accepting a request. Git results go to the service log and event files. See the official Webhook field reference.
Create /etc/systemd/system/gitpull-webhook.service:
[Unit]
Description=GitPull Webhook
After=network-online.target
Wants=network-online.target
[Service]
User=minecraft
Group=minecraft
WorkingDirectory=/srv/gitpull
ExecStart=/usr/bin/webhook -ip 127.0.0.1 -port 9000 -hooks /srv/gitpull/hooks.json -hotreload -verbose
Restart=on-failure
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now gitpull-webhook
If you already run Webhook, add the hook to its existing hooks array instead of starting another process on the same port. Restart that service if you change its systemd startup arguments.
3. Set up HTTPS
Point your domain at the server and obtain a valid TLS certificate. Add and enable an Nginx site, replacing the domain and certificate paths:
server {
listen 443 ssl;
server_name hooks.example.com;
ssl_certificate /etc/letsencrypt/live/hooks.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/hooks.example.com/privkey.pem;
location = /hooks/gitpull {
proxy_pass http://127.0.0.1:9000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
sudo nginx -t
sudo systemctl reload nginx
Allow incoming HTTPS on port 443. Webhook listens only on localhost port 9000.
4. Configure the GitHub repository
Open Settings → Webhooks → Add webhook in the repository:
| Field |
Value |
| Payload URL |
https://hooks.example.com/hooks/gitpull |
| Content type |
application/json |
| Secret |
The same secret as in hooks.json |
| SSL verification |
Enabled |
| Events |
Just the push event |
| Active |
Enabled |
You need permission to manage repository webhooks. Use gitpull consistently for the hook ID and the endpoint suffix in GitHub and Nginx. If you change branches, update the script, plugin configuration, and refs/heads/main filter together.
5. Enable in-game notifications and verify
Set the plugin configuration to:
webhook-notifications:
enabled: true
directory: "webhook-events"
max-age-seconds: 300
This resolves to /srv/minecraft/plugins/gitpull/webhook-events and must match the Python writer's directory. Run /pull reload, join the game as an operator, and push a text file outside datapack resources to main.
Check the service log:
sudo journalctl -u gitpull-webhook -n 50 --no-pager
An update produces AUTOPULL_RESULT UPDATED <old-revision> <new-revision>; no change produces AUTOPULL_RESULT UNCHANGED <revision>. The plugin normally sends the notification within about 2 seconds and deletes the event file afterward. Delete and push the test file once verification is complete to check a second notification.
Known limitations and troubleshooting
- Concurrent Webhook and manual pulls: the script's
flock coordinates only Webhook scripts. The plugin prevents concurrent plugin tasks, but the two paths do not share a lock. Avoid running both against the same repository at once; Git lock conflicts or failed pulls can occur.
- Webhook failure notifications: only successful updates and already-up-to-date results produce event files. Check Webhook logs for failures, timeouts, and busy results. HTTP 200 only acknowledges the request.
- No in-game notification: check that the plugin is loaded, event paths match, the service account can read and write them, and the player is an operator or has
gitpull.notify. Expired events are deleted; malformed files are renamed with .invalid. If no eligible player is online, the event is logged and consumed without replaying it on login.
- No sound or reload action: already-up-to-date results provide neither. The action requires reload permission; manual batches also require all repositories to succeed. Client audio settings and sound resources determine whether playback is audible.
- Files updated but gameplay unchanged: GitPull does not automatically reload datapacks. Click the reload action or run
/minecraft:reload. This reloads enabled datapacks, not just the updated repository.
- Directory or authentication errors: cloning will not overwrite a nonempty directory that is not a Git repository. Configure private repository credentials for the account actually running the script or game server.
- Other deployment limits: the bundled Webhook scripts target Linux and one repository. GitPull's listener consumes files, not remote HTTP callbacks. Separate deployments need a notification directory accessible to both the writer and the plugin.
Development checks
gradlew build compiles the plugin and runs Java tests. On Linux, test the Webhook script and event writer separately with:
python3 deploy/test_webhook.py "$(pwd)/deploy/pull-script.sh" "$(pwd)/deploy/gitpull-notify.py"
The test uses temporary Git repositories and a separate local Webhook process. It covers updates, unchanged repositories, busy execution, failures, timeouts, and successful event publication.
评论 0
登录后参与评分
还没有评论,来抢沙发吧