How to Install, Register, and Use GitLab Runner with Docker for CI/CD Pipelines

1. GitLab Runner Overview

GitLab Runner is an open‑source project that executes jobs and sends results back to GitLab. It works with GitLab CI, the built‑in continuous integration service that coordinates jobs. The runner is written in Go and runs as a single binary without language‑specific dependencies.

2. Three Types of GitLab Runner

shared : runs jobs for the entire platform (gitlab)

group : runs jobs for all projects under a specific group

specific : runs jobs for a designated project

3. Two Runner States

locked : cannot run project jobs

paused : will not run jobs

4. Installing GitLab Runner

Because services are containerized, this example uses Docker to install the runner. Other methods are available on the official documentation site.

Official docs: https://docs.gitlab.com/runner/install/

<code>$ mkdir -p /data/gitlab-runner/config
$ docker run -itd --restart=always --name gitlab-runner \
    -v /data/gitlab-runner/config:/etc/gitlab-runner \
    -v /var/run/docker.sock:/var/run/docker.sock  gitlab/gitlab-runner:latest
$ docker exec -it gitlab-runner bash
root@container:/# gitlab-runner -v
Version:      13.8.0
Git revision: 775dd39d
Git branch:   13-8-stable
GO version:    go1.13.8
Built:        2021-01-20T13:32:47+0000
OS/Arch:      linux/amd64</code>

5. Registering the Runner

Prerequisite: a reachable GitLab repository. In GitLab UI, go to **Admin → Runners** to obtain the instance URL and registration token.

Since the runner is installed via Docker, registration is performed inside the container:

<code>[root@localhost config]# docker exec -it gitlab-runner bash

root@container:/# gitlab-runner register
Runtime platform                              arch=amd64 os=linux pid=86 revision=775dd39d version=13.8.0
Running in system-mode.
Enter the GitLab instance URL (for example, https://gitlab.com/):
http://192.168.50.128/
Enter the registration token:
iqxKz5XTz4w_2RxiSQ5S
Enter a description for the runner:
[24dc60abee0b]: node1.ayunw.cn
Enter tags for the runner (comma-separated):
default
Registering runner... succeeded  runner=iqxKz5XT
Enter an executor: docker-ssh+machine, kubernetes, custom, shell, ssh, virtualbox, docker, docker-ssh, parallels, docker+machine:
 docker
Enter the default Docker image (for example, ruby:2.6):
 docker:19.03.15
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

root@container:/# gitlab-runner restart
Runtime platform                              arch=amd64 os=linux pid=98 revision=775dd39d version=13.8.0
Terminated

root@container:/# gitlab-runner list
Runtime platform                              arch=amd64 os=linux pid=130 revision=775dd39d version=13.8.0
Listing configured runners                     ConfigFile=/etc/gitlab-runner/config.toml
node1.ayunw.cn                                   Executor=docker Token=VSVWeipeMirJsJo9znT5 URL=http://192.168.50.128/</code>

After registration, a

config.toml

file is created under

/etc/gitlab-runner

. Because the configuration directory was mounted to the host (

/data/gitlab-runner/config

), you can edit the file on the host without restarting the runner; it checks for changes every five minutes.

<code>concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "node1.ayunw.cn"
  url = "your‑gitlab‑url"
  token = "token‑from‑ui"
  executor = "docker"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    tls_verify = false
    image = "docker:19.03.15"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0</code>

Verify the registration in the GitLab UI:

If the runner appears locked, edit it and uncheck “Lock to current project”, then enable “Run untagged jobs”. The runner will then be ready to execute jobs.

6. Testing the Pipeline

Create a new project and add a

.gitlab-ci.yml

file at the repository root with the following content. Pushing the file triggers the pipeline.

<code>stages:
  - maven
  - build
  - deploy

maven_job:
  stage: maven
  tags:
    - default
  only:
    - master
  script:
    - echo "This is the first maven job"

build_job:
  stage: build
  tags:
    - default
  only:
    - master
  script:
    - echo "This is the first build job"

deploy_job:
  stage: deploy
  tags:
    - default
  only:
    - master
  script:
    - echo "This is the first deploy job"</code>

After committing, the pipeline runs successfully, confirming that GitLab Runner is installed and operational.