CircleCI Provider

The CircleCI provider generates native CircleCI configuration from cigen’s universal format and validates step references against provider capabilities.

Basic Configuration

Basic CircleCI configuration

provider: circleci
output_path: .circleci
output_filename: config.yml

CircleCI Notes

• setup: true or dynamic: true in config enables CircleCI setup workflows.
• docker_images mapping can resolve architecture-specific image variants.

Advanced Git Checkout

By default, cigen performs a fast, shallow git checkout using a vendored shallow_checkout command. Checkout behavior can be configured globally, per workflow, or per job via a checkout section.

Config precedence: job > workflow > global > defaults.

Note

Cigen automatically inserts the checkout step at the start of every job. Do not add your own checkout/shallow_checkout step in job definitions.

Parameters:

• shallow (boolean, default: true): when false, use CircleCI’s standard checkout step
• clone_options (string): options for initial clone (e.g., --depth 1 --verbose)
• fetch_options (string): options for git fetch (e.g., --depth 10)
• tag_fetch_options (string): options for fetching tags (default --tags)
• keyscan (map): booleans to add SSH host keys, keys: github, gitlab, bitbucket
• path (string): checkout directory

Disable checkout entirely by setting checkout: false at global/workflow/job scope.

Global example:

checkout:
    shallow: true
    clone_options: "--depth 1"
    fetch_options: "--depth 10"
    tag_fetch_options: "--tags"
    keyscan:
      github: true
      gitlab: false
      bitbucket: false
    path: "."

Job override example:

jobs:
  build:
    image: cimg/node:20.11
    checkout:
      shallow: true
      fetch_options: "--depth 50 --no-tags"
    steps:
      - run: npm run build

Generated output (simplified):

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

If you specify any parameters, it emits the parameterized form:

steps:
  - shallow_checkout:
      fetch_options: --depth 50 --no-tags
      keyscan_github: true
      path: .

Set shallow: false to use the standard CircleCI checkout step, optionally with a path parameter.

Multi-Architecture Jobs

Multi-architecture builds

jobs:
build_image:
  image: cimg/base:stable
  architectures: [amd64, arm64]  # Creates separate jobs
  steps:
    - run: docker build -t myapp:latest .

# Generated output:

jobs:
build_image_amd64:
docker: - image: cimg/base:stable
resource_class: medium

build_image_arm64:
docker: - image: cimg/base:stable
resource_class: arm.medium

Cigen automatically creates separate jobs per architecture and maintains dependencies.

Approval Jobs

You can reference CircleCI approval jobs in your own config, and cigen will pass them through in generated YAML. API-based helpers are planned.

Advanced Features

OR Dependencies

CircleCI does not support OR dependencies. Cigen does not yet synthesize shims for this; it’s on the roadmap.

Dynamic Configuration

Dynamic configuration

setup: true  # or dynamic: true

parameters:
run_tests:
type: boolean
default: false
description: 'Whether to run test jobs'

deploy_environment:
type: enum
enum: [staging, production]
default: staging

Enables CircleCI’s dynamic configuration features:

• Conditional workflow execution
• Setup workflows that determine which jobs to run
• Parameter-driven job execution

Context Support

CircleCI contexts

jobs:
deploy_production:
  image: cimg/base:stable
  context:
    - production-secrets
    - aws-credentials
  steps:
    - run: ./deploy.sh

Maps directly to CircleCI contexts for environment-specific secrets and variables.

Built-in Template Commands

Currently available:

• continue_circleci_pipeline — continue a setup workflow using the CircleCI continuation API
• shallow_checkout — fast shallow git checkout with configurable options

Environment Variables

Common CircleCI variables like CIRCLE_SHA1, CIRCLE_BUILD_URL, etc. are available in jobs, as provided by CircleCI.

Validation

The generator automatically validates configurations:

1. Schema validation against CircleCI requirements 2. CircleCI CLI validation if circleci command is available: bash circleci config validate .circleci/config.yml 3. Dependency graph validation for circular references 4. Resource class compatibility checking

Limitations

• OR-dependencies: not supported
• Approval-status patching: not implemented
• Resource-class mapping between architectures: not implemented

Best Practices

Configuration Organization

CircleCI best practices

# Use contexts for environment-specific secrets
jobs:
deploy_staging:
  context: [staging-secrets]
deploy_production:
  context: [production-secrets]

# Use setup/dynamic config when you need to compute a next-stage config

setup: true

Resource Class Mapping

Currently, resource classes are passed through as provided.

Checkout Migration

• Remove manual checkout steps from job definitions; cigen inserts checkout automatically.
• If a job requires full history, set checkout.shallow: false at the job/workflow/global level.
• Move any custom clone/fetch/tag options under the checkout section rather than custom run steps.

Cache Configuration

CircleCI cache patterns

# Leverage CircleCI's cache restoration patterns
cache:
gems:
  # Automatic fallback keys for partial matches
  # Key: gems-ruby3.3.0-abc123
  # Fallback: gems-ruby3.3.0-
  # Fallback: gems-ruby3.3.0
  checksum_sources: [Gemfile.lock]
  paths: [vendor/bundle]

Migration from CircleCI YAML

When migrating existing CircleCI configurations:

1. Convert docker arrays to separate image and services sections 2. Optionally replace manual cache steps with cache: [type] definitions 3. Move commands to separate files in commands/ directory 4. Convert approval jobs to type: approval 5. Add schema validation with $schema property

Example Migration

CircleCI migration example

# Before (CircleCI YAML)
version: 2.1
jobs:
test:
  docker:
    - image: cimg/ruby:3.3
    - image: postgres:15
      environment:
        POSTGRES_PASSWORD: test
  steps:
    - checkout
    - restore_cache:
        keys:
          - gems-{{ checksum "Gemfile.lock" }}
    - run: bundle install
    - save_cache:
        key: gems-{{ checksum "Gemfile.lock" }}
        paths: [vendor/bundle]

# After (Cigen format)

$schema: https://cigen.dev/schemas/v1/config-schema.json
provider: circleci

services:
postgres:
image: postgres:15
environment:
POSTGRES_PASSWORD: test

jobs:
test:
image: cimg/ruby:3.3
services: [postgres]
cache: gems
steps: - run: bundle install

The cigen version is cleaner, more maintainable, and includes automatic optimizations like intelligent cache key generation and service container management.