Setting up Gitlab CI

(GET) 0: Before You “Git” Started

This tutorial assumes that you are using a Debian-based Linux Virtual Machine to execute your code! (If you are not using the appropriate system, let this guide be a reference but proceed with caution! The commands listed may not work on your machine...)

Before you start to use GitLab CI, make sure you have a…

If you haven't set up Git, then refer to this guide to help you: 

(SET) 1: Setting Up  .gitlab-ci.yml

What is .gitlab-ci.yml?

This file is where you write the commands that tells CI what to do with your project. When you push to your repository, GitLab will automatically look for this file and start to perform the jobs in it on Runners.

Creating .gitlab-ci.yml

    1. Create a new file in the root directory of your repository and name it ".gitlab-ci.yml"
    2. This file is where you will add the tasks you want to run, referred to as “jobs”. These jobs will make up what is called the “pipeline” for your project. Since these commands may differ based on your project and purpose, below is just the general format and important parts of your ".gitlab-ci.yml" file.
      1. The “script” for these jobs is what commands you want to run  
      2. output.txt is an "artifact" that is created and modified by the gitlab runner when the code executes
      3. By default, GitLab uses the build-test-deploy stages for the order/when you want to run jobs. If you do not specify a stage for the job, it uses the “test” stage by default. 
      4. “only” is used to limit when the job is executed; for example, “only” executes job3 when pushed to the master branch and another branch (“refs” is used to reference the branches)
  stage: build
  script: "script for job1" >> /home/vkp3/output.txt

  stage: test
  script: "script for job2" >> /home/vkp3/output.txt
- branch_name

  stage: deploy
  script: "script for job3" >> /home/vkp3/output.txt
- master
***A TIP to avoid CI-related Gitastrophes: Use the CI Lint to test your code for the yml file (YourProject > CI/CD > Pipelines > CI Lint button in top right hand corner)***
    1. There are so many other configurations that can be added to this file to make it work for your project. View the GitLab Reference guide for .gitlab-ci.yml to explore everything you can do!

Push .gitlab-ci.yml to GitLab

Once you are done customizing your ".gitlab-ci.yml" file , push the file you created to GitLab by running the following commands on your virtual machine:

git add .gitlab-ci.yml
git commit -m "Created .gitlab-ci.yml file"
git push origin master

Now when you go to GitLab, on the Pipelines page you will see that the pipeline is pending. Notice that the jobs we wrote in the .gitlab-ci.yml file are “stuck”*. This is because we haven’t configured a place for the code to run. 

So let’s fix that, by configuring our Runner!

*If you don’t see the stuck message, it’s probably because you already have a runner for your project or it is running on a shared GitLab Runner. Go to Settings > CI/CD > Runner to see your Runners.

(RUN) 2: Configure your Runner 

What is a Runner ?

A Runner is where the code will execute and test. You can find the Runners for your project under Settings > CI/CD > Runner. Some examples of Runners include a Virtual Machine, Docker containers, etc. For the purposes of this tutorial, we will be using a Virtual Machine.

Installing a Runner

On your virtual machine, run the following command to install a GitLab Runner:

sudo apt-get install gitlab-runner

Register your runner

    1. Run the following command on your virtual machine to begin registering your runner
sudo gitlab-runner register
    1. Follow the prompts on the terminal to complete registering your runner.
      1. The URL and token can be found on GitLab under Settings > CI/CD > Runner.
      2. It will ask you to specify tags or lock runner: press Enter for both
      3. Set your executor to what you want to execute/run your code
        1. If you’re unsure, choose Shell, which will allow you to build and test locally on your virtual machine.
    2. Once the runner is set up you can see it on GitLab under Settings > CI/CD > Runner.

On the pipelines page, you can now see the status of the jobs from your last commit!

FOEs (Frequently Obtained Errors)

If it seems that your runner has become your FOE by throwing errors at you in Git, here are somethings to check to get to the ROOT of the problem:

Error: /home/{usr}/{artifact}: Permission denied

Make sure the runner is a user on the VM and has appropriate permissions:

      1. Make sure the runner is a user by running the following command into your terminal:
cat /etc/passwd | grep git
      1. Try giving sudo privileges to your user:
sudo visudo

Add the following line to the end of the file (under #includedir /etc/sudoers.d):


(CTRL+O to save and CTRL+X to exit)


If it still doesn’t work, then we might have to check the artifact itself:

      1. Switch to the gitlab-runner user:
sudo su gitlab-runner

After this command your terminal should change to something like like:

      1. Try checking who “owns” the artifact and make sure it is gitlab-runner and not root:
sudo su gitlab-runner
      1. If you see that a user other than gitlab-runner, maybe root, owns the artifact that you are trying to modify, you will have to change the owner of the artifact:
sudo chown gitlab-runner {file_name}
sudo chown :gitlab-runner {file_name}

🥮 If it still doesn’t work, come to office hours and we’ll try to help you out!

To Learn More about GitLab CI…  

Reference the documentation provided by GitLab: