GitLab Runner Registration Failed — Fix Guide (2026)

# Registration fails
ERROR: Registering runner... failed
runner=abc123
status=couldn't execute POST against https://gitlab.com/api/v4/runners:
Post "https://gitlab.com/api/v4/runners": dial tcp: connection refused
 
# Runner shows offline
Shared Runner #1234 is offline
 
# Jobs stuck
This job is stuck because the project doesn't have any runners online assigned to it.
 
# Token error
ERROR: Registering runner... failed
status=404 Not Found

# For self-managed runner
gitlab-runner status
# or
systemctl status gitlab-runner
 
# Check runner list
gitlab-runner list
 
# Verify runner can reach GitLab
curl -v https://gitlab.com/api/v4/runners/verify \
  --request POST \
  --form "token=<runner-token>"

# Get a fresh registration token from GitLab:
# Project → Settings → CI/CD → Runners → Registration token
 
# Re-register with fresh token
gitlab-runner register \
  --url https://gitlab.com \
  --registration-token <fresh-token> \
  --executor docker \
  --docker-image alpine:latest \
  --description "my-runner" \
  --non-interactive
 
# Verify
gitlab-runner verify

# New way (GitLab 16+)
# Create runner in GitLab UI first: Admin → CI/CD → Runners → New runner
# Get the token from the UI, then:
gitlab-runner register \
  --url https://gitlab.com \
  --token <runner-authentication-token> \
  --executor docker \
  --docker-image alpine:latest \
  --non-interactive

# Test connectivity
curl -v https://gitlab.com
 
# If using self-hosted GitLab
curl -v https://your-gitlab.company.com
 
# Check DNS resolution
nslookup gitlab.com
 
# Check if port 443 is open
nc -zv gitlab.com 443
 
# Check firewall rules (Linux)
iptables -L -n | grep 443

# Set proxy in runner config
# Edit /etc/gitlab-runner/config.toml
[[runners]]
  environment = ["HTTPS_PROXY=http://proxy.company.com:8080", "HTTP_PROXY=http://proxy.company.com:8080"]

# Check Docker is running
systemctl status docker
 
# Check runner can use Docker
docker ps
 
# Runner user needs to be in docker group
usermod -aG docker gitlab-runner
 
# Restart runner after adding to docker group
systemctl restart gitlab-runner

# Check runner pods are running
kubectl get pods -n gitlab
 
# Check logs
kubectl logs -n gitlab -l app=gitlab-runner --tail=50
 
# Check runner config
kubectl get configmap -n gitlab gitlab-runner -o yaml

# The runner service account needs permission to create pods
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: gitlab-runner
  namespace: gitlab
rules:
- apiGroups: [""]
  resources: ["pods", "pods/exec", "pods/log", "secrets", "configmaps"]
  verbs: ["get", "list", "watch", "create", "delete", "update", "patch"]

# In your .gitlab-ci.yml
build:
  tags:
    - kubernetes    # must match runner's tags
  script:
    - echo "building"

# Check what tags the runner has
kubectl get configmap -n gitlab gitlab-runner -o yaml | grep tags

concurrent = 4
check_interval = 0
 
[[runners]]
  name = "my-runner"
  url = "https://gitlab.com"
  token = "runner-authentication-token"
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "alpine:latest"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0

# Error: x509: certificate signed by unknown authority
gitlab-runner register \
  --tls-ca-file /path/to/ca.crt \
  ...
 
# Or disable TLS verification (not for production)
[[runners]]
  tls-skip-verify = true

# Copy CA cert to system store
cp your-ca.crt /usr/local/share/ca-certificates/
update-ca-certificates
 
# Restart runner
systemctl restart gitlab-runner

# In .gitlab-ci.yml — if no tags specified, job only runs on untagged runners
# Add or remove tags to match your runner
 
# Check if runner is locked to a specific project
# GitLab UI: Runner settings → "Lock to current projects"
# Unlock it or assign to the project

# 1. Check runner service
systemctl status gitlab-runner
 
# 2. Check logs (most useful)
journalctl -u gitlab-runner -n 50
tail -f /var/log/gitlab-runner/gitlab-runner.log
 
# 3. Run in debug mode
gitlab-runner --debug run
 
# 4. Verify token is valid
gitlab-runner verify --delete
 
# 5. Test connectivity
curl https://gitlab.com/api/v4/version
 
# 6. Re-register if needed
gitlab-runner unregister --all-runners
gitlab-runner register ...