Scheduled Tasks

About 857 wordsAbout 3 min

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:

.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 triggered, the system pulls the code pointed to by HEAD on that branch.

Important: To ensure efficient use of system resources, 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.

Modifying Scheduled Tasks

You can modify existing scheduled tasks as follows:

Trigger Schedule: Change the cron expression (e.g., from 30 5,17 * * * to 0 9 * * *).
Pipeline Content: Modify execution details such as stages, env, etc.
Owner: Any modification and subsequent push of the scheduled task configuration will update the executor to the user who made the change. Subsequent 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. 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.

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

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.
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.
Manual Synchronization To address this, call the Open API(Open in new window) 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	Time-based triggering via `cron` expressions	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