Working with Steps

1. Checking Out Code

Option	Values	Notes
checkout	`steps:`	Standard step to check out code
path	`~/project`	Directory to check out code into

Example: Basic Checkout

steps:
  - checkout

Example: Checkout to Custom Path

steps:
  - checkout:
      path: ~/my-project

2. Running Shell Commands

Command	Description	Example
run	Executes a shell command in the context of the job	`run: echo "Hello World"`
command	Specifies the command to run	`run: command: \| echo "Starting build" npm install`
name	Provides a name for the step (optional)	`run: name: "Setup Environment" command: echo "Environment set up"`

Example: Running a Multi-line Script

steps:
  - run: |
      echo "Building project..."
      npm run build
      echo "Build completed."

Note: The run step executes in a shell environment and supports all standard shell commands.

Warning: Avoid using sudo in CircleCI steps as it can lead to unexpected behavior or security issues.

3. Naming Steps

Property	Value	Description
name	`string`	The name of the step, displayed in the CircleCI UI

Example: Naming a Step

steps:
  - run:
      name: "Install Dependencies"
      command: npm install

4. Using Step Conditionals

Step conditionals in CircleCI allow you to control whether a step should run based on specific criteria. These conditions are evaluated at runtime and can be used to skip steps under certain circumstances.

Property	Description	Values	Notes
when	Controls whether a step runs based on the result of a condition	`all-passed`, `any-passed`, `always`, `never`	Default is `all-passed`. Can be used to make a step run regardless of previous step outcomes.
condition	Custom condition using CircleCI's expression syntax	Expression string	Allows for complex conditional logic using `==`, `!=`, `&&`, `\|\|`, etc.

Example: Using `when` to run a step only if all previous steps pass

steps:
  - run:
      name: Build
      command: npm run build

  - run:
      name: Test
      command: npm test

  - run:
      name: Deploy
      command: echo "Deploying..."
      when: all-passed

Example: Using `condition` to run a step based on environment variable

steps:
  - run:
      name: Check branch
      command: echo "Branch is $CIRCLE_BRANCH"

  - run:
      name: Deploy to staging
      command: echo "Deploying to staging..."
      condition: "[[ $CIRCLE_BRANCH == 'staging' ]]"

Note: The condition property allows you to use shell expressions, but they must be enclosed in brackets like [[ ... ]]. These expressions are evaluated in the context of the current job's environment.

5. Setting Step Timeout

Property	Values	Description
timeout	`integer`	Maximum time (in seconds) a step can run before being terminated

Example: Setting Step Timeout

steps:
  - run:
      name: "Long Running Task"
      command: "sleep 300"
      timeout: 120

6. Running Background Commands

Example: Running a Background Service

jobs:
  build:
    steps:
      - checkout
      - run:
          name: Start Redis
          command: redis-server &amp;#38;gt; /dev/null 2&amp;#38;#38;1
          background: true
      - run:
          name: Run Tests
          command: npm test

Property	Description	Default
background	Run the command in the background. The command will continue running even after the step completes.	false
command	The command to run in the background.
name	A descriptive name for the step.

Note: When using background: true, make sure to properly handle the command's output to avoid cluttering logs.

7. Using Working Directory in Steps

Property	Description	Default
working_directory	Defines the directory where CircleCI runs the commands in a job.	`/home/circleci/project`

Example: Setting Working Directory

jobs:
  build:
    working_directory: /home/circleci/project/src
    steps:
      - checkout
      - run: echo "Running in custom directory"

Note: The working_directory is set per job and affects all steps within that job.

8. Setting Step Environment

Property	Description	Values	Notes
environment	Sets environment variables for the step	`key: value`	Variables are accessible in the step's context
resource_class	Defines compute resources for the step	`medium`, `large`, `xlarge`, `2xlarge`	Higher resource classes provide more CPU and memory
working_directory	Defines the working directory for the step	`/home/circleci/project`	Defaults to the project root directory

Example: Setting Environment Variables

steps:
  - run:
      name: Set Environment Variables
      command: echo $MY_VAR
      environment:
        MY_VAR: "Hello CircleCI"

Example: Using Resource Class

steps:
  - run:
      name: Heavy Compute Task
      command: ./heavy-script.sh
      resource_class: xlarge

9. Using Shell Options

Option	Description	Example
shell	Specifies the shell to use for running commands	`shell: /bin/bash`
shell_options	Additional shell options to pass to the shell	`shell_options: -e -u`

Example: Setting shell options

steps:
  - run:
      name: Run with shell options
      shell: /bin/bash
      shell_options: -e -u
      command: |
        set -e
        set -u
        echo "Running with strict shell options"

10. Chaining Multiple Commands

Example: Chaining commands in a single step

steps:
  - name: "Run multiple commands"
    command: |
      echo "Starting build"
      npm install
      npm run test
      echo "Build completed"

Command	Description	Notes
command	`echo "Starting build"`	Prints a message to the console
command	`npm install`	Installs project dependencies
command	`npm run test`	Runs the project tests
command	`echo "Build completed"`	Prints a completion message

Note: Commands are executed in sequence within the same shell session. If one command fails, subsequent commands will not run unless configured otherwise.