GitHub Actions 定时任务怎么配?cron 写法 + 4 个必踩的坑
技术教程 · DevOps · CI/CD · 2026-10-01
GitHub Actions 定时任务怎么配?cron 写法 + 4 个必踩的坑
一句话开头
想让自己写的脚本定时跑,Linux 上一句 crontab 就搞定——前提是你得先有一台 24 小时开机、环境不崩的机器。GitHub Actions 的 schedule 触发器把这件事免费搬到了云端,代价是它有几条和 crontab 不一样的规矩,第一次配基本都会踩。
前置准备
- 一个 GitHub 仓库(公开仓库的 Actions 运行时长免费)。
- workflow 文件必须提交到默认分支(一般就是 main)。
- 可选:本地装好 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 跑,不是你的本地时间。换算很清楚:
-
北京时间 09:30 → UTC 01:30 → cron 写 30 1 * * *
-
北京时间每天 00:00 → 前一天的 UTC 16:00 → cron 写 0 16 * * *(很容易忘掉「前一天」)
-
北京时间周一 10:00 → UTC 周一 02:00 → cron 写 0 2 * * 1(周字段 1 = 周一,0 = 周日)
如果你想直接按本地时区写,现在也可以指定 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 历史搞脏。
常见坑(重点看这四条)
- 只认默认分支。workflow 文件只在特性分支上时,schedule 永远不触发,workflow_dispatch 的按钮也不会出现。手动可以用 gh workflow run daily-job.yml --ref feature-branch 绕过,但定时不行。
- 公开仓库 60 天没有活动,定时任务会被自动禁用。这是官方文档明写的规则。低频仓库要定期去 Actions 页面看一眼,被禁用后手动 Enable workflow 即可恢复。(作者补充:只跑定时、很少提交的仓库最容易中招,可以让任务把产物提交回仓库,天然制造活动量;这也是我们内部日报仓库的做法。)
- 整点最容易延迟。官方文档原话是高负载时 schedule 会延迟,而且「high load times include the start of every hour」,负载足够高时排队任务还可能被丢弃。所以要准点就把分钟错开——别写 0 10 * * *,写 7 10 * * *。
- 跑完推不回去、报 403 Permission denied。默认 GITHUB_TOKEN 只有读权限,要提交产物必须写 permissions: contents: write。另外定时任务和手动触发可能同时跑,用 concurrency 组控住,避免两个 job 互相覆盖。
排查清单
-
完全不触发 → workflow 在默认分支吗?仓库是不是 60 天没活动了?
-
时间对不上 → 你是不是按本地时间写的 cron?先跑一遍 date -u 确认当前 UTC。
-
Actions 页面没有 Run workflow 按钮 → workflow_dispatch 的 YAML 缩进错了?文件合并到默认分支了吗?
-
跑到一半被杀 → 单个 job 默认最长 6 小时,标准 runner 资源有限;大任务要拆 job 或上 self-hosted runner。日志里用 set -e 让脚本遇错即停,别让它带着错误状态往下跑。
一句话总结
GitHub Actions 定时任务 = 五字段 cron + 默认 UTC + 只在默认分支生效;把分钟错开整点避开调度延迟,让仓库保持活动避免 60 天自动禁用,再挂一个 workflow_dispatch 随时补跑。这套组合不花钱,也比维护一台常开机器省心。