Scheduling Workflows

1. Using Scheduled Triggers

Property	Description	Values	Notes
trigger	Scheduled trigger configuration	`schedule`	Must be set to `schedule` to enable scheduled workflows
cron	Cron expression for scheduling	`0 0 * * *`	Uses standard cron syntax. Example runs daily at midnight
timezone	Timezone for scheduling	`America/New_York`	Defaults to UTC if not specified. Must be valid IANA timezone

Example: Basic Scheduled Workflow

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/python:3.9
    steps:
      - run: echo "Scheduled build executed"
triggers:
  - schedule:
      cron: "0 0 * * *"
      timezone: "America/New_York"
      branches:
        only:
          - main

Note: Scheduled workflows run on the main branch by default. Use branches.only to restrict execution to specific branches.

Warning: Cron expressions in CircleCI are evaluated in UTC unless a timezone is specified.

2. Setting Cron Schedules

Property	Value	Description
schedule	`0 0 * * *`	Cron expression for scheduling workflow
timezone	`UTC`	Timezone for cron schedule (optional)

Example: Cron Schedule Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm test

workflows:
  version: 2
  nightly-build:
    schedule:
      cron: "0 0 * * *"
      timezone: "UTC"
    jobs:
      - build

3. Understanding Cron Syntax

Field	Allowed Values	Description
minute	`0-59`	Minute of the hour (0-59)
hour	`0-23`	Hour of the day (0-23)
day of month	`1-31`	Day of the month (1-31)
month	`1-12` or `*` (jan-dec)	Month of the year (1-12 or jan-dec)
day of week	`0-7` or `*` (sun-sat)	Day of the week (0-7 or sun-sat)

Example: Cron Expression

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/python:3.9
    steps:
      - checkout
      - run: echo "Running scheduled build"
  schedule:
    cron: "0 12 * * *"
    branches:
      only:
        - main

Note: The cron expression 0 12 * * * runs the job at 12:00 PM every day.

Common Cron Patterns

0 0 * * * - Daily at midnight
0 0 * * 0 - Weekly on Sunday at midnight
0 0 1 * * - Monthly on the first day at midnight
0 0 1 1 * - Annually on January 1st at midnight

4. Specifying Schedule Timezone

Property	Value	Description
timezone	`UTC`	Timezone for the schedule. Defaults to UTC.
timezone	`America/New_York`	Example of a specific timezone.

Example: Setting timezone in schedule

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/python:3.9
    steps:
      - checkout
      - run: echo "Hello World"
  schedule:
    timezone: America/New_York
    cron: '0 1 * * *'

5. Filtering Scheduled Branches

Filter Type	Description	Example
branches.ignore	Specifies branches to ignore when scheduling workflows	`branches.ignore: [master, develop]`
branches.only	Specifies only these branches to run scheduled workflows	`branches.only: [main, release/*]`

Example: Ignore specific branches

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm test

workflows:
  version: 2
  scheduled-workflow:
    triggers:
      - schedule:
          cron: "0 0 * * *"
          branches:
            ignore: [master, develop]
    jobs:
      - build

6. Setting Up Daily Builds

Property	Value	Description
schedule	`{ cron: "0 0 * * *" }`	Defines the cron expression for daily execution at midnight
timezone	`"America/New_York"`	Timezone for scheduling (optional)

Example: Daily Build Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm test

workflows:
  daily-build:
    schedule:
      cron: "0 0 * * *"
      timezone: "America/New_York"
    jobs:
      - build

Note: The cron expression 0 0 * * * runs the workflow at midnight every day. Ensure that the timezone matches your team's working hours.

7. Setting Up Weekly Builds

Property	Value	Description
when	`weekly`	Schedule builds to run once a week
at	`0 0 * * 1`	Cron expression for Monday at midnight (UTC)
timezone	`UTC`	Timezone for scheduling (default: UTC)

Example: Weekly Build Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm test

workflows:
  weekly-build:
    when: weekly
    at: 0 0 * * 1
    timezone: UTC
    jobs:
      - build

Note: The at field uses cron syntax. For more details on cron expressions, refer to the Crontab Guru or CircleCI's documentation.

Warning: Ensure that the timezone is set correctly to avoid unexpected build times due to timezone differences.

8. Using Multiple Schedules

CircleCI allows you to define multiple schedules within a single workflow, enabling complex automation scenarios. Each schedule can have its own cron expression and trigger conditions.

Schedule Name	Cron Expression	Trigger Conditions	Description
daily-build	`0 0 * * *`	Daily at midnight	Runs a full build every day at 12:00 AM UTC
weekly-report	`0 0 * * 1`	Weekly on Monday at midnight	Generates weekly reports and sends them to stakeholders
monthly-maintenance	`0 0 1 * *`	Monthly on the first day at midnight	Performs maintenance tasks like dependency updates and cleanup

Example: Defining Multiple Schedules in a Workflow

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/python:3.9
    steps:
      - checkout
      - run: echo "Running daily build"

  report:
    docker:
      - image: circleci/python:3.9
    steps:
      - checkout
      - run: echo "Generating weekly report"

  maintenance:
    docker:
      - image: circleci/python:3.9
    steps:
      - checkout
      - run: echo "Performing monthly maintenance"

workflows:
  version: 2
  scheduled-workflows:
    triggers:
      - schedule:
          cron: "0 0 * * *"
          branches:
            only:
              - main
      - schedule:
          cron: "0 0 * * 1"
          branches:
            only:
              - main
      - schedule:
          cron: "0 0 1 * *"
          branches:
            only:
              - main
    jobs:
      - build
      - report
      - maintenance

Note: Schedules are evaluated in the UTC timezone. Ensure your cron expressions align with your desired local time zone.

Warning: Be cautious with frequent schedules as they may lead to increased resource consumption and costs.

9. Managing Scheduled Pipelines

Property	Description	Values	Notes
schedule	Defines the cron schedule for the pipeline	`0 0 * * *`	Uses standard cron syntax
timezone	Timezone for the schedule	`America/New_York`	Must be valid IANA timezone
enabled	Whether the schedule is active	`true` or `false`	Defaults to `true`

Example: Scheduling a Pipeline

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - run: echo "Building..."
  schedule:
    cron: "0 0 * * *"
    timezone: "America/New_York"
    enabled: true

Note: Scheduled pipelines run on the circleci/node image by default, but you can customize this.

Warning: Ensure that the cron schedule is valid to avoid unexpected pipeline runs.

Scheduling Pipeline Management

Use schedule to define when pipelines run
Supports standard cron syntax and timezone configuration
Can enable or disable schedules using the enabled flag

10. Debugging Schedule Issues

Example: Checking Workflow Schedules

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: echo "Building..."
  schedule-test:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: echo "Scheduled job running"

workflows:
  version: 2
  scheduled-builds:
    triggers:
      - schedule:
          cron: "0 0 * * *"
          filters:
            branches:
              only:
                - main
    jobs:
      - schedule-test

Issue	Possible Cause	Solution
Workflow not triggering	`filters` branch settings or incorrect `cron` syntax	Verify `cron` format and branch filter matches current branch
Incorrect schedule time	Timezone mismatch or wrong `cron` expression	Use UTC in `cron` or set timezone via CircleCI UI
Job fails on schedule	Environment variables missing or incorrect config	Ensure all required env vars are set in project settings

Note: Use circleci config validate to check for syntax errors in your config.

Warning: Scheduled workflows run on the main branch by default. Ensure sensitive jobs are not triggered on protected branches without proper checks.

Common Schedule Debugging Steps

Verify the cron expression is valid and in UTC
Check that the branch filter matches the current branch
Confirm environment variables are correctly set in CircleCI project settings
Review job logs for any runtime errors or missing dependencies