Migrating from Jenkins

If you’re migrating from Jenkins to GitLab CI/CD, you are able to create CI/CD pipelines that replicate and enhance your Jenkins workflows.

Key similarities and differences

GitLab CI/CD and Jenkins are CI/CD tools with some similarities. Both GitLab and Jenkins:

  • Use stages for collections of jobs.
  • Support container-based builds.

Additionally, there are some important differences between the two:

  • GitLab CI/CD pipelines are all configured in a YAML format configuration file. Jenkins uses either a Groovy format configuration file (declarative pipelines) or Jenkins DSL (scripted pipelines).
  • GitLab can run either on SaaS (cloud) or self-managed deployments. Jenkins deployments must be self-managed.
  • GitLab provides source code management (SCM) out of the box. Jenkins requires a separate SCM solution to store code.
  • GitLab provides a built-in container registry. Jenkins requires a separate solution for storing container images.
  • GitLab provides built-in templates for scanning code. Jenkins requires 3rd party plugins for scanning code.

Comparison of features and concepts

Many Jenkins features and concepts have equivalents in GitLab that offer the same functionality.

Configuration file

Jenkins can be configured with a Jenkinsfile in the Groovy format. GitLab CI/CD uses a .gitlab-ci.yml YAML file by default.

Example of a Jenkinsfile: 

pipeline {
    agent any

    stages {
        stage('hello') {
            steps {
                echo "Hello World"
            }
        }
    }
}

The equivalent GitLab CI/CD .gitlab-ci.yml file would be: 

stages:
  - hello

hello-job:
  stage: hello
  script:
    - echo "Hello World"

Jenkins pipeline syntax

A Jenkins configuration is composed of a pipeline block with “sections” and “directives”. GitLab CI/CD has similar functionality, configured with YAML keywords.

Sections

Jenkins GitLab Explanation
agent image Jenkins pipelines execute on agents, and the agent section defines how the pipeline executes, and the Docker container to use. GitLab jobs execute on runners, and the image keyword defines the container to use. You can configure your own runners in Kubernetes or on any host.
post after_script or stage The Jenkins post section defines actions that should be performed at the end of a stage or pipeline. In GitLab, use after_script for commands to run at the end of a job, and before_script for actions to run before the other commands in a job. Use stage to select the exact stage a job should run in. GitLab supports both .pre and .post stages that always run before or after all other defined stages.
stages stages Jenkins stages are groups of jobs. GitLab CI/CD also uses stages, but it is more flexible. You can have multiple stages each with multiple independent jobs. Use stages at the top level to the stages and their execution order, and use stage at the job level to define the stage for that job.
steps script Jenkins steps define what to execute. GitLab CI/CD uses a script section which is similar. The script section is a YAML array with separate entries for each command to run in sequence.

Directives

Jenkins GitLab Explanation
environment variables Jenkins uses environment for environment variables. GitLab CI/CD uses the variables keyword to define CI/CD variables that can be used during job execution, but also for more dynamic pipeline configuration. These can also be set in the GitLab UI, under CI/CD settings.
options Not applicable Jenkins uses options for additional configuration, including timeouts and retry values. GitLab does not need a separate section for options, all configuration is added as CI/CD keywords at the job or pipeline level, for example timeout or retry.
parameters Not applicable In Jenkins, parameters can be required when triggering a pipeline. Parameters are handled in GitLab with CI/CD variables, which can be defined in many places, including the pipeline configuration, project settings, at runtime manually through the UI, or API.
triggers rules In Jenkins, triggers defines when a pipeline should run again, for example through cron notation. GitLab CI/CD can run pipelines automatically for many reasons, including Git changes and merge request updates. Use the rules keyword to control which events to run jobs for. Scheduled pipelines are defined in the project settings.
tools Not applicable In Jenkins, tools defines additional tools to install in the environment. GitLab does not have a similar keyword, as the recommendation is to use container images prebuilt with the exact tools required for your jobs. These images can be cached and can be built to already contain the tools you need for your pipelines. If a job needs additional tools, they can be installed as part of a before_script section.
input Not applicable In Jenkins, input adds a prompt for user input. Similar to parameters, inputs are handled in GitLab through CI/CD variables.
when rules In Jenkins, when defines when a stage should be executed. GitLab also has a when keyword, which defines whether a job should start running based on the status of earlier jobs, for example if jobs passed or failed. To control when to add jobs to specific pipelines, use rules.

Common configurations

This section goes over commonly used CI/CD configurations, showing how they can be converted from Jenkins to GitLab CI/CD.

Jenkins pipelines generate automated CI/CD jobs that are triggered when certain event take place, such as a new commit being pushed. A Jenkins pipeline is defined in a Jenkinsfile. The GitLab equivalent is the .gitlab-ci.yml configuration file.

Jenkins does not provide a place to store source code, so the Jenkinsfile must be stored in a separate source control repository.

Jobs

Jobs are a set of commands that run in a set sequence to achieve a particular result.

For example, build a container then deploy it to production, in a Jenkinsfile: 

pipeline {
    agent any
    stages {
        stage('build') {
            agent { docker 'golang:alpine' }
            steps {
                apk update
                go build -o bin/hello
            }
            post {
              always {
                archiveArtifacts artifacts: 'bin/hello'
                onlyIfSuccessful: true
              }
            }
        }
        stage('deploy') {
            agent { docker 'golang:alpine' }
            when {
              branch 'staging'
            }
            steps {
                echo "Deploying to staging"
                scp bin/hello remoteuser@remotehost:/remote/directory
            }
        }
    }
}

This example:

  • Uses the golang:alpine container image.
  • Runs a job for building code.
    • Stores the built executable as an artifact.
  • Adds a second job to deploy to staging, which:
    • Only exists if the commit targets the staging branch.
    • Starts after the build stage succeeds.
    • Uses the built executable artifact from the earlier job.

The equivalent GitLab CI/CD .gitlab-ci.yml file would be: 

default:
  image: golang:alpine

stages:
  - build
  - deploy

build-job:
  stage: build
  script:
    - apk update
    - go build -o bin/hello
  artifacts:
    paths:
      - bin/hello
    expire_in: 1 week

deploy-job:
  stage: deploy
  script:
    - echo "Deploying to Staging"
    - scp bin/hello remoteuser@remotehost:/remote/directory
  rules:
    - if: $CI_COMMIT_BRANCH == 'staging'
  artifacts:
    paths:
      - bin/hello
Parallel

In Jenkins, jobs that are not dependent on previous jobs can run in parallel when added to a parallel section.

For example, in a Jenkinsfile: 

pipeline {
    agent any
    stages {
        stage('Parallel') {
            parallel {
                stage('Python') {
                    agent { docker 'python:latest' }
                    steps {
                        sh "python --version"
                    }
                }
                stage('Java') {
                    agent { docker 'openjdk:latest' }
                    when {
                        branch 'staging'
                    }
                    steps {
                        sh "java -version"
                    }
                }
            }
        }
    }
}

This example runs a Python and a Java job in parallel, using different container images. The Java job only runs when the staging branch is changed.

The equivalent GitLab CI/CD .gitlab-ci.yml file would be: 

python-version:
  image: python:latest
  script:
    - python --version

java-version:
  image: openjdk:latest
  rules:
    - if: $CI_COMMIT_BRANCH == 'staging'
  script:
    - java -version

In this case, no extra configuration is needed to make the jobs run in parallel. Jobs run in parallel by default, each on a different runner assuming there are enough runners for all the jobs. The Java job is set to only run when the staging branch is changed.

Matrix

In GitLab you can use a matrix to run a job multiple times in parallel in a single pipeline, but with different variable values for each instance of the job. Jenkins runs the matrix sequentially.

For example, in a Jenkinsfile: 

matrix {
    axes {
        axis {
            name 'PLATFORM'
            values 'linux', 'mac', 'windows'
        }
        axis {
            name 'ARCH'
            values 'x64', 'x86'
        }
    }
    stages {
        stage('build') {
            echo "Building $PLATFORM for $ARCH"
        }
        stage('test') {
            echo "Building $PLATFORM for $ARCH"
        }
        stage('deploy') {
            echo "Building $PLATFORM for $ARCH"
        }
    }
}

The equivalent GitLab CI/CD .gitlab-ci.yml file would be: 

stages:
  - build
  - test
  - deploy

.parallel-hidden-job:
  parallel:
    matrix:
      - PLATFORM: [linux, mac, windows]
        ARCH: [x64, x86]

build-job:
  extends: .parallel-hidden-job
  stage: build
  script:
    - echo "Building $PLATFORM for $ARCH"

test-job:
  extends: .parallel-hidden-job
  stage: test
  script:
    - echo "Testing $PLATFORM for $ARCH"

deploy-job:
  extends: .parallel-hidden-job
  stage: deploy
  script:
    - echo "Testing $PLATFORM for $ARCH"

Container Images

In GitLab you can run your CI/CD jobs in separate, isolated Docker containers using the image keyword.

For example, in a Jenkinsfile: 

stage('Version') {
    agent { docker 'python:latest' }
    steps {
        echo 'Hello Python'
        sh 'python --version'
    }
}

This example shows commands running in a python:latest container.

The equivalent GitLab CI/CD .gitlab-ci.yml file would be: 

version-job:
  image: python:latest
  script:
    - echo "Hello Python"
    - python --version

Variables

In GitLab, use the variables keyword to define CI/CD variables. Use variables to reuse configuration data, have more dynamic configuration, or store important values. Variables can be defined either globally or per job.

For example, in a Jenkinsfile: 

pipeline {
    agent any
    environment {
        NAME = 'Fern'
    }
    stages {
        stage('English') {
            environment {
                GREETING = 'Hello'
            }
            steps {
                sh 'echo "$GREETING $NAME"'
            }
        }
        stage('Spanish') {
            environment {
                GREETING = 'Hola'
            }
            steps {
                sh 'echo "$GREETING $NAME"'
            }
        }
    }
}

This example shows how variables can be used to pass values to commands in jobs.

The equivalent GitLab CI/CD .gitlab-ci.yml file would be: 

default:
  image: alpine:latest

stages:
  - greet

variables:
  NAME: "Fern"

english:
  stage: greet
  variables:
    GREETING: "Hello"
  script:
    - echo "$GREETING $NAME"

spanish:
  stage: greet
  variables:
    GREETING: "Hola"
  script:
    - echo "$GREETING $NAME"

Variables can also be set in the GitLab UI, in the CI/CD settings. In some cases, you can use protected and masked variables for secret values. These variables can be accessed in pipeline jobs the same as variables defined in the configuration file.

For example, in a Jenkinsfile: 

pipeline {
    agent any
    stages {
        stage('Example Username/Password') {
            environment {
                AWS_ACCESS_KEY = credentials('aws-access-key')
            }
            steps {
                sh 'my-login-script.sh $AWS_ACCESS_KEY'
            }
        }
    }
}

The equivalent GitLab CI/CD .gitlab-ci.yml file would be: 

login-job:
  script:
    - my-login-script.sh $AWS_ACCESS_KEY

Additionally, GitLab CI/CD makes predefined variables available to every pipeline and job which contain values relevant to the pipeline and repository.

Expressions and conditionals

When a new pipeline starts, GitLab checks which jobs should run in that pipeline. You can configure jobs to run depending on factors like the status of variables, or the pipeline type.

For example, in a Jenkinsfile: 

stage('deploy_staging') {
    agent { docker 'alpine:latest' }
    when {
        branch 'staging'
    }
    steps {
        echo "Deploying to staging"
    }
}

In this example, the job only runs when the branch we are committing to is named staging.

The equivalent GitLab CI/CD .gitlab-ci.yml file would be: 

deploy_staging:
  stage: deploy
  script:
    - echo "Deploy to staging server"
  rules:
    - if: '$CI_COMMIT_BRANCH == staging'

Runners

Like Jenkins agents, GitLab runners are the hosts that run jobs. If you are using GitLab.com, you can use the shared runner fleet to run jobs without provisioning your own runners.

To convert a Jenkins agent for use with GitLab CI/CD, uninstall the agent and then install and register a runner. Runners do not require much overhead, so you might be able to use similar provisioning as the Jenkins agents you were using.

Some key details about runners:

  • Runners can be configured to be shared across an instance, a group, or dedicated to a single project.
  • You can use the tags keyword for finer control, and associate runners with specific jobs. For example, you can use a tag for jobs that require dedicated, more powerful, or specific hardware.
  • GitLab has autoscaling for runners. Use autoscaling to provision runners only when needed and scale down when not needed.

For example, in a Jenkinsfile: 

pipeline {
    agent none
    stages {
        stage('Linux') {
            agent {
                label 'linux'
            }
            steps {
                echo "Hello, $USER"
            }
        }
        stage('Windows') {
            agent {
                label 'windows'
            }
            steps {
                echo "Hello, %USERNAME%"
            }
        }
    }
}

The equivalent GitLab CI/CD .gitlab-ci.yml file would be: 

linux_job:
  stage: build
  tags:
    - linux
  script:
    - echo "Hello, $USER"

windows_job:
  stage: build
  tags:
    - windows
  script:
    - echo "Hello, %USERNAME%"

Artifacts

In GitLab, any job can use the artifacts keyword to define a set of artifacts to be stored when a job completes. Artifacts are files that can be used in later jobs, for example for testing or deployment.

For example, in a Jenkinsfile: 

stages {
    stage('Generate Cat') {
        steps {
            sh 'touch cat.txt'
            sh 'echo "meow" > cat.txt'
        }
        post {
            always {
                archiveArtifacts artifacts: 'cat.txt'
                onlyIfSuccessful: true
            }
        }
    }
    stage('Use Cat') {
        steps {
            sh 'cat cat.txt'
        }
    }
  }

The equivalent GitLab CI/CD .gitlab-ci.yml file would be: 

stages:
  - generate
  - use

generate_cat:
  stage: generate
  script:
    - touch cat.txt
    - echo "meow" > cat.txt
  artifacts:
    paths:
      - cat.txt
    expire_in: 1 week

use_cat:
  stage: use
  script:
    - cat cat.txt
  artifacts:
    paths:
      - cat.txt

Caching

A cache is created when a job downloads one or more files and saves them for faster access in the future. Subsequent jobs that use the same cache don’t have to download the files again, so they execute more quickly. The cache is stored on the runner and uploaded to S3 if distributed cache is enabled. Jenkins core does not provide caching.

For example, in a .gitlab-ci.yml file: 

cache-job:
  script:
    - echo "This job uses a cache."
  cache:
    key: binaries-cache-$CI_COMMIT_REF_SLUG
    paths:
      - binaries/

Jenkins plugins

Some functionality in Jenkins that is enabled through plugins is supported natively in GitLab with keywords and features that offer similar functionality. For example:

Jenkins plugin GitLab feature
Build Timeout timeout keyword
Cobertura Coverage report artifacts and Code coverage
Code coverage API Code coverage and Test coverage visualization
Embeddable Build Status Pipeline status badges
JUnit JUnit test report artifacts and Unit test reports
Mailer Notification emails
Parameterized Trigger Plugin trigger keyword and downstream pipelines
Role-based Authorization Strategy GitLab permissions and roles
Timestamper Job logs are time stamped by default

Security Scanning features

You might have used plugins for things like code quality, security, or static application scanning in Jenkins. GitLab provides security scanners out-of-the-box to detect vulnerabilities in all parts of the SDLC. You can add these plugins in GitLab using templates, for example to add SAST scanning to your pipeline, add the following to your .gitlab-ci.yml: 

include:
  - template: Security/SAST.gitlab-ci.yml

You can customize the behavior of security scanners by using CI/CD variables, for example with the SAST scanners.

Secrets Management

Privileged information, often referred to as “secrets”, is sensitive information or credentials you need in your CI/CD workflow. You might use secrets to unlock protected resources or sensitive information in tools, applications, containers, and cloud-native environments.

Secrets management in Jenkins is usually handled with the Secret type field or the Credentials Plugin. Credentials stored in the Jenkins settings can be exposed to jobs as environment variables by using the Credentials Binding plugin.

For secrets management in GitLab, you can use one of the supported integrations for an external service. These services securely store secrets outside of your GitLab project, though you must have a subscription for the service:

GitLab also supports OIDC authentication for other third party services that support OIDC.

Additionally, you can make credentials available to jobs by storing them in CI/CD variables, though secrets stored in plain text are susceptible to accidental exposure, the same as in Jenkins. You should always store sensitive information in masked and protected variables, which mitigates some of the risk.

Also, never store secrets as variables in your .gitlab-ci.yml file, which is public to all users with access to the project. Storing sensitive information in variables should only be done in the project, group, or instance settings.

Review the security guidelines to improve the safety of your CI/CD variables.

Planning and Performing a Migration

The following list of recommended steps was created after observing organizations that were able to quickly complete this migration.

Create a Migration Plan

Before starting a migration you should create a migration plan to make preparations for the migration. For a migration from Jenkins, ask yourself the following questions in preparation:

  • What plugins are used by jobs in Jenkins today?
    • Do you know what these plugins do exactly?
    • Do any plugins wrap a common build tool? For example, Maven, Gradle, or NPM?
  • What is installed on the Jenkins agents?
  • Are there any shared libraries in use?
  • How are you authenticating from Jenkins? Are you using SSH keys, API tokens, or other secrets?
  • Are there other projects that you need to access from your pipeline?
  • Are there credentials in Jenkins to access outside services? For example Ansible Tower, Artifactory, or other Cloud Providers or deployment targets?

Prerequisites

Before doing any migration work, you should first:

  1. Get familiar with GitLab.
  2. Set up and configure GitLab.
  3. Test your GitLab instance.
    • Ensure runners are available, either by using shared GitLab.com runners or installing new runners.

Migration Steps

  1. Migrate projects from your SCM solution to GitLab.
  2. Create a .gitlab-ci.yml file in each project.
  3. Migrate Jenkins configuration to GitLab CI/CD jobs and configure them to show results directly in merge requests.
  4. Migrate deployment jobs by using cloud deployment templates, environments, and the GitLab agent for Kubernetes.
  5. Check if any CI/CD configuration can be reused across different projects, then create and share CI/CD templates.
  6. Check the pipeline efficiency documentation to learn how to make your GitLab CI/CD pipelines faster and more efficient.

Additional Resources

  • You can use the JenkinsFile Wrapper to run a complete Jenkins instance inside of a GitLab CI/CD job, including plugins. Use this tool to help ease the transition to GitLab CI/CD, by delaying the migration of less urgent pipelines.

    note
    The JenkinsFile Wrapper is not packaged with GitLab and falls outside of the scope of support. For more information, see the Statement of Support.

If you have questions that are not answered here, the GitLab community forum can be a great resource.