Working with Environment Variables

1. Defining Job-Level Variables

Variable	Value	Description
environment	`{}`	Defines environment variables for the job
resource_class	`medium`	Resource class for the job (e.g., `medium`, `large`, `xlarge`)
working_directory	`/home/circleci/project`	Working directory for the job

Example: Setting Environment Variables

jobs:
  build:
    environment:
      NODE_ENV: production
      DATABASE_URL: "postgres://user:pass@localhost/db"
    steps:
      - run: echo $NODE_ENV

2. Defining Step-Level Variables

Variable	Definition	Usage	Notes
steps	`steps:`	Array of job steps	Each step can define its own environment variables
environment	`environment:`	Key-value pairs	Variables available to all commands in the step

Example: Setting Step-Level Variables

steps:
  - checkout
  - run:
      command: echo $MY_VAR
      environment:
        MY_VAR: "Hello CircleCI"

3. Referencing Variables in Config

Variable Type	Reference Syntax	Description
Environment Variables	`<env_var_name>`	Referenced using the standard environment variable syntax in config files
Context Variables	`<context_var_name>`	Accessed via the context object in config files
Parameter Variables	`<param_var_name>`	Used in parameterized builds to pass values into the config

Example: Referencing Environment Variables

jobs:
  build:
    steps:
      - run: echo $API_KEY

Example: Using Context Variables

jobs:
  build:
    steps:
      - run: echo $CIRCLE_BRANCH

Example: Parameter Variables in Config

parameters:
  env:
    type: string
    default: "dev"

jobs:
  build:
    steps:
      - run: echo "Environment is $env"

4. Using Built-in Variables

Variable	Description	Example Value
CIRCLE_BUILD_NUM	Unique build number for each build	`1234`
CIRCLE_SHA1	Git commit SHA1 hash	`abc123def456...`
CIRCLE_BRANCH	Git branch name	`main`
CIRCLE_TAG	Git tag name (if built from a tag)	`v1.0.0`
CIRCLE_USERNAME	CircleCI username of the user who triggered the build	`johndoe`
CIRCLE_PROJECT_REPONAME	Repository name	`my-app`
CIRCLE_BUILD_URL	URL to the current build	`https://circleci.com/gh/johndoe/my-app/1234`
CIRCLE_REPOSITORY_URL	Git repository URL	`https://github.com/johndoe/my-app.git`

Example: Using Built-in Variables in a Script

#!/bin/bash
echo "Build number: $CIRCLE_BUILD_NUM"
echo "Commit SHA: $CIRCLE_SHA1"
echo "Branch: $CIRCLE_BRANCH"

5. Setting Project Variables

Variable Type	Scope	Description	Usage
Project Environment Variables	Project-wide	Variables set at the project level and available to all builds	`export MY_VAR=value`
Context Variables	Context-specific	Variables that are only accessible within a specific context (e.g., `CI`)	`echo $CI`
Build Parameters	Build-specific	Variables that are passed to a build and can be used in configuration	`circleci config process --build-parameter key=value`

Example: Setting a Project Variable via CLI

circleci env set MY_VAR "my_value"

Example: Using Project Variables in Configuration

version: 2.1
jobs:
  build:
    steps:
      - run:
          command: echo $MY_VAR

Note: Project variables can be managed via the CircleCI web UI or CLI. Ensure sensitive values are stored as Secrets to prevent exposure in logs.

6. Using Organization Variables

Variable	Value	Description
CIRCLECI_ORG_NAME	`circleci`	Organization name in CircleCI
CIRCLECI_ORG_ID	`org-id-12345`	Unique identifier for the organization

Example: Setting an organization variable in a config

version: 2.1
jobs:
  build:
    steps:
      - run:
          name: "Use Org Variable"
          command: echo $CIRCLECI_ORG_NAME

Note: Organization variables are accessible to all projects within the organization and can be used in any job or workflow.

7. Setting Multiline Variables

Variable	Value	Notes
multiline_var	`line1\nline2\nline3`	Single-line variable with newline characters
multiline_env	`#!/bin/bash echo "First line" echo "Second line" echo "Third line"`	Environment variable containing a script

Example: Setting Multiline Variable in CircleCI Config

version: 2.1
jobs:
  build:
    steps:
      - run:
          name: Set Multiline Variable
          command: |
            export MULTI_LINE_VAR="line1
line2
line3"
            echo "$MULTI_LINE_VAR"

Note: When using multiline variables in CircleCI, ensure proper escaping to avoid parsing errors.

8. Escaping Special Characters

When using environment variables in CircleCI configuration, special characters must be properly escaped to prevent parsing issues or unintended behavior.

Character	Description	Escaping Method	Example
`$`	Dollar sign used for variable interpolation	Double dollar sign (`$$`)	`$$HOME` expands to `$HOME`
`&`	Ampersand used in shell commands	Backslash escape (`\&`)	`echo "Value&more"` becomes `echo "Value\&more"`
`"`	Double quotes in strings	Backslash escape (`\"`)	`"Hello \"World\""`
`'`	Single quotes in strings	Backslash escape (`\'`)	`'It\'s working'`
`\`	Backslash itself	Double backslash (`\\`)	`path/to\\file`

Example: Using Escaped Characters in Environment Variables

version: 2.1
jobs:
  build:
    steps:
      - run:
          name: "Print Escaped String"
          command: |
            echo "Home directory: $HOME"
            echo "Value&more"

9. Using Base64 Encoding

Property	Description	Usage
circleci env encode	Encodes a string using Base64 encoding	`circleci env encode "my-secret"`
circleci env decode	Decodes a Base64 encoded string	`circleci env decode "bXktc2VjcmV0"`

Example: Encoding a Secret

circleci env encode "my-api-key"

Example: Decoding a Secret

circleci env decode "bXktYXBpLWtl"

10. Debugging Variable Values

Example: Print Environment Variables

echo $MY_VARIABLE
printenv | grep MY_

Variable	Value	Description
CIRCLE_JOB	`build`	Current job name
CIRCLE_BUILD_NUM	`12345`	Build number
CIRCLE_SHA1	`abc123def456...`	Git commit SHA

Note: Use echo or printenv to inspect variable values during a job run.

Warning: Sensitive variables should not be printed in logs. Use echo $SECRET_VAR with caution.