Basic Usage Examples

Here are common patterns and examples to help you get started with cigen.

Simple Test Job

The most basic cigen configuration:

.cigen/config.yml

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

provider: circleci
output_path: .circleci

jobs:
  test:
    image: cimg/node:18.0
    steps:
      - run:
          name: Install dependencies
          command: npm install
      - run:
          name: Run tests
          command: npm test

workflows:
  main:
    jobs:
      - test

Generates a complete CircleCI configuration with proper job and workflow structure.

Multi-Job Workflow

Multi-job pipeline

jobs:
  install:
    image: cimg/node:18.0
    cache: node_modules
    steps:
      - run: npm install

  lint:
    image: cimg/node:18.0
    cache: node_modules
    requires: [install]
    steps:
      - run: npm run lint

  test:
    image: cimg/node:18.0
    cache: node_modules
    requires: [install]
    steps:
      - run: npm test

  build:
    image: cimg/node:18.0
    cache: node_modules
    requires: [lint, test]
    steps:
      - run: npm run build

workflows:
  main:
    jobs:
      - install
      - lint:
          requires: [install]
      - test:
          requires: [install]
      - build:
          requires: [lint, test]

Service Dependencies

Using service containers

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: testuser
      POSTGRES_PASSWORD: testpass
      POSTGRES_DB: testdb
  redis:
    image: redis:7

jobs:
  integration_test:
    image: cimg/ruby:3.3
    services: [postgres, redis]
    steps:
      - run: bundle install
      - run:
          name: Setup database
          command: |
            bundle exec rails db:create
            bundle exec rails db:migrate
      - run: bundle exec rspec spec/integration/

Multi-Architecture Builds

Multi-architecture Docker builds

jobs:
  build_image:
    image: cimg/base:stable
    architectures: [amd64, arm64]
    steps:
      - run:
          name: Build Docker image
          command: |
            docker build -t myapp:latest-${CIRCLE_JOB##*_} .
            docker push myapp:latest-${CIRCLE_JOB##*_}

workflows:
  build:
    jobs:
      - build_image

# Generates:
# - build_image_amd64 (resource_class: medium)
# - build_image_arm64 (resource_class: arm.medium)

Intelligent Job Skipping

Skip jobs when files haven't changed

source_file_groups:
  backend: ['src/**/*.py', 'requirements.txt', 'pyproject.toml']
  frontend: ['web/**/*.js', 'web/**/*.css', 'package.json']
  docs: ['docs/**/*.md', 'mkdocs.yml']

jobs:
  test_backend:
    image: cimg/python:3.11
    source_files: '@backend'
    steps:
      - run: pip install -r requirements.txt
      - run: pytest

  test_frontend:
    image: cimg/node:18.0
    source_files: '@frontend'
    steps:
      - run: npm install
      - run: npm test

  build_docs:
    image: cimg/python:3.11
    source_files: '@docs'
    steps:
      - run: pip install mkdocs
      - run: mkdocs build

Approval Workflows

Manual approval gates

jobs:
  test:
    image: cimg/node:18.0
    steps:
      - run: npm test

approve_deploy:
  type: approval
  requires: [test]

deploy_staging:
  image: cimg/base:stable
  requires: [approve_deploy]
  steps:
    - run: ./deploy.sh staging

deploy_production:
  image: cimg/base:stable
  requires: [approve_deploy]
  context: [production-secrets]
  steps:
    - run: ./deploy.sh production

OR Dependencies

OR dependency logic

jobs:
  build_app:
    image: cimg/base:stable
    requires_any:
      - manual_approval
      - scheduled_trigger
      - hotfix_trigger
    steps:
      - run: ./build.sh

manual_approval:
  type: approval

scheduled_trigger:
  image: cimg/base:stable  # Could be triggered by schedule or other conditions
  steps:
    - run: echo "Scheduled build trigger"

# Cigen automatically creates shim jobs to make OR logic work

Custom Commands

Command Definition

commands/deploy.yml

# commands/deploy.yml
parameters:
  environment:
    type: string
    default: staging

steps:
  - run:
      name: Deploy to << parameters.environment >>
      command: |
        echo "Deploying to << parameters.environment >>"
        ./scripts/deploy.sh << parameters.environment >>
  - run:
      name: Verify deployment
      command: |
        curl -f https://api-<< parameters.environment >>.example.com/health

Using Command

Using custom command

jobs:
  deploy_staging:
    image: cimg/base:stable
    steps:
      - deploy:
          environment: staging

  deploy_production:
    image: cimg/base:stable
    context: [production-secrets]
    steps:
      - deploy:
          environment: production

Environment-Specific Configuration

Environment-specific deployments

# Global configuration
vars:
  app_name: myapp
  version: "1.0.0"

# Environment-specific jobs
jobs:
  deploy_staging:
    image: cimg/base:stable
    context: [staging-secrets]
    environment:
      ENVIRONMENT: staging
      API_URL: https://api-staging.example.com
    steps:
      - run: ./deploy.sh

  deploy_production:
    image: cimg/base:stable
    context: [production-secrets]
    environment:
      ENVIRONMENT: production
      API_URL: https://api.example.com
    steps:
      - run: ./deploy.sh

Complex Cache Configuration

ML pipeline with model caching

cache_definitions:
  ml_models:
    versions: [python]
    checksum_sources:
      - requirements-ml.txt
      - models/config.json
    paths:
      - models/cache
      - ~/.cache/torch

jobs:
  train_model:
    image: cimg/python:3.11
    resource_class: gpu.large
    cache: [pip, ml_models]
    steps:
      - run: pip install -r requirements-ml.txt
      - run: python train.py

  inference_test:
    image: cimg/python:3.11
    cache: [ml_models]  # Reuse cached models
    requires: [train_model]
    steps:
      - run: python test_inference.py

Full-Stack Application

Complete full-stack application

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: testpass
  redis:
    image: redis:7

source_file_groups:
  backend: ['api/**/*.py', 'requirements.txt']
  frontend: ['web/**/*', 'package.json', 'webpack.config.js']
  shared: ['shared/**/*', 'docker-compose.yml']

jobs:
  test_backend:
    image: cimg/python:3.11
    services: [postgres, redis]
    source_files: ['@backend', '@shared']
    cache: pip
    steps:
      - run: pip install -r requirements.txt
      - run: pytest api/

  test_frontend:
    image: cimg/node:18.0
    source_files: ['@frontend', '@shared']
    cache: node_modules
    steps:
      - run: npm install
      - run: npm test

  build_images:
    image: cimg/base:stable
    architectures: [amd64, arm64]
    requires: [test_backend, test_frontend]
    steps:
      - run: docker build -t myapp:backend-latest .
      - run: docker build -f Dockerfile.frontend -t myapp:frontend-latest .

workflows:
  full_pipeline:
    jobs:
      - test_backend
      - test_frontend
      - build_images:
          requires: [test_backend, test_frontend]

Tips for Getting Started

Start Simple

Begin with a single job, then gradually add complexity as you understand the patterns.

Use Built-in Caches

Leverage cache: gems, cache: node_modules instead of manual cache steps.

Enable Job Skipping

Add source_files to jobs that can be skipped when unchanged.

Validate Early

Use cigen validate frequently to catch configuration errors early.

Next Steps

• Explore advanced features like OR dependencies
• Learn about CircleCI-specific features
• Read about intelligent caching
• Understand job skipping for maximum efficiency