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

Docker

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

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</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: ...</code>
<code>shell</code>
<code>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</code>
<code>gitlab-runner <command> --help    # help</code>
<code>gitlab-runner run                # run as normal user (config at ~/.gitlab-runner/config.toml)</code>
<code>sudo gitlab-runner run           # run as root (config at /etc/gitlab-runner/config.toml)

Registration and management

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

Service management

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

Sample Pipeline Configuration

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