Project Settings API

Project Features Available via API

These are API endpoints that are available to manipulate project settings.

Please provide any feedback about these endpoints to your account team.

API Endpoints

Feature	Description	Visible on UI	Project Settings
disable-ssh	Disable SSH capability for builds on this project	NO	N/A
write-settings-requires-admin	Only admins will be allowed to modify(write permissions) project settings	NO	N/A
set-github-status	Report the status of every pushed commit to GitHub’s status API. Updates reported per job.	YES	GitHub Status Updates
build-fork-prs	Run builds for pull requests from forks. CircleCI will automatically update the commit status shown on GitHub’s pull request page	YES	Build forked pull requests
forks-receive-secret-env-vars	Run builds for forked pull requests with this project’s configuration, environment variables, and secrets. The build cache is also shared between the the original repository and all forks.	YES	Pass secrets to builds from forked pull requests
build-prs-only	By default, we will build all the commits for this project. Once turned on, we will only build branches that have associated pull requests open.	YES	Only build pull requests
autocancel-builds	With the exception of your default branch, we will automatically cancel any outstanding workflows on a branch when a newer pipeline is triggered on that branch. Scheduled workflows and re-runs are not auto-canceled.	YES	Auto-cancel redundant workflows
oss	Organizations on our free plan get 400,000 free credits per month ($2,880 annual value) to use for Linux open source builds. Enabling this will allow this project’s builds to use them and let others see your builds, both through the web UI and the API.	YES	Free and Open Source
setup-workflows	This will allow you to conditionally trigger configurations outside of the primary .circleci parent directory, update pipeline parameters before a build is run, and generate your own customized configurations if defined in your config.yml.	YES	Enable dynamic config using setup workflows

There is another feature flag, pr-only-branch-overrides, that allows users to set additional branches to build other then PRs and the default branch. This is extremely help as many users think they are stuck with PRs and ONLY the default branch. Please see this Discuss post for more information

Curl Command Examples

PUT Requests

Invisible Project Settings:

curl -X PUT --header "Circle-Token: <token>" --header "Accept: application/json" --header "Content-Type: application/json" --data '{"feature_flags":{"disable-ssh": true, "write-settings-requires-admin": true}}' 'https://circleci.com/api/v1.1/project/vcs-type/org-slug/project-slug/settings'

Visible Project Settings:

curl -X PUT --header "Circle-Token: <token>" --header "Accept: application/json" --header "Content-Type: application/json" --data '{"feature_flags":{"set-github-status": true, "build-fork-prs": true, "forks-receive-secret-env-vars": true, "build-prs-only": true, "autocancel-builds": true, "oss": true, "setup-workflows": true}}' 'https://circleci.com/api/v1.1/project/vcs-type/org-slug/project-slug/settings'

Response: None

GET Request

curl -X GET --header "Circle-Token: <token>" --header "Accept: application/json" --header "Content-Type: application/json" 'https://circleci.com/api/v1.1/project/vcs-type/org-slug/project-slug/settings' | jq 'del(."branches")'

The GET request example uses jq to remove the branches section which is rather long with data not relevant to the project settings, but is not necessary. Some relevant project data, like the default branch(es), is outside of the feature_flagsection.

Response:

{
  "irc_server": null,
  "slack_integration_channel": null,
  "irc_keyword": null,
  "slack_integration_team_id": null,
  "vcs-type": "<vcs-type>",
  "aws": {
    "keypair": null
  },
  "slack_webhook_url": null,
  "slack_integration_team": null,
  "username": "<username>",
  "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/<org-name>/<repo-name>",
  "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": true,
    "pr-only-branch-overrides": [
      "main"
    ],
    "write-settings-requires-admin": false,
    "disable-ssh": false,
    "set-github-status": false,
    "build-prs-only": false,
    "forks-receive-secret-env-vars": false,
    "build-fork-prs": false,
    "autocancel-builds": false,
    "oss": true
  },
  "slack_integration_channel_id": null,
  "irc_channel": null,
  "oss": true,
  "reponame": "<repo-name>",
  "slack_integration_access_token": null,
  "ssh_keys": []
}