Master GitLab CI Runner: Step-by-Step Installation, Configuration, and Best Practices

Continuous Integration (CI)

CI, Continuous Integration, is a crucial phase in software development, especially in agile internet projects. It is used for daily compilation and automated testing to detect issues early and avoid project delays.

Typical CI process includes:

Submitting (merging) code

Compiling

Testing

Releasing

Projects may add static code analysis; some small projects skip testing due to schedule pressure.

CI Tools

Many CI tools exist; Jenkins is the most common. Jenkins consists of a master and many slaves. The master configures nodes and jobs; slaves execute them. A rich plugin ecosystem helps newcomers configure tasks quickly.

GitLab CI is GitLab's built‑in CI tool, with a dedicated CI configuration page.

Open‑source projects on GitHub often display a “build|passing” badge in their README, showing CI/CD status.

GitLab CI can be seen as a lightweight Jenkins; the GitLab server acts as the master, and only a runner (slave) is needed. Its runner supports multiple environments, especially Docker, and its configuration is simpler than Jenkins.

GitLab‑CI Runner Installation and Configuration

1. Install Docker

Docker is required to run the runner.

Linux:

<code>curl -sSL https://get.docker.com/ | sh</code>

macOS (Homebrew):

<code>$ brew cask install docker</code>

After launching Docker, a whale icon appears in the status bar.

2. Install GitLab CI Runner

Linux (reference: https://docs.gitlab.com/runner/install/linux-manually.html):

Using binary:

<code># Linux x86-64
sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64
sudo chmod +x /usr/local/bin/gitlab-runner
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start</code>

Check status:

<code>gitlab-runner status</code>

macOS:

<code>brew install gitlab-runner
brew services start gitlab-runner
gitlab-runner status</code>

3. Set Docker Permissions

Add the gitlab-runner user to the docker group and restart services.

<code>usermod -aG docker gitlab-runner
service docker restart
gitlab-runner restart</code>

4. Register GitLab Runner

Registration obtains a runner token and creates the runner.

4.1 Runner Types

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

locked – cannot run project jobs

paused – will not run jobs

Tokens differ by the UI where they are generated (instance, group, project). After obtaining URL and token, you can register.

4.2 Interactive Registration

<code>gitlab-runner register
# prompts for URL, token, description, tags, executor, etc.</code>

Key fields:

url – GitLab instance address

token – project or group token

name – runner identifier

tags – used to match jobs

executor – execution environment (commonly docker)

Example: runner tags “python2.7,python3.4” will match jobs tagged with the same language.

The runner configuration is stored in

~/.gitlab-runner/config.toml

. Multiple runners appear as separate sections.

After registration the runner appears as active in GitLab.

4.3 Non‑interactive Registration

<code>gitlab-runner register \
  --non-interactive \
  --executor "shell" \
  --url "http://gitlab.example.com/" \
  --registration-token "AvpQDzBCL66sYKyURChH" \
  --description "devops-runner" \
  --tag-list "build,deploy" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"</code>

If the GitLab server uses HTTPS, provide the TLS CA file during registration.

<code>gitlab-runner register \
  --non-interactive \
  --tls-ca-file=/etc/gitlab/ssl/gitlab.example.com.crt \
  --url "https://gitlab.example.com/" \
  --registration-token "AvpQDzBCL66sYKyURChH" \
  --executor "docker" \
  --docker-image maven:latest \
  --description "runner " \
  --tag-list "run" \
  --run-untagged \
  --locked="false"</code>

References: Jianshu article , GitLab documentation .