GitHub Actions 构建失败自动推到微信 / Telegram

💡 想先看接口参数？接入文档里有完整字段与错误码。这一页只讲「构建失败怎么推」。

为什么值得接这一步

GitHub 的失败通知只有邮件，而失败多半发生在你没盯着屏幕的时候：夜里、周末、下班路上。
把「构建挂了」变成锁屏上的一条消息，比刷新邮件列表快得多；正文里直接带运行链接，点开就是日志。
不需要给流水线配仓库权限：一个通知 Token 只能发消息，读不到代码、提交与 Issue。
私有仓库一样用：信鸽只接收你发来的标题与正文，不申请任何仓库读权限。

三步接入

1. 建一个通知 Token

在控制台的「通知 Token」卡片里点「创建 Token」。Token 会直接显示在列表里，随时可以复制或单独删除。免费档可以建 1 个，每天 20 条消息，个人项目通常够用。

2. 把 Token 存进仓库

仓库 Settings → Secrets and variables → Actions 里新增两样东西： Secret PIGEON_TOKEN（第 1 步建的 Token），以及 Variable PIGEON_ENDPOINT（你的实例地址，形如 https://你的域名，不要带结尾斜杠）。 Secret 用来放凭据，Variable 用来放地址——两者都不该出现在日志里。

3. 粘一段 workflow

- name: Notify on failure
  if: failure()
  env:
    PIGEON_TOKEN: ${{ secrets.PIGEON_TOKEN }}
    PIGEON_ENDPOINT: ${{ vars.PIGEON_ENDPOINT }}
  run: |
    set -euo pipefail
    curl --fail-with-body -sS -X POST "$PIGEON_ENDPOINT/api/v1/notify" \
      -H "Authorization: Bearer $PIGEON_TOKEN" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: ${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}" \
      --data "$(jq -n \
        --arg title "Build failed: ${{ github.repository }}" \
        --arg content "branch ${{ github.ref_name }} · commit ${GITHUB_SHA:0:8} · ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
        '{title: $title, content: $content}')"

💡 两个细节。 --fail-with-body 让额度用尽（429）这类失败以非 0 退出，同时把响应体打进日志，排障时不用猜；幂等键里带上 run_attempt，否则「重跑一次」会命中 24 小时去重，看起来像没发出去。

矩阵构建：只发一条

免费档每天 20 条，而一个 2×3 的矩阵挂掉就是 6 条。把发送挪到依赖它们的汇总 job 上，一次失败只消耗一条额度：

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [20, 22, 24]
        os: [ubuntu-latest, macos-latest]
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

  notify:
    needs: [test]
    if: failure()          # any matrix leg failed — this job still runs once
    runs-on: ubuntu-latest
    steps:
      - run: ./scripts/notify.sh

额度与失败处理

只有真正投递成功才计数：发送失败与幂等去重都不扣额度。
同一个 Idempotency-Key 在 24 小时内只投一次，第二次返回 duplicate: true，也不消耗额度。
额度用尽返回 429，次日 00:00（UTC+8）自动恢复，剩余额度不结转。
不想让「通知失败」把 CI 标红，就在命令末尾加 || true——日志里仍然能看到响应体。

仓库多、矩阵大的话，看看额度与价格；每天 10000 条的高级会员通常就不必再逐仓库算账。

常见问题

Token 泄露了怎么办？在控制台删掉那一个 Token，它立刻失效；其他 Token 与访客聊天入口不受影响。
能在 GitHub 之外用吗？能。Gitea、GitLab CI、Jenkins、青龙、crontab 都是同一条 curl，参见接入文档里的其他语言示例。
消息长什么样？标题一行在前，正文在后；正文里放运行链接，点开直接到失败日志。
要不要在成功时也发？可以，但同一条流水线成功、失败各发一条就要双倍额度。多数人只发失败。

💡 下一步：建好 Token、粘上 workflow，第一次失败就会收到消息。还没绑定渠道？先用 GitHub 登录扫码绑定微信，或粘一个 Telegram bot 的 token。

GitHub Actions 构建失败，推到微信 / Telegram