Scheduled Tasks
About 741 wordsAbout 2 min
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:
# 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 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
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 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:
- 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 owner to the user who made the change. Subsequent task 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. 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.
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.
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 |
