---
url: /en/build/crontab.md
---
Pipelines are typically triggered by active events, such as a Git push (`push`), manual trigger via the web interface (`web_trigger`), or an API call (`api_trigger`). In addition, you can configure **Scheduled Tasks (Crontab)** to enable pipelines to run automatically and periodically at specified times. This is suitable for automation scenarios like nightly builds, regular testing, data backups, etc.

## Configuring Scheduled Tasks

The following example shows a basic scheduled task configuration:

```yaml title=".cnb.yml"
# This scheduled task is configured for the main branch.
# When triggered, the system will pull the latest code from the main branch for the build.
main:
  # Scheduled task configuration. After User A submits this config, they become the executor when the task triggers.
  "crontab: 30 5,17 * * *": # Uses a cron expression to define the schedule
    - name: nightly-build-and-test # Pipeline name
      stages:
        - name: run-tests # Stage name
          script: echo "Running scheduled tasks..." # Actual script command to execute
```

### Configuration Details

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

The key name here (e.g., `main`) specifies the **code branch** used when the scheduled task executes. When the scheduled task is triggered, the system will pull the code version currently pointed to by `HEAD` on this branch.

> **Important**: To ensure efficient use of system resources, scheduled tasks do **not** support using `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 are defined using a `cron` expression. The configuration must use `crontab:` as a fixed prefix, followed by a standard `POSIX cron` expression.

Taking the example configuration `crontab: 30 5,17 * * *`, 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 execution identity (triggerer) of the pipeline is the user who most recently **added or modified** this scheduled task configuration and pushed it to the repository.

> **Restriction Note**: To ensure system stability, the minimum scheduling interval for scheduled tasks is **5 minutes**. Configurations with a shorter interval (e.g., `* * * * *`) will fail to be submitted.

## Modifying Scheduled Tasks

You can make the following modifications to existing scheduled tasks:

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**: **Any modification and subsequent push of the scheduled task configuration will update the owner to the user who made the change.** Subsequent task triggers will execute under this new owner's identity.

```yaml title=".cnb.yml"
main:
  # User B modified the cron expression and task script. The task owner is now B.
  "crontab: 0 9 * * *": # Trigger time modified
    - name: morning-build
      stages:
        - name: test
          script: echo "Task updated by User B" # Task content modified
```

> **Tip**: If the current owner is removed from the repository, their scheduled tasks will fail. Simply 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

Remove the specific `"crontab: ..."` key-value pair from the configuration of the corresponding branch to delete that scheduled task.

```yaml title=".cnb.yml"
main:
  # The "crontab: 0 9 * * *" config has been removed; this task is now deleted.
  "crontab: 0 20 * * *": # Another scheduled task remains
    - ...
```

### Delete All Tasks for a Branch

Remove all `crontab` configurations under a specific branch to delete all scheduled tasks for that branch.

```yaml title=".cnb.yml"
main: # This branch now has no scheduled task configurations.
  push: # 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.

## Synchronizing Template Scheduled Tasks

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

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 configured under the `main` branch. If there are any additions or deletions, the system persists these changes.

2. **Template Update Issues**\
   If the scheduled tasks configured in `crontab.yml` change (e.g., tasks are added or removed), the `main` branch of Repository A cannot automatically detect these changes.
   * For deleted tasks, an error will occur during the next trigger.
   * For added tasks, they will not be triggered automatically.

3. **Manual Synchronization**\
   To address this issue, you can manually synchronize the scheduled tasks under the `main` branch of Repository A by calling the Open API. After synchronization, the owner of newly added tasks will be set to the API caller.

## Feature Comparison: Scheduled Tasks vs. Push Events

The following table summarizes the key differences between scheduled tasks and common `push` event pipelines to help you better choose and configure them.

| Feature           | Scheduled Tasks (Crontab)                               | Push Events                           |
| :---------------- | :------------------------------------------------------ | :------------------------------------ |
| **Trigger Mechanism** | Time-based triggering via `cron` rules                  | Triggered by pushing code to the repo |
| **Branch Config**     | Supports only a **specific** single branch name         | Supports `glob` patterns for multiple branches |
| **Execution Identity** | User who last modified the config (`Last Modifier`)     | User who performed the `git push` (`Committer`) |
| **Minimum Interval**  | **5 minutes**                                           | Unlimited                             |
| **Deletion Method**    | Remove the corresponding `crontab:` entry from the config file | Remove the corresponding `push:` entry from the config file |