CircleCI Logo
Navigation Menu Icon

Migrate from GitLab

Language Icon 1 month ago · 6 min read
Cloud Server v4+
Contribute Go to Code

This document provides an overview of how to migrate from GitLab to CircleCI.

The CircleCI configuration translator provides a way to convert your GitHub Actions or GitLab config into a CircleCI config.yml file. The configuration translator is currently in open preview.

Tips provided by ImagineX Consulting

Sign up with GitLab

Follow the steps on the Sign Up and Try page to connect your GitLab account with CircleCI, then follow the steps in the following sections to migrate your CI/CD setup to CircleCI.

Build configuration

If you are using GitLab’s CI/CD, you will need to migrate your build configuration. On GitLab, the build configuration is defined in a file called .gitlab-ci.yml in the root directory of your source code repository. If you use shell scripts to perform your build, you can reuse those scripts in CircleCI.

First, create a CircleCI build configuration file. In the root directory of your source code repository, create a folder named .circleci and create a file in that folder named config.yml. Next, follow the CircleCI documentation here to learn how to configure the .config.yml file.

The GitLab and CircleCI configurations will be different. It may be helpful to have both GitLab and CircleCI reference documentation open side-by-side to help with the conversion of the build steps:

Configuration comparison

Using Docker? Authenticating Docker pulls from image registries is recommended when using the Docker execution environment. Authenticated pulls allow access to private Docker images, and may also grant higher rate limits, depending on your registry provider. For further information see Using Docker authenticated pulls.
GitLab CircleCI

Defining a job that executes a single build step

 
job1:
  script: "execute-script-for-job1"
yaml
 
jobs:
  job1:
    steps:
      - checkout
      - run: "execute-script-for-job1"
yaml

Specify a Docker image to use for a job.

 
job1:
  image: node:10
yaml
 
jobs:
  job1:
    docker:
      - image: node:10
yaml

Define a multi-stage build pipeline. Job1 and Job2 run concurrently. Once they are done, Job3 runs. Once Job3 is done, Job4 runs.

 
job1:
  stage: build
  script: make build dependencies

job2:
  stage: build
  script: make build artifacts

job3:
  stage: test
  script: make test

job4:
  stage: deploy
  script: make deploy

stages:
  - build
  - test
  - deploy
yaml
 
version: 2.1
jobs:
  job1:
    steps:
      - checkout
      - run: make build dependencies
  job2:
    steps:
      - run: make build artifacts
  job3:
    steps:
      - run: make test
  job4:
    steps:
      - run: make deploy

workflows:
  jobs:
    - job1
    - job2
    - job3:
        requires:
          - job1
          - job2
    - job4:
        requires:
          - job3
yaml

Execute jobs on multiple platforms. GitLab uses tags to identify build runners. CircleCI provides all major OSes and Docker and must explicitly set in config. See our execution environments documentation for more information.

 
ubuntu job:
  tags:
    - ubuntu
  script:
    - echo "Hello, $USER!"

osx job:
  tags:
    - osx
  script:
    - echo "Hello, $USER!"
yaml
 
jobs:
  ubuntu-job:
    machine:
      # The image uses the current tag, which always points to the most recent
      # supported release. If stability and determinism are crucial for your CI
      # pipeline, use a release date tag with your image, e.g. ubuntu-2004:202201-02
      ubuntu-2004:current
    steps:
      - checkout
      - run: echo "Hello, $USER!"
  osx-job:
    macos:
      xcode: 14.2.0
    steps:
      - checkout
      - run: echo "Hello, $USER!"
yaml

Cache Dependencies.

 
image: node:latest

# Cache modules in between jobs
cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/

before_script:
  - npm install

test_async:
  script:
    - node ./specs/start.js
yaml
 
jobs:
  test_async:
    steps:
      - restore_cache:
          key: source-v1-{{ checksum "package.json" }}
      - checkout
      - run: npm install
      - save_cache:
          key: source-v1-{{ checksum "package.json" }}
          paths:
            - node_modules
      - run: node ./specs/start.js
yaml

For larger and more complex build files, we recommend moving over the build steps in phases until you get comfortable with the CircleCI platform. We recommend this order:

  1. Pick your executor

  2. Checkout code

  3. Environment variables and Contexts

  4. Install dependencies, also see Cache dependencies

  5. Service containers

  6. Run testing commands

  7. Custom convenience images

  8. Resource classes

  9. Workflows

  10. Test results / test splitting / parallelism

  11. Artifacts