Skip to main content
Mapagam

Creating Reusable Executors

1. Defining Executors

Executors in CircleCI define the environment in which jobs run. They specify the machine, Docker image, or resource class to use for execution.

Property Description Values
name Name of the executor string
machine Use a machine executor true or false
docker Use a Docker image executor list of image
resource_class Resource class for the executor medium, large, xlarge, 2xlarge
environment Environment variables to set map of key: value

Example: Defining a Docker Executor

executors:
  nodejs-executor:
    docker:
      - image: circleci/node:18
    environment:
      NODE_ENV: production

Example: Defining a Machine Executor

executors:
  machine-executor:
    machine:
      image: ubuntu-2004:2023.07.1
    environment:
      CI: true

2. Creating Docker Executors

Example: Basic Docker Executor Configuration

executors:
  docker-executor:
    docker:
      - image: circleci/node:16
        environment:
          NODE_ENV: production
Property Description Values
docker List of Docker images to use for the executor [{image: string, environment?: object}]
environment Environment variables to set in the container {key: value}
working_directory Working directory for the job /app
Note: The docker property must contain at least one image definition.
Warning: Avoid using latest tag in production; use specific version tags for consistency.

Example: Executor with Custom Working Directory

executors:
  custom-docker-executor:
    docker:
      - image: circleci/python:3.9
    working_directory: /home/circleci/project

Example: Executor with Environment Variables

executors:
  env-docker-executor:
    docker:
      - image: circleci/ruby:3.0
        environment:
          RAILS_ENV: production
          DATABASE_URL: postgres://user:pass@localhost/db

3. Creating Machine Executors

Property Value Description
machine {image: 'ubuntu-2004:2023.07.1'} Specifies the machine executor configuration including image and size
machine.image ubuntu-2004:2023.07.1 Base image for the machine executor (latest stable Ubuntu)
machine.size medium Size of the machine (small, medium, large, xlarge)

Example: Defining a Machine Executor

executors:
  my-machine-executor:
    machine:
      image: ubuntu-2004:2023.07.1
      size: medium

jobs:
  build:
    executor: my-machine-executor
    steps:
      - checkout
      - run: echo "Running on machine executor"
Note: Machine executors provide full virtualization and are ideal for complex builds or when specific system-level access is required.

4. Referencing Executors in Jobs

Property Description Example
executor Name of the executor to use in a job executor: my-executor

Example: Referencing an Executor in a Job

jobs:
  build:
    executor: my-executor
    steps:
      - checkout
      - run: echo "Running on executor"
Note: The executor must be defined in the executors section of the config file before it can be referenced in a job.

5. Parameterizing Executors

Parameter Type Description Default
executor string Name of the executor to use Required
parameters map Map of parameter names to values Empty map

Example: Parameterized Executor

executors:
  node-executor:
    parameters:
      node-version:
        type: string
        default: "18"
    docker:
      - image: cimg/node:<%= parameters.node-version %>

Example: Using Parameterized Executor

jobs:
  test:
    executor:
      name: node-executor
      parameters:
        node-version: "20"

6. Using Executor Parameters

Parameter Type Description Default
name string Name of the executor parameter None
type string Type of the parameter (e.g., string, number, boolean) string
default any Default value if not overridden None
description string Description for documentation purposes None

Example: Defining Executor Parameters

executors:
  my-executor:
    parameters:
      node-version:
        type: string
        default: "18"
        description: "Version of Node.js to use"
      memory-limit:
        type: number
        default: 2048
        description: "Memory limit in MB"
    docker:
      - image: circleci/node:<%= parameters.node-version %>
        environment:
          MEMORY_LIMIT: <%= parameters.memory-limit %>

Example: Using Executor Parameters in Jobs

jobs:
  build:
    executor:
      name: my-executor
      parameters:
        node-version: "20"
        memory-limit: 4096
Note: Executor parameters are resolved at job runtime and support interpolation using <%= parameters.<param-name> %>.

7. Setting Default Parameter Values

Parameter Default Value Description
executor.name default Name of the executor to use
executor.image circleci/python:3.9 Docker image to use for the executor
executor.resource_class medium Resource class for the executor (e.g., medium, large)

Example: Setting Default Parameter Values

executors:
  my-executor:
    docker:
      - image: circleci/python:3.9
        resource_class: medium
    parameters:
      python-version:
        type: string
        default: "3.9"

8. Overriding Executor Settings

Setting Description Values Notes
name Unique identifier for the executor string Required when defining a custom executor
environment Environment variables to set in the executor map<string, string> Can override or append to parent executor
resource_class Resource class to use for the executor string Can override parent resource class
working_directory Working directory for the executor string Can override parent working directory
shell Shell to use for commands in the executor string Can override parent shell setting

Example: Overriding Environment Variables

executors:
  my-executor:
    environment:
      NODE_ENV: production
      CUSTOM_VAR: value
    resource_class: large
    working_directory: /app
    shell: /bin/bash

  overridden-executor:
    name: my-executor
    environment:
      NODE_ENV: development
      CUSTOM_VAR: overridden_value

9. Combining Executors with Resource Classes

Resource Class Description Usage in Executor
medium Standard resource class with 2 vCPUs and 4GB RAM resource_class: medium
large High-performance resource class with 4 vCPUs and 8GB RAM resource_class: large
xlarge High-memory resource class with 8 vCPUs and 16GB RAM resource_class: xlarge
2xlarge Ultra-high-memory resource class with 16 vCPUs and 32GB RAM resource_class: 2xlarge

Example: Using Resource Class in Executor

executors:
  node-executor:
    docker:
      - image: circleci/node:18
    resource_class: large

workflows:
  version: 2
  build:
    jobs:
      - test:
          executor: node-executor
Note: Resource classes can be specified at the job level or within an executor definition. When defined in an executor, they apply to all jobs using that executor.

10. Sharing Executors Across Jobs

Property Description Usage
executor Reference to a reusable executor defined in the config executor: my-executor

Example: Using a Shared Executor

version: 2.1
executors:
  my-executor:
    docker:
      - image: circleci/node:16
        environment:
          NODE_ENV: test

jobs:
  build:
    executor: my-executor
    steps:
      - checkout
      - run: npm install

Was this article helpful?

Related Cheat Sheets