Installing GitLab Runner

1. Installing Runner on Linux

Method	Description	Command	Notes
Package Manager (apt/yum)	Install using official GitLab repositories	`curl -L https://packages.gitlab.com/runner/gitlab-runner/gpgkey \| sudo apt-key add -` `echo "deb https://packages.gitlab.com/runner/gitlab-runner/ubuntu/ $(lsb_release -cs) main" \| sudo tee /etc/apt/sources.list.d/gitlab-runner.list` `sudo apt update && sudo apt install gitlab-runner`	Supports Ubuntu, Debian, CentOS, RHEL
Binary Download	Download and install the binary directly	`wget -O /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64` `chmod +x /usr/local/bin/gitlab-runner`	Manual installation; requires manual updates
Docker	Run runner in a Docker container	`docker run -d --name gitlab-runner --restart always --volume /var/run/docker.sock:/var/run/docker.sock --volume $(pwd)/config:/etc/gitlab-runner --privileged gitlab/gitlab-runner:latest`	Useful for isolated environments or CI/CD pipelines

Example: Registering a Runner

gitlab-runner register \
  --url "https://gitlab.example.com/" \
  --registration-token "PROJECT_REGISTRATION_TOKEN" \
  --executor "shell" \
  --description "My Runner" \
  --tag-list "linux,shell" \
  --run-untagged="true" \
  --locked="false"

Note: Ensure the GitLab Runner service is started after installation using sudo systemctl start gitlab-runner and enabled to start on boot with sudo systemctl enable gitlab-runner.

Warning: When using Docker, make sure the Docker socket is properly mounted to allow the runner to execute jobs in containers.

2. Installing Runner on macOS

Install GitLab Runner on macOS using Homebrew or the official binary.

Example: Install using Homebrew

brew tap gitlab/gitlab-runner
brew install gitlab-runner

Example: Install using official binary

curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-darwin-amd64
chmod +x /usr/local/bin/gitlab-runner

Installation Method	Command	Notes
Homebrew	`brew install gitlab-runner`	Recommended for easy updates and management
Binary	`curl -L ...`	Manual installation, no package manager

Note: Ensure the runner is registered with your GitLab instance after installation.

3. Installing Runner on Windows

Step	Description	Details
1. Download Runner	Download the GitLab Runner executable for Windows	Go to GitLab Runner releases and download the `gitlab-runner-windows-amd64.exe` file.
2. Install Runner	Run the installer or place the executable in a directory	Place `gitlab-runner-windows-amd64.exe` in a directory like `C:\gitlab-runner`. Optionally run as a service using the command line.
3. Register Runner	Register the runner with your GitLab instance	Run `gitlab-runner register` and follow the prompts to configure the runner with your GitLab project or group.

Example: Registering Runner on Windows

gitlab-runner register

Note: Ensure the Windows user has appropriate permissions to run GitLab Runner and access required resources.

Warning: GitLab Runner must be run with sufficient privileges to access the system and execute jobs.

4. Installing Runner via Docker

Example: Run GitLab Runner in a Docker container

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "/srv/gitlab-runner/config":/etc/gitlab-runner \
  -v "/srv/gitlab-runner/bin":/home/gitlab-runner \
  gitlab/gitlab-runner:latest

Option	Values	Description
--name	`gitlab-runner`	Name of the Docker container
--restart	`always`	Restart policy for the container
-v /var/run/docker.sock:/var/run/docker.sock	`/var/run/docker.sock`	Mount Docker socket to access Docker daemon
-v /srv/gitlab-runner/config:/etc/gitlab-runner	`/etc/gitlab-runner`	Mount configuration directory to persist settings
-v /srv/gitlab-runner/bin:/home/gitlab-runner	`/home/gitlab-runner`	Mount binary directory to persist binaries

Note: Ensure the Docker socket is mounted correctly to allow GitLab Runner to execute jobs using Docker.

Warning: Running GitLab Runner in Docker requires appropriate permissions and security considerations.

5. Installing Runner via Kubernetes

Example: Deploy GitLab Runner using Helm Chart

apiVersion: v1
kind: Namespace
metadata:
  name: gitlab-runner

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gitlab-runner
  namespace: gitlab-runner
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gitlab-runner
  template:
    metadata:
      labels:
        app: gitlab-runner
    spec:
      containers:
      - name: runner
        image: gitlab/gitlab-runner:latest
        command:
          - "gitlab-runner"
          - "run"
        env:
          - name: GITLAB_SERVER_URL
            value: "https://gitlab.example.com"
          - name: REGISTRATION_TOKEN
            value: "your-registration-token"

Configuration	Description	Default Value	Notes
image	Docker image to use for the runner	`gitlab/gitlab-runner:latest`	Ensure image is compatible with your GitLab version
GITLAB_SERVER_URL	URL to the GitLab instance	`https://gitlab.example.com`	Must be accessible from the Kubernetes cluster
REGISTRATION_TOKEN	Runner registration token from GitLab	`your-registration-token`	Generated in GitLab UI under Settings > CI/CD > Runners

Note: Ensure that the GitLab server URL is accessible from within the Kubernetes cluster and that the registration token has not expired.

Warning: The registration token should be stored securely, such as in a Kubernetes secret, rather than hardcoded in the deployment manifest.

Installation Steps

Create a namespace for the runner
Deploy the GitLab Runner using the provided Docker image
Set environment variables for server URL and registration token
Ensure the runner can communicate with GitLab

6. Using Runner Authentication

Property	Description	Default Value	Notes
runner.token	Authentication token for the runner to connect to GitLab	None	Required for runner registration
runner.request_timeout	Timeout for API requests to GitLab	30 seconds	Can be adjusted for slow networks

Example: Registering a Runner with Authentication

gitlab-runner register \
  --url https://gitlab.example.com/ \
  --registration-token <your-registration-token> \
  --executor docker \
  --docker-image "python:3.9" \
  --name "my-docker-runner" \
  --tag-list "docker,python" \
  --run-untagged="true" \
  --locked="false"

Note: The registration-token is valid only once and must be replaced after use.

Warning: Ensure runner tokens are stored securely and not exposed in logs or configuration files.

7. Registering Runners

Option	Values	Description
gitlab-runner register	`gitlab-runner register`	Command to register a new runner
--url	`https://gitlab.example.com/`	GitLab instance URL
--registration-token	`abc123xyz`	Runner registration token from GitLab
--executor	`shell`, `docker`, `kubernetes`	Executor type to use for jobs
--name	`my-runner`	Name of the runner
--tag-list	`web,production`	Comma-separated list of tags for the runner
--run-untagged	`true`, `false`	Whether to run untagged jobs
--locked	`true`, `false`	Whether to lock the runner to prevent execution

Example: Registering a Runner with Shell Executor

gitlab-runner register \
  --url https://gitlab.example.com/ \
  --registration-token abc123xyz \
  --executor shell \
  --name "my-shell-runner" \
  --tag-list "web,production" \
  --run-untagged=true \
  --locked=false

Note: The registration token can be found in your GitLab project or group settings under "CI/CD" > "Runners".

Warning: Ensure the runner has appropriate permissions to access required resources (e.g., Docker images, secrets).

8. Verifying Runner Installation

Example: Check runner status

gitlab-runner status

Command	Description	Output
gitlab-runner status	Checks the status of the GitLab Runner service	`Running` or `Stopped`

Note: Ensure the runner is in Running state to process jobs.

Example: List registered runners

gitlab-runner list

Field	Description	Sample Value
Runner	Name of the runner instance	`my-runner`
Executor	Executor type used by the runner	`shell`, `docker`
Status	Current status of the runner	`running`

Example: Check runner configuration

gitlab-runner verify --config /etc/gitlab-runner/config.toml

Option	Description	Notes
--config	Path to the GitLab Runner config file	Default: `/etc/gitlab-runner/config.toml`
--dry-run	Run without actually registering the runner	Useful for testing configuration

9. Understanding Runner Versioning

Version Type	Description	Release Notes
Major	Breaking changes and new features	Changes may require configuration updates or re-registration of runners
Minor	Backward-compatible features and enhancements	Typically safe to upgrade without configuration changes
Patch	Non-breaking bug fixes and security patches	Recommended for all users to keep runners secure and stable

Note: GitLab Runner follows semantic versioning (SemVer) principles. Always check official documentation for compatibility with your GitLab instance version.

Example: Checking Runner Version

gitlab-runner --version

Versioning Strategy

NEW Major versions indicate breaking changes
NEW Minor versions introduce new features
NEW Patch versions fix bugs and apply security updates

10. Managing Runner Configuration File

Property	Values	Description
concurrent	`1`	Maximum number of jobs that can run concurrently
check_interval	`0`	How often (in seconds) to check for new jobs
shutdown_timeout	`30`	Time (in seconds) to wait for a graceful shutdown
output_limit	`1048576`	Maximum size (in bytes) of job output

Example: Configuration file structure

concurrent: 1
check_interval: 0
shutdown_timeout: 30
output_limit: 1048576

Note: The configuration file is typically located at /etc/gitlab-runner/config.toml on Linux systems.

Warning: Changes to the configuration file require a runner restart to take effect.