Migrating from CircleCI (FREE)
If you are currently using CircleCI, you can migrate your CI/CD pipelines to GitLab CI/CD, and start making use of all its powerful features. Check out our CircleCI vs GitLab comparison to see what's different.
We have collected several resources that you may find useful before starting to migrate.
The Quick Start Guide is a good overview of how GitLab CI/CD works. You may also be interested in Auto DevOps which can be used to build, test, and deploy your applications with little to no configuration needed at all.
For advanced CI/CD teams, custom project templates can enable the reuse of pipeline configurations.
If you have questions that are not answered here, the GitLab community forum can be a great resource.
config.yml configuration file defines scripts, jobs, and workflows (known as "stages" in GitLab). In GitLab, a similar approach is used with a
.gitlab-ci.yml file in the root directory of your repository.
In CircleCI, jobs are a collection of steps to perform a specific task. In GitLab, jobs are also a fundamental element in the configuration file. The
checkout keyword is not necessary in GitLab CI/CD as the repository is automatically fetched.
CircleCI example job definition:
jobs: job1: steps: - checkout - run: "execute-script-for-job1"
Example of the same job definition in GitLab CI/CD:
job1: script: "execute-script-for-job1"
Docker image definition
CircleCI defines images at the job level, which is also supported by GitLab CI/CD. Additionally, GitLab CI/CD supports setting this globally to be used by all jobs that don't have
CircleCI example image definition:
jobs: job1: docker: - image: ruby:2.6
Example of the same image definition in GitLab CI/CD:
job1: image: ruby:2.6
CircleCI determines the run order for jobs with
workflows. This is also used to determine concurrent, sequential, scheduled, or manual runs. The equivalent function in GitLab CI/CD is called stages. Jobs on the same stage run in parallel, and only run after previous stages complete. Execution of the next stage is skipped when a job fails by default, but this can be allowed to continue even after a failed job.
See the Pipeline Architecture Overview for guidance on different types of pipelines that you can use. Pipelines can be tailored to meet your needs, such as for a large complex project or a monorepo with independent defined components.
Parallel and sequential job execution
The following examples show how jobs can run in parallel, or sequentially:
job2run in parallel (in the
buildstage for GitLab CI/CD).
job3runs only after
job2complete successfully (in the
job4runs only after
job3completes successfully (in the
CircleCI example with
version: 2 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: version: 2 jobs: - job1 - job2 - job3: requires: - job1 - job2 - job4: requires: - job3
Example of the same workflow as
stages in GitLab CI/CD:
stages: - build - test - deploy job 1: stage: build script: make build dependencies job 2: stage: build script: make build artifacts job3: stage: test script: make test job4: stage: deploy script: make deploy
CircleCI example of a scheduled workflow:
commit-workflow: jobs: - build scheduled-workflow: triggers: - schedule: cron: "0 1 * * *" filters: branches: only: try-schedule-workflow jobs: - build
Example of the same scheduled pipeline using
rules in GitLab CI/CD:
job1: script: - make build rules: - if: '$CI_PIPELINE_SOURCE == "schedule" && $CI_COMMIT_REF_NAME == "try-schedule-workflow"'
After the pipeline configuration is saved, you configure the cron schedule in the GitLab UI, and can enable or disable schedules in the UI as well.
CircleCI example of a manual workflow:
release-branch-workflow: jobs: - build - testing: requires: - build - deploy: type: approval requires: - testing
Example of the same workflow using
when: manual in GitLab CI/CD:
deploy_prod: stage: deploy script: - echo "Deploy to production server" when: manual
Filter job by branch
Rules are a mechanism to determine if the job runs for a specific branch.
CircleCI example of a job filtered by branch:
jobs: deploy: branches: only: - main - /rc-.*/
Example of the same workflow using
rules in GitLab CI/CD:
deploy_prod: stage: deploy script: - echo "Deploy to production server" rules: - if: '$CI_COMMIT_BRANCH == "main"'
GitLab provides a caching mechanism to speed up build times for your jobs by reusing previously downloaded dependencies. It's important to know the different between cache and artifacts to make the best use of these features.
CircleCI example of a job using a cache:
jobs: job1: steps: - restore_cache: key: source-v1-< .Revision > - checkout - run: npm install - save_cache: key: source-v1-< .Revision > paths: - "node_modules"
Example of the same pipeline using
cache in GitLab CI/CD:
image: node:latest # Cache modules in between jobs cache: key: $CI_COMMIT_REF_SLUG paths: - .npm/ before_script: - npm ci --cache .npm --prefer-offline test_async: script: - node ./specs/start.js ./specs/async.spec.js
Contexts and variables
CircleCI provides Contexts to securely pass environment variables across project pipelines. In GitLab, a Group can be created to assemble related projects together. At the group level, CI/CD variables can be stored outside the individual projects, and securely passed into pipelines across multiple projects.
There are two GitLab issues open addressing CircleCI Orbs and how GitLab can achieve similar functionality.
executors as the underlying technology to run a specific job. In GitLab, this is done by runners.
The following environments are supported:
GitLab.com shared runners:
- Planned: macOS
Machine and specific build environments
Tags can be used to run jobs on different platforms, by telling GitLab which runners should run the jobs.
CircleCI example of a job running on a specific environment:
jobs: ubuntuJob: machine: image: ubuntu-1604:201903-01 steps: - checkout - run: echo "Hello, $USER!" osxJob: macos: xcode: 11.3.0 steps: - checkout - run: echo "Hello, $USER!"
Example of the same job using
tags in GitLab CI/CD:
windows job: stage: - build tags: - windows script: - echo Hello, %USERNAME%! osx job: stage: - build tags: - osx script: - echo "Hello, $USER!"