Triggering CircleCI Builds on New Branches via API

Overview

When using CircleCI with restricted trigger settings (such as "PR opened or pushed to, default branch pushes, tag pushes"), you may need to trigger builds via the API on newly created branches that haven't triggered a pipeline automatically.

As of May 20, 2025, all branches will appear in the branch picker in the CircleCI UI regardless of whether they've triggered a pipeline. This makes it easier to manually trigger builds through the UI, but you may still need to use the API for automation purposes.

Solution Options

Option 1: Use the UI to Trigger Builds (Now Improved)

With our recent enhancement, all branches will now appear in the branch picker dropdown in the CircleCI UI, even if they haven't triggered a pipeline. This means you can:

1. Navigate to your project in CircleCI
2. Use the branch picker to select any branch
3. Click "Trigger Pipeline" to manually start a build

This is the simplest option for most users who need to occasionally trigger manual builds.

Option 2: Use the Pipeline Run API endpoint (Recommended for Automation)

For automated workflows or CI/CD tools, use the Pipeline Run API endpoint:

curl --request POST \
  --url https://circleci.com/api/v2/project/github/{org}/{repo}/pipeline/run \
  --header 'Circle-Token: YOUR_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"definition_id":"YOUR_DEFINITION_ID","config":{"branch":"YOUR_BRANCH"},"checkout":{"branch":"YOUR_BRANCH"}}'

The Pipeline Run endpoint can initiate builds on any branch, making it ideal for automation workflows that create branches programmatically.

To find your definition_id, go to Project Settings > Pipelines in the CircleCI UI.

Option 3: Adjust your trigger settings

If you frequently need to build all new branches, you might consider modifying your project's trigger settings to include one of the following:

• Enable "All branch pushes" (may increase build costs)
• Create a Pull Request for the branch (may complicate automation workflows)

Important Notes

• The standard Pipeline Trigger API (/pipeline) may not work for branches that haven't triggered a pipeline yet. The Pipeline Run API is more reliable for these cases.
• The definition_id does not change when you update your config.yml file. It's a stable identifier for your project.
• This information is particularly useful for CI/CD automation tools like Argo that programmatically create branches and need to trigger builds.

Related Documentation

• Trigger a Pipeline (Standard API)
• Trigger a Pipeline Run (Recommended for new branches)
• CircleCI Project Trigger Settings