How to install and use GitLab Runners
Guillaume Briday
3 minutes
If you've ever worked with GitLab, you might have had the opportunity to explore continuous integration (CI). Today, we’ll discuss what a Runner is and how to set it up.
Why use it?
Continuous integration allows you to run your tests and builds directly on the server via pipelines. Pipelines are groups of jobs that define the scripts to execute on the server.
To manage your pipelines, you need to set up a GitLab Runner. The GitLab Runner manages your jobs and automatically executes them when a branch is pushed to the repository or merged, for example. You can also run jobs manually or completely reconfigure them.
If you use GitLab.com, several runners are available to you for free, which is great. This lets you run multiple pipelines in parallel to get feedback faster.
These are Shared Runners, meaning they’re used across all your projects, reducing the number of runners you need to install. However, this can be an issue if one project is very active. Pipelines from other projects might have to wait until the Shared Runners are free again.
Depending on your needs, this might not be enough. Based on the number of projects or the activity level of a project, you may need more runners or a lot of patience.
If you host GitLab yourself, you’ll need to define one or more runners to use GitLab CI.
You can define Specific Runners that are available only for a specific project.
How to install GitLab Runner
On Linux
Add the repository:
# For Debian/Ubuntu/Mint
$ curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
# For RHEL/CentOS/Fedora
$ curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh | sudo bashInstall the package:
# For Debian/Ubuntu/Mint
$ sudo apt-get install gitlab-runner
# For RHEL/CentOS/Fedora
$ sudo yum install gitlab-runnerOn macOS
Use Brew as the package manager for macOS:
$ brew update
$ brew install gitlab-runnerTo start GitLab Runner automatically at system startup (optional):
$ brew services start gitlab-runnerFor Windows, you can follow the documentation.
Registering your runner with GitLab
$ gitlab-runner register
> # example: https://gitlab.com/Add the URL of your GitLab instance. Note: This is not the URL of a specific repository.
You’ll be asked for a token, which can be found in the project’s https://gitlab.com/<group>/<repo>/settings/ci_cd section:
> Please enter the gitlab-ci token for this runner:
a1b2c3d4e5
Registering runner... succeeded runner=a1b2c3d4e5Next, select the executor type for your Runner. Depending on your needs and stack, there are many options:
> Please enter the executor: docker+machine, docker-ssh+machine, kubernetes, docker, shell, ssh, virtualbox, docker-ssh, parallels:
dockerPersonally, I chose Docker, but feel free to pick the technology that works best for you.
After selecting the final options, your Runner is ready to use. You can see it in the project settings on GitLab:
You need to start the GitLab Runner service for the first time:
$ gitlab-runner startThis service handles running the runners.
To enable your machine to receive and execute pipelines:
$ gitlab-runner run
Starting multi-runner ...When I run a job on GitLab, it selects one of the available runners. The job interface shows which runner was used:
You can also see the job status in the terminal running the Runner:
$ gitlab-runner run
Checking for jobs... received job=52772913 repo_url=https://gitlab.com/<group>/<repo>.git runner=bdfebe22
Job succeeded job=52772913 project=5049427 runner=bdfebe22You can modify your GitLab Runner configuration by changing the settings in the ~/.gitlab-runner/config.toml file.
Conclusion
You can now add as many Runners as you want, whether on a self-hosted instance or gitlab.com.
Adding runners based on your needs can significantly speed up merge request reviews and production deployments.
If you have suggestions or questions, feel free to leave them in the comments.
Thank you!
