GitLab CI Runner Tutorial

By the end of this video you will have seen how to install a GitLab CI Runner, and you will know about the two gotchas that may get in your way.

Installing the Runner itself is really quite straightforward. The documentation is here, and honestly, it's largely a copy and paste exercise.

As part of the install process, you will need to enter three values.

The first is the URL of your GitLab CI Cordinator. Uh huh... In our case, this is the URL of our GitLab CI server - http://ci.gitlab.home/. The trailing slash is very important here. Note, the GitLab CI server, not the GitLab server.

Next, you will need to provide a Token. There are two possible tokens you could use, but you can't use them both on one Runner.

Shared Runners

The first Token type is for Shared runners. This can be found on /admin/runners, e.g.:

http://ci.gitlab.home/admin/runners

To get there, from GitLab CI, go to Admin on the topbar, and then click Runners. From there you will see something like:

To register new Runner you should enter the following registration token. With this token the Runner will request a unique Runner token and use that for future communication. 71c808f46c1d62dcdd06

If you want a Shared Runner - i.e. a Runner that's available to all / any project - then copy / paste that Token string into your command line and continue on.

Specific Runners

The second Token type is for Specific runners. This can be found on /projects/{projectId}/runners, e.g.:

http://ci.gitlab.home/projects/6/runners

To get there, from GitLab CI, go to Admin on the topbar which should take you to the Manage Projects page. Click the name of your project, then choose 'Runners' from the right hand menu. On that page should be a list of instructions, with the third instruction detailing the alternative token, e.g.:

Use the following registration token during setup: b48244b094a463e7ddf1765c99f3dc

If you want a Specific Runner - i.e. a Runner that's available to only this project - then copy / paste that Token string into your command line and continue on.

Chosen The Wrong Type?

Don't worry, reconfiguring is simple.

Essentially we re-run the same setup procedure that we used to Register the Runner initially. Go back here, choose your installation type, and follow the guide from the Register the runner:, but this time using the right Token type.

Chancellor of the Executor

Whichever Token type you provided, the next question is what kind of 'executor' you want to use to trigger your build script. The default is shell and unless you have a good reason not to do so, I would recommend going with this choice.

Wondering what each of the executors would do for you? There's a little more info in the documentation.

With that final step completed, our Runner should now be showing up in our Manager Runners page on the GitLab CI Admin Dashboard (topbar > Admin > Runners). Depending on your Runner type, it may be green, blue, or red.

Gotcha #1

If you have followed along with this guide, knowing which Runner is running and why is hopefully not at all confusing.

However, if you followed the official guide, you may have ended up with a Shared Runner, but hit the problem that whenever you import a project from your GitLab in to your GitLab CI, that that project will be effectively private. The upshot being that when you push up a new commit, it won't be able to run your build process as no Runners are configured to run for this project.

Thankfully, fixing this is quite straightforward. It's more confusing than difficult.

To fix this, go back to your GitLab CI Admin Dashboard (click GitLab CI in the topbar), then click your project's name. On the right hand menu, choose Settings. Scroll down a touch and under Project settings, put a tick in the box for Allow shared runners, then scroll to the bottom and Save changes.

Now, when you next push up a commit, your build should kick off.

Gotcha #2

Whilst the first Gotcha is a quirk in GitLab CI, this second one will affect any Continuous Integration set up you use - unless you use a paid CI service, who may well have pre-empted this problem and provided an in-service solution.

So, our test Runner has been installed and configured on a brand new box. As the Runner set up page will tell you:

Runners can be placed on separate users, servers, and even on your local machine.

Which is very true.

However, where ever you put the Runner software, that user / machine will need access to the 'things' that make a build possible.

We're going to cover GitLab CI build scripts in the next video, but let's take a quick look at the one it generates for us:

git submodule update --init
ls -la

If you have installed your Runner on your GitLab CI server, you should at least be able to execute this and get a pass.

However, if you have built a brand new machine, even this basic build script will likely fail.

Why?

Well, Git isn't installed by default on Ubuntu, for example.

Therefore, it won't work.

We must install all the dependencies that our build script relies on. Everything from Git and PHP, to Composer, MySQL, Selenium maybe...

Of course, we can leverage Composer to do a lot of the work for us - we could require Behat, Codeception, PHPUnit, etc, from our composer.json, and let Composer handle those issues, but of course none of this would work if PHP isn't even installed.

As such, it makes sense to use a configuration management tool like Ansible (or simply, Virtual Machines that have been built to spec and then cloned) to allow us to 'spin up' as many Runners as we need, or have the hardware capacity to do so.