Getting Started with Gitlab CI: Installing and Configuring Gitlab CI

Getting Started with Gitlab CI: Installing and Configuring Gitlab CI

What is this about?

Over the next weeks I will go over how to use Gitlab CI from scratch. I will go over how to install and configure it on your server, run unit and integration tests, build and push Docker images, deploy code, and go over other use cases. I will assume you already use Gitlab as your repo manager since it's required by Gitlab CI.

What is Gitlab

Gitlab is a great open source repository manager that I've been using for about 2 years. It has evolved over the past 2 years with many great features added, one of those being Gitlab CI. Gitlab CI is the integrated CI and CD to test, build and deploy your code. It's personally one of my favorite features because it's easy to use, flexible, and integrated with Gitlab. Check out the official website to learn more about it.

Installing Gitlab CI

If you are using the hosted version of Gitlab then you have access to the free runners. Feel free to skip this step.

Overall, the installation process is easy and simple. You can choose from three different recommended options:

  1. Install the official RPM/DEB package
  2. Run it with Docker
  3. Download the binary

Option 1 is my recommended way of installing it since it's by far the easiest method. It only requires a few bash commands for the installation and updating is just as easy. The RPM/DEB package takes care of creating the user, configuring permissions, running the service, and managing updates. Let's move on to the requirements and installation.

If you don't want to go with option 1 then check out the official Gitlab instructions provides.

As far as requirements, there aren't many but here they are:

  • A supported Operating System: Debian, Ubuntu, RHEL, or CentOS.
  • Internet connection
  • Gitlab CE, EES, or EEP.

Alright, let's install it:

  1. Lets add the official repository:

    # For Debian/Ubuntu
    curl -L | sudo bash
    # For RHEL/CentOS
    curl -L | sudo bash
  2. Lets install Gitlab CI

    # For Debian/Ubuntu
    sudo apt-get install gitlab-ci-multi-runner
    # For RHEL/CentOS
    sudo yum install gitlab-ci-multi-runner

That's it, Gitlab CI should be running on your machine. You can see it running by checking it's status:

service gitlab-runner status
● gitlab-runner.service - GitLab Runner
   Loaded: loaded (/etc/systemd/system/gitlab-runner.service; enabled; vendor preset: enabled)
   Active: active (running) since Mon 2017-07-10 01:22:41 UTC; 59s ago
 Main PID: 20674 (gitlab-ci-multi)
    Tasks: 6
   Memory: 4.9M
      CPU: 28ms

If it's not then feel free to ask for help by commenting.

Registering Gitlab CI Runners

Gitlab runners execute the code defined in the .gitlab-ci.yml file which will go over later. These runners run in an isolated environment speficic to a project or shared throughout many. Check out the official documentation to learn more about them.

Getting the runner token

Before we continue we need to obtain a token from Gitlab. For shared projects, go to admin/runners and copy the "Registration token" highlighted in red.

Gitlab Shared Runner Token

To grab the token for project specific runners go to the projects Settings page and then Pipelines sub page.

Gitlab Project Runner Token

Alright lets move onto creating our own project specific and shared runners.

Registering Shared and Project Specific Runners

Run the following commands on the machine we just installed Gitlab CI from the previous step.

  1. Run the following command to start the process:

    sudo gitlab-runner register
  2. Enter the URL of your GitLab instance. This can be a custom domain or if you are using the hosted version.

    Please enter the gitlab-ci coordinator URL (e.g. )

    Gitlab URL

  3. Enter the token we retrieved from the previous step:

    Please enter the gitlab-ci token for this runner
  4. Enter the description of our runner.

    Please enter the gitlab-ci description for this runner
  5. Enter any tags you want to associate with this runner:

    Please enter the gitlab-ci tags for this runner (comma separated):
    test, docker, example
  6. Choose whether the runner should execute jobs that do not have tags:

    Whether to run untagged jobs [true/false]:
    [false]: true
  7. Choose whether this runner is shared or project specific:

    Whether to lock Runner to current project [true/false]:
    [false]: false
  8. Enter the type of executor:

    Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:
  9. If you are using the Docker executor then you will be asked to enter the default image:

    Please enter the Docker image (eg. ruby:2.1):

That is it! You should have a fully functional runner, you can confirm by going into admin/runners or the project's pipeline settings. Feel free to ask in the comments if you have any questions or problems.

Gitlab Admin Page

Additional resources:

What's Next?

I hope everything worked as expected. On the next article we will go over how to use the .gitlab-ci.yml on your projects and run basic unit test.

Edgar Pino

About Edgar Pino

I’m a passionate software engineer working @ Pluralsight interested in distributed systems, machine learning, and the web. I am also a graduate student at the University of Illinois.