无服务器精准定时触发 GitHub Actions：Cron-job.org + workflow_dispatch 实战

GitHub Actions 的原生 Cron 定时任务精度感人（延迟可达 10~60 分钟），而某些场景又需要精准的"准点触发"。本文记录如何利用免费的 Cron-job.org 配合 GitHub API，实现秒级精准的定时触发。

痛点

GitHub Actions 自带的 schedule 触发本质上是"低优先级队列"，在公开仓库中排队等待执行，延迟完全不可控：

触发方式	精度	稳定性
GitHub Actions 原生 Cron	±10~60 分钟	一般
外部 API 触发（workflow_dispatch）	±1 秒	高

workflow_dispatch 是 GitHub Actions 的"手动触发"事件，但通过 API 调用可以实现自动化精准触发。

整体架构

┌─────────────────┐      HTTP POST       ┌──────────────────┐
│   Cron-job.org  │ ──────────────────▶  │   GitHub API     │
│ (免费精准定时)   │  Authorization: PAT │ workflow_dispatch│
└─────────────────┘                      └────────┬─────────┘
                                                  │
                                                  ▼
                                         ┌──────────────────┐
                                         │  GitHub Actions  │
                                         │  真正执行脚本     │
                                         └──────────────────┘

外部 Cron 服务只负责"到点敲门"，脚本执行依然在 GitHub Actions 的容器里完成，两者各司其职。

第一步：配置 GitHub Actions

在 .github/workflows/your-workflow.yml 中，触发条件加上 workflow_dispatch：

name: Your Workflow

on:
  workflow_dispatch:   # 允许 API / 手动触发
  # schedule:          # 可以删除原生 Cron，或保留作备用
  #   - cron: '0 * * * *'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      - name: Run your script
        run: python scripts/your_script.py

推送到 GitHub 备用。

第二步：获取 GitHub Personal Access Token (PAT)

1. 打开 GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. 点击 Generate new token (classic)
3. 勾选 repo（或更精细的 workflows: write）
4. 生成后复制 Token（只出现一次，务必保存）

⚠️ 安全建议：建议创建一个 Fine-grained PAT，仅授予目标仓库的 Actions: Read and write 权限，泄露影响最小化。

第三步：在 Cron-job.org 创建定时任务

1. 访问 cron-job.org 并注册登录
2. 点击 Create Cronjob
3. 填写配置：

配置项	值
Title	Trigger My Action（随意）
URL	https://api.github.com/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches
Request method	POST

4. Headers → Add header，添加两个：

   Authorization: token ghp_xxxxxxxxxxxxxxxxxxxx
   Content-Type: application/json
   

5. Request body：

   {"ref":"main"}
   

6. Execution schedule：用 Cron 表达式设定精准时间，例如：

   • 每天早上 8:00：0 8 * * *
   • 每周五下午 3:00：0 15 * * 5
   • 每 30 分钟：*/30 * * * *

7. 点击 Create 完成。

第四步（可选）：通过命令行本地测试

如果想先验证 API 调用是否正确，可以用 curl 在本地测试：

curl -s -X POST \
  -H "Authorization: token ghp_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  --data '{"ref":"main"}' \
  "https://api.github.com/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches"

如果返回 204 No Content，说明触发成功。去 GitHub 仓库的 Actions 页面查看运行状态即可。

注意事项

1. 代理问题

本地 curl 命令可能需要 --socks5 代理访问 GitHub，但 Cron-job.org 运行在云端，不需要代理，直接访问即可。

2. 触发频率限制

GitHub Actions 有并发限制（约 20 个 workflow 同时运行）。如果触发了但没反应，可能是前面有任务还在排队。

3. 安全

• 不要把 PAT 提交到代码仓库
• PAT 在第三方平台存储时，优先使用平台的 Secret/Variable 功能（如果支持）
• 定期轮换 PAT

4. GitHub Actions 超时

如果脚本运行时间较长（> 5 分钟），记得在 workflow YAML 中设置 timeout-minutes: 60 防止超时中断。

总结

对比维度	GitHub 原生 Cron	Cron-job.org + API
触发精度	±10~60 分钟	±1 秒
配置难度	一行 YAML	多平台配合
免费额度	免费（有限制）	完全免费
稳定性	依赖 GitHub 队列	依赖两个平台

这套方案兼顾了零成本和秒级精度，脚本执行依然在 GitHub Actions 强大的云端容器中进行，非常适合数据抓取、定期统计等不需要实时响应的自动化场景。

---

本文方法可应用于任何需要精准定时触发 GitHub Actions 的场景，如定期数据抓取、静态站点自动更新等。