Start Building for Free

Set a nightly scheduled pipeline

5 months ago1 min read
On This Page

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

In your desired project, navigate to Project Settings > Triggers to see the form for specifying a schedule for a trigger.

Scheduled pipelines 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.

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.

Set a schedule with the API

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;

// environment variables
const API_BASE_URL = ""
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,
      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 }


You can view the build scheduling of this sample project on GitHub.

Suggest an edit to this page

Make a contribution
Learn how to contribute