GitLab Runner Basic Commands with Practical Examples

Intro

GitLab Runner is the agent that executes jobs in GitLab CI/CD pipelines. Knowing the right commands can turn a confusing failure into a quick fix. This guide provides a practical, command-first reference for developers, DevOps consultants, and technical startup teams who manage their own runners.

You will learn how to check the version, register and verify runners, inspect configuration, diagnose common failures, and recover from misconfigurations. Every command includes expected output, failure signals, and safety notes. The goal is operational confidence: observe before changing, limit the blast radius, use placeholders instead of secrets, verify results, and document recovery paths.

All examples assume a Linux-based runner installed via the official package. Commands are compatible with GitLab Runner 15.x and 16.x unless otherwise noted. Replace placeholders like <your-registration-token> with your own values. Never paste real tokens, private keys, or production identifiers into scripts or documentation.

Version and Environment Inventory

Before touching a runner, know exactly what you are working with. Run these read-only commands to capture version, architecture, and service state.

Check the GitLab Runner version:

gitlab-runner --version

Expected output (example):

Version:      16.5.0
Git revision: 8a2c1b6e
Git branch:   16-5-stable
GO version:   go1.21.3
Built:        2023-10-20T14:32:11Z
OS/Arch:      linux/amd64

If the command returns command not found, the runner is not installed or not in the current $PATH. Check common installation paths such as /usr/local/bin/gitlab-runner or /usr/bin/gitlab-runner. Use which gitlab-runner to find the executable.

Check the runner service status:

sudo systemctl status gitlab-runner

Expected output when running:

● gitlab-runner.service - GitLab Runner
   Loaded: loaded (/etc/systemd/system/gitlab-runner.service; enabled; vendor preset: enabled)
   Active: active (running) since Mon 2023-12-04 09:15:42 UTC; 1h 12min ago
 Main PID: 1532 (gitlab-runner)
    Tasks: 11 (limit: 4915)
   CGroup: /system.slice/gitlab-runner.service
           └─1532 /usr/bin/gitlab-runner run --working-directory /home/gitlab-runner --config /etc/gitlab-runner/config.toml --service gitlab-runner --syslog

If the service is inactive (dead) or failed, do not restart blindly. First inspect logs to understand why it stopped:

sudo journalctl -u gitlab-runner -n 50 --no-pager

Look for lines containing ERROR, FATAL, or repeated connection timeouts. Common causes include an invalid config.toml, a lost network connection to the GitLab instance, or a full disk.

Check the runner configuration summary (read-only):

sudo gitlab-runner verify --delete

This command contacts the GitLab server and checks whether each runner is still registered. It does not modify the local configuration unless --delete is used, so it is safe to run. Expected output:

Runtime platform                                    arch=amd64 os=linux pid=12345 revision=8a2c1b6e version=16.5.0
Running in system-mode.

Verifying runner... is alive                        runner=AbCdEfGh

If you see is not alive or an authentication error, the runner registration is broken or the token has been revoked. You will need to re-register (see Safe Configuration Path).

Check disk space:

Runners can fill their disk with build artifacts and Docker images. Use:

df -h /var/lib/gitlab-runner

Expected output:

Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1        50G   12G   36G  25% /

If Use% is above 90%, clean up old Docker images and build directories:

sudo docker system prune -af --volumes
sudo gitlab-runner cache-archive --path /var/lib/gitlab-runner/cache --delete-older-than 7d

The second command deletes cache archives older than 7 days. Adjust the time as needed. Always verify disk space after cleanup.

Check runner type and executor:

sudo gitlab-runner list

Expected output:

Runtime platform                                    arch=amd64 os=linux pid=12345 revision=8a2c1b6e version=16.5.0
Listing configured runners                          ConfigFile=/etc/gitlab-runner/config.toml
my-docker-runner                                    Executor=docker Token=xxxxxx URL=https://gitlab.example.com
my-shell-runner                                     Executor=shell Token=xxxxxx URL=https://gitlab.example.com

This shows every runner configured on this host, its executor type, and the GitLab instance it connects to. If the list is empty, no runners are configured, or the config.toml file is missing.

Safe Configuration Path

Changing runner configuration can break pipelines. Follow a controlled process: back up, modify, verify, and be ready to roll back.

Register a New Runner

The register command is the most common configuration change. Before running it, gather these prerequisites:

• GitLab instance URL (e.g., https://gitlab.example.com)
• Registration token from your project's Settings > CI/CD > Runners, or a group/instance token
• A descriptive name for the runner
• An executor type (docker, shell, kubernetes, etc.)
• A tag list (optional but recommended)

Example registration for a Docker executor:

sudo gitlab-runner register \
  --non-interactive \
  --url https://gitlab.example.com \
  --registration-token <your-registration-token> \
  --executor docker \
  --docker-image alpine:latest \
  --description "ci-docker-runner-01" \
  --tag-list "docker,linux,small" \
  --run-untagged=false \
  --locked=false

Expected output on success:

Runtime platform                                    arch=amd64 os=linux pid=12345 revision=8a2c1b6e version=16.5.0
Running in system-mode.

Registering runner... succeeded                     runner=AbCdEfGh
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

Verification after registration:

sudo gitlab-runner verify

If you see is alive for the new runner, it is correctly registered and can connect to the GitLab server. If it says is not alive, check that the URL is reachable from the runner host and that the token was not mistyped.

Edit config.toml Safely

All runner settings live in /etc/gitlab-runner/config.toml (system-wide install). Before editing:

sudo cp /etc/gitlab-runner/config.toml /etc/gitlab-runner/config.toml.bak.$(date +%Y%m%d)
sudo gitlab-runner verify

After editing, always run gitlab-runner verify again. If it fails, restore the backup:

sudo cp /etc/gitlab-runner/config.toml.bak.$(date +%Y%m%d) /etc/gitlab-runner/config.toml
sudo gitlab-runner restart

Unregister a Runner

If a runner is no longer needed, unregister it from the GitLab server and remove its local configuration:

sudo gitlab-runner unregister --url https://gitlab.example.com --token <runner-token>

The runner token is found in config.toml or by running sudo gitlab-runner list. Expected output:

Unregistering runner... succeeded                  runner=AbCdEfGh

After unregistering, remove the runner entry from config.toml manually if it was not automatically removed, then restart the service.

Update Runner Executor

Changing from Docker to Shell executor, for example, requires editing config.toml. Change these lines:

[[runners]]
  name = "my-shell-runner"
  url = "https://gitlab.example.com"
  token = "<your-token>"
  executor = "shell"

Then restart and verify:

sudo gitlab-runner restart
sudo gitlab-runner verify

If the runner still shows the old executor in gitlab-runner list, ensure you edited the correct runner section and that the service loaded the new config.

Verification and Diagnostics

Use these commands to confirm a runner is healthy, troubleshoot job failures, and inspect build logs.

Check Runner Status via API

Every runner can be queried through the GitLab API. Get the runner ID from gitlab-runner list or the CI settings page. Then:

curl --header "PRIVATE-TOKEN: <your-personal-access-token>" \
  "https://gitlab.example.com/api/v4/runners/<runner_id>"

Expected response (truncated):

{
  "id": 42,
  "description": "ci-docker-runner-01",
  "active": true,
  "online": true,
  "status": "online",
  "ip_address": "10.0.0.15",
  "runner_type": "project_type"
}

If online is false, the runner service may be down or cannot reach GitLab. Check systemctl status gitlab-runner and network connectivity.

Test a Job Locally

You can run a simple job directly without GitLab by using gitlab-runner exec. This is useful for debugging executor issues.

For Docker executor:

sudo gitlab-runner exec docker echo-test

Where echo-test is a job defined in .gitlab-ci.yml:

echo-test:
  script:
    - echo "Hello from GitLab Runner"

Expected output:

Running with gitlab-runner 16.5.0 (8a2c1b6e)
  on localhost 12345678
Preparing the "docker" executor
Using Docker executor with image alpine:latest ...
Pulling docker image alpine:latest ...
Using docker image sha256:... for alpine:latest ...
Preparing environment
Running on runner-12345678-project-1-concurrent-0 via hostname...
Getting source from Git repository
Fetching changes...
$ echo "Hello from GitLab Runner"
Hello from GitLab Runner
Job succeeded

If the job fails at Pulling docker image, the runner may not have access to Docker Hub or the configured registry. Check Docker daemon status and network egress.

View Runner Logs for a Job

GitLab Runner writes job logs to its own log file and to the GitLab UI. For system-level issues, tail the runner log:

sudo tail -f /var/log/gitlab-runner/gitlab-runner.log

During a job run, you will see lines like:

Checking for jobs... received                       job=12345 repo_url=https://gitlab.example.com/group/project.git runner=AbCdEfGh
Job succeeded                                       duration_s=12.34 job=12345 project=42 runner=AbCdEfGh

If a job hangs or fails with no clear reason, increase log verbosity by setting log_level = "debug" in config.toml temporarily. Restart the runner, reproduce the job, then set log level back to info.

Check Runner Concurrency and Limits

Use gitlab-runner status to see current running jobs and limits:

sudo gitlab-runner status

Expected output:

Runtime platform                                    arch=amd64 os=linux pid=12345 revision=8a2c1b6e version=16.5.0
Checking status of gitlab-runner...                 runner=runner-01
Service is running.                                  runner=runner-01
Concurrent jobs: 1 / 4                               runner=runner-01
Active jobs: 1                                       runner=runner-01
  12345: project 'my-project' job 'build' ... running runner=runner-01

If Concurrent jobs is at its maximum, new jobs will wait. Increase concurrent in config.toml if the host has resources.

Failure Modes and Recovery

Runners fail for predictable reasons. Here are the most common failure modes, how to diagnose them, and how to recover.

Failure: "Runner is not alive" or "Authentication failed"

This usually means the runner token is invalid or the runner was unregistered from GitLab. Diagnose:

sudo gitlab-runner verify

If verify fails, check config.toml for the correct token, and check the GitLab UI under Settings > CI/CD > Runners to see if the runner exists. If the runner is missing, re-register it using the register command as described earlier.

Failure: Jobs stuck in "pending" state

This often means no runner is picking up jobs due to tags mismatch or runner being offline.

Check runner tags: In .gitlab-ci.yml, a job may specify tags: [docker]. If your runner's tags are docker,linux, it should match. But if the job specifies tags: [windows], no runner will pick it.

Check runner online status: Use the API or gitlab-runner status. If offline, restart the service:

sudo systemctl restart gitlab-runner
sudo systemctl status gitlab-runner

If the service fails to start, inspect logs:

sudo journalctl -u gitlab-runner -n 100 --no-pager | grep -i error

Common startup errors include malformed config.toml (e.g., missing [[runners]] section) or conflicting options.

Failure: Docker executor cannot pull image

Error in job log: ERROR: Preparation failed: Error response from daemon: pull access denied for <image> or no such host.

Fix: Ensure the runner host can reach the image registry. For Docker Hub, test:

docker pull alpine:latest

If that fails, check DNS and firewall. For private registries, ensure the runner has the correct credentials. Add DOCKER_AUTH_CONFIG as a CI variable or configure runners.docker settings in config.toml to include pull_policy = "if-not-present" to use local images when available.

Failure: Runner disk full

If jobs fail with No space left on device, check:

df -h /var/lib/gitlab-runner

Clean up Docker resources if using Docker executor:

sudo docker system prune -af --volumes

Clean up old build directories:

sudo find /var/lib/gitlab-runner/builds -mindepth 1 -maxdepth 1 -type d -mtime +7 -exec rm -rf {} \;

Verify space recovered and restart the runner if necessary.

Failure: Shell executor job fails with permission denied

If the runner user cannot write to the build directory, jobs fail. Check permissions:

sudo ls -ld /var/lib/gitlab-runner
sudo ls -ld /var/lib/gitlab-runner/builds

They should be owned by gitlab-runner:gitlab-runner. Fix with:

sudo chown -R gitlab-runner:gitlab-runner /var/lib/gitlab-runner

Then restart the runner.

Operations Checklist

Use this checklist before and after any change to a GitLab Runner environment.

After any change, run a quick smoke test by triggering a trivial pipeline on a test project. Keep a log of changes with timestamps to aid troubleshooting.

Conclusion

Mastering GitLab Runner commands turns a black-box failure into a systematic diagnosis. The commands in this guide give you a solid foundation for day-to-day operations: version checks, registration, verification, diagnostics, and recovery. Always observe before changing, back up configurations, use placeholders for secrets, and verify after every modification.

As a next step, pick one low-risk verification from this article and run it on your runner. Record the current state, run the check, compare the result with the expected output, and then review dependencies such as GitLab CI/CD, Docker, and Kubernetes. Build a local cheat sheet from these commands and share it with your team to reduce incident response time.

A reliable operational workflow makes failures visible, protects sensitive values, limits changes to the intended resource, and defines recovery verification before an incident forces the decision. With these GitLab Runner commands, you can operate with confidence and keep your CI/CD pipelines running smoothly.