Implementing Conditional Logic

1. Using When Conditions

Property	Description	Values	Notes
when	Condition to evaluate	`equal`, `not_equal`, `in`, `not_in`, `matches`, `not_matches`	Used to conditionally execute jobs or steps

Example: Using `when` with `equal`

jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - run:
          name: Run build only on master
          command: echo "Building..."
          when:
            equal: [master, <em>circleci</em>.branch]

Example: Using `when` with `in`

jobs:
  deploy:
    docker:
      - image: circleci/python:3.9
    steps:
      - run:
          name: Deploy only on release branches
          command: echo "Deploying..."
          when:
            in: [release, <em>circleci</em>.branch]

Note: The when condition is evaluated at runtime and supports referencing environment variables, context variables, and parameters.

2. Using Unless Conditions

Property	Description	Values	Notes
unless	Defines a condition under which a job or step will be skipped	`condition`	Can be used with `steps`, `jobs`, or `executors`

Example: Skip job based on branch

jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Run tests
          command: npm test
      - unless:
          condition: <span class="property">branch</span>.matches("main")
          steps:
            - run:
                name: Skip on main
                command: echo "Skipping tests on main branch"

Example: Skip job based on environment variable

jobs:
  deploy:
    docker:
      - image: circleci/python:3.9
    steps:
      - checkout
      - unless:
          condition: <span class="property">env</span>.variable("SKIP_DEPLOY") == "true"
          steps:
            - run:
                name: Deploy to production
                command: ./deploy.sh

3. Using Step Conditionals

Property	Description	Values	Notes
when	Defines the condition for running a step	`steps`, `always`, `on_success`, `on_fail`	Default is `steps`

Example: Using `when` to run a step only on success

jobs:
  build:
    steps:
      - run: echo "Building..."
      - run: echo "Testing..."
        when: on_success

Note: The when property can be used to control when a step runs based on the outcome of previous steps.

4. Using Workflow Conditionals

Condition	Description	Example
branches	Specify which branches to run the workflow on	`branches: { only: [main, develop] }`
tags	Run workflow only on specific tags	`tags: { only: /^v\d+\.\d+\.\d+$/ }`
status	Run workflow based on job status (success or failure)	`status: { only: [success] }`
context	Run workflow based on context variables	`context: { only: [production] }`

Example: Branch-based conditional workflow

workflows:
  build-and-deploy:
    branches:
      only:
        - main
        - develop
    jobs:
      - build
      - deploy

Example: Tag-based conditional workflow

workflows:
  release:
    tags:
      only: /^v\d+\.\d+\.\d+$/
    jobs:
      - build
      - publish

Note: Use branches and tags to control when workflows run based on source branch or tag patterns.

Warning: Be careful with regex patterns in tags as they can lead to unintended matches.

5. Using Logic Operators

Operator	Description	Usage Example
and	Logical AND operator. Returns true if both operands are true.	`and: [condition1, condition2]`
or	Logical OR operator. Returns true if at least one operand is true.	`or: [condition1, condition2]`
not	Logical NOT operator. Returns true if the operand is false.	`not: condition1`

Example: Using `and` operator

jobs:
  build:
    steps:
      - run: echo "Running build"
      - when:
          and:
            - condition: << pipeline.number >> > 10
            - condition: << pipeline.branch >> == "main"

Example: Using `or` operator

jobs:
  deploy:
    steps:
      - run: echo "Deploying to production"
      - when:
          or:
            - condition: << pipeline.branch >> == "main"
            - condition: << pipeline.branch >> == "staging"

Example: Using `not` operator

jobs:
  test:
    steps:
      - run: echo "Running tests"
      - when:
          not:
            condition: << pipeline.branch >> == "release"

6. Comparing Values

Operator	Description	Example	Notes
=	Equal to	`branch: main`	Matches exact string value
!=	Not equal to	`branch: != develop`	Matches any string except the specified value
<	Less than	`pipeline.number < 100`	For numeric comparisons
>	Greater than	`pipeline.number > 50`	For numeric comparisons
<=	Less than or equal to	`pipeline.number <= 100`	For numeric comparisons
>=	Greater than or equal to	`pipeline.number >= 50`	For numeric comparisons
contains	Contains substring	`branch: contains feature/`	Case-sensitive matching
matches	Matches regex pattern	`branch: matches /^feature\/.*$/`	Uses JavaScript-style regex syntax
not matches	Does not match regex pattern	`branch: not matches /^release\/.*$/`	Uses JavaScript-style regex syntax
in	Value is in list	`branch: in [main, develop]`	Matches any value in the array
not in	Value is not in list	`branch: not in [release, hotfix]`	Does not match any value in the array

Example: Using comparison operators in a job condition

jobs:
  build:
    docker:
      - image: circleci/node:18
    steps:
      - run:
          name: "Build on main branch"
          command: echo "Building on main branch"
          when:
            condition: branch = "main"

Example: Using multiple conditions with logical operators

jobs:
  deploy:
    docker:
      - image: circleci/python:3.9
    steps:
      - run:
          name: "Deploy to production"
          command: echo "Deploying to prod"
          when:
            condition: |
              (branch = "main" and pipeline.number > 100)
              or
              (branch matches /^release\/.*$/ and pipeline.number < 50)

7. Using Pipeline Values

Property	Description	Usage
pipeline.number	Unique identifier for the pipeline	`<%= pipeline.number %>`
pipeline.project.git_url	Git URL of the project	`<%= pipeline.project.git_url %>`
pipeline.git.branch	Current branch name	`<%= pipeline.git.branch %>`
pipeline.git.tag	Tag associated with the pipeline	`<%= pipeline.git.tag %>`
pipeline.git.commit	Commit SHA of the current build	`<%= pipeline.git.commit %>`

Example: Using pipeline values in a job

jobs:
  build:
    steps:
      - run:
          name: "Log pipeline info"
          command: |
            echo "Pipeline ID: $CIRCLE_PIPELINE_NUMBER"
            echo "Branch: $CIRCLE_GIT_BRANCH"
            echo "Commit: $CIRCLE_SHA1"

Note: Pipeline values are available as environment variables in the job context and can be used for logging, tagging, or conditional logic.

8. Using Parameter-Based Conditions

Parameter	Description	Usage
context.parameters	Accesses parameters passed to the workflow	`context.parameters.my_param`
context.pipeline	Provides pipeline-level context including parameters	`context.pipeline.parameters.env`

Example: Using Parameters in a Job Condition

jobs:
  build:
    parameters:
      environment:
        type: string
        default: "staging"
    steps:
      - run:
          name: "Build for Environment"
          command: echo "Building for jobs:
  build:
    parameters:
      environment:
        type: string
        default: "staging"
    steps:
      - run:
          name: "Build for Environment"
          command: echo "Building for $<parameters.environment>"
          when:
            condition: <parameters.environment> == "production"
#x3C;parameters.environment>"
          when:
            condition: <parameters.environment> == "production"

Example: Conditional Step Based on Parameter

jobs:
  deploy:
    parameters:
      target:
        type: string
        default: "staging"
    steps:
      - run:
          name: "Deploy to Staging"
          command: echo "Deploying to staging environment"
          when:
            condition: <parameters.target> == "staging"
      - run:
          name: "Deploy to Production"
          command: echo "Deploying to production environment"
          when:
            condition: <parameters.target> == "production"

9. Implementing Branch-Based Logic

Condition	Description	Example
branches	Specifies which branches to run the job on	`branches: only: - main - develop`
branches.ignore	Specifies which branches to ignore	`branches: ignore: - /feature\/.*/`
branches.allow	Allows specific branches to run	`branches: allow: - main - release/*`

Example: Branch-Based Conditional Job

jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Run tests on main branch
          command: npm test
      - run:
          name: Deploy to production
          command: echo "Deploying to prod"
          when: branch == "main"

Note: The when clause can be used to conditionally execute steps based on branch names or patterns.

10. Combining Multiple Conditions

Operator	Description	Example
and	Logical AND operator; all conditions must be true	`and: [condition1, condition2]`
or	Logical OR operator; at least one condition must be true	`or: [condition1, condition2]`
not	Logical NOT operator; negates a condition	`not: condition1`

Example: Combining Conditions in a Workflow

jobs:
  build:
    steps:
      - run:
          name: "Build Only on Master or Release"
          command: echo "Building..."
          when:
            or:
              - condition: <span class="property">branch</span>.name == "master"
              - condition: <span class="property">branch</span>.name == "release"

Example: Complex Nested Conditions

jobs:
  deploy:
    steps:
      - run:
          name: "Deploy to Production"
          command: echo "Deploying..."
          when:
            and:
              - condition: <span class="property">branch</span>.name == "master"
              - condition: <span class="property">pipeline</span>.number == 1
              - not:
                  condition: <span class="property">env</span>.CI == "false"