Scheduled Tasks

About 959 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
main:
  "crontab: 30 5,17 * * *":
    - name: nightly-build-and-test
      stages:
        - name: run-tests
          script: echo "Running scheduled tasks..."

Configuration Details

1. Branch (`main`)

The key name specifies the code branch used when the scheduled task executes.

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

Access Scope Limitation

The CNB_TOKEN of a scheduled task is issued under the identity of its owner (the user who last modified the crontab configuration). To prevent token abuse, its access scope is limited to the current repository by default, and cannot access resources across repositories or root organizations.

If a scheduled task needs to operate across repositories within the root organization (e.g., aggregating build artifacts from multiple repositories), a root organization administrator can enable the Allow crontab jobs to operate across repositories switch under "Organization Settings → Repository Control". Once enabled, the CNB_TOKEN of scheduled tasks is scoped to the root organization (accessible to all repositories under the root organization, but still not across root organizations).

Tip: To access resources across root organizations, it is recommended to use OPENAPI trigger(Open in new window) (api_trigger): an external scheduling system holds a dedicated token and triggers the target repository's pipeline on demand, providing a clearer permission boundary.

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: The user who modifies and pushes the scheduled task configuration becomes the new executor. Subsequent triggers will execute under this new owner's identity.

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.

Delete All Tasks for a Branch

Remove all crontab configurations under a specific branch to delete all scheduled tasks for that branch (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.
When the repository is archived, all scheduled tasks within it are also automatically cleaned up.

Recovering from Archive: After the repository is unarchived, you can click the sync button on the scheduled tasks page to restore the tasks for a branch, or push the branch again.

Synchronizing Template Scheduled Tasks

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

Example: .cnb.yml includes the crontab.yml template via include:

.cnb.yml
include:
  - crontab.yml

main:
  push:
    - stages:
        - name: build
          script: npm run build

crontab.yml
main:
  "crontab: 30 5,17 * * *":
    - name: nightly-build-and-test
      stages:
        - name: run-tests
          script: echo "Running scheduled tasks..."

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	Via `cron` time expressions	Triggered by code push
Branch Config	Specific single branch only	Supports `glob` patterns
Execution Identity	Last config modifier	User who performed `git push`
Minimum Interval	5 minutes	Unlimited
Deletion Method	Remove `crontab:` config	Remove `push:` config

Branch Config: Scheduled tasks require an exact branch name. Push events support glob patterns (e.g., feature/*) to match multiple branches.
Execution Identity: For scheduled tasks, the executor is the user who last added or modified the crontab configuration (Last Modifier). For push events, the executor is the user who performed the git push (Committer).