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:

.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.

.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.

.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.

.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