Set a nightly schedule trigger
5 hours ago
| 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 CircleCI web app, or if you would prefer, you can set one using the API.
Set a schedule in the web app
To access the form for specifying a schedule for a trigger, follow the steps below for your pipeline type.
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.
-
GitHub App
-
GitHub OAuth
-
Bitbucket Cloud
-
In the CircleCI web app, select your org from the org cards on your user homepage.
-
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
-
Select the ellipsis
next to your project and select Project Settings.You can also access project settings from each project overview page using the Settings button. -
Select Project Setup in the sidebar. Locate your pipeline and select Schedule +.
-
Complete the schedule trigger form:
-
Give your trigger a descriptive name.
-
Select a branch to tell CircleCI which code to checkout and where to find your config file.
-
Under Pipeline attribution, select the actor to initiate the trigger. You can choose yourself, one of your team, or the scheduling system if you want the trigger to be independent from individual users. If your project requires the use of environment variables stored in restricted contexts, you should assign someone who has access to those contexts.
-
Enter any pipeline parameters that you would like to set when triggering the pipeline. If you enter any new pipeline parameters make sure to also add them to your config file. You can select Populate from config to automatically populate the parameters fields from your config file.
-
Select a trigger frequency and repeat options.
Field Options Repeats
Weekly, Monthly
Days of the week
Radio buttons for each or select all
Months
Radio buttons for each or select all
Start time (UTC)
Radio buttons for each hour or select all
Times per hour
-
1 (once per hour)
-
2 (every 30 minutes)
-
3 (every 20 minutes)
-
4 (every 15 minutes)
-
5 (every 12 minutes)
-
6 (every 10 minutes)
-
7 (every 8.6 minutes)
-
8 (every 7.5 minutes)
-
9 (every 6.7 minutes)
-
10 (every 6 minutes)
-
11 (every 5.5 minutes)
-
12 (every 5 minutes)
-
-
-
Enable the trigger and select Save.
-
In the CircleCI web app, select your org from the org cards on your user homepage.
-
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
-
Select the ellipsis
next to your project and select Project Settings.You can also access project settings from each project overview page using the Settings button. -
Select Triggers in the sidebar.
-
Select Add Trigger.
-
Give your trigger a descriptive name.
-
Enter an optional trigger description.
-
Select the pipeline to run.
-
Select a release frequencies (weekly/monthly, which days/months/time etc.).
-
Enter a branch or tag name to determine when to trigger the pipeline.
-
Optionally, enter pipeline parameters. If you declare pipeline parameters in the form, you need to make sure they are configured in your project’s
.circleci/config.yml. See the Pipeline values and parameters page for more information. -
Select an actor to initiate the trigger.
-
-
Define the new schedule by filling out the form, then select Save Trigger.
-
In the CircleCI web app, select your org from the org cards on your user homepage.
-
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
-
Select the ellipsis
next to your project and select Project Settings.You can also access project settings from each project overview page using the Settings button. -
Select Triggers in the sidebar.
-
Select Add Trigger.
-
Give your trigger a descriptive name.
-
Enter an optional trigger description.
-
Select the pipeline to run.
-
Select a release frequencies (weekly/monthly, which days/months/time etc.).
-
Enter a branch or tag name to determine when to trigger the pipeline.
-
Optionally, enter pipeline parameters. If you declare pipeline parameters in the form, you need to make sure they are configured in your project’s
.circleci/config.yml. See the Pipeline values and parameters page for more information. -
Select an actor to initiate the trigger.
-
-
Define the new schedule by filling out the form, then select Save Trigger.
Set a schedule with the API
| Setting up a schedule trigger with the API is not currently available for GitHub App pipelines. |
To set a schedule with the API, you will need a project building on CircleCI, environment variables set, and your CircleCI personal API token. Much like in the web app form, you are required to enter a name, parameters (like the branch or tag) as well as a timetable.
const axios = require('axios').default;
require('dotenv').config()
// environment variables
const API_BASE_URL = "https://circleci.com/api/v2/project"
const vcs = process.env.VCS_TYPE
const org = process.env.ORG_NAME
const project = process.env.PROJECT_ID
const token = process.env.CIRCLE_TOKEN
const postScheduleEndpoint = `${API_BASE_URL}/${vcs}/${org}/${project}/schedule`
async function setupNightlySchedule(){
let res = await axios.post(postScheduleEndpoint,
{
name: "Nightly build",
description: "Builds and pushes a new build every night.",
"attribution-actor": "system",
"parameters": {
"branch": "main",
"run-schedule": true
},
"timetable": {
// once per hour
"per-hour": 1,
// at 01:00 UTC
"hours-of-day": [1],
// on the following days of the week
"days-of-week": ["TUE", "WED", "THU", "FRI", "SAT"]
}
},
{
headers: { 'Circle-Token': token }
}
)
console.log(res.data)
}
setupNightlySchedule()You can view the build scheduling of this sample project on GitHub.