Migrate scheduled workflows to schedule triggers

5 hours ago · 5 min read

Cloud

This feature is not supported for GitLab or Bitbucket Data Center pipelines.

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
Cannot use scheduled workflows together with dynamic configuration without complex workarounds
Cannot change or cancel scheduled workflows on a branch without triggering a pipeline
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, 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.

1. Find your schedule workflow

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:

daily-run-workflow:
  triggers:
    - schedule:
        # Every day, 0421Z.
        cron: "21 4 * * *"
        filters:
          branches:
            only:
              - main
  jobs:
    - test
    - build

2. Create the new schedule trigger

Before you 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.

a. Use the API

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 Managing API tokens page. Create a new schedule using the API. For example:

curl --location --request POST "https://circleci.com/api/v2/project/<project-slug>/schedule" \
--header "Circle-Token: <PERSONAL_API_KEY>" \
--header "Content-Type: application/json" \
--data-raw '{
    "name": "my schedule name",
    "description": "some description",
    "attribution-actor": "system",
    "parameters": {
      "branch": "main"
      <additional pipeline parameters can be added here>
    },
    "timetable": {
        "per-hour": 3,
        "hours-of-day": [1,15],
        "days-of-week": ["MON", "WED"]
    }
}'

To find your project slug, follow these steps:

Head to the CircleCI web app and select your org from the cards on your user homepage.
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
Select the ellipsis menu next to your project and select Project Settings. The project slug is listed on the project settings homepage.
- GitHub App: Project slug starts with circleci followed by UUIDs. For example, circleci/34R3kN5RtfEE7v4sa4nWAU/4nYdoKGkb6RXn7JGt8SQtg).
- GitHub OAuth app: Project slug is human readable. For example, github/circleci/circleci-demo-workflows.

For additional information, refer to the Schedule section under the API v2 docs. Also see the Getting started with the API section of the API Developer’s Guide for more guidance on making requests.

b. Use project settings in the web app

In the CircleCI web app, select your org from the org cards on your user homepage.
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
Select the ellipsis next to your project and select Project Settings.

You can also access project settings from each project overview page using the Settings button.
If you are using GitHub, navigate to Project Settings Project Setup, identify the pipeline you want to schedule, and select Schedule +.

If you are using Bitbucket Cloud, navigate to Project Settings Triggers and select Add Trigger.
Define the new schedule by filling out the form, then select Save.

The form also provides the option of adding pipeline parameters, which are typed pipeline variables declared at the top level of a configuration.

3. Remove triggers section

In the configuration file, remove the triggers section, so that it resembles a standard workflow.

daily-run-workflow:
  jobs:
    - test
    - build

[path]

[title]