Managing Project Settings

1. Configuring Project Settings

Setting	Description	Values	Notes
builds	Controls build behavior	`true` / `false`	Disables builds when set to false
test	Defines test command	`string`	Used to run tests in the project
deploy	Defines deployment command	`string`	Used to deploy project after successful build
notify	Enables notifications	`true` / `false`	Enables email/slack notifications

Example: Configuring Project Settings

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: npm install
      - run:
          name: Run tests
          command: npm test
      - run:
          name: Deploy
          command: npm run deploy

workflows:
  version: 2
  build-and-deploy:
    jobs:
      - build

2. Adding Environment Variables

Variable Name	Value	Description	Scope
API_TOKEN	`**********`	CircleCI API token for authentication	Project
DATABASE_URL	`postgres://user:pass@host:port/db`	Connection string for database	Project
NODE_ENV	`production`	Environment mode for application	Build

Example: Setting Environment Variables in CircleCI Config

version: 2.1
jobs:
  build:
    environment:
      NODE_ENV: production
      DATABASE_URL: "postgres://user:pass@host:port/db"
    steps:
      - checkout
      - run: npm install

Note: Environment variables set at the project level are available to all builds in that project. Variables can be encrypted using CircleCI's encryption feature.

3. Managing SSH Keys

Property	Description	Value
ssh-key.type	SSH key type	`rsa`, `ecdsa`, `ed25519`
ssh-key.name	Name of the SSH key	`circleci-ssh-key`
ssh-key.value	Base64 encoded private key	`LS0tLS1CRUdJTiBSU0EgUFJJV...==`

Example: Adding SSH Key to Project

version: 2.1
jobs:
  build:
    steps:
      - checkout
      - run:
          name: Setup SSH
          command: |
            mkdir -p ~/.ssh
            echo "$SSH_KEY" > ~/.ssh/id_rsa
            chmod 600 ~/.ssh/id_rsa
            ssh-keyscan github.com >> ~/.ssh/known_hosts
      - run:
          name: Clone Private Repo
          command: git clone git@github.com:org/repo.git

Note: Ensure the SSH key is added to CircleCI project settings under SSH Permissions.

Warning: Never commit SSH keys to version control. Always use environment variables.

4. Setting Up Outbound Webhooks

Field	Description	Example
webhook.url	URL to send webhook payload	`https://api.example.com/circleci`
webhook.secret	Secret for HMAC-SHA256 signature	`my-secret-key`
webhook.events	Event types to trigger webhook	`build.success, build.failed`

Example: Webhook Configuration

version: 2.1
jobs:
  build:
    steps:
      - run:
          name: Send Webhook
          command: |
            curl -X POST \
              -H "Content-Type: application/json" \
              -H "X-CircleCI-Signature: $(echo -n '{"build_num":123}' | openssl dgst -sha256 -hmac 'my-secret-key' | cut -d ' ' -f 2)" \
              -d '{"build_num":123}' \
              https://api.example.com/circleci

Note: Webhook signatures use HMAC-SHA256 with the secret key.

Warning: Ensure webhook URLs are HTTPS and secured.

5. Configuring Auto-Cancel

Setting	Description	Default	Notes
auto_cancel	Controls whether to cancel running builds when a new build is triggered for the same branch	`false`	Applies to all branches unless overridden in branch-specific settings
auto_cancel_on_new_commit	Cancel builds when a new commit is pushed to the same branch	`true`	Only affects builds that are currently running

Example: Enabling auto-cancel in config

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
workflows:
  version: 2
  build-and-test:
    jobs:
      - build
    auto_cancel: true

6. Setting Build Forked PRs

Setting	Description	Default	Notes
build_forked_pull_requests	Controls whether CircleCI builds forked pull requests	`false`	When set to `true`, CircleCI will build forked PRs. When `false`, forked PRs are not built.

Example: Configuring build_forked_pull_requests

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
workflows:
  version: 2
  build-and-test:
    jobs:
      - build
    settings:
      build_forked_pull_requests: true

Note: Enabling build_forked_pull_requests can pose security risks as it allows code from external sources to be executed in your CircleCI environment. Ensure that appropriate security measures are in place.

7. Enabling Advanced Features

Feature	Description	Enablement	Notes
Orbs	Reusable configuration templates	`orbs:` in config	Requires orb registry access
Workflows	Define job dependencies and execution	`workflows:` in config	Advanced scheduling and triggers
Triggers	Automated job starts based on events	`triggers:` in config	Supports webhooks and cron
Dynamic Config	Generate config at runtime	`executors:` and `parameters:`	Requires CircleCI 2.1+
Contexts	Secure variable groups	`contexts:` in config	Access via project settings

Example: Enabling Workflows

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install

workflows:
  version: 2
  build-and-test:
    jobs:
      - build

Note: Advanced features require CircleCI 2.1 or higher.

Warning: Enabling features may require additional permissions or configuration in project settings.

8. Managing Build Timeouts

Setting	Description	Default Value	Notes
build_timeout	Maximum time a build can run before being terminated	`10`	Time in minutes
job_timeout	Maximum time a job can run before being terminated	`10`	Time in minutes

Example: Setting build timeout in config.yml

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Run tests
          command: npm test
    build_timeout: 15

Note: Build timeout is applied per job, and can be overridden at the job level.

9. Configuring Follow Project

Setting	Description	Default	Notes
follow	Controls whether CircleCI should automatically follow new branches	`false`	When set to `true`, CircleCI will automatically start building new branches as they are pushed
follow_branches	List of branches to follow	`[]`	Specify which branches should be followed. If empty, all branches are followed

Example: Enabling Follow Project

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install

workflows:
  version: 2
  build-and-deploy:
    jobs:
      - build
      - follow: true

Note: The follow setting is only available in CircleCI 2.1 configuration.

10. Archiving Projects

Setting	Description	Value
project.archived	Archives a project, making it read-only	`true`
project.archive_reason	Reason for archiving the project	`"inactive"`

Example: Archive a Project via API

curl -X POST \
  https://circleci.com/api/v2/project/<VCS>/<ORG>/<PROJECT>/archive \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Circle-Token: <TOKEN>' \
  -d '{"archive_reason": "inactive"}'

Note: Archived projects can be unarchived by the project owner or organization admin.

Warning: Archiving a project removes it from active builds and can't be undone without support.