Introduction

GitLab CI supports scheduled pipelines that run on cron intervals. When schedules fail to trigger, regular tasks like nightly builds, cleanup jobs, and security scans do not execute.

Common Symptoms

  • Schedule shows "never run" in the UI
  • Schedule was running but suddenly stopped
  • Pipeline runs manually but not on schedule

Root Causes

1. Schedule references non-existent branch

The schedule targets a branch that was deleted or renamed.

2. Schedule is deactivated

Schedules can be accidentally deactivated in the UI.

3. Pipeline configuration does not match schedule

The .gitlab-ci.yml does not have rules that match the scheduled trigger.

Step-by-Step Fix

Fix 1: Verify schedule configuration

  1. 1.In GitLab UI: CI/CD > Schedules:
  2. 2.Check that the schedule is active (toggle is on)
  3. 3.Verify the target branch exists
  4. 4.Check the cron expression

Fix 2: Add pipeline rules for scheduled triggers

yaml
nightly-tests:
  script:
    - npm run test:e2e
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual

Fix 3: Create schedule via API

bash
curl --header "PRIVATE-TOKEN: $TOKEN" \
  --data "description=Nightly Build" \
  --data "ref=main" \
  --data "cron=0 2 * * *" \
  --data "cron_timezone=UTC" \
  --data "active=true" \
  "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/pipeline_schedules"

Common Cron Expressions

  • 0 2 * * * - Daily at 2 AM UTC
  • 0 */4 * * * - Every 4 hours
  • 0 9 * * 1 - Monday at 9 AM
  • 0 0 1 * * - First of every month

Debugging

```bash # List all pipeline schedules curl --header "PRIVATE-TOKEN: $TOKEN" \ "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/pipeline_schedules"

# Check scheduled pipeline runs curl --header "PRIVATE-TOKEN: $TOKEN" \ "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/pipelines?source=schedule" ```

Prevention

  • Monitor scheduled pipeline runs with alerts
  • Use API to create and manage schedules (version controlled)
  • Test schedules with manual trigger first
  • Document all scheduled pipelines and their purpose