---
url: /en/build/crontab.md
description: >-
  Explains how to configure cron-based scheduled tasks in Cloud Native Build
  pipelines, allowing pipelines to run automatically at specified times for
  scenarios like nightly builds and periodic testing.
---
Pipelines are typically triggered by active events, such as a Git push (`push`), manual trigger (`web_trigger`),
or API call (`api_trigger`). In addition,
you can configure **Scheduled Tasks (Crontab)** to run pipelines automatically at specified times,
suitable for nightly builds, periodic testing, data backups, etc.

## Configuring Scheduled Tasks

The following example shows a basic scheduled task configuration:

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

### Configuration Details

#### 1. Branch (`main`)

The key name specifies the **code branch** used when the scheduled task executes.

> **Important**: Scheduled tasks do **not** support `glob` patterns to match multiple branches.
> They must be configured with a **specific single** branch name.

#### 2. Scheduled Trigger (`"crontab: ..."`)

Unlike events like `push`, scheduled tasks use a `cron` expression. The configuration must use `crontab:` as a prefix,
followed by a standard `POSIX cron` expression.

Taking `crontab: 30 5,17 * * *` as an example,
this means the task triggers daily at 5:30 AM and 5:30 PM in the system timezone (`Asia/Shanghai`).

**Owner Mechanism**: When a scheduled task triggers,
the pipeline's execution identity is the user who most recently **added or modified** this configuration and pushed it
to the repository.

> **Restriction**: To ensure system stability, the minimum scheduling interval is **5 minutes**.
> Configurations below this interval (e.g., `* * * * *`) will fail to submit.

### Access Scope Limitation

The `CNB_TOKEN` of a scheduled task is issued under the identity of its owner
(the user who last modified the `crontab` configuration).
To prevent token abuse, its access scope is **limited to the current repository** by default,
and cannot access resources across repositories or root organizations.

If a scheduled task needs to operate **across repositories within the root organization**
(e.g., aggregating build artifacts from multiple repositories),
a root organization administrator can enable the **Allow crontab jobs to operate across repositories**
switch under "Organization Settings → Repository Control".
Once enabled, the `CNB_TOKEN` of scheduled tasks is scoped to the root organization
(accessible to all repositories under the root organization, but still not across root organizations).

> **Tip**: To access resources **across root organizations**, it is recommended to use
> [OPENAPI trigger](https://api.cnbprod.alpha.qq.com/#/operations/StartBuild) (`api_trigger`):
> an external scheduling system holds a dedicated token and triggers the target repository's pipeline on demand,
> providing a clearer permission boundary.

## Modifying Scheduled Tasks

You can modify existing scheduled tasks as follows:

1. **Trigger Schedule**: Change the `cron` expression (e.g., from `30 5,17 * * *` to `0 9 * * *`).
2. **Pipeline Content**: Modify execution details such as `stages`, `env`, etc.
3. **Owner**:
   **The user who modifies and pushes the scheduled task configuration becomes the new executor.**
   Subsequent triggers will execute under this new owner's identity.

> **Tip**: If the current owner is removed from the repository, their scheduled tasks will fail.
> Have another user with permissions modify and push the configuration to update the owner and resume normal execution.

## Deleting Scheduled Tasks

### Delete a Single Task

To delete a specific scheduled task, remove the
`"crontab: ..."` key-value pair from the configuration of the corresponding branch.

### Delete All Tasks for a Branch

Remove all `crontab` configurations under a specific branch to delete all scheduled tasks for that branch
(pipeline configurations for other event types are unaffected).

### System-Level Cleanup

* When a branch in the remote repository is deleted, all scheduled tasks under that branch are automatically cleaned up.
* When the entire repository is deleted, all scheduled tasks within it are automatically cleaned up.
* When the repository is archived, all scheduled tasks within it are also automatically cleaned up.

> **Recovering from Archive**: After the repository is unarchived,
> you can click the sync button on the scheduled tasks page to restore the tasks for a branch,
> or push the branch again.

## Synchronizing Template Scheduled Tasks

When the `.cnb.yml` file in the `main` branch of Repository A includes a template file (e.g., `crontab.yml`),
the synchronization mechanism for scheduled tasks works as follows:

**Example**: `.cnb.yml` includes the `crontab.yml` template via `include`:

```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. **Push-Triggered Synchronization**
   When there is a code push to the `main` branch of Repository A,
   the system parses `.cnb.yml` and loads `crontab.yml`, resolving all scheduled tasks.
   Additions and deletions are automatically persisted.

2. **Template Update Issues**
   If scheduled tasks in `crontab.yml` change (added or removed),
   the `main` branch of Repository A cannot automatically detect these changes.
   * Deleted tasks will error on the next trigger.
   * Added tasks will not trigger automatically.

3. **Manual Synchronization**
   To address this, call the [Open API](https://api.cnbprod.alpha.qq.com/#/operations/BuildCrontabSync) to manually synchronize.
   After synchronization, the owner of newly added tasks is set to the API caller.

## Feature Comparison: Scheduled Tasks vs. Push Events

The following table summarizes the key differences between scheduled tasks and `push` event pipelines:

| Feature                | Scheduled Tasks (Crontab)   | Push Events                   |
| :--------------------- | :-------------------------- | :---------------------------- |
| **Trigger Mechanism**  | Via `cron` time expressions | Triggered by code push        |
| **Branch Config**      | Specific single branch only | Supports `glob` patterns      |
| **Execution Identity** | Last config modifier        | User who performed `git push` |
| **Minimum Interval**   | **5 minutes**               | Unlimited                     |
| **Deletion Method**    | Remove `crontab:` config    | Remove `push:` config         |

* **Branch Config**: Scheduled tasks require an exact branch name.
  Push events support `glob` patterns (e.g., `feature/*`) to match multiple branches.
* **Execution Identity**: For scheduled tasks, the executor is the user who last added or modified the
  `crontab` configuration (`Last Modifier`).
  For push events, the executor is the user who performed the `git push` (`Committer`).