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_<arch>.rpm</code>
<code>rpm -i gitlab-runner_<arch>.rpm</code>
<code>rpm -Uvh gitlab-runner_<arch>.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</code>
<code>sudo chmod +x /usr/local/bin/gitlab-runner</code>
<code>gitlab-runner install</code>
<code>gitlab-runner start

Docker‑based installation :

mkdir ~/data/gitlab-runner/config</code>
<code>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</code>
<code>Runtime platform                                    arch=amd64 os=linux pid=6 revision=ac8e767a version=12.6.0</code>
<code>Running in system-mode.</code>
<code>Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/):</code>
<code>http://192.168.1.105</code>
<code>Please enter the gitlab-ci token for this runner:</code>
<code>4tutaeWWL3srNEcmHs1s</code>
<code>Please enter the gitlab-ci description for this runner:</code>
<code>[00ef023b5ae]: devops-service-runner</code>
<code>Please enter the gitlab-ci tags for this runner (comma separated):</code>
<code>build</code>
<code>Registering runner... succeeded                     runner=4tutaeWW</code>
<code>Please enter the executor: ... shell</code>
<code>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 \</code>
<code>  --non-interactive \</code>
<code>  --executor "shell" \</code>
<code>  --url "http://192.168.1.200:30088/" \</code>
<code>  --registration-token "JRzzw2j1Ji6aBjwvkxAv" \</code>
<code>  --description "devops-runner" \</code>
<code>  --tag-list "build,deploy" \</code>
<code>  --run-untagged="true" \</code>
<code>  --locked="false" \</code>
<code>  --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 <command>   # debug mode</code>
<code>gitlab-runner <command> --help   # help</code>
<code>gitlab-runner run                # user mode</code>
<code>sudo gitlab-runner run           # root mode</code>
<code>gitlab-runner register           # register (add --non-interactive for CI)</code>
<code>gitlab-runner list               # list registered runners</code>
<code>gitlab-runner verify             # verify connectivity</code>
<code>gitlab-runner unregister         # unregister runner</code>
<code>gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner</code>
<code>gitlab-runner start</code>
<code>gitlab-runner stop</code>
<code>gitlab-runner restart</code>
<code>gitlab-runner status

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

stages:</code>
<code>  - build</code>
<code>  - deploy</code>
<code>build:</code>
<code>  stage: build</code>
<code>  tags:</code>
<code>    - build</code>
<code>  only:</code>
<code>    - master</code>
<code>  script:</code>
<code>    - echo "mvn clean "</code>
<code>    - echo "mvn install"</code>
<code>deploy:</code>
<code>  stage: deploy</code>
<code>  tags:</code>
<code>    - deploy</code>
<code>  only:</code>
<code>    - master</code>
<code>  script:</code>
<code>    - 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.