iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
If GitLab marks a runner never_contacted, GitLab has not recorded a successful contact from that runner. The status does not identify why. GitLab’s first suggested action is to run gitlab-runner run on the runner host; then use the runner’s logs to find the failing layer instead of applying every possible fix.
What never_contacted means
GitLab defines never_contacted as a runner that has never contacted the instance. In GitLab’s current documentation, online means contact within the last two hours, offline means no contact for more than two hours, and stale means no contact for more than seven days. These are GitLab’s operational status definitions, not a diagnosis of the runner’s condition. GitLab’s runner management documentation gives the immediate action for the never-contacted state: run gitlab-runner run.
The cause could be as basic as a stopped process, or it could be a wrong instance URL, invalid or misapplied credentials, a version incompatibility, or a DNS, proxy, or TLS problem. Start with the process and its logs; the error message should guide the next check.
1. Start the runner and inspect its logs
Run gitlab-runner run on the machine or in the environment where the runner is configured. If it starts contacting GitLab, check its service or container setup so it continues running outside an interactive session.
#1 Best Overall
For an existing deployment, inspect logs using the command for that environment. Replace example names with the actual service, container, or pod name:
- Linux service:
journalctl --unit=gitlab-runner.service -n 100 --no-pager - Docker:
docker logs gitlab-runner-container - Kubernetes:
kubectl logs gitlab-runner-pod
If you have just changed the configuration, restart the runner service and follow its logs for new errors. A restart cannot correct a bad URL, credential, or network route by itself. GitLab’s troubleshooting guide describes these log sources and checks.
Rank #2
2. Check the instance URL and runner credentials
Inspect the effective configuration in config.toml, which GitLab Runner uses to store runner configuration. The configured URL must identify the GitLab instance, not a project page. For a project at gitlab.example.com/group/project, the instance URL is https://gitlab.example.com. For GitLab.com, use https://gitlab.com; for a self-managed installation, use its base URL.
Confirm that the runner was registered against the intended instance and with the intended project, group, or instance workflow. GitLab recommends runner authentication tokens. Registration tokens are a legacy workflow: GitLab says their use was disabled on all instances in GitLab 17.0 unless enabled, and its registration documentation schedules registration tokens and several related arguments for removal in GitLab 20.0. The behavior therefore depends on the GitLab version and configuration in use; check the deployed version’s guidance. GitLab’s registration guide explains the current workflow.
Rank #3
Authentication tokens appear in the UI only for a limited period during registration and are stored in config.toml afterward. Treat them as secrets: do not paste a token into public logs, issue reports, or support posts. If the token may have been exposed, follow your GitLab administrator’s credential rotation process.
3. Check GitLab and Runner version compatibility
GitLab recommends checking the GitLab and GitLab Runner versions early in troubleshooting and matching them where possible. A mismatch does not automatically cause never_contacted, so use the logs to confirm whether compatibility is relevant.
One specific incompatibility is documented: Runner 15.0 changed the registration request format, which prevents communication with earlier GitLab versions. If your logs and version history point to this issue, use a compatible Runner version or upgrade GitLab. See the version notes in GitLab’s registration documentation and the checks in its troubleshooting guide.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match4. Follow the network and TLS errors
The runner process’s network path may differ from the host’s or from the build environment’s. Diagnose the environment running the runner itself: an interactive shell can have different proxy variables, DNS configuration, and certificate trust from a system service or container.
Best Value
Proxy configuration
If registration must pass through an HTTP proxy, GitLab documents setting HTTP_PROXY and HTTPS_PROXY before running registration. Make sure those variables reach the actual runner service or container; setting them only in your interactive shell may not configure a system service. Follow GitLab’s registration instructions and configuration guidance for your deployment.
DNS in Docker
With the Docker executor, DNS resolution inside the runner’s container may differ from the host’s. This can matter when GitLab and Runner use separate networks, VPNs, or internet paths. GitLab documents a dns setting under [runners.docker] in config.toml. Choose a DNS server that is appropriate for your environment; do not copy an example address without checking that it can resolve and reach the required GitLab instance. GitLab’s troubleshooting guide covers this configuration.
TLS certificate errors
If the log reports x509: certificate signed by unknown authority, check whether the runner trusts the certificate chain used by your GitLab instance, including any required self-signed certificate configuration. GitLab documents certificate setup in its Runner configuration guide. Disabling TLS verification is not a safe general fix.
Intermediaries and correlation IDs
Runner logs include correlation IDs for API requests. GitLab says a fallback correlation ID can mean the request did not reach Workhorse, which points the investigation toward an intermediary such as a web application firewall (WAF), content delivery network (CDN), load balancer, or proxy. Where server logs are available, match the request’s ID between Runner and GitLab logs to identify how far it traveled. GitLab’s troubleshooting guide explains the correlation-ID clue.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.5. Check runner scope after connectivity
Runner scope determines which projects can use a runner; it is a separate check from whether the runner host has contacted GitLab. GitLab distinguishes instance, group, and project runners. A project runner must be enabled for each relevant project, while group and instance settings affect availability at their respective scopes. If the runner has begun contacting GitLab but jobs cannot use it, check its scope and project settings in GitLab’s runner management documentation.
Quick Recap
Quick diagnostic order
- Run
gitlab-runner runin the runner’s execution environment. - Read that environment’s service, Docker, or Kubernetes logs and note the exact error.
- Verify the base instance URL, registration workflow, and authentication token in
config.toml. - Compare GitLab and Runner versions, especially if registration fails against an older GitLab instance.
- Investigate only the network layer indicated by the logs: proxy, container DNS, TLS trust, or an intermediary hop.
- Once contact is established, check runner scope separately if the runner is unavailable to jobs.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
