GitLab Runner Installation, Registration, and Common Commands Guide

GitLab Runner is an open‑source agent that executes jobs and reports results back to GitLab CI, supporting Linux, macOS, Windows, and FreeBSD. It runs as a binary compiled from Go and can be installed via Docker, native packages, or manual download.

Installation requirements : Docker version ≥ v1.13.0 is required for Docker‑based installations, and the Runner version should match the GitLab version.

CentOS installation :

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

macOS installation :

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‑based installation :

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 types include shared , group , and specific , each with states such as locked and paused . Tokens are obtained from the GitLab UI under Settings → CI/CD → Runners.

Interactive registration (Docker) :

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) :

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 include debugging, help, running the runner in user or root mode, registering, listing, verifying, and unregistering runners, as well as service management commands ( install , uninstall , start , stop , restart , status ).

gitlab-runner --debug
# debug mode
gitlab-runner
--help   # help
gitlab-runner run                # user mode
sudo gitlab-runner run           # root mode
gitlab-runner register           # register (add --non-interactive for CI)
gitlab-runner list               # list registered runners
gitlab-runner verify             # verify connectivity
gitlab-runner unregister         # unregister runner
gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
gitlab-runner start
gitlab-runner stop
gitlab-runner restart
gitlab-runner status

Running a pipeline (example .gitlab-ci.yml ):

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 where development and operations are handled by the same person, while Jenkins CI suits larger teams with distinct roles, richer plugins, and configuration‑as‑code separation.