Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Migrate scheduled workflows to scheduled pipelines

1 week ago1 min read
Cloud
On This Page

Introduction

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

  • Cannot control the actor, so scheduled workflows can’t use restricted contexts

  • Cannot control the interaction with auto-cancelling of pipelines

  • Cannot use scheduled workflows together with dynamic config 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:

daily-run-workflow:
  triggers:
    - schedule:
        # Every day, 0421Z.
        cron: "21 4 * * *"
        filters:
          branches:
            only:
              - main
  jobs:
    - 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 CCI 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"]
    }
}'

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

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 config file, remove the triggers section, so that it resembles a standard workflow.

daily-run-workflow:
  jobs:
    - test
    - build

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.