Start Building for Free

Migrate scheduled workflows to scheduled pipelines

3 months ago2 min read
On This Page


Migrating to scheduled pipelines from scheduled workflows will eliminate the following limitations of scheduled workflows:

  • Cannot control the actor (yourself, or the scheduling system), so scheduled workflows cannot use restricted contexts

  • Cannot control the interaction with auto-cancelling of pipelines

  • Cannot use scheduled workflows together with dynamic configuration without complex workarounds

  • Cannot change or cancel scheduled workflows on a branch without triggering a pipeline

  • Cannot kick off test runs for scheduled workflows without changing the schedule

  • Cannot restrict scheduled workflows from PR branches if you want the workflow to run on webhooks

In addition, scheduled pipelines allow for the consolidation of common schedules. With scheduled workflows, for example, if you had three workflows you wanted to run at midnight every day, you would need three separate schedules. However, with scheduled pipelines, you can set up a single schedule to run all three workflows at midnight every day.

1. Find your scheduled trigger

To migrate from scheduled workflows to scheduled pipelines, you will first need to find the scheduled trigger in your project’s .circleci/config.yml.

For example, it might look like:

    - schedule:
        # Every day, 0421Z.
        cron: "21 4 * * *"
              - main
    - test
    - build

2. Create the new schedule

Before you can create a new schedule, you will need to interpret the frequency your trigger needs to run from the cron expression. Once you have done that, you will create a schedule using either the API or the project settings in the web app. Both methods are described below.

Use the API

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 "<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. Also see the Getting started with the API section of the API Developer’s Guide for more guidance on making requests.

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.

3. Remove triggers section

In the configuration file, remove the triggers section, so that it resembles a standard workflow.

    - test
    - build

Suggest an edit to this page

Make a contribution
Learn how to contribute