Documentation structure for LLMs (llms.txt)

Set a nightly schedule trigger

Cloud

Version control: GitHub, GitHub Enterprise Server, Bitbucket Cloud, Cursor Origin

Schedule triggers are not currently available for GitLab projects.

A common scenario you might want to set up is to trigger a pipeline run overnight. The examples below show how to schedule a pipeline run to be triggered at midnight every night. You can set a schedule right from the CircleCI web app, or 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 that 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 App Server, and Cursor Origin

  • GitHub OAuth and Bitbucket Cloud

  1. In the CircleCI web app, select your org from the org cards on your user homepage.

  2. Select Projects from the sidebar and locate your project from the list. You can use the search to help.

  3. Select the ellipsis Ellipsis menu iconEllipsis menu icon next to your project and select Project Settings.

    You can also access project settings from each project overview page using the Settings button.
  4. Select Project Setup in the sidebar.

  5. Locate your pipeline and select Schedule +.

  6. Complete the schedule trigger form:

    Schedule triggers web app form
    Figure 1. Screenshot showing the schedule trigger form
    • Give your trigger a descriptive name.

    • Enter a Config branch. CircleCI fetches your config file from this branch.

    • Enter a Checkout branch. CircleCI checks out your code from this branch.

    • Under Pipeline attribution, select the actor to initiate the trigger. You can choose yourself, 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 must assign someone who has access to those contexts.

    • Optionally, select Add parameter to enter pipeline parameters 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.

    • Enter a Schedule (cron expression). Schedules must run at least 5 minutes apart. The start time can be offset by up to 10 minutes, but stays consistent across all runs.

  7. Make sure Trigger status is enabled, then select Save.

  1. In the CircleCI web app, select your org from the org cards on your user homepage.

  2. Select Projects from the sidebar and locate your project from the list. You can use the search to help.

  3. Select the ellipsis Ellipsis menu iconEllipsis menu icon next to your project and select Project Settings.

    You can also access project settings from each project overview page using the Settings button.
  4. Select Triggers in the sidebar.

  5. Select Add Trigger.

    Schedule triggers web app form
    Figure 2. Screenshot showing the schedule trigger form
    • Give your trigger a descriptive name.

    • Enter an optional trigger description.

    • Select the pipeline to run.

    • Select a release frequency (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.

  6. Define the new schedule by filling out the form, then select Save Trigger.

Set a schedule with the API

To set a schedule with the API, you will need your CircleCI personal API token. Select the tab for your pipeline type:

  • GitHub App, GitHub App Server, and Cursor Origin

  • GitHub OAuth and Bitbucket Cloud

  1. Have your CircleCI personal API token ready, or create a new token by following the steps on the Managing API Tokens page. Set it as an environment variable:

    $ export CIRCLE_TOKEN=<YOUR_API_TOKEN>
  2. List your organizations:

    $ curl -g https://circleci.com/api/v3/orgs \
      --header "Authorization: Bearer $CIRCLE_TOKEN"

    Locate your organization in the response and copy its id value.

  3. Find your project ID. Replace <ORG_ID> with your organization ID:

    $ curl -g "https://circleci.com/api/v3/projects?filter[org_id]=<ORG_ID>" \
      --header "Authorization: Bearer $CIRCLE_TOKEN"

    Locate your project in the response and copy its id value.

  4. Get your pipeline definition ID. Replace <PROJECT_ID> with your project ID:

    $ curl -g "https://circleci.com/api/v3/pipelines?filter[project_id]=<PROJECT_ID>" \
      --header "Authorization: Bearer $CIRCLE_TOKEN"

    Locate your pipeline in the response and copy its id value.

  5. Create the nightly schedule trigger. Replace <PIPELINE_ID> with your pipeline definition ID:

    curl --request POST \
      --url https://circleci.com/api/v3/triggers \
      --header "Authorization: Bearer $CIRCLE_TOKEN" \
      --header "Content-Type: application/json" \
      --data '{
        "data": {
          "attributes": {
            "config":   { "ref": "main" },
            "checkout": { "ref": "main" },
            "event": {
              "type": "schedule",
              "schedule": {
                "name": "nightly-build",
                "cron_expression": "0 0 * * *",
                "attribution_actor": "current"
              }
            }
          },
          "references": {
            "pipeline": { "id": "<PIPELINE_ID>" }
          }
        }
      }'

The cron expression 0 0 * * * triggers a pipeline run at midnight UTC every day. Update config.ref and checkout.ref to point to your target branch. For more information, see the Schedule Triggers page.

  1. Create a nightly schedule using the API v2 Create Schedule endpoint. Replace <project-slug> with your project slug:

    curl --request POST "https://circleci.com/api/v2/project/<project-slug>/schedule" \
      --header "Circle-Token: $CIRCLE_TOKEN" \
      --header "Content-Type: application/json" \
      --data '{
        "name": "nightly-build",
        "description": "Runs the pipeline at midnight UTC every night.",
        "attribution-actor": "system",
        "parameters": {
          "branch": "main"
        },
        "timetable": {
          "per-hour": 1,
          "hours-of-day": [0],
          "days-of-week": ["MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"]
        }
    }'

To find your project slug, see Find a Project Slug.

For more information, refer to the Schedule section under the API v2 Reference.