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:
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:
Lets add the official repository:
# For Debian/Ubuntu curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.deb.sh | sudo bash # For RHEL/CentOS curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.rpm.sh | sudo bash
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.
To grab the token for project specific runners go to the projects Settings page and then Pipelines sub page.
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.
Run the following command to start the process:
sudo gitlab-runner register
Enter the URL of your GitLab instance. This can be a custom domain or
https://gitlab.comif you are using the hosted version.
Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com ) https://gitlab.com
Enter the token we retrieved from the previous step:
Please enter the gitlab-ci token for this runner AxeM5Sn2uC2VAf6g34dfd2
Enter the description of our runner.
Please enter the gitlab-ci description for this runner test-runner
Enter any tags you want to associate with this runner:
Please enter the gitlab-ci tags for this runner (comma separated): test, docker, example
Choose whether the runner should execute jobs that do not have tags:
Whether to run untagged jobs [true/false]: [false]: true
Choose whether this runner is shared or project specific:
Whether to lock Runner to current project [true/false]: [false]: false
Enter the type of executor:
Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell: docker
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): alpine:latest
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.
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.