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. |
| Scheduled pipelines are not currently available for GitLab and GitHub App projects. To find out if you authorized your GitHub account through the GitHub OAuth app, or the GitHub App, see the GitHub App integration 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.
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"]
}
}'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
-
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.
-
Navigate to Triggers.
-
To create a new schedule, click Add Trigger.
-
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.
daily-run-workflow:
jobs:
- test
- build