流水线通常由主动事件触发，例如 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 分钟。配置低于此间隔（如 * * * * *）将无法成功提交。

修改定时任务

您可以对已有的定时任务进行以下修改：

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

.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）时，定时任务的同步机制如下：

1. 推送触发同步
   当仓库 A 的 main 分支有代码推送时，系统会解析 .cnb.yml 并加载 crontab.yml，解析出所有 main 分支下配置的定时任务。如果有新增或删除的定时任务，系统会将其持久化。

2. 模板更新问题
   如果 crontab.yml 中配置的定时任务发生变化（例如新增或删除），仓库 A 的 main 分支无法自动感知这些变化。

   • 对于删除的定时任务，下次触发时会报错。
   • 对于新增的定时任务，不会自动触发。

3. 手动同步
   为了解决上述问题，可以通过调用 Open API 手动同步仓库 A 的 main 分支下的定时任务。同步后，新增的定时任务的负责人会被设置为 API 触发者。

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

下表总结了定时任务与常见的 push 事件流水线的主要区别，助您更好地进行选择与配置。

特性	定时任务	push 事件
触发机制	基于时间的 cron 规则定时触发	由向仓库推送代码的行为触发
分支配置	仅支持明确的单一分支名	支持使用 glob 通配符匹配多个分支
执行身份	最后修改配置的用户 (Last Modifier)	执行 git push 操作的用户 (Committer)
最小间隔	5 分钟	无限制
删除方式	从配置文件中移除对应的 crontab: 条目	从配置文件中移除对应的 push: 条目