Overview
In some cases, you may wish to add additional default branches to your project on CircleCI. This is possible via the API v3 project settings endpoint. The example commands use jq to filter the results, it is available here.
This feature expands on the Only Build Pull Requests offering by enabling you to configure additional branches (by name or regular expression) that always build on every commit, outside of the default branch in your VCS.
⚠ This is an override and not an addition. ⚠
You must specify all branches you want allowlisted each time you update the setting. Sending a new list replaces the existing list; it does not append.
Resolve Your Project ID
API v3 paths use the project UUID. Resolve it from the project slug <vcs>/<org>/<project> using the following:
curl -sS \
--header "Authorization: Bearer ${CIRCLE_TOKEN}" \
--header "Accept: application/json" \
"https://circleci.com/api/v3/projects?filter\[slug\]=${PROJECT_SLUG}" \
| jq -r '.data[0].id'
CIRCLE_TOKEN and PROJECT_SLUG will have to be set as needed. The Project UUID can also be found in Project Settings → Overview.
Enable "Only Build Pull Requests"
Using the CLI:
circleci project setting set build-prs-only true --project <project-slug>
Using the v3 API:
curl -sS -X POST \
--header "Authorization: Bearer ${CIRCLE_TOKEN}" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{"is_build_prs_only": true}' \
"https://circleci.com/api/v3/projects/${PROJECT_ID}/update-settings" \
| jq '.data.attributes.is_build_prs_only'
Get Current Allowlisted Branches
Using the CLI:
circleci project setting list --project <project-slug> --json | jq '.pr_only_branch_overrides'
Using the v3 API:
curl -sS \
--header "Authorization: Bearer ${CIRCLE_TOKEN}" \
--header "Accept: application/json" \
"https://circleci.com/api/v3/projects/${PROJECT_ID}/settings" \
| jq '.data.attributes.pr_only_branch_overrides'
Once you have the current list, include every branch you still want when you update.
Example 1: Allowlist merge-queue and staging branches
In this example, we add gh-readonly-queue.* and staging, and keep main as the default branch that should always build.
curl -sS -X POST \
--header "Authorization: Bearer ${CIRCLE_TOKEN}" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
"pr_only_branch_overrides": [
"main",
"gh-readonly-queue.*",
"staging"
]
}' \
"https://circleci.com/api/v3/projects/${PROJECT_ID}/update-settings" \
| jq '.data.attributes.pr_only_branch_overrides'
Result: A successful response is HTTP 200. The JSON body includes the updated settings. For example, pr_only_branch_overrides should list main, gh-readonly-queue.*, and staging.
Any branch that matches gh-readonly-queue.*, staging or main, will trigger validation on all commits. Other branches continue to follow "Only build pull requests" (if that setting is enabled).
Example 2: Enable Only build pull requests and allowlist release branches
In this example, we enable Only build pull requests and allowlist main plus a regex for branches like (123)-release2.
Set branch overrides using the v3 API:
curl -sS -X POST \
--header "Authorization: Bearer ${CIRCLE_TOKEN}" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
"is_build_prs_only": true,
"pr_only_branch_overrides": [
"main",
"(\\d+)-release.*"
]
}' \
"https://circleci.com/api/v3/projects/${PROJECT_ID}/update-settings" \
| jq '.data.attributes | {is_build_prs_only, pr_only_branch_overrides}'
Java-style regex special characters must be escaped in the JSON string. For a pattern like (\d+)-release.*.
Result: Branches such as (123)-release2, (7)-release-to-prod, and (334)-release trigger validation on all commits, as does main. All other branches only build when they have an open pull request.