GitHub Actions schedule 仅在默认分支生效怎么办

如果 GitHub Actions 的定时任务只在默认分支生效，先不要急着改 cron。官方规则是：schedule 工作流只在默认分支运行，并使用默认分支的最新提交；工作流文件也必须已经存在于默认分支。官方文档地址：https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows。

最常见的根因是“YAML 只提交到了功能分支”。先确认仓库的默认分支和 .github/workflows/ 文件，再检查时间表达式；定时器本身不会按你当前检出的分支单独运行。

• 执行分支：schedule 只在默认分支执行，代码取默认分支最新提交。
• 文件位置：工作流必须位于仓库根目录的 .github/workflows/，并存在于默认分支。
• 时间语义：默认使用 UTC；也可以为 schedule 指定 IANA 时区，最短间隔为五分钟。
• 运行状态：公开仓库 60 天没有活动时，定时工作流可能被自动禁用；整点高峰也可能延迟。

先确认 schedule 到底使用哪个分支

schedule 不是“当前分支上的 cron”。你在 feature 分支新增了 YAML，即使文件内容完全正确，定时事件也不会因为当前分支存在它而运行。先在仓库设置中确认 Default branch，再打开该分支的文件树，检查文件名是否位于根目录下的 .github/workflows/。

可以用下面的最小配置做结构对照。示例只表达触发器，不代表某个仓库已经执行过；其中注释说明了默认分支和时区边界。

# 这个文件必须提交到仓库默认分支的 .github/workflows/ 目录
name: scheduled-check

on:
  schedule:
    # 每天 02:15（UTC）触发；不要按本地时区直接填写小时
    - cron: '15 2 * * *'

jobs:
  check:
    # 使用默认分支最新提交运行这个作业
    runs-on: ubuntu-latest
    steps:
      - name: Print branch context
        run: |
          # 输出上下文，便于区分定时运行与手动运行
          echo "ref=${GITHUB_REF}"
          echo "sha=${GITHUB_SHA}"

排查时重点看两个事实：文件是否已经合并到默认分支，以及 Actions 页面看到的运行是否来自该分支。不要只在本地切换分支后看 YAML，就把它当成 GitHub 已经加载的版本。

分支确认后再检查 cron 和时区

确认文件在默认分支后，再检查时间表达式。GitHub Actions 默认按 UTC 解释 cron；当前文档也支持用 IANA 时区表达时区感知的计划。若你希望北京时间每天 10 点运行，可以明确写出时区，避免把本地时间直接换算错。

on:
  schedule:
    - cron: '0 10 * * *'
      # 用 IANA 时区表达业务时间，避免把北京时间误当 UTC
      timezone: 'Asia/Shanghai'

同时注意，schedule 的最短间隔是每五分钟一次。整点附近属于高负载时段，官方提示工作流可能延迟，严重时排队任务可能被丢弃。把分钟设在整点后的非整五分钟位置，只能降低高峰碰撞概率，不能把它当成严格实时保证。

仍不运行时按这四项排查

第一，打开 Actions 页面，看工作流是否被禁用，以及最近是否有运行记录。第二，确认公开仓库是否超过 60 天没有活动；这类仓库的 scheduled workflows 可能被自动禁用，需要按页面提示重新启用。第三，检查 YAML 的缩进、事件名称和 cron 五个字段。第四，用手动触发做一次结构烟雾检查。

name: schedule-smoke-check

on:
  # 手动触发只用于检查工作流能否被识别；正式定时仍由 schedule 负责
  workflow_dispatch:
  schedule:
    - cron: '17 2 * * *'

jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - name: Show trigger
        run: |
          # 打印事件类型和提交引用，帮助定位触发来源
          echo "event=${{ github.event_name }}"
          echo "ref=${GITHUB_REF}"
          echo "sha=${GITHUB_SHA}"

手动运行成功，只能说明工作流文件和作业结构可以被识别，不等于 schedule 已经按预期到点触发。最终仍要回到默认分支、Actions 状态、仓库活动和时间表达式四个检查点。

常见问题

schedule 能不能只让某个功能分支定时运行？

schedule 本身只在默认分支运行。若业务需要针对某个分支执行，可以让定时工作流在默认分支启动，再在作业中显式检出目标分支，并把这种行为当作工作流逻辑处理，而不是把 schedule 误认为分支级 cron。

为什么 cron 写对了，运行时间还是差几个小时？

先确认是否按 UTC 理解。未指定时区时，GitHub Actions 默认使用 UTC；如果业务按本地时间安排，使用 IANA 时区或先做明确换算。

默认分支改名后需要重新配置 schedule 吗？

重点检查工作流文件是否已经存在于新的默认分支，以及 Actions 页面是否仍启用该工作流。默认分支变化会影响 schedule 的执行分支和关联上下文。

如何区分没有触发和触发后失败？

先看 Actions 页面有没有对应时间的运行记录：没有记录时优先查默认分支、文件路径、禁用状态和 cron；有记录但失败时，再进入作业日志排查具体步骤。