GitLab Runner Installation, Registration, and Common Commands Guide

GitLab Runner is an open‑source agent that executes jobs and reports results back to GitLab, working together with GitLab CI for continuous integration.

Installation Requirements

Runner is written in Go, runs as a binary on GNU/Linux, macOS, Windows, and FreeBSD, and requires at least Docker v1.13.0 if Docker is used. The Runner version should match the GitLab version.

Installation Methods

CentOS

curl -LJO https://gitlab-runner-downloads.s3.amazonaws.com/latest/rpm/gitlab-runner_<arch>.rpm
rpm -i gitlab-runner_<arch>.rpm
rpm -Uvh gitlab-runner_<arch>.rpm

macOS

sudo curl --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/v12.6/binaries/gitlab-runner-darwin-amd64
sudo chmod +x /usr/local/bin/gitlab-runner
gitlab-runner install
gitlab-runner start

Docker

mkdir ~/data/gitlab-runner/config
docker run --rm -t -id -v ~/data/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner:v12.9.0

Runner Registration

Three runner types are supported:

shared – runs jobs for the whole GitLab instance

group – runs jobs for all projects in a specific group

specific – runs jobs for a single project

Runners can be in locked or paused states.

Obtaining Tokens

Tokens are retrieved from the GitLab UI under Settings → CI/CD → Runners for each runner type (shared, group, specific).

Interactive Registration

docker run --rm -t -i -v ~/data/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner:v12.6.0 register
Runtime platform                                    arch=amd64 os=linux pid=6 revision=ac8e767a version=12.6.0
Running in system‑mode.
Please enter the gitlab‑ci coordinator URL (e.g. https://gitlab.com/):
http://192.168.1.105
Please enter the gitlab‑ci token for this runner:
4tutaeWWL3srNEcmHs1s
Please enter the gitlab‑ci description for this runner:
[00ef023b5ae]: devops-service-runner
Please enter the gitlab‑ci tags for this runner (comma separated):
build
Registering runner... succeeded                     runner=4tutaeWW
Please enter the executor: ...
shell
Runner registered successfully.

Non‑Interactive Registration

docker run -itd --rm -v ~/data/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner:v12.6.0 register \
  --non-interactive \
  --executor "shell" \
  --url "http://192.168.1.200:30088/" \
  --registration-token "JRzzw2j1Ji6aBjwvkxAv" \
  --description "devops-runner" \
  --tag-list "build,deploy" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

Common Commands

Runner execution

gitlab-runner --debug <command>   # debug mode
gitlab-runner <command> --help    # help
gitlab-runner run                # run as normal user (config at ~/.gitlab-runner/config.toml)
sudo gitlab-runner run           # run as root (config at /etc/gitlab-runner/config.toml)

Registration and management

gitlab-runner register                # interactive registration
gitlab-runner list                    # list registered runners
gitlab-runner verify                  # verify connectivity
gitlab-runner unregister              # unregister a runner
gitlab-runner unregister --url http://gitlab.example.com/ --token t0k3n
gitlab-runner unregister --name test-runner
gitlab-runner unregister --all-runners

Service management

gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
gitlab-runner uninstall
gitlab-runner start
gitlab-runner stop
gitlab-runner restart
gitlab-runner status

Sample Pipeline Configuration

stages:
- build
- deploy
build:
stage: build
tags: [build]
only: [master]
script:
- echo "mvn clean "
- echo "mvn install"
deploy:
stage: deploy
tags: [deploy]
only: [master]
script:
- echo "hello deploy"

The guide notes that GitLab CI is convenient for DevOps practitioners who combine development and operations, while Jenkins CI suits larger teams with distinct roles, extensive plugins, and configuration‑as‑code practices.