GitHub Actions 定时任务怎么配?cron 写法 + 4 个必踩的坑

技术教程 · DevOps · CI/CD · 2026-10-01

GitHub Actions 定时任务怎么配?cron 写法 + 4 个必踩的坑

一句话开头

想让自己写的脚本定时跑,Linux 上一句 crontab 就搞定——前提是你得先有一台 24 小时开机、环境不崩的机器。GitHub Actions 的 schedule 触发器把这件事免费搬到了云端,代价是它有几条和 crontab 不一样的规矩,第一次配基本都会踩。

前置准备

  1. 一个 GitHub 仓库(公开仓库的 Actions 运行时长免费)。
  2. workflow 文件必须提交到默认分支(一般就是 main)。
  3. 可选:本地装好 gh CLI,调试速度会快很多。

步骤 1:写一个最小可用的定时 workflow

在仓库里新建 .github/workflows/daily-job.yml:

name: daily-job

on:
  schedule:
    - cron: '30 1 * * *'   # 每天 UTC 01:30
  workflow_dispatch:        # 同时允许手动触发

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 打印时间
        run: date -u

cron 是五个字段:分 时 日 月 周。GitHub 不支持秒,最短间隔是 5 分钟(*/5 * * * *),高频任务还可能被限流。

步骤 2:把本地时间换算成 UTC(第一个坑)

schedule 默认按 UTC 跑,不是你的本地时间。换算很清楚:

如果你想直接按本地时区写,现在也可以指定 timezone(IANA 名字):

on:
  schedule:
    - cron: '0 10 * * *'
      timezone: 'Asia/Shanghai'

很多老教程写「GitHub Actions 不支持 timezone」,那是早期的情况;官方文档现在已明确支持 IANA 时区字符串。不过团队里最好统一一个口径——要么全用 UTC 并在注释里标出本地时间,要么全用 timezone,混着写最容易出事故。

步骤 3:加 workflow_dispatch,出问题能立刻补跑

定时任务最尴尬的场景是:凌晨 3 点跑挂了,你只能早上干等到第二天。加一行 workflow_dispatch 就有 Run workflow 按钮,还能带参数:

on:
  workflow_dispatch:
    inputs:
      force_run:
        description: '忽略缓存强制跑'
        type: boolean
        default: false

本地用 gh CLI 调试验证,比等定时触发快得多:

gh auth login
gh workflow list
gh workflow run daily-job.yml
gh run list --workflow=daily-job.yml
gh run watch          # 实时刷日志,类似 docker logs -f

步骤 4:一个可以直接抄的完整例子

定时抓数据、把结果提交回仓库:

name: daily-fetch

on:
  schedule:
    - cron: '7 2 * * *'    # UTC 02:07 —— 故意避开整点
  workflow_dispatch:

permissions:
  contents: write          # 默认 token 只读,要推送必须显式声明

concurrency:
  group: ${{ github.workflow }}
  cancel-in-progress: false

jobs:
  fetch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install -r requirements.txt
      - run: python fetch_data.py
      - run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add data/
          git diff --staged --quiet || git commit -m "chore: update data"
          git push

最后那句 git diff --staged --quiet || 是为了「没有变更就不提交」,避免刷出一堆空提交把 commit 历史搞脏。

常见坑(重点看这四条)

  1. 只认默认分支。workflow 文件只在特性分支上时,schedule 永远不触发,workflow_dispatch 的按钮也不会出现。手动可以用 gh workflow run daily-job.yml --ref feature-branch 绕过,但定时不行。
  2. 公开仓库 60 天没有活动,定时任务会被自动禁用。这是官方文档明写的规则。低频仓库要定期去 Actions 页面看一眼,被禁用后手动 Enable workflow 即可恢复。(作者补充:只跑定时、很少提交的仓库最容易中招,可以让任务把产物提交回仓库,天然制造活动量;这也是我们内部日报仓库的做法。)
  3. 整点最容易延迟。官方文档原话是高负载时 schedule 会延迟,而且「high load times include the start of every hour」,负载足够高时排队任务还可能被丢弃。所以要准点就把分钟错开——别写 0 10 * * *,写 7 10 * * *。
  4. 跑完推不回去、报 403 Permission denied。默认 GITHUB_TOKEN 只有读权限,要提交产物必须写 permissions: contents: write。另外定时任务和手动触发可能同时跑,用 concurrency 组控住,避免两个 job 互相覆盖。

排查清单

一句话总结

GitHub Actions 定时任务 = 五字段 cron + 默认 UTC + 只在默认分支生效;把分钟错开整点避开调度延迟,让仓库保持活动避免 60 天自动禁用,再挂一个 workflow_dispatch 随时补跑。这套组合不花钱,也比维护一台常开机器省心。