## 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 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 \ --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 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 = "" 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: " \ "https://gitlab.example.com/api/v4/runners/" 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 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.
StepCommand / ActionExpected ResultFailure SignalRecovery
1. Version checkgitlab-runner --versionDisplays version and architectureCommand not foundInstall or fix PATH
2. Service statussystemctl status gitlab-runnerActive (running)inactive or failedCheck logs, restart if safe
3. Runner verificationsudo gitlab-runner verifyAll runners "is alive""is not alive" or auth errorRe-register runner
4. Configuration backupcp config.toml config.toml.bakBackup file existsFile copy errorCheck disk space, permissions
5. Registrationgitlab-runner register --non-interactive ...Success message with runner tokenRegistration failedCheck URL, token, network
6. Post-change verifysudo gitlab-runner verifyAll runners aliveAny failureRestore config backup, restart
7. Job testgitlab-runner exec docker test-jobJob succeededJob failedCheck executor config, image pull
8. Disk spacedf -h /var/lib/gitlab-runnerUse% below 80%Use% above 90%Clean Docker images, old builds
9. Log monitoringtail -f /var/log/gitlab-runner/gitlab-runner.logJobs completing successfullyErrors or timeoutsAddress specific error, increase log level
10. Concurrency checksudo gitlab-runner statusConcurrent jobs below limitAt or above limitIncrease concurrent value or add another runner
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.