Flutter 仓库定时自动化任务实战：用 GitHub Actions 的 schedule 触发器自动创建周期性维护 Issue

本篇技术指南以 Flutter 官方仓库 docs/infra/Scheduled-Recurring-Tasks.md 为骨架，系统讲解 Flutter 如何通过 GitHub Actions 的定时调度（on.schedule / cron 任务）自动创建与指派周期性的维护类 Issue。读完你既能掌握一套可直接复用的「定时 Issue 工作流」标准模板与最佳实践，也能结合仓库中真实在跑的 quarterly-scheduled-tasks.yml 与 .ci.yaml 深入理解其落地细节与工程约束。

为什么需要"定时自动化任务"

像 Flutter 这样的大型开源仓库，存在大量不依赖某次具体提交、却又必须按时完成的周期性维护工作，例如：

• 定期把新字符串送上游翻译、并把内部翻译控制台的结果同步回框架；
• 定期把 golden 测试工具 goldctl 的二进制版本升级到最新修订；
• 定期关闭长时间无回应的 Issue、锁定期刊等。

这些工作如果只靠人工记忆和线下跟踪，极易遗漏。为此，Flutter 仓库引入了一套约定：GitHub Actions 工作流按 on.schedule 定时器触发，在 Job 内部通过 GitHub CLI（gh issue create）直接向仓库创建 GitHub Issue，把"该做的事"以带上下文的 Issue + Checklist 形式自动落到每个人都能看到的待办列表里。文档原文的定义见 Scheduled-Recurring-Tasks.md 的 Overview 小节。

所有由这类工作流生成的 Issue 都统一携带 automated task 标签，并叠加相关团队标签与领域标签（例如 team-framework、a: internationalization、infra: flutter gold），便于检索与分流。

在仓库中查找这些自动化任务

仓库文档建议直接使用以下 GitHub Issue 搜索查询来观察"自动任务"的运转状态（在 Issues 页面搜索框中粘贴查询串即可，无需依赖人工跟踪列表）：

• 所有打开中的自动任务：is:issue is:open label:"automated task"
• 本地化（Localization）任务：is:issue label:"automated task" label:"a: internationalization"
• goldctl 版本升级任务：is:issue label:"automated task" label:"infra: flutter gold"

这套"用统一标签 + Issue 搜索查询跟踪工作"的方式，是理解 Flutter 维护流程的入口之一。

工作流设计模式与标准模板

文档指出，定时任务工作流统一放在仓库根目录的 .github/workflows/ 下（即 .github/workflows/ 目录），核心动作是使用 GitHub CLI 的 gh issue create 在 GitHub Actions Job 中直接提交 Issue。仓库根目录当前确实集中存放了 20 个工作流文件，其中包括两个已投入使用的定时/周期性工作流，以及多个 schedule 类维护工作流，印证了文档描述的目录约定。

下面是文档给出的标准模板（新增定时任务时以此为基础复制改造成新 .yml）：

# Copyright 2014 The Flutter Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

name: Scheduled Task Name

on:
  schedule:
    # Offset cron schedule to avoid high load periods (e.g., top of the hour)
    # Use https://crontab.guru to test and adjust schedules
    - cron: 40 09 2 2,5,8,11 *
  workflow_dispatch:

jobs:
  create_issue:
    name: Create scheduled task issue
    runs-on: ubuntu-latest
    if: ${{ github.repository == 'flutter/flutter' }}
    permissions:
      issues: write
    steps:
      - name: Create scheduled task issue
        run: |
          gh issue create \
            --title "$TITLE" \
            --assignee "$ASSIGNEES" \
            --label "$LABELS" \
            --body "$BODY"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GH_REPO: ${{ github.repository }}
          TITLE: '[Automated Task] Issue Title'
          ASSIGNEES: assignee_username
          LABELS: 'automated task,team-label'
          BODY: |
            ### Task Description

            Detailed context and checklist here.

对模板中各要素逐项拆解：

模板要素	说明
on.schedule[].cron	5 字段标准 cron 语法，决定触发时间点（详见下文"时间偏移"）。
on.workflow_dispatch	允许手动触发，便于临时补跑与联调测试。
runs-on: ubuntu-latest	Job 运行环境；gh CLI 在 GitHub 托管 runner 上预装，无需额外安装步骤。
if: github.repository == 'flutter/flutter'	仓库守卫，防止工作流在 fork 仓库中被无谓执行。
permissions.issues: write	Job 级最小权限声明，只有声明后才能创建 Issue。
gh issue create	GitHub CLI 建单命令，配合 4 个参数把内容从环境变量注入：--title 标题、--assignee 指派对象、--label 标签（逗号分隔）、--body 正文（可含 Checklist）。
GH_TOKEN / GH_REPO	前者使用 secrets.GITHUB_TOKEN（自动注入的仓库令牌），后者指向当前仓库，二者都是让 gh 认账鉴权与确定目标的必要环境变量。

关键要求与最佳实践

文档明确列出五条硬性要求，逐条对应到上面的模板：

1. 权限声明：Job 权限必须包含 issues: write，否则 gh issue create 会被拒绝。
2. 仓库守卫：必须写 if: ${{ github.repository == 'flutter/flutter' }}，避免定时任务在用户 fork 出的副本仓库里也创建一堆 Issue。
3. 手动触发：必须声明 workflow_dispatch，让工作流可以被手动测试（schedule 的触发时机很难即时验证，手动触发是回归验证的关键手段）。
4. 标签统一：每个周期性任务工作流都必须打上 automated task 标签，这是"自动任务"能被上面的搜索查询聚合的前提。
5. 时间偏移（Offset cron）：GitHub 官方明确提示——schedule 事件在 GitHub Actions 工作流运行高峰期可能被延迟，每个整点开头（top of the hour）就是典型高峰；负载足够高时，部分排队的 Job 甚至可能被丢弃。因此应把 cron 的小时分钟偏移开，例如用 40 分而不是 00 分，以降低延迟与丢单概率。

结合真实源码：季度任务工作流是如何落地的

模板不是纸上谈兵。仓库中 quarterly-scheduled-tasks.yml 是文档"Current Active Workflows"表格里两个活跃任务的真实载体——它在一个工作流文件的同一个 Job 中连续创建两条 Issue，完整演示了"一个 cron 触发点承载多个周期性任务"的组织方式。

该工作流的 cron 表达式为：

on:
  schedule:
    # Triggers quarterly at 09:40 UTC on the 2nd of Feb, May, Aug, Nov
    - cron: 40 09 2 2,5,8,11 *
  workflow_dispatch:

拆解 40 09 2 2,5,8,11 *：分钟 40、小时 09（UTC）、日期 2、月份 2/5/8/11（2 月、5 月、8 月、11 月）、任意星期。即在 2 月、5 月、8 月、11 月的 2 号 09:40 UTC 各触发一次，一年 4 次，正好对齐 Flutter 的季度节奏（每个季度一次）。分钟取 40 而非 00，正是文档"避开整点高峰"原则的实战体现。

两个子步骤都遵循同一套模式：定义 env → 调用 gh issue create。差异只在注入的内容，这意味着同一 Job 可以低成本复用 runner 与 token，串行创建多条不同领域的任务单。

实例一：季度本地化（Localization）同步任务

- name: Create localization update issue
  run: |
    gh issue create \
      --title "$TITLE" \
      --assignee "$ASSIGNEES" \
      --label "$LABELS" \
      --body "$BODY"
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    GH_REPO: ${{ github.repository }}
    TITLE: '[Automated Task] Quarterly Localizations Update (flutter_localizations)'
    ASSIGNEES: QuncCccccc
    LABELS: 'automated task,a: internationalization,team-framework'
    BODY: |
      ### Quarterly Localization Update

      **Context**: Ahead of the upcoming stable release cut, localized strings need to be synchronized from the internal console into the framework.

      ### Checklist
      - [ ] Check for any new strings that need to be sent upstream for translation.
      - [ ] Pull latest translations from internal translation console.
      - [ ] Update localizations in `flutter_localizations`, Material (`material_ui`), and Cupertino (`cupertino_ui`).
        - [ ] **Follow-up check**: Note that updates to Material or Cupertino localizations might need to wait for the stable roll. If so, file a new follow-up issue to complete after the stable roll.
      - [ ] Run test suite for localizations.
      - [ ] Open PR to close this issue.

      *This issue was automatically generated by GitHub Actions workflow.*

这则 Issue 承担的任务与仓库结构直接对应：本地化资源分散在 packages/flutter_localizations/lib（内含大量 .arb 翻译文件，如目录下 src/material、src/cupertino 对应的各语言资源）、Material 与 Cupertino 组件库中。正文把工作拆成"送新字符串上游翻译 → 从内部翻译控制台拉取 → 更新三处本地化 → 跑本地化测试套件 → 开 PR 关闭本 Issue"的可勾选清单；其中还刻意埋了跟进提醒：Material/Cupertino 的本地化更新可能依赖 stable roll 合并，若需等待，应另开 follow-up Issue，这正是把"无法一步到位"的复杂工作继续自动向下流转的细节。

实例二：季度 goldctl 版本升级任务

- name: Create goldctl update issue
  run: |
    gh issue create \
      --title "$TITLE" \
      --assignee "$ASSIGNEES" \
      --label "$LABELS" \
      --body "$BODY"
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    GH_REPO: ${{ github.repository }}
    TITLE: '[Automated Task] Bump goldctl version in .ci.yaml'
    ASSIGNEES: Piinks
    LABELS: 'automated task,team-ecosystem,infra: flutter gold'
    BODY: |
      ### Quarterly goldctl Version Update

      **Context**: Ahead of the upcoming stable release cut, the `goldctl` binary version used for golden file testing needs to be updated to the latest revision in both `flutter/flutter` and `flutter/packages`.

      ### Checklist
      - [ ] Check for the latest `goldctl` git revision (e.g. from CIPD or the Skia Gold repository).
      - [ ] Update `goldctl` in `flutter/flutter`:
        - [ ] Update `git_revision` for `goldctl` instances in `.ci.yaml`.
        - [ ] Validate `.ci.yaml` changes and ensure tests pass.
        - [ ] Open PR in `flutter/flutter` to close this issue.
      - [ ] Update `goldctl` in `flutter/packages`:
        - [ ] Update `goldctl` version in `.ci.yaml`.
        - [ ] Run golden file tests and verify CI checks pass.
        - [ ] Open PR in `flutter/packages`.

      *This issue was automatically generated by GitHub Actions workflow.*

goldctl 是 Flutter golden 文件测试（像素级对比测试）所用的外部二进制工具。它在仓库中的引用形式高度集中且可批量定位：在根目录 .ci.yaml 中，所有 CI 目标的依赖列表都以 {"dependency": "goldctl", "version": "git_revision:c845c41b9b81bfcb11f2f0ab17b5b2386d634c31"} 形式声明同一份 git_revision（该文件共出现数十到上百处相同实例）。也就是说，升级任务在 flutter/flutter 侧的实操本质是：把 .ci.yaml 里所有 git_revision 值统一替换成最新的 goldctl 提交哈希，然后跑一遍依赖校验与 golden 测试，确认 CI 通过后开 PR。从源码结构看，同一版本号在 .ci.yaml 中被大范围重复引用，因此升级必须"全量同步替换 + 测试兜底"，这也解释了为什么 Issue 的 Checklist 会要求逐一验证测试通过。

从零新增一个定时任务工作流

若要在 Flutter 仓库（或任何借鉴该模式的项目）中引入一个新的自动维护任务，文档给出如下步骤：

1. 在 .github/workflows/ 下按上面的标准模板新建一个 .yml 文件；
2. 用标准 5 字段 cron 语法定义调度时间（语法可用 crontab.guru 等工具先行测试推演），务必把分钟位从整点 :00 偏移开；
3. 在 BODY 环境变量中写入清晰的背景上下文与可勾选的 Checklist；
4. 更新本文档（Scheduled-Recurring-Tasks.md）末尾的 Current Active Workflows 表格；
5. 提交 Pull Request 供评审合并。

值得补充的是：Issue 正文中 Checklist 尽量写成"每一步都能独立验证并最终落到开 PR 关闭本 Issue"的可执行条目；对于依赖外部条件（如等待 stable roll）的步骤，应显式标注并引导创建 follow-up Issue，保证任务状态始终在 Issue 时间线上可追溯。

仓库内当前活跃的定时工作流

文档在 "Current Active Workflows" 一节用表格登记了两个季度任务（两者共享同一个 quarterly-scheduled-tasks.yml 触发器）。内容整理如下：

任务名称	GitHub 工作流	任务描述	使用的标签
本地化更新（Localization Update）	quarterly-scheduled-tasks.yml	提示团队在稳定版本分支前检查是否有新的上游字符串、从内部翻译控制台拉取翻译、更新 flutter_localizations 以及 Material、Cupertino 本地化、运行测试、提交 PR；若需要 stable roll 则另开 follow-up Issue。	automated task、a: internationalization、team-framework
goldctl 版本更新（Goldctl Version Update）	quarterly-scheduled-tasks.yml	提示团队查找最新 goldctl git 修订版本，更新 flutter/flutter 与 flutter/packages 两仓库 .ci.yaml 中的 goldctl 依赖，验证 golden 文件测试后开 PR。	automated task、team-ecosystem、infra: flutter gold

除这两个季度任务外，从 .github/workflows/ 目录清单可以看出，该仓库的定时工作流并不止于此：例如 lock.yaml（锁定陈旧 Issue）、no-response.yaml（对无回应 Issue 打标/关闭）等维护类工作流同样声明了 schedule 触发；它们与季度任务共同构成了一套"无人值守的仓库治理"体系——凡与具体提交无关、但与时间强相关的维护动作，都被收敛进 GitHub Actions 的 cron 中自动执行。

小结：该模式的适用边界与可迁移要点

把本文内容收束为几条可直接迁移的工程要点：

• 用 Issue 而非人肉日历做任务载体：定时触发只负责"建单"，把上下文、Checklist、负责人、标签一次写全，让任务在 Issue 时间线上自然流转、闭环（以 PR 关闭 Issue）。
• 标签即队列：automated task + 领域标签的组合，使所有自动任务可以用一两条 Issue 搜索查询随时总览，无需专门的看板系统。
• 宁可手动，不可误跑：workflow_dispatch（可手动补跑测试）与 if: github.repository == ...（防 fork 误跑）必须同时存在。
• 时间偏移是可靠性设计而非洁癖：GitHub 高峰期（每小时整点）可能延迟甚至丢弃排队的 schedule Job，cron 分钟位取 40 而非 00 是实际部署中必须遵守的约束。
• 内容模板化、动作原子化：参考 quarterly-scheduled-tasks.yml 的组织方式，一个 Job 内可串行创建多个任务单，每条 Issue 内部再拆成"可独立验证、以 PR 收尾"的原子 Checklist——这正是该机制能在 Flutter 这种大型仓库中长期稳定运转的原因。