定时任务

1288 字约 4 分钟

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

配置定时任务

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

.cnb.yml
# 此定时任务配置在 main 分支下
# 触发时，系统将拉取 main 分支的最新代码进行构建
main:
  # 定时任务配置。用户 A 提交此配置后，任务触发时的执行者即为 A
  "crontab: 30 5,17 * * *": # 使用 cron 表达式定义执行计划
    - 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 等执行细节。
负责人：对定时任务配置的修改并推送后，会将操作者更新为执行者，后续触发将以新负责人身份执行。

.cnb.yml
main:
  # 用户 B 修改了 cron 表达式和任务脚本，此后该任务触发者变为 B
  "crontab: 0 9 * * *": # 触发时间已修改
    - name: morning-build
      stages:
        - name: test
          script: echo "Task updated by User B" # 任务内容已修改

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

删除定时任务

删除单个任务

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

.cnb.yml
main:
  # "crontab: 0 9 * * *" 配置已被移除，该定时任务现已删除
  "crontab: 0 20 * * *": # 另一个定时任务会被保留
    - ...

删除分支全部任务

移除某分支下所有的 crontab 配置，即可删除该分支下的所有定时任务。

.cnb.yml
main: # 此分支下已无任何定时任务配置
  push: # 其他类型事件的流水线配置不受影响
    - ...

系统级清理

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

同步模板定时任务

当仓库 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` 通配符匹配多个分支
执行身份	最后修改配置的用户 (`Last Modifier`)	执行 `git push` 的用户 (`Committer`)
最小间隔	5 分钟	无限制
删除方式	从配置文件中移除 `crontab:` 条目	从配置文件中移除 `push:` 条目