定时任务

1126 字约 4 分钟

流水线通常由主动事件触发，如 Git 推送（push）、页面手动触发（web_trigger）或 API 调用（api_trigger）。此外，还可配置定时任务，使流水线在指定时间周期性自动执行，适用于夜间构建、定期测试、数据备份等场景。

配置定时任务

以下示例展示了一个基本的定时任务配置：

.cnb.yml
main:
  "crontab: 30 5,17 * * *":
    - name: nightly-build-and-test
      stages:
        - name: run-tests
          script: echo "Running scheduled tasks..."

配置详解

1. 分支 (`main`)

此处的键名（如 main）指定定时任务执行时使用的代码分支。任务触发时，系统会拉取该分支 HEAD 指向的代码。

重要：定时任务不支持 glob 表达式匹配多个分支，必须配置为明确的单一分支名称。

2. 定时触发器 (`"crontab: ..."`)

与 push 等事件不同，定时任务通过 cron 表达式定义触发计划，配置须以 crontab: 为前缀，后接标准 POSIX cron 表达式。

以上述 crontab: 30 5,17 * * * 为例，表示每天在系统时区 (Asia/Shanghai) 的 5:30 AM 和 5:30 PM 各触发一次。

负责人机制：定时任务触发时，流水线的执行身份是最新添加或修改此配置并推送到仓库的用户。

限制：为确保系统稳定性，定时任务最小调度间隔为 5 分钟。配置低于此间隔（如 * * * * *）将无法提交。

修改定时任务

可对已有定时任务进行修改：

触发时机：更改 cron 表达式（如从 30 5,17 * * * 改为 0 9 * * *）。
流水线内容：修改 stages、env 等执行细节。
负责人：对定时任务配置的修改并推送后，会将操作者更新为执行者，后续触发将以新负责人身份执行。

提示：若当前负责人被移出仓库，其创建的定时任务将执行失败。由其他有权限的用户修改并推送配置即可更新负责人，恢复正常执行。

删除定时任务

删除单个任务

从对应分支的配置中移除特定的 "crontab: ..." 键值对，即可删除该定时任务。

删除分支全部任务

移除某分支下所有的 crontab 配置，即可删除该分支下的所有定时任务（其他类型事件的流水线配置不受影响）。

系统级清理

当远程仓库的某个分支被删除时，该分支下的所有定时任务会自动清理。
当整个仓库被删除时，其下的所有定时任务也会被自动清理。

同步模板定时任务

当仓库 A 的 main 分支通过 include 引用了其他仓库的模板文件（如 crontab.yml）时，定时任务的同步机制如下：

推送触发同步 仓库 A 的 main 分支有代码推送时，系统解析 .cnb.yml 并加载 crontab.yml，解析出所有 main 分支的定时任务。有新增或删除时自动持久化。
模板更新问题 若 crontab.yml 中的定时任务发生变化（新增或删除），仓库 A 的 main 分支无法自动感知。
- 删除的定时任务，下次触发时会报错。
- 新增的定时任务不会自动触发。
手动同步 通过调用 Open API（在新窗口打开）手动同步。同步后新增定时任务的负责人设置为 API 触发者。

特性对比：定时任务 vs. push 事件

下表总结了定时任务与 push 事件流水线的主要区别：

特性	定时任务	push 事件
触发机制	基于 `cron` 时间表达式	由代码推送行为触发
分支配置	仅支持单一明确分支	支持 `glob` 通配符
执行身份	最后修改配置的用户	执行 `git push` 的用户
最小间隔	5 分钟	无限制
删除方式	从配置中移除 `crontab:` 条目	从配置中移除 `push:` 条目

分支配置：定时任务需指定明确的分支名称。 push 事件支持 glob 通配符匹配多个分支（如 feature/*）。
执行身份：定时任务的执行者为最后添加或修改 crontab 配置的用户（Last Modifier）， push 事件的执行者为执行 git push 的用户（Committer）。