Migrate scheduled workflows to scheduled pipelines
| The deprecation of the scheduled workflows feature has been postponed. Since the deprecation announcement went live, your feedback and feature requests have been monitored and it is clear there is more work to do in order to improve the existing scheduled pipelines experience, and also make migration easier for all. Updates on a new deprecation timeline will be announced here and on CircleCI Discuss. |
| This feature is supported for orgs that use OAuth authentication. Check your Organization slug at . OAuth authenticated orgs are structured as follows:
This feature is not supported if your organization slug is in the following format:
For an overview of feature support, see the VCS integration overview page. |
Introduction
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:
daily-run-workflow:
triggers:
- schedule:
# Every day, 0421Z.
cron: "21 4 * * *"
filters:
branches:
only:
- main
jobs:
- test
- build2. 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.
a. 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 "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:
|
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.
b. Use project settings in the web app
-
In the CircleCI web app, navigate to Projects in the sidebar, then select the ellipsis (…) next to your project and select Project Settings. You can also find the Project Settings button on each project’s landing page.
-
Navigate to Triggers.
-
To create a new schedule, select Add 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 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.
daily-run-workflow:
jobs:
- test
- build