---
url: /zh/build/crontab.md
---
流水线通常由主动事件触发，例如 Git 推送 (`push`)、页面手动触发 (`web_trigger`) 或 API 调用 (`api_trigger`)。除此之外，您还可以配置**定时任务**，使流水线在指定的时间点周期性地自动执行，适用于执行夜间构建、定期测试、数据备份等自动化场景。

## 配置定时任务

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

```yaml title=".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. **负责人**：**任何对定时任务配置的修改并推送，都会将操作者更新为执行此任务的负责人。** 后续任务触发时将以此新负责人身份执行。

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

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

## 删除定时任务

### 删除单个任务

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

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

### 删除分支全部任务

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

```yaml title=".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](https://api.cnb.share.ralphlauren.cn/#/operations/BuildCrontabSync) 手动同步仓库 A 的 `main` 分支下的定时任务。同步后，新增的定时任务的负责人会被设置为 API 触发者。

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

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

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