Scheduled pipelines

Cloud

Control the actor (yourself, or the scheduling system) associated with the pipeline, which can enable the use of Restricted contexts.
Use Dynamic configuration via setup workflows.
Modify the schedule without having to edit .circleci/config.yml.
Take advantage of auto-cancelling.
Specify Pipeline parameters associated with a schedule.
Manage common schedules, for example, across workflows.

Scheduled pipelines are configured through the API, or through the project settings in the CircleCI web app.

A scheduled pipeline can only be configured for one branch. If you need to schedule for two branches, you would need to set up two schedules.

Introduction

Scheduled pipelines allow you to trigger pipelines periodically based on a schedule. Schedules can range from daily, weekly, monthly, or on a very specific timetable. To set up basic scheduled pipelines, you do not need any extra configuration in your .circleci/config.yml file. However, more advanced usage of the feature will require extra .circleci/config.yml configuration (for example, workflow filtering, or using parameters).

Pipeline parameters are typed pipeline variables in the form of a string, integer, or boolean. Adding a parameter to a scheduled pipeline can be done in the web app in the triggers form while setting up a schedule. Any parameters set up in this manner must be added to your configuration file using the parameters key.

Scheduled pipelines are set to run by an "actor", either the CircleCI scheduling system, or a specific user (for example, yourself). The scheduling actor is important to consider if making use of restricted contexts in workflows. If the user (actor) running the workflow does not have access to the context, the workflow will fail with the Unauthorized status.

You can find a basic how-to guide on the Set a nightly scheduled pipeline page, and more advanced examples on the Schedule pipelines with multiple workflows pages.

Get started with scheduled pipelines

To get started with scheduled pipelines, you have the option of using the API, or using the CircleCI web app. Both methods are described below.

Use project settings in the web app

In the CircleCI web app, select your org from the org cards on your user homepage.
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
Select the ellipsis () next to your project and select Project Settings.
Select Triggers in the sidebar.
Select Add Trigger.

The "Pipeline to run" menu only shows the OAuth pipelines, you cannot schedule GitHub App, GitLab or Bitbucket Data Center pipelines.
- Give your trigger a descriptive name.
- Enter an optional trigger description.
- Select the pipeline to run.
- Select a release frequencies (weekly/monthly, which days/months/time etc.).
- Enter a branch or tag name to determine when to trigger the pipeline.
- Optionally, enter pipeline parameters. If you declare pipeline parameters in the form, you need to make sure they are configured in your project’s .circleci/config.yml. See the Pipeline values and parameters page for more information.
- Select an actor to initiate the trigger.
Define the new schedule by filling out the form, then select Save Trigger.

The form also provides the option of adding pipeline parameters, which are typed pipeline variables that you declare at the top level of a configuration.

If you would like to manage common schedules for multiple workflows, you will need to manually set this in your .circleci/config.yml file. See the Schedule pipelines with multiple workflows page for examples.

Use the API

If your project has no scheduled workflows, and you would like to try out scheduled pipelines:

Have your CircleCI token ready, or create a new token by following the steps on the Managing API tokens page.

Create a new schedule using the API. For example:

curl --location --request POST "https://circleci.com/api/v2/project/<project-slug>/schedule" \
--header "circle-token: <PERSONAL_API_KEY>" \
--header "Content-Type: application/json" \
--data-raw '{
    "name": "my schedule name",
    "description": "some description",
    "attribution-actor": "system",
    "parameters": {
      "branch": "main"
      <additional pipeline parameters can be added here>
    },
    "timetable": {
        "per-hour": 3,
        "hours-of-day": [1,15],
        "days-of-week": ["MON", "WED"]
    }
}'

To find your project slug, follow these steps:

Head to the CircleCI web app and select your org from the cards on your user homepage.
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
Select the ellipsis menu () next to your project and select Project Settings. The project slug is listed on the project settings homepage.
- GitHub App: Project slug starts with circleci followed by UUIDs. For example, circleci/34R3kN5RtfEE7v4sa4nWAU/4nYdoKGkb6RXn7JGt8SQtg).
- GitHub OAuth app: Project slug is human readable. For example, github/circleci/circleci-demo-workflows.

For additional information, refer to the Schedule section under the API v2 docs. Also see the Getting started with the API section of the API Developer’s Guide for more guidance on making requests.

Migrate scheduled workflows to scheduled pipelines

If you have existing scheduled workflows you need to migrate to scheduled pipelines, use the Scheduled pipelines migration guide.

Scheduled pipelines video tutorial

The video offers a short tutorial for the following scenarios:

Set a schedule in the web app
Set a schedule with the API
Migrate from scheduled workflows to scheduled pipelines

For the documentation for these scenarios, visit the following pages: - Set a nightly scheduled pipeline - Schedule pipelines with multiple workflows

FAQs

Can I migrate existing scheduled workflows to scheduled pipelines?

Yes, visit the Scheduled pipelines migration guide for more information.

How do I find the schedules that I have created?

As scheduled pipelines are stored directly in CircleCI, there is a UUID associated with each schedule. You can view schedules that you have created on the Triggers page of the project settings. You can also list all the schedules under a single project:

curl --location --request GET "https://circleci.com/api/v2/project/<project-slug>/schedule" \
--header "circle-token: <PERSONAL_API_KEY>"

Refer to the Getting started with the API section of the API Developer’s Guide for more guidance on making requests.

What time zone is used for scheduled pipelines?

Coordinated Universal Time (UTC) is the time zone in which schedules are interpreted.

Can pipelines be scheduled to run at a specific time of day?

Yes, you can set up Scheduled pipelines through the CircleCI web app, or with CircleCI API v2.

If you are currently using Scheduled workflows, see the Migration guide to update your scheduled workflows to scheduled pipelines.

Are scheduled pipelines guaranteed to run at precisely the time scheduled?

CircleCI provides no guarantees about precision. A schedule will be run as if the commit was pushed at the configured time.

Why did my scheduled pipeline run later than expected?

The scheduling expression with scheduled pipelines is different to the Cron expression.

For example, when you express the schedule as 1 per-hour for 08:00 UTC, the scheduled pipeline will run once within the 08:00 to 09:00 UTC window. Note that it does not mean that it will run at 08:00 UTC exactly.

However, subsequent runs of the scheduled pipeline will always be run on the same time as its previous run. In other words, if a previous scheduled pipeline ran at 08:11 UTC, the next runs should also be at 08:11 UTC.

Do you support regex?

Not currently. Scheduled pipelines require highly deterministic inputs such as a commit SHA, branch, or tag (fully qualified, no regex) included in the webhook, API call, or schedule.

If you do not see your pipeline in the "Pipeline to run" dropdown menu, it may be that you are trying to access an unsupported pipeline type. Only OAuth pipelines are supported for scheduling, so GitHub App, GitLab, and Bitbucket Data Center pipelines will not appear in the list. You can see the pipeline type by looking at your pipeline list (Project Settings Pipelines) and inspecting the pipeline labels.