Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Set a nightly scheduled pipeline

1 week ago1 min read
Cloud
Server v4.x
Server v3.x
Server v2.x
On This Page

Introduction

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. Unlike deprecated scheduled workflows, you do not set up basic scheduled pipelines in your configuration file. 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;
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.CIRCLECI_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.


Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.