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:
# 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 executeConfiguration 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
globpatterns 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
cronexpression (e.g., from30 5,17 * * *to0 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.
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 modifiedTip: 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.
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.
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
mainbranch of Repository A, the system parses.cnb.ymland loadscrontab.yml, resolving all scheduled tasks. Additions and deletions are automatically persisted.Template Update Issues If scheduled tasks in
crontab.ymlchange (added or removed), themainbranch 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 |