Skip to content
Draft
Show file tree
Hide file tree
Changes from 5 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 @@ -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
@@ -1,44 +1,36 @@
= Schedule pipelines with multiple workflows
= Schedule triggers with multiple workflows
:page-platform: Cloud
:page-description: "Learn how to set conditionals for scheduled pipelines in multiple workflows."
:page-description: "Learn how to set conditionals for schedule triggers in multiple workflows."
:experimental:

NOTE: Scheduled pipelines are not currently available for GitLab, Bitbucket Data Center or GitHub App projects. To find out if you authorized your GitHub account through the GitHub OAuth app, or the GitHub App, see the xref:integration:github-apps-integration.adoc[GitHub App integration page].
NOTE: Schedule triggers are not currently available for GitLab and Bitbucket Data Center projects.

Scheduled pipelines are simply triggered pipelines, and by default, for each trigger, every workflow that has been configured will run. You can filter workflows in your `.circleci/config.yml` file with conditionals. The conditionals you set will control which workflows will run when a scheduled pipeline is triggered. These conditions can be set with built-in pipeline values, or through custom pipeline parameters. The examples below demonstrate various ways to set conditionals in your `.circleci/config.yml` file.
By default, when a pipeline is triggered via schedule trigger each of its workflows will run . You can filter workflows in your `.circleci/config.yml` file with conditionals. The conditionals you set will control which workflows will run when a pipeline is triggered via schedule. These conditions can be set with built-in pipeline values, or through custom pipeline parameters. The examples below demonstrate various ways to set conditionals in your `.circleci/config.yml` file.

[#schedule-using-built-in-pipeline-values]
## Schedule using built-in pipeline values

One way to implement workflows filtering is by using pipeline values. The example below uses the built-in pipeline values `pipeline.trigger_source` and `pipeline.schedule.name`. The examples use `daily_build` and `nightly_build` as the `pipeline.schedule.name`, however, the value of `pipeline.schedule.name` can be whatever you would like when using scheduled pipelines.
One way to implement workflows filtering is by using pipeline values. The example below uses the built-in pipeline values `pipeline.trigger_source` and `pipeline.schedule.name`. The examples use `daily_build` and `nightly_build` as the `pipeline.schedule.name`, however, the value of `pipeline.schedule.name` can be whatever you would like when using schedule triggers.

```yaml
version: 2.1
...
daily-run-workflow:
# run workflow only when the daily_build pipeline is triggered
when:
and:
- equal: [ scheduled_pipeline, << pipeline.trigger_source >> ]
- equal: [ daily_build, << pipeline.schedule.name >> ]
when: pipeline.trigger_source == "scheduled_pipeline" and pipeline.schedule.name == "daily_build"
jobs:
- test
- build

nightly-run-workflow:
# run workflow only when the nightly_build pipeline is triggered
when:
and:
- equal: [ scheduled_pipeline, << pipeline.trigger_source >> ]
- equal: [ nightly_build, << pipeline.schedule.name >> ]
when: pipeline.trigger_source == 'scheduled_pipeline' and pipeline.schedule.name == 'nightly_build'
jobs:
- build
- deploy
...
```

Note that in the above example, the second `equal` under `when` is not strictly necessary. The `pipeline.schedule.name` is an available pipeline value when the pipeline is triggered by a schedule.

You may also add filtering for workflows that should *not* run when a schedule is triggered:

[,yaml]
Expand All @@ -47,19 +39,14 @@ version: 2.1
...
daily-run-workflow:
# run workflow only when the daily_build pipeline is triggered
when:
and:
- equal: [ scheduled_pipeline, << pipeline.trigger_source >> ]
- equal: [ daily_build, << pipeline.schedule.name >> ]
when: pipeline.trigger_source == "scheduled_pipeline" and pipeline.schedule.name == "daily_build"
jobs:
- test
- build

nightly-run-workflow:
# do NOT run workflow if a scheduled pipeline is triggered
when:
not:
equal: [ scheduled_pipeline, << pipeline.trigger_source >> ]
# do NOT run workflow if a schedule trigger is triggered
when: pipeline.trigger_source != "scheduled_pipeline"
jobs:
- build
- deploy
Expand All @@ -83,14 +70,13 @@ parameters:
default: false

workflows:
# do not run the scheduled pipeline if build-test-deploy
# do not run the schedule trigger if build-test-deploy
build-test-deploy:
when:
not: << pipeline.parameters.run-schedule >>
when: pipeline.parameters.run-schedule == false
jobs:
- test
- build
# run the scheduled pipeline if nightly-snapshot
# run the schedule trigger if nightly-snapshot
nightly-snapshot:
when: << pipeline.parameters.run-schedule >>
jobs:
Expand All @@ -112,22 +98,19 @@ version: 2.1
workflows:
# run workflow only when the daily_build pipeline is triggered
daily-run-workflow:
when:
equal: [ daily_build, << pipeline.schedule.name >> ]
when: pipeline.schedule.name == 'daily_build'
jobs:
- job-one

nightly-run-workflow:
# run workflow only when the daily_build pipeline is triggered
when:
equal: [ daily_build, << pipeline.schedule.name >> ]
# run workflow only when the nightly_build pipeline is triggered
when: pipeline.schedule.name == 'nightly_build'
jobs:
- job-two

weekly-run-workflow:
# run workflow only when the weekly_build pipeline is triggered
when:
equal: [ weekly_build, << pipeline.schedule.name >> ]
when: pipeline.schedule.name == 'weekly_build'
jobs:
- job-three
...
Expand All @@ -136,5 +119,5 @@ workflows:
[#next-steps]
== Next steps

- xref:set-a-nightly-scheduled-pipeline.adoc[Set a nightly scheduled pipeline]
- xref:migrate-scheduled-workflows-to-scheduled-pipelines.adoc[Migrate scheduled workflows to scheduled pipelines]
- xref:set-a-nightly-scheduled-pipeline.adoc[Set a nightly schedule trigger]
- xref:migrate-scheduled-workflows-to-scheduled-pipelines.adoc[Migrate scheduled workflows to schedule triggers]
Loading