---
url: /zh/build/crontab.md
description: 介绍如何在云原生构建中通过 cron 表达式配置定时触发流水线，适用于夜间构建、定期测试等自动化场景。
---
流水线通常由主动事件触发，如 Git 推送（`push`）、页面手动触发（`web_trigger`）或 API 调用（`api_trigger`）。
此外，还可配置**定时任务**，让流水线在指定时间自动执行，适用于夜间构建、定期测试、数据备份等场景。

## 配置定时任务

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

```yaml title=".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 分钟**。
> 配置低于此间隔（如 `* * * * *`）将无法提交。

### 访问范围限制

定时任务的 `CNB_TOKEN` 以触发者（最后修改 `crontab` 配置的用户）身份签发。
为防止 token 被滥用，其访问范围默认**限定在当前仓库**，不能跨仓库、跨根组织访问资源。

如需定时任务在**根组织内跨仓库**操作（如聚合多个仓库的构建产物），
可由根组织管理员在「组织设置 → 仓库管控」中开启**允许定时任务跨仓操作**开关。
开启后，定时任务的 `CNB_TOKEN` 限定为根组织范围（可访问根组织下所有仓库，仍不可跨根组织）。

> **提示**：如需**跨根组织**调用资源，推荐使用 [OPENAPI 触发](https://api.cnbprod.alpha.qq.com/#/operations/StartBuild)（`api_trigger`）：
> 由外部调度系统持有专用 token 按需触发目标仓库的流水线，权限边界更清晰。

## 修改定时任务

可修改已有定时任务：

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

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

## 删除定时任务

### 删除单个任务

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

### 删除分支全部任务

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

### 系统级清理

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

> **归档恢复**：仓库取消归档后，可在定时任务页面点击同步按钮恢复对应分支的定时任务，或重新推送对应分支。

## 同步模板定时任务

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

**示例**：`.cnb.yml` 通过 `include` 引入 `crontab.yml` 模板：

```yaml title=".cnb.yml"
include:
  - crontab.yml

main:
  push:
    - stages:
        - name: build
          script: npm run build
```

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

1. **推送触发同步**
   仓库 A 的 `main` 分支有代码推送时，系统解析 `.cnb.yml` 并加载 `crontab.yml`，
   解析出所有 `main` 分支的定时任务。有新增或删除时自动持久化。

2. **模板更新问题**
   若 `crontab.yml` 中的定时任务发生变化（新增或删除），仓库 A 的 `main` 分支无法自动感知。
   * 删除的定时任务，下次触发时会报错。
   * 新增的定时任务不会自动触发。

3. **手动同步**
   通过调用 [Open API](https://api.cnbprod.alpha.qq.com/#/operations/BuildCrontabSync) 手动同步。
   同步后新增定时任务的负责人设置为 API 触发者。

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

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

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

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