Migrate scheduled workflows to schedule triggers
| This feature is not supported for GitLab pipelines. |
Migrating to schedule triggers gives you more control over how and when your scheduled pipelines run:
-
Choose the actor (yourself, or the scheduling system), so scheduled pipelines can use restricted contexts.
-
Control how scheduled pipelines interact with auto-cancelling of pipelines (GitHub OAuth and Bitbucket Cloud only, as GitHub App schedule triggers are never auto-cancelled).
-
Use schedules together with dynamic configuration, with no workarounds.
-
Change or cancel a schedule on a branch without triggering a pipeline run.
-
Kick off a test run of a schedule without changing it.
-
Keep scheduled workflows off PR branches while still running them on webhooks.
Schedule triggers also let you consolidate common schedules. For example, if you want three workflows to run at midnight every day, you can set up a single schedule that runs all three, instead of three separate schedules.
1. Find your scheduled workflow
To migrate from scheduled workflows to schedule triggers, first find the scheduled workflow in your project’s configuration YAML file. For example:
daily-run-workflow:
triggers:
- schedule:
# Every day, 0421Z.
cron: "21 4 * * *"
filters:
branches:
only:
- main
jobs:
- test
- build
2. Create the new schedule trigger
Before you create a new schedule, read the frequency and branch from your scheduled workflow. In the example from step 1, 21 4 * * * runs every day at 04:21 UTC, and the filters section limits the schedule to the main branch. Use the same branch for the new schedule trigger.
The steps depend on your pipeline type. GitHub App, GitHub App Server, and Cursor Origin schedules use a cron expression, so you can reuse the expression from your scheduled workflow as it is. GitHub OAuth and Bitbucket Cloud schedules use a timetable instead, so you translate the hours and days from the cron expression into timetable fields. Create the schedule using either the API or project settings in the CircleCI web app.
2.1. Option 1: Use the API
Select the tab for your pipeline type:
-
GitHub App, GitHub App Server, and Cursor Origin
-
GitHub OAuth and Bitbucket Cloud
-
Have your CircleCI personal API token ready, or create a new token by following the steps on the Managing API Tokens page. Set it as an environment variable:
$ export CIRCLE_TOKEN=<YOUR_API_TOKEN> -
List your organizations:
$ curl -g https://circleci.com/api/v3/orgs \ --header "Authorization: Bearer $CIRCLE_TOKEN"Locate your organization in the response and copy its
idvalue. -
Find your project ID. Replace
<ORG_ID>with your organization ID:$ curl -g "https://circleci.com/api/v3/projects?filter[org_id]=<ORG_ID>" \ --header "Authorization: Bearer $CIRCLE_TOKEN"Locate your project in the response and copy its
idvalue. -
Get your pipeline definition ID. Replace
<PROJECT_ID>with your project ID:$ curl -g "https://circleci.com/api/v3/pipelines?filter[project_id]=<PROJECT_ID>" \ --header "Authorization: Bearer $CIRCLE_TOKEN"Locate your pipeline in the response and copy its
idvalue. -
Create a new schedule trigger. Replace
<PIPELINE_ID>with your pipeline definition ID,<SCHEDULE_NAME>with a name for your schedule, and<CRON_EXPRESSION>with the cron expression from your scheduled workflow. Updateconfig.refandcheckout.refto the branch from thefilterssection of your scheduled workflow:curl --request POST \ --url https://circleci.com/api/v3/triggers \ --header "Authorization: Bearer $CIRCLE_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "data": { "attributes": { "config": { "ref": "main" }, "checkout": { "ref": "main" }, "event": { "type": "schedule", "schedule": { "name": "<SCHEDULE_NAME>", "cron_expression": "<CRON_EXPRESSION>", "attribution_actor": "current" } } }, "references": { "pipeline": { "id": "<PIPELINE_ID>" } } } }'
For additional information, refer to the API v3 Triggers Reference.
| We recommend using the CircleCI API v3 as described here but you can also create schedule triggers for these pipeline types with the API v2 Create Trigger endpoint. The API v2 Create Schedule endpoint only supports GitHub OAuth and Bitbucket Cloud pipelines. |
-
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 v2 Create Schedule endpoint. The v2 API uses a
timetableobject instead of a cron expression. Translate the hours and days from your cron expression into thehours-of-dayanddays-of-weekfields. For example,21 4 * * *becomeshours-of-dayof[4]and all seven days indays-of-week. Replace<project-slug>with your project slug and<SCHEDULE_NAME>with a name for your schedule:curl --request POST "https://circleci.com/api/v2/project/<project-slug>/schedule" \ --header "Circle-Token: $CIRCLE_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "name": "<SCHEDULE_NAME>", "description": "some description", "attribution-actor": "system", "parameters": { "branch": "main" }, "timetable": { "per-hour": 1, "hours-of-day": [4], "days-of-week": ["MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"] } }'
To find your project slug, see Find a Project Slug.
For additional information, refer to the Schedule section under the API v2 Reference.
Also see the Getting Started With the API section of the API Developer’s Guide for more guidance on making requests.
2.2. Option 2: Use project settings in the web app
The steps to set up a schedule trigger in the web app are different depending on your pipeline type:
-
GitHub App, GitHub App Server, and Cursor Origin
-
GitHub OAuth and Bitbucket Cloud
-
In the CircleCI web app, select your org from the org cards on your user homepage.
-
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
-
Select the ellipsis
next to your project and select Project Settings.
You can also access project settings from each project overview page using the Settings button. -
Select Project Setup in the sidebar.
-
Locate your pipeline and select Schedule +.
-
Complete the schedule trigger form:
Figure 1. Screenshot showing the schedule trigger form-
Give your trigger a descriptive name.
-
Enter a Config branch. CircleCI fetches your config file from this branch.
-
Enter a Checkout branch. CircleCI checks out your code from this branch.
-
Under Pipeline attribution, select the actor to initiate the trigger. You can choose yourself, or the scheduling system if you want the trigger to be independent from individual users. If your project requires the use of environment variables stored in restricted contexts, you must assign someone who has access to those contexts.
-
Optionally, select Add parameter to enter pipeline parameters to set when triggering the pipeline. If you enter any new pipeline parameters make sure to also add them to your config file. You can select Populate from config to automatically populate the parameters fields from your config file.
-
Enter a Schedule (cron expression). Schedules must run at least 5 minutes apart. The start time can be offset by up to 10 minutes, but stays consistent across all runs.
-
-
Make sure Trigger status is enabled, then select Save.
-
In the CircleCI web app, select your org from the org cards on your user homepage.
-
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
-
Select the ellipsis
next to your project and select Project Settings.
You can also access project settings from each project overview page using the Settings button. -
Select Triggers in the sidebar.
-
Select Add Trigger.
Figure 2. Screenshot showing the schedule trigger form-
Give your trigger a descriptive name.
-
Enter an optional trigger description.
-
Select the pipeline to run.
-
Select a release frequency (weekly/monthly, which days/months/time etc.).
-
Enter a branch or tag name to determine when to trigger the pipeline.
-
Optionally, enter pipeline parameters. If you declare pipeline parameters in the form, you need to make sure they are configured in your project’s
.circleci/config.yml. See the Pipeline Values and Parameters page for more information. -
Select an actor to initiate the trigger.
-
-
Define the new schedule by filling out the form, then select Save Trigger.