diff --git a/docs/guides/modules/ROOT/nav.adoc b/docs/guides/modules/ROOT/nav.adoc index 24556eb475..17c47902f1 100644 --- a/docs/guides/modules/ROOT/nav.adoc +++ b/docs/guides/modules/ROOT/nav.adoc @@ -50,8 +50,7 @@ *** xref:orchestrate:github-trigger-event-options.adoc[GitHub trigger event options] *** xref:orchestrate:gitlab-trigger-options.adoc[GitLab trigger options] *** xref:orchestrate:custom-webhooks.adoc[Custom webhooks] -** Schedule -*** xref:orchestrate:scheduled-pipelines.adoc[Scheduled pipelines] +*** xref:orchestrate:schedule-triggers.adoc[Schedule triggers] ** How-to guides *** xref:orchestrate:orchestration-cookbook.adoc[Orchestration cookbook] *** xref:orchestrate:how-to-override-config.adoc[How to override config] @@ -59,9 +58,9 @@ *** xref:orchestrate:notify-a-slack-channel-of-a-paused-workflow.adoc[Notify a Slack channel of a paused workflow] *** xref:orchestrate:using-branch-filters.adoc[Using branch filters] *** xref:orchestrate:selecting-a-workflow-to-run-using-pipeline-parameters.adoc[Select a workflow to run using pipeline parameters] -*** xref:orchestrate:migrate-scheduled-workflows-to-scheduled-pipelines.adoc[Migrate scheduled workflows to scheduled pipelines] -*** xref:orchestrate:schedule-pipelines-with-multiple-workflows.adoc[Schedule pipelines with multiple workflows] -*** xref:orchestrate:set-a-nightly-scheduled-pipeline.adoc[Set a nightly scheduled pipeline] +*** xref:orchestrate:migrate-scheduled-workflows-to-schedule-triggers.adoc[Migrate scheduled workflows to schedule triggers] +*** xref:orchestrate:schedule-triggers-with-multiple-workflows.adoc[Schedule triggers with multiple workflows] +*** xref:orchestrate:set-a-nightly-schedule-trigger.adoc[Set a nightly schedule trigger] *** xref:orchestrate:using-dynamic-configuration.adoc[Using dynamic configuration] *** xref:orchestrate:databases.adoc[Configure databases] *** xref:orchestrate:migrate-from-deploy-to-run.adoc[Migrate from deploy to run] diff --git a/docs/guides/modules/ROOT/partials/app-navigation/steps-to-project-settings.adoc b/docs/guides/modules/ROOT/partials/app-navigation/steps-to-project-settings.adoc index 866276273c..0e41d5a88a 100644 --- a/docs/guides/modules/ROOT/partials/app-navigation/steps-to-project-settings.adoc +++ b/docs/guides/modules/ROOT/partials/app-navigation/steps-to-project-settings.adoc @@ -1,3 +1,5 @@ . In the link:https://app.circleci.com[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 image:guides:ROOT:icons/more.svg[more icon, role="no-border"] next to your project and select **Project Settings**. ++ +TIP: You can also access project settings from each project overview page using the btn:[Settings] button. diff --git a/docs/guides/modules/ROOT/partials/faq/schedule-trigger-faq-snip.adoc b/docs/guides/modules/ROOT/partials/faq/schedule-trigger-faq-snip.adoc new file mode 100644 index 0000000000..591a7577cb --- /dev/null +++ b/docs/guides/modules/ROOT/partials/faq/schedule-trigger-faq-snip.adoc @@ -0,0 +1,41 @@ +[#can-i-migrate-existing-scheduled-workflows] +=== Can I migrate existing scheduled workflows to schedule triggers? + +Yes, visit the xref:guides:orchestrate:migrate-scheduled-workflows-to-schedule-triggers.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 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//schedule" \ +--header "circle-token: " +``` + +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 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:schedule-triggers.adoc[schedule triggers] through the xref:guides:orchestrate:schedule-triggers.adoc#get-started-with-schedule-triggers[CircleCI web app], or with xref:guides:orchestrate:schedule-triggers.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-schedule-triggers.adoc[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. 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). diff --git a/docs/guides/modules/ROOT/partials/faq/scheduled-pipelines-faq-snip.adoc b/docs/guides/modules/ROOT/partials/faq/scheduled-pipelines-faq-snip.adoc deleted file mode 100644 index 0d80d13c8e..0000000000 --- a/docs/guides/modules/ROOT/partials/faq/scheduled-pipelines-faq-snip.adoc +++ /dev/null @@ -1,51 +0,0 @@ -[#can-i-migrate-existing-scheduled-workflows] -=== Can I migrate existing scheduled workflows to scheduled pipelines? - -Yes, visit the xref:guides:orchestrate:migrate-scheduled-workflows-to-scheduled-pipelines.adoc[Scheduled pipelines 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: - -```shell -curl --location --request GET "https://circleci.com/api/v2/project//schedule" \ ---header "circle-token: " -``` - -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? - -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]. - -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. - -[#scheduled-pipelines-guaranteed-to-run-time-scheduled] -=== Are scheduled pipelines 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. - -[#scheduled-pipeline-run-later] -=== Why did my scheduled pipeline 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]. - -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 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. - -[#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. diff --git a/docs/guides/modules/ROOT/partials/pipelines-and-triggers/pipeline-values.adoc b/docs/guides/modules/ROOT/partials/pipelines-and-triggers/pipeline-values.adoc index 89c7236558..24966ec964 100644 --- a/docs/guides/modules/ROOT/partials/pipelines-and-triggers/pipeline-values.adoc +++ b/docs/guides/modules/ROOT/partials/pipelines-and-triggers/pipeline-values.adoc @@ -120,7 +120,7 @@ d| [.nowrap]#GitHub App# + d| [.nowrap]#GitHub OAuth# + [.nowrap]#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. | [.circle-green]#**Yes**# | [.circle-green]#**Yes**# @@ -128,7 +128,7 @@ d| [.nowrap]#GitHub OAuth# + d| [.nowrap]#GitHub OAuth# + [.nowrap]#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. | [.circle-green]#**Yes**# | [.circle-green]#**Yes**# diff --git a/docs/guides/modules/ROOT/partials/pipelines-and-triggers/scheduled-pipeline-setup.adoc b/docs/guides/modules/ROOT/partials/pipelines-and-triggers/scheduled-pipeline-setup.adoc deleted file mode 100644 index fdc886e3a3..0000000000 --- a/docs/guides/modules/ROOT/partials/pipelines-and-triggers/scheduled-pipeline-setup.adoc +++ /dev/null @@ -1,19 +0,0 @@ -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. -+ -** 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 xref:guides:orchestrate:pipeline-variables.adoc#pipeline-parameters-in-configuration[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**. - - -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. diff --git a/docs/guides/modules/ROOT/partials/troubleshoot/pipelines-troubleshoot-snip.adoc b/docs/guides/modules/ROOT/partials/troubleshoot/pipelines-troubleshoot-snip.adoc index ab7db8587d..05525ab67f 100644 --- a/docs/guides/modules/ROOT/partials/troubleshoot/pipelines-troubleshoot-snip.adoc +++ b/docs/guides/modules/ROOT/partials/troubleshoot/pipelines-troubleshoot-snip.adoc @@ -18,8 +18,8 @@ config file .circleci/sample-filename.yml could not be located on branch sample- If your scheduled pipeline is not running, verify the following things: -- Is the actor who is set for the scheduled pipelines still part of the organization? You can find this setting is under **Attribution** in the **Triggers** section of the web app. -- Is the branch set for the schedule deleted? +- Is the actor who is set for the schedule trigger still part of the organization? You can find this setting in the *Pipeline attribution* section for your trigger in the CircleCI web app. +- Does the branch set for the trigger still exist? - Is your VCS organization using SAML protection? SAML tokens expire often, which can cause requests to fail. [#jobs-not-running-when-push-commits] diff --git a/docs/guides/modules/about-circleci/pages/introduction-to-the-circleci-web-app.adoc b/docs/guides/modules/about-circleci/pages/introduction-to-the-circleci-web-app.adoc index 992d4a15a3..1cdd22b4aa 100644 --- a/docs/guides/modules/about-circleci/pages/introduction-to-the-circleci-web-app.adoc +++ b/docs/guides/modules/about-circleci/pages/introduction-to-the-circleci-web-app.adoc @@ -153,7 +153,7 @@ The following settings are available in the project settings page. If you do not **Groups**: Provides a list of user groups that have been granted project-specific permissions. For more information, see the xref:permissions-authentication:manage-groups.adoc[Manage groups] page. -**Project Setup**: Provides a list of GitHub pipelines that have been set up for the project and their associated triggers. See xref:orchestrate:pipelines.adoc[Pipelines Overview and Setup] for more information. Pipelines integrated with VCS different from GitHub are shown in the **Pipelines** tab. This page includes the option to create a first pipeline if none exist. The setup UI for scheduled pipelines is located here for GitHub pipelines or in the *Triggers* section for Bitbucket pipelines. To set up a xref:orchestrate:scheduled-pipelines.adoc[scheduled pipeline] you will define a timetable, parameter, and attribution to automatically run a pipeline when the criteria is met. +**Project Setup**: Provides a list of pipelines that have been set up for the project and their associated triggers. See xref:orchestrate:pipelines.adoc[Pipelines Overview and Setup] for more information. This page includes the option to begin setting up pipelines if none exist. The setup UI for scheduled pipelines is located either here or in the *Triggers* section (if available for your integration). To set up a xref:orchestrate:schedule-triggers.adoc[schedule trigger] you will define a timetable, parameter, and attribution to automatically run a pipeline when the criteria is met. *Pipelines* and *Triggers*: These pages let you set up pipelines and triggers when using the GitLab, Bitbucket Cloud and Bitbucket Data Center integrations. diff --git a/docs/guides/modules/integration/pages/bitbucket-data-center-integration.adoc b/docs/guides/modules/integration/pages/bitbucket-data-center-integration.adoc index 3d5beca09c..f9b67dd5b5 100644 --- a/docs/guides/modules/integration/pages/bitbucket-data-center-integration.adoc +++ b/docs/guides/modules/integration/pages/bitbucket-data-center-integration.adoc @@ -209,10 +209,9 @@ You can only manage your connections between CircleCI and Bitbucket Data Center Passing secrets to forked pull requests is not a currently supported option for Bitbucket Data Center integrations. -[#scheduled-pipelines] -=== Scheduled pipelines +=== Scheduled triggers -The ability to xref:orchestrate:scheduled-pipelines.adoc[schedule pipelines] is not currently supported for Bitbucket Data Center projects. This feature is planned for a future release. +The ability to xref:orchestrate:schedule-triggers.adoc[schedule triggers] is not currently supported for Bitbucket Data Center projects. [#stop-building] === Stop building diff --git a/docs/guides/modules/integration/pages/github-apps-integration.adoc b/docs/guides/modules/integration/pages/github-apps-integration.adoc index 5040099d0d..b4ae0764f6 100644 --- a/docs/guides/modules/integration/pages/github-apps-integration.adoc +++ b/docs/guides/modules/integration/pages/github-apps-integration.adoc @@ -183,11 +183,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 diff --git a/docs/guides/modules/integration/pages/gitlab-integration.adoc b/docs/guides/modules/integration/pages/gitlab-integration.adoc index 6a66f798ae..bf72c2067f 100644 --- a/docs/guides/modules/integration/pages/gitlab-integration.adoc +++ b/docs/guides/modules/integration/pages/gitlab-integration.adoc @@ -287,10 +287,9 @@ Currently, there is no method to manage the connection with GitLab outside of th Passing secrets to forked pull requests is not a currently supported option for GitLab integrations. -[#scheduled-pipelines] -=== Scheduled pipelines +=== Schedule triggers -The ability to xref:orchestrate:scheduled-pipelines.adoc[schedule pipelines] is not currently supported for GitLab projects. This feature is planned for a future release. +The ability to xref:orchestrate:schedule-triggers.adoc[schedule triggers] is not currently supported for GitLab projects. [#stop-building] === Stop building diff --git a/docs/guides/modules/integration/pages/using-the-circleci-github-app-in-an-oauth-org.adoc b/docs/guides/modules/integration/pages/using-the-circleci-github-app-in-an-oauth-org.adoc index ee0950624c..cc89e5e762 100644 --- a/docs/guides/modules/integration/pages/using-the-circleci-github-app-in-an-oauth-org.adoc +++ b/docs/guides/modules/integration/pages/using-the-circleci-github-app-in-an-oauth-org.adoc @@ -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. @@ -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*# diff --git a/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc b/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc index 9c02d16237..50f19f6257 100644 --- a/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc +++ b/docs/guides/modules/integration/pages/version-control-system-integration-overview.adoc @@ -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:schedule-triggers.adoc[Schedule triggers] +| [[.circle-green]#**Yes**# | [.circle-red]#**No**# | [.circle-red]#**No**# | [.circle-green]#**Yes**# diff --git a/docs/guides/modules/orchestrate/pages/migrate-scheduled-workflows-to-scheduled-pipelines.adoc b/docs/guides/modules/orchestrate/pages/migrate-scheduled-workflows-to-schedule-triggers.adoc similarity index 54% rename from docs/guides/modules/orchestrate/pages/migrate-scheduled-workflows-to-scheduled-pipelines.adoc rename to docs/guides/modules/orchestrate/pages/migrate-scheduled-workflows-to-schedule-triggers.adoc index 1dff114cb9..46cf7a401c 100644 --- a/docs/guides/modules/orchestrate/pages/migrate-scheduled-workflows-to-scheduled-pipelines.adoc +++ b/docs/guides/modules/orchestrate/pages/migrate-scheduled-workflows-to-schedule-triggers.adoc @@ -1,16 +1,12 @@ -= 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: +:page-aliases: migrate-scheduled-workflows-to-scheduled-pipelines.adoc -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]. +NOTE: This feature is not supported for GitLab or Bitbucket Data Center pipelines. -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 @@ -19,12 +15,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: @@ -43,14 +39,16 @@ 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. +Before you can create a new schedule, you should interpret the frequency your trigger needs to run from the `cron` expression. Once you have these details, create a schedule via either the API or project settings in the CircleCIweb app. Both methods are described below. [#use-the-api] === a. Use the API +NOTE: Setting up schedule trigger via the API is not yet available for GitHub App pipelines. + 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: ```shell @@ -80,10 +78,12 @@ 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**. +include::ROOT:partial$app-navigation/steps-to-project-settings.adoc[] + +. If you are using GitHub, navigate to menu:Project Settings[Project Setup], identify the pipeline you want to schedule, and select btn:[Schedule +]. ++ +If you are using Bitbucket Cloud, navigate to menu:Project Settings[Triggers] and select **Add Trigger**. +. Define the new schedule by filling out the form, then select btn:[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. @@ -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-schedule-trigger.adoc[Set a nightly schedule trigger] diff --git a/docs/guides/modules/orchestrate/pages/orchestration-cookbook.adoc b/docs/guides/modules/orchestrate/pages/orchestration-cookbook.adoc index 4e7ec66128..dc01005193 100644 --- a/docs/guides/modules/orchestrate/pages/orchestration-cookbook.adoc +++ b/docs/guides/modules/orchestrate/pages/orchestration-cookbook.adoc @@ -203,19 +203,20 @@ 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]. + +.The nightly-run-workflow only runs when the trigger is a scheduled pipeline AND the name of that trigger is "nightly_build" [,yaml] ---- -include::ROOT:example$logic-statement-examples/when-in-workflows/or-equal-dynamic.yml[] +include::ROOT:example$logic-statement-examples/when-in-workflows/and-equal-dynamic.yml[] ---- === Notes diff --git a/docs/guides/modules/orchestrate/pages/pipeline-variables.adoc b/docs/guides/modules/orchestrate/pages/pipeline-variables.adoc index da720869dd..b61f068622 100644 --- a/docs/guides/modules/orchestrate/pages/pipeline-variables.adoc +++ b/docs/guides/modules/orchestrate/pages/pipeline-variables.adoc @@ -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 diff --git a/docs/guides/modules/orchestrate/pages/schedule-pipelines-with-multiple-workflows.adoc b/docs/guides/modules/orchestrate/pages/schedule-triggers-with-multiple-workflows.adoc similarity index 54% rename from docs/guides/modules/orchestrate/pages/schedule-pipelines-with-multiple-workflows.adoc rename to docs/guides/modules/orchestrate/pages/schedule-triggers-with-multiple-workflows.adoc index 07bb3fbe93..cd055552bb 100644 --- a/docs/guides/modules/orchestrate/pages/schedule-pipelines-with-multiple-workflows.adoc +++ b/docs/guides/modules/orchestrate/pages/schedule-triggers-with-multiple-workflows.adoc @@ -1,44 +1,37 @@ -= 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: +:page-aliases: schedule-pipelines-with-multiple-workflows.adoc -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] @@ -47,19 +40,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 @@ -83,14 +71,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: @@ -112,22 +99,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 ... @@ -136,5 +120,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-schedule-trigger.adoc[Set a nightly schedule trigger] +- xref:migrate-scheduled-workflows-to-schedule-triggers.adoc[Migrate scheduled workflows to schedule triggers] diff --git a/docs/guides/modules/orchestrate/pages/schedule-triggers.adoc b/docs/guides/modules/orchestrate/pages/schedule-triggers.adoc new file mode 100644 index 0000000000..2fed79075e --- /dev/null +++ b/docs/guides/modules/orchestrate/pages/schedule-triggers.adoc @@ -0,0 +1,174 @@ += Schedule triggers +:page-platform: Cloud +:page-description: Learn about schedule triggers for your CircleCI projects. +:experimental: +:page-aliases: scheduled-pipelines.adoc + +NOTE: 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 xref:security:contexts.adoc#project-restrictions[Restricted contexts]. +- Use xref:dynamic-config.adoc[Dynamic configuration] via setup workflows. +- Modify the schedule without having to edit `.circleci/config.yml`. +- Take advantage of xref:skip-build.adoc#auto-cancel[auto-cancelling] (only applicable to GitHub OAuth and Bitbucket Cloud pipelines. GitHub App schedule triggers are never auto-cancelled by design) +- Specify xref:pipeline-variables.adoc#pipeline-parameters-in-configuration[Pipeline parameters] associated with a schedule. +- Manage common schedules, for example, across workflows. + +Configure schedule triggers from menu:Project Settings[Project Setup] or menu:Project Setting[Triggers] in the web app, or via the API for GitHub OAuth or Bitbucket Cloud pipelines. + +NOTE: 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] +== 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 xref:set-a-nightly-schedule-trigger.adoc[Set a nightly schedule trigger] page, and more advanced examples on the xref:schedule-triggers-with-multiple-workflows.adoc[Schedule pipelines with multiple workflows] pages. + +NOTE: Schedule triggers were previously named "scheduled pipelines". + +[#get-started-with-schedule-triggers] +== 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: + +[tabs] +==== +GitHub App:: ++ +-- +include::ROOT:partial$app-navigation/steps-to-project-settings.adoc[] + +. Select **Project Setup** in the sidebar. +Locate your pipeline and select btn:[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 btn:[Populate from config] to automatically populate the parameters fields from your config file. +** Select a trigger frequency and repeat options. ++ +[options="header",cols="1,2"] +|=== +|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 +a|* 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 btn:[Save]. +-- +GitHub OAuth:: ++ +-- +include::ROOT:partial$app-navigation/steps-to-project-settings.adoc[] + +. Select **Triggers** in the sidebar. +. Select btn:[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 xref:guides:orchestrate:pipeline-variables.adoc#pipeline-parameters-in-configuration[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**. +-- +Bitbucket Cloud:: ++ +-- +include::ROOT:partial$app-navigation/steps-to-project-settings.adoc[] + +. Select **Triggers** in the sidebar. +. Select btn:[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 xref:guides:orchestrate:pipeline-variables.adoc#pipeline-parameters-in-configuration[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 xref:guides:orchestrate:schedule-pipelines-with-multiple-workflows.adoc[Schedule pipelines with multiple workflows] page for examples. + +[#use-the-api] +=== Use the API + +NOTE: 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 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: ++ +[source,shell] +---- +curl --location --request POST "https://circleci.com/api/v2/project//schedule" \ +--header "circle-token: " \ +--header "Content-Type: application/json" \ +--data-raw '{ + "name": "my schedule name", + "description": "some description", + "attribution-actor": "system", + "parameters": { + "branch": "main" + + }, + "timetable": { + "per-hour": 3, + "hours-of-day": [1,15], + "days-of-week": ["MON", "WED"] + } +}' +---- + +include::ROOT:partial$tips/find-project-slug.adoc[] + +For additional information, refer to the **Schedule** section under the link:https://circleci.com/docs/api/v2/[API v2 docs]. Also see the xref: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. + +== Migrate scheduled workflows to schedule triggers + +If you have existing scheduled workflows you need to migrate to schedule triggers, use the xref:migrate-scheduled-workflows-to-schedule-triggers.adoc[Schedule triggers migration] guide. + +[#scheduled-pipelines-faqs] +== FAQs + +include::ROOT:partial$faq/schedule-trigger-faq-snip.adoc[] + +[#next-steps] +== Next steps + +- xref:migrate-scheduled-workflows-to-schedule-triggers.adoc[Migrate scheduled workflows to schedule triggers] +- xref:schedule-triggers-with-multiple-workflows.adoc[Schedule pipelines with multiple workflows] +- xref:set-a-nightly-schedule-trigger.adoc[Set a nightly schedule trigger] diff --git a/docs/guides/modules/orchestrate/pages/scheduled-pipelines.adoc b/docs/guides/modules/orchestrate/pages/scheduled-pipelines.adoc deleted file mode 100644 index 598ca92027..0000000000 --- a/docs/guides/modules/orchestrate/pages/scheduled-pipelines.adoc +++ /dev/null @@ -1,108 +0,0 @@ -= Scheduled pipelines -:page-platform: Cloud -:page-description: Learn about scheduled pipelines for your CircleCI projects. -:experimental: - -include::ROOT:partial$notes/standalone-unsupported.adoc[This feature is not supported for GitLab, GitHub App or Bitbucket Data Center] - -Scheduled pipelines allow you to trigger pipelines periodically based on a schedule. Scheduled pipelines retain all the features of pipelines: - -- Control the actor (yourself, or the scheduling system) associated with the pipeline, which can enable the use of xref:security:contexts.adoc#project-restrictions[Restricted contexts]. -- Use xref:dynamic-config.adoc[Dynamic configuration] via setup workflows. -- Modify the schedule without having to edit `.circleci/config.yml`. -- Take advantage of xref:skip-build.adoc#auto-cancel[auto-cancelling]. -- Specify xref:pipeline-variables.adoc#pipeline-parameters-in-configuration[Pipeline parameters] associated with a schedule. -- Manage common schedules, for example, across workflows. - -Scheduled pipelines are configured through the API, or through the project settings in the CircleCI web app. - -NOTE: A scheduled pipeline can only be configured for one branch. If you need to schedule for two branches, you would need to set up two schedules. - -[#introduction] -== Introduction - -Scheduled pipelines 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 scheduled pipelines, 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 scheduled pipeline 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. - -Scheduled pipelines 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. - -You can find a basic how-to guide on the xref:set-a-nightly-scheduled-pipeline.adoc[Set a nightly scheduled pipeline] page, and more advanced examples on the xref:schedule-pipelines-with-multiple-workflows.adoc[Schedule pipelines with multiple workflows] pages. - -[#get-started-with-scheduled-pipelines] -== Get started with scheduled pipelines - -To get started with scheduled pipelines, you have the option of using the API, or using the CircleCI web app. Both methods are described below. - -[#use-project-settings] -=== Use project settings in the web app - -include::ROOT:partial$pipelines-and-triggers/scheduled-pipeline-setup.adoc[Setting up a scheduled pipeline using the CircleCI web app] - -[#use-the-api] -=== Use the API - -If your project has no scheduled workflows, and you would like to try out scheduled pipelines: - -. 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: -+ -```shell -curl --location --request POST "https://circleci.com/api/v2/project//schedule" \ ---header "circle-token: " \ ---header "Content-Type: application/json" \ ---data-raw '{ - "name": "my schedule name", - "description": "some description", - "attribution-actor": "system", - "parameters": { - "branch": "main" - - }, - "timetable": { - "per-hour": 3, - "hours-of-day": [1,15], - "days-of-week": ["MON", "WED"] - } -}' -``` - -include::ROOT:partial$tips/find-project-slug.adoc[] - -For additional information, refer to the **Schedule** section under the link:https://circleci.com/docs/api/v2/[API v2 docs]. Also see the xref: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. - -[#migrate-scheduled-workflows-to-scheduled-pipelines] -== Migrate scheduled workflows to scheduled pipelines - -If you have existing scheduled workflows you need to migrate to scheduled pipelines, use the xref:migrate-scheduled-workflows-to-scheduled-pipelines.adoc[Scheduled pipelines migration] guide. - -[#scheduled-pipelines-video-tutorial] -== Scheduled pipelines video tutorial - -The video offers a short tutorial for the following scenarios: - -- Set a schedule in the web app -- Set a schedule with the API -- Migrate from scheduled workflows to scheduled pipelines - -++++ -
- -
-++++ - -For the documentation for these scenarios, visit the following pages: -- xref:set-a-nightly-scheduled-pipeline.adoc[Set a nightly scheduled pipeline] -- xref:schedule-pipelines-with-multiple-workflows.adoc[Schedule pipelines with multiple workflows] - -[#scheduled-pipelines-faqs] -== FAQs - -include::ROOT:partial$faq/scheduled-pipelines-faq-snip.adoc[] - -[#next-steps] -== Next steps - -- xref:migrate-scheduled-workflows-to-scheduled-pipelines.adoc[Migrate scheduled workflows to scheduled pipelines] -- xref:schedule-pipelines-with-multiple-workflows.adoc[Schedule pipelines with multiple workflows] -- xref:set-a-nightly-scheduled-pipeline.adoc[Set a nightly scheduled pipeline] diff --git a/docs/guides/modules/orchestrate/pages/set-a-nightly-scheduled-pipeline.adoc b/docs/guides/modules/orchestrate/pages/set-a-nightly-schedule-trigger.adoc similarity index 75% rename from docs/guides/modules/orchestrate/pages/set-a-nightly-scheduled-pipeline.adoc rename to docs/guides/modules/orchestrate/pages/set-a-nightly-schedule-trigger.adoc index 56bb3372e7..56061bf9f9 100644 --- a/docs/guides/modules/orchestrate/pages/set-a-nightly-scheduled-pipeline.adoc +++ b/docs/guides/modules/orchestrate/pages/set-a-nightly-schedule-trigger.adoc @@ -1,9 +1,10 @@ -= Set a nightly scheduled pipeline += Set a nightly schedule trigger :page-platform: Cloud -:page-description: "Learn how to create scheduled pipelines on a specific timetable." +:page-description: "Learn how to create schedule triggers on a specific timetable." :experimental: +:page-aliases: set-a-nightly-scheduled-pipeline.adoc -NOTE: Scheduled pipelines are not currently available for GitLab, GitHub App or Bitbucket Data Center 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. A common scenario you might want to set up is to trigger a pipeline overnight. The examples below shows how to schedule a pipeline to be run at midnight every night. You can set a schedule right from the link:https://app.circleci.com/[CircleCI web app], or if you would prefer, you can set one using the link:https://circleci.com/docs/api/v2/index.html[API]. @@ -15,9 +16,9 @@ To access the form for specifying a schedule for a trigger, navigate to the foll * menu:Project Settings[Project Setup] if you are using GitHub. * menu:Project Settings[Triggers] if you are using Bitbucket Cloud. -image::guides:ROOT:pipelines-scheduled-trigger-form.png[Scheduled pipelines web app form] +image::guides:ROOT:pipelines-scheduled-trigger-form.png[Schedule triggers web app form] -The form allows you to schedule a trigger weekly or monthly. The weekly option (shown above) allows you to select specific days of the week. The monthly option allows you to select specific days of the month's calendar. With either option, you then specify which months of the year you would like the trigger to repeat. +The form allows you to schedule a trigger to run weekly or monthly. The weekly option (shown above) allows you to select specific days of the week. The monthly option allows you to select specific days of the month's calendar. With either option, you then specify which months of the year you would like the trigger to repeat. For a nightly schedule, you will need to take into account the form uses UTC (coordinated universal time). For example, if you would like your pipeline to trigger at midnight (0:00) in eastern standard time (EST), you would need to find the difference from UTC. In this scenario, 0:00 EST is 5:00 UTC. @@ -73,5 +74,5 @@ You can view the build scheduling of this link:https://github.com/zmarkan/Androi [#next-steps] == Next steps -- xref:migrate-scheduled-workflows-to-scheduled-pipelines.adoc[Migrate scheduled workflows to scheduled pipelines] +- xref:migrate-scheduled-workflows-to-schedule-triggers.adoc[Migrate scheduled workflows to schedule triggers] - xref:schedule-pipelines-with-multiple-workflows.adoc[Schedule pipelines with multiple workflows] diff --git a/docs/guides/modules/orchestrate/pages/set-up-triggers.adoc b/docs/guides/modules/orchestrate/pages/set-up-triggers.adoc index 30cea3242e..fc2547e3b9 100644 --- a/docs/guides/modules/orchestrate/pages/set-up-triggers.adoc +++ b/docs/guides/modules/orchestrate/pages/set-up-triggers.adoc @@ -11,7 +11,7 @@ A trigger kicks off a pipeline to run the workflows defined in your connected co == Add a trigger -NOTE: Bitbucket Cloud triggers are created automatically when setting up a project and they cannot be edited. The only additional trigger types available for Bitbucket Cloud pipelines are xref:scheduled-pipelines.adoc[scheduled triggers]. +NOTE: Bitbucket Cloud triggers are created automatically when setting up a project and they cannot be edited. The only additional trigger types available for Bitbucket Cloud pipelines are xref:schedule-triggers.adoc[schedule triggers]. NOTE: **Using CircleCI server?** The Pipeline and Trigger pages under Project Settings and pipeline and trigger add/edit functionality is **not** available. CircleCI server pipelines are set up when a project is set up and cannot be edited. CircleCI server requires CircleCI configuration files to be stored in the same repository as your code at `.circleci/config.yml`. @@ -105,9 +105,7 @@ For steps to add a trigger for a pipeline using Bitbucket Data Center, see the x Scheduled:: + -- -include::ROOT:partial$notes/standalone-unsupported.adoc[Unsupported for GitHub App, GitLab, Bitbucket Data Center orgs] - -include::ROOT:partial$pipelines-and-triggers/scheduled-pipeline-setup.adoc[Setting up a scheduled pipeline using the CircleCI web app] +For steps to add a schedule trigger, see the xref:schedule-triggers.adoc[Schedule Triggers] page. -- ==== diff --git a/docs/guides/modules/orchestrate/pages/triggers-overview.adoc b/docs/guides/modules/orchestrate/pages/triggers-overview.adoc index e6e5d93573..6bb4556d93 100644 --- a/docs/guides/modules/orchestrate/pages/triggers-overview.adoc +++ b/docs/guides/modules/orchestrate/pages/triggers-overview.adoc @@ -163,9 +163,9 @@ image::guides:ROOT:vscode-ext-config-test-run-crop.png[Screenshot showing the ru [#schedule-a-pipeline] == Schedule a pipeline -include::ROOT:partial$notes/standalone-unsupported.adoc[This feature is not supported for GitLab, GitHub App or Bitbucket Data Center] +NOTE: Schedule triggers are not available for GitLab and Bitbucket Data Center pipelines. -For non GitLab/GitHub App/Bitbucket Data Center projects, scheduled pipelines allow you to trigger pipelines periodically based on a schedule. To get this set up for a project you can either use the CircleCI web app or use the link:https://circleci.com/docs/api/v2/index.html#operation/createSchedule[API v2]. For full details of both methods see the <> docs. +Schedule triggers allow you to trigger pipelines periodically based on a schedule. To get this set up for a project you can either use the CircleCI web app or use the link:https://circleci.com/docs/api/v2/index.html#operation/createSchedule[API v2]. For full details of both methods see the xref:schedule-triggers.adoc[Schedule Triggers] docs. [#next-steps] == Next steps diff --git a/docs/guides/modules/orchestrate/pages/workflows.adoc b/docs/guides/modules/orchestrate/pages/workflows.adoc index a0388e845b..353c445180 100644 --- a/docs/guides/modules/orchestrate/pages/workflows.adoc +++ b/docs/guides/modules/orchestrate/pages/workflows.adoc @@ -388,7 +388,7 @@ NOTE: Scheduled workflows are not available for projects integrated through the NOTE: *The deprecation of the scheduled workflows feature is postponed*. Since the deprecation announcement went live, your feedback and feature requests have been monitored and it is clear there is more work for us to do 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]. -CAUTION: The scheduled workflows feature does not support xref:dynamic-config.adoc[Dynamic configuration]. If you use dynamic configuration you will need to use xref:scheduled-pipelines.adoc[Scheduled pipelines] for scheduling. More information can be found in this link:https://support.circleci.com/hc/en-us/articles/360060833331-Support-for-Scheduled-Workflows-in-Dynamic-Configurations-Setup-Workflows[support article]. +CAUTION: The scheduled workflows feature does not support xref:dynamic-config.adoc[dynamic configuration]. If you use dynamic configuration you will need to use xref:schedule-triggers.adoc[schedule triggers] for scheduling. More information can be found in this link:https://support.circleci.com/hc/en-us/articles/360060833331-Support-for-Scheduled-Workflows-in-Dynamic-Configurations-Setup-Workflows[support article]. By default, a workflow runs on every push, or based on the event rules you have set up for your trigger (menu:Project settings[Triggers] or menu:Project settings[Project Setup]). To trigger a workflow on a schedule, add the `triggers` key to the workflow and specify a `schedule`. Scheduled workflows use the `cron` syntax to represent Coordinated Universal Time (UTC). diff --git a/docs/reference/modules/ROOT/pages/configuration-reference.adoc b/docs/reference/modules/ROOT/pages/configuration-reference.adoc index f1713e5580..2b44d21a26 100644 --- a/docs/reference/modules/ROOT/pages/configuration-reference.adoc +++ b/docs/reference/modules/ROOT/pages/configuration-reference.adoc @@ -2378,7 +2378,7 @@ workflows: NOTE: Scheduled workflows are not available for projects integrated through the GitHub App, GitLab or Bitbucket Data Center. -CAUTION: The scheduled workflows feature is set to be deprecated. Using *scheduled pipelines* rather than scheduled workflows offers several benefits. Visit the scheduled pipelines xref:guides:orchestrate:migrate-scheduled-workflows-to-scheduled-pipelines.adoc#[migration guide] to find out how to migrate existing scheduled workflows to scheduled pipelines. If you would like to set up scheduled pipelines from scratch, visit the xref:guides:orchestrate:scheduled-pipelines.adoc#[Scheduled pipelines] page. +NOTE: Using *schedule triggers* rather than scheduled workflows offers several benefits. Visit the schedule triggers xref:guides:orchestrate:migrate-scheduled-workflows-to-schedule-triggers.adoc[migration guide] to find out how to migrate existing scheduled workflows to schedule triggers. If you would like to set up schedule triggers from scratch, visit the xref:guides:orchestrate:schedule-triggers.adoc[Schedule triggers] page. A workflow may have a `schedule` indicating it runs at a certain time, for example a nightly build that runs every day at 12am UTC: diff --git a/docs/reference/modules/ROOT/pages/faq.adoc b/docs/reference/modules/ROOT/pages/faq.adoc index 1dad925f71..54190528b8 100644 --- a/docs/reference/modules/ROOT/pages/faq.adoc +++ b/docs/reference/modules/ROOT/pages/faq.adoc @@ -15,7 +15,7 @@ This page answers frequently asked questions about the following CircleCI topics | <> | <> -| <> +| <> | <> | <> @@ -70,10 +70,9 @@ include::guides:ROOT:partial$faq/self-hosted-runner-faq-snip.adoc[] include::guides:ROOT:partial$faq/pipelines-faq-snip.adoc[] -[#scheduled-pipelines] -== Scheduled pipelines +== Schedule triggers -include::guides:ROOT:partial$faq/scheduled-pipelines-faq-snip.adoc[] +include::guides:ROOT:partial$faq/schedule-trigger-faq-snip.adoc[] [#workflows] == Workflows