Working with Pipeline Schedules
1. Creating Pipeline Schedules
| Field | Description | Example |
|---|---|---|
| cron | Cron expression defining the schedule | 0 2 * * * |
| description | Description of the schedule | Weekly build at 2 AM |
| ref | Branch or tag to run the pipeline on | main |
| active | Whether the schedule is active | true |
Example: Creating a Schedule via API
curl --request POST \
--url 'https://gitlab.example.com/api/v4/projects/123/pipeline_schedules' \
--header 'PRIVATE-TOKEN: <your_access_token>' \
--form 'cron=0 2 * * *' \
--form 'description=Weekly build at 2 AM' \
--form 'ref=main' \
--form 'active=true'
Note: The
cron expression follows the standard format with five fields (minute, hour, day of month, month, day of week). GitLab supports cron expressions up to 5 fields.
2. Setting Schedule Variables
| Variable | Value | Description |
|---|---|---|
| CI_SCHEDULED_PIPELINE | true |
Indicates that the pipeline was triggered by a schedule |
| CI_SCHEDULE_NAME | nightly-build |
Name of the schedule that triggered the pipeline |
| CI_SCHEDULE_DESCRIPTION | Daily build at 2 AM |
Description of the schedule that triggered the pipeline |
Example: Using Scheduled Variables in a Job
job_with_scheduled_vars:
script:
- echo "Scheduled pipeline: $CI_SCHEDULED_PIPELINE"
- echo "Schedule name: $CI_SCHEDULE_NAME"
- echo "Schedule description: $CI_SCHEDULE_DESCRIPTION"3. Using Scheduled Pipeline Rules
| Rule | Description | Example |
|---|---|---|
| only | Specifies when the schedule should run | only: [schedule] |
| when | Defines the conditions under which the job runs | when: manual |
| variables | Variables passed to the scheduled pipeline | variables: { ENV: 'production' } |
Example: Scheduled Pipeline with Variables
job_name:
only:
- schedule
variables:
ENV: "production"
DEPLOY_VERSION: "v1.2.3"
Note: Scheduled pipelines inherit the project's default variables unless overridden.
4. Configuring Cron Syntax
| Field | Format | Description |
|---|---|---|
| minute | 0-59 |
Minute of the hour (0-59) |
| hour | 0-23 |
Hour of the day (0-23) |
| day | 1-31 |
Day of the month (1-31) |
| month | 1-12 |
Month of the year (1-12) |
| weekday | 0-7 |
Day of the week (0 or 7 = Sunday, 1-6 = Monday to Saturday) |
Example: Cron Syntax in GitLab CI/CD
schedule:
- cron: '0 2 * * *'
description: 'Daily at 2 AM'
ref: 'main'
Note: The cron syntax follows the standard POSIX format. GitLab CI/CD uses the
0 2 * * * format where each field corresponds to minute, hour, day, month, and weekday respectively.
5. Setting Schedule Timezone
| Property | Value | Description |
|---|---|---|
| timezone | UTC |
Timezone for the schedule. Defaults to UTC. |
Note: Timezone values must be valid IANA timezone identifiers (e.g.,
America/New_York, Europe/London). Invalid identifiers will cause the schedule to be ignored.6. Using Schedule for Nightly Builds
| Property | Value | Description |
|---|---|---|
| schedule | 0 0 * * * |
Cron expression for nightly build at midnight |
| description | Nightly build pipeline |
Human-readable description of the schedule |
| ref | main |
Branch or tag to run the pipeline on |
Example: Schedule Configuration
nightly_build:
triggers:
schedule:
- cron: '0 0 * * *'
description: 'Nightly build pipeline'
ref: main
Note: The cron expression
0 0 * * * runs the pipeline at midnight every day.Warning: Ensure that the branch specified in
ref exists and is protected to avoid unintended pipeline runs.7. Using Schedule for Periodic Scans
GitLab CI/CD allows you to schedule pipelines to run at regular intervals, which is useful for periodic scans such as security audits, code quality checks, or system monitoring.
| Property | Description | Default Value |
|---|---|---|
| schedule | Defines the schedule for running pipelines. Accepts cron-like syntax or predefined intervals. | None |
| cron | Cron expression defining when the pipeline should run (e.g., 0 2 * * * for daily at 2 AM). |
None |
| description | A human-readable description of the schedule. | None |
| ref | The branch or tag to run the pipeline on. | Default branch |
| active | Boolean indicating whether the schedule is active. | true |
Example: Schedule a Daily Security Scan
security_scan:
stage: scan
script:
- echo "Running security scan..."
only:
schedules:
- security_daily_scan
# Schedule definition in .gitlab-ci.yml
security_daily_scan:
cron: '0 2 * * *'
ref: main
active: true
description: "Daily security scan"
Note: The
cron expression uses the standard format with five fields (minute, hour, day of month, month, day of week). GitLab supports cron expressions with a maximum of 5 fields.
Warning: Ensure that the
cron expression aligns with your GitLab instance's timezone settings. By default, schedules run in UTC.
8. Deactivating Schedules
To deactivate a GitLab CI/CD pipeline schedule, you can either use the GitLab UI or the API.
Example: Deactivating a Schedule via GitLab UI
1. Navigate to your project in GitLab.
2. Go to Settings > CI/CD.
3. Expand the "Schedules" section.
4. Find the schedule you want to deactivate.
5. Click the "Deactivate" button next to the schedule.| Option | Description | Notes |
|---|---|---|
| schedule.active | false |
Setting this to false deactivates the schedule |
Note: Deactivating a schedule does not delete it. It can be reactivated at any time.
9. Running Schedules Manually
| Option | Values | Description |
|---|---|---|
| schedule | gitlab-ci.yml |
Defines the schedule in the pipeline configuration file |
| cron | 0 1 * * * |
Cron expression defining when the schedule runs |
| description | Weekly build |
User-friendly description of the schedule |
Example: Manual Trigger via API
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--request POST \
"https://gitlab.example.com/api/v4/projects/<project_id>/pipelines"
Note: Manual triggers require appropriate permissions in the GitLab project.
Warning: Ensure that the schedule is configured correctly to avoid unintended pipeline runs.
10. Monitoring Schedule Execution
| Property | Description | Values |
|---|---|---|
| schedule.status | Indicates the current status of the scheduled pipeline | active, paused |
| schedule.last_run_at | Timestamp of the last pipeline execution | 2025-04-05T14:30:00Z |
| schedule.next_run_at | Timestamp of the next scheduled pipeline execution | 2025-04-12T14:30:00Z |
Example: Check schedule status via API
curl --header "PRIVATE-TOKEN: glpat-xxxxxxxx" \
"https://gitlab.example.com/api/v4/projects/123/pipeline_schedules/456"
Note: The schedule status can be toggled between
active and paused using the GitLab UI or API.
Warning: If a scheduled pipeline fails, it will not retry automatically. You must manually trigger the pipeline or adjust the schedule.