Migrating to CircleCI

1. Migrating from Jenkins

Feature	CircleCI Equivalent	Notes
Pipeline Definition	`config.yml`	YAML-based configuration file
Build Environment	Orbs & Executors	Pre-configured environments for common tasks
Job Scheduling	Scheduled Workflows	Support for cron-like triggers
Notifications	Webhooks & Email	Configurable notification methods
Artifacts	Store Artifacts	Store and retrieve build artifacts

Example: Basic Pipeline Migration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
      - run: npm test

workflows:
  version: 2
  build-and-test:
    jobs:
      - build

Migration Considerations

Jenkins pipelines are Groovy-based; CircleCI uses YAML
CircleCI orbs simplify configuration but require learning new syntax
Scheduling in CircleCI uses workflows, not cron jobs
Artifacts are stored differently; use store_artifacts step

2. Migrating from Travis CI

Travis CI Feature	CircleCI Equivalent	Notes
.travis.yml	`config.yml`	Configuration file format changed
language	`docker` or `executor`	CircleCI uses executors for runtime environments
script	`steps`	Steps replace the single script section
env	`environment`	Environment variables are managed differently
branches	`filters`	Filtering logic is more granular in CircleCI

Example: Basic Migration

# Travis CI
language: node_js
node_js:
  - "14"
script:
  - npm test
env:
  - NODE_ENV=test

# CircleCI
version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:14
    steps:
      - checkout
      - run:
          name: Run tests
          command: npm test
      - run:
          name: Set environment
          command: echo "NODE_ENV=test"

Key Differences

Configuration: Travis CI uses .travis.yml, CircleCI uses config.yml
Execution: Travis CI runs in a single environment, CircleCI uses containers/VMs
Steps: Travis CI has a single script section, CircleCI uses steps
Environment: Travis CI sets environment variables in env, CircleCI uses environment

Note: CircleCI supports a version: 2.1 configuration that allows for more complex workflows and reusability.

Warning: Not all Travis CI features are directly supported in CircleCI. Some features may require custom scripts or alternative approaches.

3. Migrating from GitHub Actions

GitHub Actions	CircleCI Equivalent	Notes
workflow_dispatch	`circleci config process`	CircleCI uses config processing for workflow triggers
on: push	`workflows` with `triggers`	CircleCI uses triggers to define when workflows run
jobs	`steps`	CircleCI uses steps instead of jobs for execution units

Example: Migrating a simple job

# GitHub Actions
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: npm install
      - run: npm test

# CircleCI
workflows:
  build:
    jobs:
      - build:
          steps:
            - checkout
            - run: npm install
            - run: npm test

Key Differences

Configuration: GitHub Actions uses YAML in .github/workflows, CircleCI uses config.yml
Execution: GitHub Actions uses jobs, CircleCI uses steps
Triggers: GitHub Actions uses on:, CircleCI uses triggers

4. Migrating from GitLab CI

Feature	GitLab CI	CircleCI	Notes
Pipeline Configuration	`.gitlab-ci.yml`	`config.yml`	CircleCI uses a single config file in the `.circleci` directory
Job Definition	`job_name:` block	`jobs:` section with `steps:`	CircleCI jobs are defined in a more structured way
Runner	GitLab Runner	CircleCI orbs or self-hosted executors	CircleCI uses orbs for reusable configuration

Example: Basic Pipeline Migration

# GitLab CI
test:
  stage: test
  script:
    - npm install
    - npm test

# CircleCI
version: 2.1
jobs:
  test:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: npm install
      - run:
          name: Run tests
          command: npm test

Key Differences

Configuration File: GitLab CI uses .gitlab-ci.yml, while CircleCI uses config.yml in the .circleci directory
Job Structure: GitLab CI uses stage and script, CircleCI uses steps with explicit commands
Orbs: CircleCI provides orbs for common workflows, while GitLab CI uses templates or custom scripts
Parallelism: CircleCI supports parallel jobs natively, while GitLab CI requires manual configuration

Migration Steps

Review existing GitLab CI configuration
Create .circleci/config.yml with equivalent jobs
Use CircleCI orbs where applicable to reduce configuration complexity
Test the new pipeline in a development branch
Update project settings to use CircleCI instead of GitLab CI

5. Converting Pipeline Syntax

Old Syntax	New Syntax	Notes
version: 2	version: 2.1	Upgrade to version 2.1 for enhanced features and better support
jobs:	jobs:	Structure remains the same, but new capabilities added
steps:	steps:	Steps syntax is preserved but extended

Example: Converting from v2 to v2.1

version: 2
jobs:
  build:
    docker:
      - image: circleci/node:14
    steps:
      - checkout
      - run: npm install
      - run: npm test

# Convert to:
version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:14
    steps:
      - checkout
      - run: npm install
      - run: npm test

Note: Version 2.1 introduces orbs, better caching, and enhanced configuration capabilities.

Warning: Ensure all jobs and steps are compatible with v2.1 syntax before migration.

6. Mapping Environment Variables

Environment Variable	CircleCI Equivalent	Description
CIRCLE_BUILD_NUM	`CIRCLE_BUILD_NUM`	Unique identifier for the build
CIRCLE_SHA1	`CIRCLE_SHA1`	Git commit SHA of the current build
CIRCLE_BRANCH	`CIRCLE_BRANCH`	Branch name for the current build
CIRCLE_TAG	`CIRCLE_TAG`	Tag name if the build was triggered by a tag
CIRCLE_USERNAME	`CIRCLE_USERNAME`	Username of the user who triggered the build
CIRCLE_PROJECT_REPONAME	`CIRCLE_PROJECT_REPONAME`	Name of the repository
CIRCLE_REPOSITORY_URL	`CIRCLE_REPOSITORY_URL`	URL of the repository
CIRCLE_BUILD_URL	`CIRCLE_BUILD_URL`	URL to the CircleCI build page

Example: Using Environment Variables in Config

version: 2.1
jobs:
  build:
    steps:
      - run:
          name: "Print Build Info"
          command: |
            echo "Build Number: $CIRCLE_BUILD_NUM"
            echo "Commit SHA: $CIRCLE_SHA1"
            echo "Branch: $CIRCLE_BRANCH"

7. Migrating Secrets

Secret Type	Migration Method	Notes
Environment Variables	Use `circleci env set` CLI command or CircleCI web UI	Available in all jobs and workflows
Project API Tokens	Recreate in CircleCI project settings	Replace old tokens in configuration files
SSH Keys	Upload via CircleCI web UI under Project Settings > SSH Keys	Used for accessing private repositories or servers
AWS Credentials	Use `circleci env set` or AWS integration in CircleCI	Ensure proper IAM roles and permissions are set up

Example: Setting Environment Variables

circleci env set DATABASE_URL &quot;postgres://user:pass@host:port/db&quot;
circleci env set API_KEY &quot;your-api-key-here&quot;

Note: Ensure that sensitive data is not committed to version control during migration.

Warning: Do not use hardcoded secrets in configuration files.

8. Adapting Build Scripts

Aspect	Description	Migration Notes
Build Steps	CircleCI uses orbs and configuration as code (YAML) to define build steps.	Replace shell scripts with YAML-based job definitions using `steps`.
Environment Setup	CircleCI supports setting environment variables, installing dependencies, and running commands.	Use `environment` or `steps` to configure environment variables and dependencies.
Caching	CircleCI provides caching for dependencies to speed up builds.	Implement `restore_cache` and `save_cache` steps in your config.
Workflows	CircleCI workflows define the order and execution of jobs.	Define `workflows` in your config to orchestrate jobs.

Example: Migrating a Simple Build Script

# Before: Shell script
npm install
npm test
npm run build

# After: CircleCI config (config.yml)
version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: npm install
      - run:
          name: Run tests
          command: npm test
      - run:
          name: Build project
          command: npm run build

Note: Ensure all commands in your build script are translated into CircleCI steps. Use orbs for common tasks to reduce configuration complexity.

9. Using Migration Tools

Example: Migrating from Travis CI to CircleCI

# .travis.yml
language: node_js
node_js:
  - "14"
script:
  - npm test

Example: Equivalent CircleCI Configuration

# .circleci/config.yml
version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:14
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: npm install
      - run:
          name: Run tests
          command: npm test

Tool	Description	Migration Type	Status
CircleCI Migration Assistant	Automated tool to analyze and suggest config changes	Config Analysis	NEW
Travis CI to CircleCI Converter	Converts Travis CI config to CircleCI format	Config Conversion	BETA
Manual Migration Script	Custom scripts to migrate artifacts and workflows	Workflow Migration	DEPRECATED

Note: The Migration Assistant is available in CircleCI v2.1 and later.

Warning: Manual migration scripts may require updates to handle new features or deprecated syntax.

Migration Steps Overview

Review existing CI configuration files
Use the Migration Assistant to identify changes
Update job definitions and steps
Test workflows in CircleCI environment

10. Testing Migration Incrementally

Migration Workflow

Set up a new CircleCI project for your repository
Configure the project to use the new configuration file (e.g., .circleci/config.yml)
Run a subset of your existing tests in parallel with the old system to compare results
Gradually increase test coverage in the new environment
Monitor for any discrepancies or failures in test execution
Once confident, fully migrate to CircleCI and decommission the old system

Migration Step	Description	Notes
Project Setup	`circleci config validate`	Validates the new configuration file before running tests
Test Execution	`circleci build`	Builds and runs tests in the new environment
Parallel Execution	`circleci job build`	Runs jobs in parallel to simulate real-world usage

Old vs New Test Environments

Old: Tests run on Jenkins with custom scripts
New: Tests run on CircleCI with YAML configuration

Example: Running Tests in Parallel

version: 2.1
jobs:
  test:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Run Tests
          command: npm test
      - run:
          name: Parallel Test Execution
          command: |
            circleci job build --job test --parallel 4

Migrating to CircleCI

1. Migrating from Jenkins

Example: Basic Pipeline Migration

Migration Considerations

2. Migrating from Travis CI

Example: Basic Migration

Key Differences

3. Migrating from GitHub Actions

Example: Migrating a simple job

Key Differences

4. Migrating from GitLab CI

Example: Basic Pipeline Migration

Key Differences

Migration Steps

5. Converting Pipeline Syntax

Example: Converting from v2 to v2.1

6. Mapping Environment Variables

Example: Using Environment Variables in Config

7. Migrating Secrets

Example: Setting Environment Variables

8. Adapting Build Scripts

Example: Migrating a Simple Build Script

9. Using Migration Tools

Example: Migrating from Travis CI to CircleCI

Example: Equivalent CircleCI Configuration

Migration Steps Overview

10. Testing Migration Incrementally

Migration Workflow

Old vs New Test Environments

Example: Running Tests in Parallel

Was this article helpful?

Related Cheat Sheets

Working with Kubernetes Integration

Implementing WebSocket Support

Managing CGI Script Execution

Using Terraform CDK