GitHub Actions schedule 怎样按时区安排定时工作流

GitHub Actions 的定时工作流由 on.schedule 配置。现在可以在五段 POSIX cron 后写入 IANA 时区，直接表达“上海时间工作日上午 9:30”这类需求，不必再手工把时间换算成 UTC。要让配置真正生效，还要同时满足三个条件：工作流文件存在于默认分支、cron 语法正确、并且接受定时事件在高负载时可能延迟的事实。

官方地址：https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax

最小可用写法是把 timezone 放在同一个 schedule 条目下，例如 30 9 * * 1-5 配合 Asia/Shanghai。提交到默认分支后，从 Actions 的运行记录核对 schedule 事件；不要把排队延迟、夏令时跳时或文件不在默认分支，误认为是 cron 没生效。

先把工作流放在默认分支

schedule 只会使用默认分支上的工作流文件，并以默认分支的最新提交运行。也就是说，在功能分支里新增 YAML 后，不能只在该分支等待定时触发；先合并或直接提交到仓库当前的默认分支，再观察运行记录。

常见的文件位置如下：

.github/workflows/business-day-report.yml

如果仓库刚改过默认分支名称，先确认仓库设置中的默认分支与自己的提交目标一致。工作流文件的路径和名称可以自定义，但必须位于 .github/workflows/ 目录。

用 cron 和 IANA 时区写出定时规则

cron 按“分钟、小时、日、月、星期”五段书写。下面的例子表示周一到周五、上海时间每天 09:30 触发：

name: business-day-report

on:
  schedule:
    - cron: '30 9 * * 1-5'
      timezone: 'Asia/Shanghai'

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Build report
        run: |
          # 这里放生成报表的命令，保持任务本身与调度规则分离。
          ./scripts/build-report.sh

关键点有三个：

• 30 是分钟，9 是小时；使用 1-5 表示周一到周五。
• timezone 使用 IANA 时区名，例如 Asia/Shanghai、America/New_York，不是随意写的缩写。
• 同一工作流可以有多个 schedule 条目；如果任务需要区分不同 cron，可以在步骤中读取 github.event.schedule。

如果仍使用旧的“默认 UTC”思路，也可以把本地时间换算成 UTC，但维护成本更高，尤其是涉及夏令时的地区。显式写 timezone 更容易让审核者直接读懂规则。

提交后如何确认定时事件已经接管

提交到默认分支后，不要只看 YAML 文件有没有绿色检查。打开仓库的 Actions，进入对应工作流，重点核对运行记录里的事件类型、分支和触发时间。

1. 打开 Actions，选择刚提交的工作流。
2. 在运行列表中查看事件来源是否为 schedule，而不是手动的 workflow_dispatch。
3. 打开一次运行，确认它使用的是默认分支对应的提交。
4. 进入任务详情，确认步骤状态和实际开始时间，再判断是否只是排队延迟。

可以在工作流中加一个简短的环境输出，帮助区分“定时事件没来”和“事件来了但业务步骤失败”。日志命令本身不负责改变调度，只记录事件上下文：

      - name: Print schedule context
        env:
          # 读取触发本次运行的 cron 字符串，方便和多个 schedule 条目对应。
          SCHEDULE_EXPR: ${{ github.event.schedule }}
          # 记录本次工作流实际使用的提交引用。
          WORKFLOW_REF: ${{ github.ref }}
        run: |
          # 输出最小排查信息，不打印令牌或仓库私密配置。
          echo "schedule=${SCHEDULE_EXPR}"
          echo "ref=${WORKFLOW_REF}"

高负载时为什么看起来没有准点运行

GitHub 文档明确提示，Actions 负载较高时，schedule 事件可能延迟；每个小时开始时尤其容易遇到高负载，极端情况下排队中的任务还可能被丢弃。因此“没有在 09:30 整准时启动”不等于 cron 解析失败。

生产任务可以做两件事降低误判：

• 不要把 cron 集中写在整点，例如把 0 9 * * * 调整为 17 9 * * *，避开整点高峰。
• 在业务层记录计划时间和实际开始时间；如果必须准点执行，不要把 GitHub Actions schedule 当作硬实时调度器。

排查时按这个顺序更快：先看工作流是否在默认分支，再看运行列表有没有 schedule，最后看任务是否排队。只有在没有运行记录且配置也未提交到默认分支时，才优先回头检查 YAML。

夏令时地区要特别检查跳时

如果 IANA 时区会实行夏令时，春季向前跳时可能跳过某个本地时间。例如规则设置为凌晨 02:30，而当天 02:30 不存在，平台会把它推进到下一个有效时间。这个行为是时区规则的结果，不是把 timezone 改回 UTC 就能“修复”的错误。

需要稳定业务窗口时，可以选择不经过夏令时的时区，或把任务安排在不会落入跳时区间的时间。选择前先确认业务真正要求的是“当地墙上时间”还是“固定 UTC 时刻”，两者的含义不同。

一张表记住常见边界

结语

安排 GitHub Actions 定时任务时，推荐把本地时间直接写成 cron + IANA timezone，并把工作流提交到默认分支。上线后用 Actions 运行记录确认 schedule 事件、实际分支和任务状态，同时为高负载延迟与夏令时跳时留出业务余量。这样既能避免 UTC 换算带来的维护错误，也不会把平台的正常调度边界误判成配置故障。

相关问题

GitHub Actions schedule 最短多久运行一次？

官方文档给出的最短间隔是每 5 分钟一次。即使 cron 写得更密，也不应把它当作高频实时任务机制。

schedule 为什么只在默认分支生效？

scheduled workflow 使用默认分支上的工作流文件和最新提交。功能分支里的 YAML 没有进入默认分支前，不能按预期接管仓库的定时事件。

能否用北京时间缩写代替 Asia/Shanghai？

不建议。配置应使用 IANA 时区标识，例如 Asia/Shanghai，避免缩写的含义不明确。