# \[Product Launch\] Override Only Build PRs Setting **URL:** \ **Category:** Build Environment\ **Created:** [April 18, 2023, 6:53pm UTC](https://discuss.circleci.com/t/product-launch-override-only-build-prs-setting/47807 "2023-04-18T18:53:56Z")\ **Posts on this page:** 10\ **Page:** 1
**Author:** ![sebastian-lerner](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/sebastian-lerner/32/27833_2.png) [@sebastian-lerner](https://discuss.circleci.com/u/sebastian-lerner)\ **Post date:** [April 18, 2023, 6:53pm UTC](https://discuss.circleci.com/t/product-launch-override-only-build-prs-setting/47807/1 "2023-04-18T18:53:56Z")
**Context:** The “Only build pull requests” project setting enables users to only trigger validation on CircleCI when a pull request is present on non-default branches. ![](https://global.discourse-cdn.com/circleci/original/3X/b/9/b9ace1b8afc6f6d2812bc1da9fc33d47b8e47fd4.png) This setting can be too restrictive for certain scenarios, such as when trying to use CircleCI with GitHub’s [merge queue functionality.](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue) Original feedback in this [Canny post](https://circleci.canny.io/cloud-feature-requests/p/allow-branch-whitelist-to-override-only-build-pull-requests). Starting April 18, 2023, the [CircleCI API](https://circleci.com/docs/api/v1/index.html#circleci-v1-api-overview) can be used to override the “Only build pull requests” setting. **This enables you to specify certain branches (via regular expression) that trigger validation on every commit, while maintaining the “Only build pull requests” setting on all other non-default branches.** **Input:** - Comma-separated list of regular expressions or full branch names to match - These branches will build all commits, while all other branches will continue to only build when a pull request is present - The default branch (ie. `main`) must be included in the comma-separated list in order to maintain the behavior of always building all commits to the default branch - **Notes** : - `vcs-type`, `org-slug` and `project-slug` values that are used as input to the CircleCI API can be seen in the URL when viewing a project in the CircleCI UI - Any user that has access to change project settings can use this override - A valid API token is required to make these API calls, see [“add an API token”](https://circleci.com/docs/api/v1/index.html#add-an-api-token) if this is your first time using the CircleCI API - To match literal characters with regex significance, they must be escaped. For example, to match a branch named `main-(2123)`, the parenthesis must be double-escaped with a backslash: `main-\\(2123\\)` - Regex character classes must be double escaped. For example, `main-\\d+` will match branches named `main-3` and `main-32`. To match a branch composed of characters in the Greek UTF-8 block, specify `\\p{IsGreek}.` - Any call to the API to update the settings will _replace_ the current settings, not add to the existing settings **Example #1:** _Assumes that the “Only build pull requests” setting is already enabled._ _Override the “Only build pull requests” setting for the following branch and branch patterns:_ `main`, `release.*`, `enterprise-.*` ```auto curl -X PUT --header "Circle-Token: " --header "Accept: application/json" --header "Content-Type: application/json" --data '{"feature_flags":{"pr-only-branch-overrides": "main, release.*, enterprise-.*"}}' 'https://circleci.com/api/v1.1/project/vcs-type/org-slug/project-slug/settings' ``` **Note** : Replace `` with your CircleCI API token **Result** : If the response looks like the following: `""%` Any branch that starts with release, such as `release2` or `release-to-prod`, and any branch that starts with `enterprise-`, such as `enterprise-2.0`, will now trigger validation on all commits. Additionally, the default branch, `main`, will continue to build all commits. All other branches in this project will only build when they have an open pull request. **Example #2:** _Enable “Only build pull requests” setting via the CircleCI API and override the setting for the following branch and branch patterns:_ `main`, `release.*`, `enterprise-.*` ```auto curl -X PUT --header "Circle-Token: " --header "Accept: application/json" --header "Content-Type: application/json" --data '{"feature_flags":{"build-prs-only":true, "pr-only-branch-overrides": "main, release.*, enterprise-.*"}}' 'https://circleci.com/api/v1.1/project/vcs-type/org-slug/project-slug/settings' ``` **Result** : Any branch that starts with `release`, such as `release2` or `release-to-prod`, and any branch that starts with `enterprise-`, such as `enterprise-2.0`, will trigger validation on all commits. Additionally, the default branch, `main`, will continue to build all commits. All other branches in this project will now only build when they have an open pull request. **Example #3:** _Enable “Only build pull requests” setting via the CircleCI API and override the setting for the following branch and branch patterns:_ `main`, `\\(\\d+\\)-release.*` **Note** : Replace `` with your CircleCI API token ```auto curl -X PUT --header "Circle-Token: " --header "Accept: application/json" --header "Content-Type: application/json" --data '{"feature_flags":{"build-prs-only":true, "pr-only-branch-overrides": "main, \(\\d+\)-release.*"}}' 'https://circleci.com/api/v1.1/project/vcs-type/org-slug/project-slug/settings' ``` **Result** : Will build any branch that starts with one or more digits enclosed in parenthesis followed by the string `-release` suffixed with zero or more characters. For example: Branches `(123)-release2 `, `(7)-release-to-prod`, and `(334)-release` will all trigger validation on all commits. Additionally, the default branch, `main`, will continue to build all commits. **Limits:** - `pr-only-branch-overrides` will only have an effect if the “Only build pull requests” setting is turned on - You can verify this via the API response by observing the boolean `build-prs-only?` is set to `true` or via the Project Settings UI under the “Advanced” section - There is a maximum of 100 branch regular expressions per project and a limit of 1,000 characters per regular expression - Branch names cannot include a “comma” (“,”). The API will not reject this as input, it will simply assume that the comma splits the input into two branch names - There is not a way to retrieve the value of a single project setting - to see the currently set values, retrieve all of the settings for a given project - As of writing this post, this functionality only works for CircleCI organizations that use GitHub as their VCS **Example of retrieving Project Settings for a given project within an organization** ```auto curl -X GET --header "Circle-Token: " --header "Accept: application/json" --header "Content-Type: application/json" 'https://circleci.com/api/v1.1/project/vcs-type/org-slug/project-slug/settings' ``` **Note** : Replace `` with your CircleCI API token **Response:** **Note** : this response includes information that may be considered sensitive. `"pr-only-branch-overrides":` will show which branch regexes are set-up. ```auto { "irc_server": null, "slack_integration_channel": null, "irc_keyword": null, "slack_integration_team_id": null, "vcs-type": "github", "aws": { "keypair": null }, "slack_webhook_url": null, "slack_integration_team": null, "username": "foo-user", "branches": { "circleci-project-setup": { "running_builds": [], "recent_builds": [ { "status": "success", "outcome": "success", "build_num": 1, "vcs_revision": "f2aa5c44b9db87f76b5cec3827b5f973f80a2ff2", "pushed_at": "2022-05-02T23:26:20.608Z", "added_at": "2022-05-02T23:26:25.446Z", "is_workflow_job": true, "is_2_0_job": true, }, ], "is_using_workflows": true, "pusher_logins": ["foo-user"], "last_success": { "status": "success", "outcome": "success", "build_num": 1, "vcs_revision": "f2aa5c44b9db87f76b5cec3827b5f973f80a2ff2", "pushed_at": "2022-05-02T23:26:20.608Z", "added_at": "2022-05-02T23:26:25.446Z", "is_workflow_job": true, "is_2_0_job": true, }, "last_non_success": {}, "latest_workflows": { "say-hello-workflow": { "id": "231434a4-19da-46cd-b88f-91a92234ac00", "status": "canceled", "created_at": "2022-05-20T15:11:08.201Z", }, }, "latest_completed_workflows": { "say-hello-workflow": { "id": "231434a4-19da-46cd-b88f-91a92234ac00", "status": "canceled", "created_at": "2022-05-20T15:11:08.201Z", }, }, }, }, "jira": null, "slack_integration_notify_prefs": null, "slack_integration_webhook_url": null, "slack_subdomain": null, "following": true, "slack_notify_prefs": null, "irc_password": null, "vcs_url": "https://github.com/foo-user/helloworld", "default_branch": "main", "irc_username": null, "language": null, "slack_channel_override": null, "slack_api_token": null, "has_usable_key": true, "irc_notify_prefs": null, "slack_channel": null, "feature_flags": { "setup-workflows": false, "set-github-status": false, "build-prs-only": true, "forks-receive-secret-env-vars": false, "build-fork-prs": false, "autocancel-builds": false, "pr-only-branch-overrides": "main, release.*, enterprise-.*" }, "slack_integration_channel_id": null, "irc_channel": null, "oss": false, "reponame": "helloworld", "slack_integration_access_token": null, "ssh_keys": [], } ``` ---
**Author:** ![wyardley](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/wyardley/32/19231_2.png) [@wyardley](https://discuss.circleci.com/u/wyardley)\ **Post date:** [May 22, 2023, 4:06pm UTC](https://discuss.circleci.com/t/product-launch-override-only-build-prs-setting/47807/2 "2023-05-22T16:06:51Z")
This is great. Also very useful for situations using a gitflow type workflow where there’s a default branch and then that’s merged into trunk (e.g., `develop` and `main`). ---
**Author:** ![laurentyv](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/laurentyv/32/33247_2.png) [@laurentyv](https://discuss.circleci.com/u/laurentyv)\ **Post date:** [June 19, 2023, 1:02pm UTC](https://discuss.circleci.com/t/product-launch-override-only-build-prs-setting/47807/3 "2023-06-19T13:02:17Z")
Thanks @sebastian-lerner for this tips, it works but there’s a side effect. I enabled `Only build pull requests` on our `develop` and `master` branches. I also have `Auto-cancel redundant workflows` enabled. My default branch is `develop`. I have a _deploy_ pipeline. In my deploy pipeline, at the end, I add a git-tag which auto-cancel current pipeline because `Auto-cancel redundant workflows` is enabled. Is it possible to also configure default branches on this option `Auto-cancel redundant workflows` as `Only build pull requests` ? ---
**Author:** ![sebastian-lerner](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/sebastian-lerner/32/27833_2.png) [@sebastian-lerner](https://discuss.circleci.com/u/sebastian-lerner)\ **Post date:** [June 20, 2023, 1:36pm UTC](https://discuss.circleci.com/t/product-launch-override-only-build-prs-setting/47807/4 "2023-06-20T13:36:28Z")
@laurentyv good question…I unfortunately do not know off the top of my head, can you open a support ticket at [support.circleci.com](http://support.circleci.com)? ---
**Author:** ![worace](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/worace/32/32980_2.png) [@worace](https://discuss.circleci.com/u/worace)\ **Post date:** [June 28, 2023, 2:25pm UTC](https://discuss.circleci.com/t/product-launch-override-only-build-prs-setting/47807/5 "2023-06-28T14:25:02Z")
@sebastian-lerner can you confirm that the only way to control this setting is via the HTTP API? There is no setting in the UI or in the `.circleci/config.yml` file to do it? ---
**Author:** ![sebastian-lerner](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/sebastian-lerner/32/27833_2.png) [@sebastian-lerner](https://discuss.circleci.com/u/sebastian-lerner)\ **Post date:** [June 28, 2023, 3:16pm UTC](https://discuss.circleci.com/t/product-launch-override-only-build-prs-setting/47807/6 "2023-06-28T15:16:24Z")
> [@worace](#): > > t the only way to control this setting is via the HTTP API? There is no setting in the UI or in the `.circl` Correct, at this time, the _override_ enumerated in this post is only supported via the API. The “Only Bulid PRs” feature is available via the UI in Project Settings ---
**Author:** ![jheison-rodriguez](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/jheison-rodriguez/32/33773_2.png) [@jheison-rodriguez](https://discuss.circleci.com/u/jheison-rodriguez)\ **Post date:** [September 15, 2023, 5:00pm UTC](https://discuss.circleci.com/t/product-launch-override-only-build-prs-setting/47807/7 "2023-09-15T17:00:17Z")
It’s been a while I haven’t used Circle CI, and this would be a common feature that we can find in other CICD Tools. Anyways, Can I use this override to filter by tags (using regex)? ---
**Author:** ![sebastian-lerner](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/sebastian-lerner/32/27833_2.png) [@sebastian-lerner](https://discuss.circleci.com/u/sebastian-lerner)\ **Post date:** [September 18, 2023, 1:30pm UTC](https://discuss.circleci.com/t/product-launch-override-only-build-prs-setting/47807/8 "2023-09-18T13:30:56Z")
@jheison-rodriguez I believe this will only work for branch names. ---
**Author:** ![jheison-rodriguez](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/jheison-rodriguez/32/33773_2.png) [@jheison-rodriguez](https://discuss.circleci.com/u/jheison-rodriguez)\ **Post date:** [September 25, 2023, 8:29pm UTC](https://discuss.circleci.com/t/product-launch-override-only-build-prs-setting/47807/9 "2023-09-25T20:29:35Z")
Yes, I confirm that only applies to branches names ---
**Author:** ![wyardley](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/wyardley/32/19231_2.png) [@wyardley](https://discuss.circleci.com/u/wyardley)\ **Post date:** [March 24, 2026, 9:38pm UTC](https://discuss.circleci.com/t/product-launch-override-only-build-prs-setting/47807/10 "2026-03-24T21:38:22Z")
Finally got around to using this today. One thing I noticed is that it seems to possibly override the behavior of the default branch always building? I added the default branch as well as the others, but without that, the default branch didn’t seem to build.