lingxi-webhook-dispatcher

一款智能 Webhook 路由系统，在标准 git push 失败时自动回退至 GitHub API。

解决的问题

Git push 可能因以下原因失败：

• 防火墙或网络屏蔽了 443 端口
• DNS 解析异常
• SSL 证书问题
• Git 协议遭遇速率限制（rate limiting）

本能力提供健壮的回退机制：当 git push 失败时，自动切换至 GitHub Contents API（PUT /repos/{owner}/{repo}/contents/{path}），直接上传文件。

架构

git push → [失败] → Webhook Dispatcher
  → GitHub Contents API（回退上传）
  → 重试逻辑（指数退避）
  → 投递回执（JSON 日志）
  → 告警通知（若持续失败）

使用方式

触发方式：在 git push 失败时自动触发

触发条件：任意工作流中 git push 失败  
执行动作：Dispatcher 拦截 → 切换至 GitHub API 回退 → 上传文件  
输出结果：投递回执保存于 ~/webhook-dispatch/logs/YYYY-MM-DD.json

手动分发

触发指令：“Dispatch files to GitHub via API”  
执行动作：使用 Contents API 将指定文件上传至 GitHub

扇出式分发（Fan-out Dispatch）

触发指令：“Push this update to repos: [repo1, repo2, repo3]”  
执行动作：并行上传至所有指定仓库  
输出结果：按仓库维度汇总的成功/失败报告

配置

{
  "github_token": "ghp_xxx",
  "default_owner": "nima54851",
  "retry_attempts": 3,
  "retry_backoff_ms": 1000,
  "log_path": "~/webhook-dispatch/logs/",
  "alert_webhook": "https://your-alert-channel.com/webhook"
}

GitHub Contents API 上传流程

# 1. 获取当前文件 SHA（若已存在）
gh api repos/{owner}/{repo}/contents/{path} --jq '.sha'

# 2. 带 SHA 上传（更新）或不带 SHA（新建）
gh api -X PUT repos/{owner}/{repo}/contents/{path} 
  -f message="Automated dispatch: {timestamp}" 
  -f content=$(base64 -w 0 file.txt) 
  -f sha={sha}

重试逻辑

安装

clawhub install lingxi-webhook-dispatcher

与 GitHub Actions 集成

在工作流中添加为回退步骤：

- name: GitHub API Fallback Dispatch
  if: failure()
  run: |
    curl -X POST https://your-dispatcher-endpoint.com/dispatch 
      -H "Authorization: Bearer ${{ secrets.DISPATCH_TOKEN }}" 
      -d '{"event": "push_failure", "repo": "${{ github.repository }}"}'

典型应用场景

1. CI/CD 流水线回退：CI 中 git push 失败时，通过 API 推送构建产物
2. 自动化报告发布：以 API 方式每日/每周上传报告，避免依赖 git 推送
3. 多仓库同步：将相同内容同时推送至多个仓库
4. 离线-在线同步：本地暂存变更，待网络恢复后通过 API 批量同步