Skip to content
Draft
Show file tree
Hide file tree
Changes from 15 commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
[#can-i-migrate-existing-scheduled-workflows]
=== Can I migrate existing scheduled workflows to scheduled pipelines?
=== Can I migrate existing scheduled workflows to schedule triggers?

Yes, visit the xref:guides:orchestrate:migrate-scheduled-workflows-to-scheduled-pipelines.adoc[Scheduled pipelines migration] guide for more information.
Yes, visit the xref:guides:orchestrate:migrate-scheduled-workflows-to-scheduled-pipelines.adoc[Schedule triggers migration] guide for more information.

[#find-schedules-that-i-have-created]
=== How do I find the schedules that I have created?

As scheduled pipelines 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:
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:

```shell
curl --location --request GET "https://circleci.com/api/v2/project/<project-slug>/schedule" \
Expand All @@ -16,36 +16,29 @@ curl --location --request GET "https://circleci.com/api/v2/project/<project-slug
Refer to the xref:guides:toolkit:api-developers-guide.adoc#getting-started-with-the-api[Getting started with the API] section of the API Developer's Guide for more guidance on making requests.

[#what-time-zone-is-used-for-scheduled-pipelines]
=== What time zone is used for scheduled pipelines?
=== What time zone is used for schedule triggers?

Coordinated Universal Time (UTC) is the time zone in which schedules are interpreted.

[#pipelines-scheduled-to-run-specific-time-of-day]
=== Can pipelines be scheduled to run at a specific time of day?

Yes, you can set up xref:guides:orchestrate:scheduled-pipelines.adoc[Scheduled pipelines] through the xref:guides:orchestrate:scheduled-pipelines.adoc#use-project-settings[CircleCI web app], or with xref:guides:orchestrate:scheduled-pipelines.adoc#use-the-api[CircleCI API v2].
Yes, you can set up xref:guides:orchestrate:scheduled-pipelines.adoc[Schedule triggers] through the xref:guides:orchestrate:scheduled-pipelines.adoc#use-project-settings[CircleCI web app], or with xref:guides:orchestrate:scheduled-pipelines.adoc#use-the-api[CircleCI API v2].

If you are currently using xref:guides:orchestrate:workflows.adoc#scheduling-a-workflow[Scheduled workflows], see the xref:guides:orchestrate:migrate-scheduled-workflows-to-scheduled-pipelines.adoc[Migration guide] to update your scheduled workflows to scheduled pipelines.
If you are currently using xref:guides:orchestrate:workflows.adoc#scheduling-a-workflow[Scheduled workflows], see the xref:guides:orchestrate:migrate-scheduled-workflows-to-scheduled-pipelines.adoc[Migration guide] to update your scheduled workflows to schedule triggers.

[#scheduled-pipelines-guaranteed-to-run-time-scheduled]
=== Are scheduled pipelines guaranteed to run at precisely the time scheduled?
=== Are schedule triggers guaranteed to run at precisely the time scheduled?

CircleCI provides no guarantees about precision. A schedule will be run as if the commit was pushed at the configured time.
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.

[#scheduled-pipeline-run-later]
=== Why did my scheduled pipeline run later than expected?
=== Why did my schedule trigger run later than expected?

The scheduling expression with scheduled pipelines is different to link:https://en.wikipedia.org/wiki/Cron#CRON_expression[the Cron expression].
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.

For example, when you express the schedule as 1 per-hour for 08:00 UTC, the scheduled pipeline will run once within the 08:00 to 09:00 UTC window. Note that it does not mean that it will 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.

However, subsequent runs of the scheduled pipeline will always be run on the same time as its previous run. In other words, if a previous scheduled pipeline 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?

[#do-you-support-regex]
=== Do you support regex?

Not currently. Scheduled pipelines require highly deterministic inputs such as a commit SHA, branch, or tag (fully qualified, no regex) included in the webhook, API call, or schedule.

=== Why can I not see my pipeline in the scheduled pipeline to run menu?

If you do not see your pipeline in the "Pipeline to run" dropdown menu, it may be that you are trying to access an unsupported pipeline type. Only OAuth pipelines are supported for scheduling, so GitHub App, GitLab, and Bitbucket Data Center pipelines will not appear in the list. You can see the pipeline type by looking at your pipeline list (menu:Project Settings[Pipelines] or menu:Project Settings[Project Setup]) and inspecting the pipeline labels.
Only GitHub OAuth, GitHub App and Bitbucket Cloud pipelines support schedule triggers. If you try to set up a schedule trigger through the menu:Project Settings[Triggers] menu and do not see your pipeline in the "Pipeline to run" dropdown menu, it may be that you are trying to access an unsupported pipeline type (Gitlab or Bitbucket Data Center).
Original file line number Diff line number Diff line change
Expand Up @@ -80,14 +80,14 @@
| `pipeline.schedule.name`
| GitHub OAuth, Bitbucket Cloud
| String
| The name of the schedule if it is a scheduled pipeline. Value will be empty string if the pipeline is triggered by other sources.
| The name of the schedule trigger if the pipeline was triggered via schedule. The value will be empty string if the pipeline is triggered by other sources.
| image:guides:ROOT:icons/check.svg[check icon, role="no-border"]
| image:guides:ROOT:icons/check.svg[check icon, role="no-border"]

| `pipeline.schedule.id`
| GitHub OAuth, Bitbucket Cloud
| String
| The unique id of the schedule if it is a scheduled pipeline. Value will be empty string if the pipeline is triggered by other sources.
| The unique id of the schedule if the pipeline was triggered via schedule trigger. Value will be empty string if the pipeline is triggered by other sources.
| image:guides:ROOT:icons/check.svg[check icon, role="no-border"]
| image:guides:ROOT:icons/check.svg[check icon, role="no-border"]

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ include::ROOT:partial$app-navigation/steps-to-project-settings.adoc[]
. Select **Triggers** in the sidebar.
. Select btn:[Add Trigger].
+
NOTE: The "Pipeline to run" menu only shows the OAuth pipelines, you cannot schedule GitHub App, GitLab or Bitbucket Data Center pipelines.
NOTE: Gitlab and Bitbucket Data Center pipelines do not yet support schedule triggers.
+
** Give your trigger a descriptive name.
** Enter an optional trigger description.
Expand All @@ -13,7 +13,4 @@ NOTE: The "Pipeline to run" menu only shows the OAuth pipelines, you cannot sche
** Select an actor to initiate the trigger.
. Define the new schedule by filling out the form, then select **Save Trigger**.


The form also provides the option of adding xref:guides:orchestrate:pipeline-variables.adoc[pipeline parameters], which are typed pipeline variables that you declare at the top level of a configuration.

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 xref:guides:orchestrate:schedule-pipelines-with-multiple-workflows.adoc[Schedule pipelines with multiple workflows] page for examples.
Original file line number Diff line number Diff line change
Expand Up @@ -184,11 +184,6 @@ The in-app config editor is currently **only** available for GitHub App accounts

Viewing menu:User settings[Account integrations] does not currently show a GitHub App integration. This page only shows GitHub OAuth app integrations.

[#scheduled-pipelines]
=== Scheduled pipelines

The ability to xref:orchestrate:scheduled-pipelines.adoc[schedule pipelines] is not yet supported for pipelines that use the GitHub App integration. This feature is planned for release by September 2025. As an alternative, use a xref:orchestrate:custom-webhooks.adoc[custom webhook] or the xref:orchestrate:triggers-overview.adoc#run-a-pipeline-using-the-api[V2 API to trigger a pipeline], which you can `curl` with a 3rd party scheduling tool.

[#build-forked-pull-requests]
=== Build forked pull requests

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,8 @@ _Used to trigger pipelines from any external system that can send HTTP requests_
* Event name and event source are user-defined.

*Schedules* +
Not supported yet, but coming soon. As an alternative, use custom webhooks with third-party scheduling tools.
_Used to trigger pipelines on a schedule (nightly builds for example)_
* Zero, one or many can be created per pipeline.

*API / Manual* +
GitHub App pipelines can be triggered via API and manually through the CircleCI web app.
Expand All @@ -138,7 +139,7 @@ The following table summarizes the trigger availability by pipeline type.

|GitHub App image:guides:ROOT:icons/github-app.svg[GitHub App pipeline badge, role="no-border"]
^|[.circle-red]#*No*#
^|[.circle-red]#*No*#
^|Zero, one, many
^|Zero, one, many
^|Zero, one, many
^|[.circle-green]#*Yes*#
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -116,8 +116,8 @@ include::ROOT:partial$tips/check-github-type.adoc[Check your GitHub integration
| [.circle-red]#**No**#
| [.circle-red]#**No**#

| xref:orchestrate:scheduled-pipelines.adoc[Scheduled pipelines]
| [.circle-red]#**No** ^1^#
| xref:orchestrate:scheduled-pipelines.adoc[Schedule triggers]
| [[.circle-green]#**Yes**#
| [.circle-red]#**No**#
| [.circle-red]#**No**#
| [.circle-green]#**Yes**#
Expand Down
Original file line number Diff line number Diff line change
@@ -1,16 +1,14 @@
= Migrate scheduled workflows to scheduled pipelines
= Migrate scheduled workflows to schedule triggers
:page-platform: Cloud
:page-description: Migrate scheduled workflows to scheduled pipelines
:page-description: Migrate scheduled workflows to schedule triggers
:experimental:

NOTE: **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 link:https://discuss.circleci.com/[CircleCI Discuss].

include::ROOT:partial$notes/standalone-unsupported.adoc[This feature is not supported for GitLab, GitHub App or Bitbucket Data Center]

[#introduction]
== Introduction

Migrating to scheduled pipelines from scheduled workflows will eliminate the following limitations of scheduled workflows:
Schedule workflows have some limitations that make them less convenient than schedule triggers:

- 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
Expand All @@ -19,12 +17,12 @@ Migrating to scheduled pipelines from scheduled workflows will eliminate the fol
- 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.
In addition, schedule triggers 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 schedule triggers, you can set up a single schedule to run all three workflows at midnight every day.

[#find-your-scheduled-trigger]
== 1. Find your scheduled trigger
[#find-your-scheduled-workflow]
== 1. Find your schedule workflow

To migrate from scheduled workflows to scheduled pipelines, you will first need to find the scheduled trigger in your project's `.circleci/config.yml`.
To migrate from scheduled workflows to schedule triggers, you will first need to find the schedule workflow in your project's `.circleci/config.yml`.

For example, it might look like:

Expand All @@ -43,12 +41,14 @@ daily-run-workflow:
- build
```

[#create-the-new-schedule]
== 2. Create the new schedule
[#create-the-new-schedule-trigger]
== 2. Create the new schedule trigger

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]

// TODO: not available yet for github app schedules
=== a. Use the API

Have your CircleCI token ready, or create a new token by following the steps on the xref:toolkit:managing-api-tokens.adoc[Managing API tokens] page. Create a new schedule link:https://circleci.com/docs/api/v2/index.html#operation/createSchedule[using the API]. For example:
Expand Down Expand Up @@ -80,10 +80,10 @@ For additional information, refer to the **Schedule** section under the link:htt
[#use-project-settings]
=== 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**.
. 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.
If you are using GitHub, navigate to menu:Project Settings[Project Setup], identify the pipeline you want to schedule, and select "Schedule +".
If yuo are using Bitbucket Cloud, navigate to menu:Project Settings[Triggers] and select **Add Trigger**.
Define the new schedule by filling out the form, then save.

The form also provides the option of adding xref:pipeline-variables.adoc[pipeline parameters], which are typed pipeline variables declared at the top level of a configuration.

Expand All @@ -102,4 +102,4 @@ daily-run-workflow:
[#next-steps]
== Next steps
- xref:schedule-pipelines-with-multiple-workflows.adoc[Schedule pipelines with multiple workflows]
- xref:set-a-nightly-scheduled-pipeline.adoc[Set a nightly scheduled pipeline]
- xref:set-a-nightly-scheduled-pipeline.adoc[Set a nightly schedule trigger]
Original file line number Diff line number Diff line change
Expand Up @@ -208,15 +208,15 @@ include::ROOT:partial$using-expressions/env-vars-in-conditional-caveat.adoc[]

include::ROOT:partial$tips/trigger-pipeline-with-parameters.adoc[]

== Run a workflow only for scheduled pipelines with a specific name
== Run a workflow only on schedule triggers that have a specific name

=== Goal

In some cases, you may want to configure a workflow that will only run when a scheduled pipeline has a specific name.
In some cases, you may want to configure a workflow that will only run when a scheduled trigger has a specific name.

=== Steps

* Update your CircleCI config to use the `pipeline.scheduled_source` and `pipeline.schedule.name` xref:pipeline-variables.adoc#pipeline-values[pipeline values].
* Update your CircleCI config to use the `pipeline.schedule.name` xref:pipeline-variables.adoc#pipeline-values[pipeline values].
+
[,yaml]
----
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ In addition to using the API, you can also trigger a pipeline with parameters fr
. Use the *Add Parameters* dropdown to specify the type, name, and value of your desired parameters.
. Select *Trigger Pipeline*.

Parameters can also be passed when setting up a scheduled pipeline in the web app. The parameters are part of the trigger form in menu:Project Settings[Triggers] or menu:Project Settings[Project Setup]. Any parameter set up as a part of a scheduled pipeline will also need to be declared in the configuration file, otherwise the pipeline will fail with the error `Unexpected argument(s)`.
Parameters can also be passed when setting up a schedule trigger in the web app. The parameters are part of the trigger form in menu:Project Settings[Triggers] or menu:Project Settings[Project Setup]. Any parameter set up as a part of a schedule trigger will also need to be declared in the configuration file, otherwise the pipeline will fail with the error `Unexpected argument(s)`.

[#configuration-processing-stages]
== Configuration processing stages
Expand Down
Loading