Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Scheduled Pipelines

2 days ago3 min read
Cloud
On This Page

Introduction

Scheduled pipelines allow you to trigger pipelines periodically based on a schedule. Scheduled pipelines retain all the features of pipelines:

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

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. If you have existing workflows you need to migrate to scheduled pipelines, use the Scheduled pipelines migration guide.

Use project settings in the web app

  1. In the CircleCI web app, navigate to Projects in the sidebar, then click the ellipsis (…) next to your project and click on Project Settings. You can also find the Project Settings button on each project’s landing page.
  2. Navigate to Triggers.
  3. To create a new schedule, click Add Trigger.
  4. Define the new schedule by filling out the form, then click Save Trigger.

The form also provides the option of adding pipeline parameters, which are typed pipeline variables declared 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:

  1. Have your CCI token ready, or create a new token by following the steps on the Managing API tokens page.
  2. 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"]
    }
}'

For additional information, refer to the Schedule section under the API v2 docs.

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:

FAQs

Q: Can I migrate existing scheduled workflows to scheduled pipelines?

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


Q: How do I find the schedules that I have created?

A: 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>"

For GitHub and Bitbucket users: project-slug takes the form of vcs-type/org-name/repo-name, e.g. gh/CircleCI-Public/api-preview-docs.

For GitLab SaaS Support users: project-slug takes the form of circleci/:slug-remainder. Refer to the Getting started section of the API Developer’s Guide for more information on the project slug format.


Q: Why is my scheduled pipeline not running?

A: There could be a few possible reasons:

  • Is the actor who is set for the scheduled pipelines still part of the organization?
  • Is the branch set for the schedule deleted?
  • Is your GitHub organization using SAML protection? SAML tokens expire often, which can cause requests to GitHub to fail.

Q: Why did my scheduled pipeline run later than expected?

A: There is a nuanced difference in the scheduling expression with Scheduled Pipelines, compared 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.


Q: Do you support regex?

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

Next steps


Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.