# GitLab Runner Not Picking Up Jobs: Complete Fix Guide

Your GitLab CI pipeline shows jobs as "pending" but your runner just sits there idle. You've registered the runner, it shows as online, but it won't pick up any jobs. This disconnect between runner availability and job execution is a common GitLab CI headache.

Let me walk through all the reasons a runner won't pick up jobs and how to fix each one.

Quick Diagnosis: Why Isn't the Runner Working?

Start with these checks:

bash
# On the runner machine
sudo gitlab-runner status        # Is it running?
sudo gitlab-runner verify        # Is it registered correctly?
sudo gitlab-runner list          # What runners are configured?

If all these pass but jobs still don't run, the issue is likely tags, configuration, or GitLab server-side settings.

Fix 1: Runner Not Registered or Registration Expired

The runner may not be properly registered with GitLab.

Symptoms: - Runner shows offline in GitLab - gitlab-runner verify shows errors

Diagnosis:

```bash # Check registration status sudo gitlab-runner verify

# Look for errors like: # Verifying runner... is not valid... runner removed ```

Solution:

Re-register the runner:

```bash # 1. Get the registration token from GitLab # Settings → CI/CD → Runners → "Set up a specific runner manually" # Copy the registration token

# 2. Register the runner sudo gitlab-runner register --url https://gitlab.com --registration-token YOUR_REGISTRATION_TOKEN

# Follow prompts: # - Enter tags (comma-separated): docker,linux,production # - Enter executor: docker, shell, kubernetes, etc. # - Enter default Docker image (if using docker executor): alpine:latest

# 3. Verify registration sudo gitlab-runner verify sudo gitlab-runner list ```

For non-interactive registration:

bash
sudo gitlab-runner register \
  --non-interactive \
  --url https://gitlab.com \
  --registration-token YOUR_TOKEN \
  --executor docker \
  --docker-image alpine:latest \
  --description "my-docker-runner" \
  --tag-list "docker,linux" \
  --run-untagged=true

Fix 2: Tag Mismatch Between Job and Runner

Jobs specify tags, but runners don't have matching tags. This is the most common cause.

Symptoms: - Jobs show "pending" or "stuck" - GitLab shows: "There are no runners that match the tags" - Runner shows online in GitLab

Diagnosis:

Check your job definition:

yaml
# .gitlab-ci.yml
deploy_job:
  tags:
    - production
    - kubernetes
  script:
    - kubectl apply -f deployment.yaml

Check runner tags:

bash
# On runner machine
cat /etc/gitlab-runner/config.toml | grep -A 5 "name"
  1. 1.Or in GitLab UI:
  2. 2.Go to Settings → CI/CD → Runners
  3. 3.Click on the runner
  4. 4.Check "Tags" field

Solution:

Either add tags to the runner:

```bash # Edit runner config sudo nano /etc/gitlab-runner/config.toml

# Find your runner and add tags [[runners]] name = "my-runner" token = "..." executor = "docker" tag_list = "production,kubernetes,docker" # Add these tags

# Restart runner sudo gitlab-runner restart ```

Or modify the job to use available tags:

yaml
deploy_job:
  tags:
    - docker  # Use tags your runner actually has
  script:
    - kubectl apply -f deployment.yaml

Important: A runner with tags will NOT pick up untagged jobs unless "Run untagged jobs" is enabled.

To enable untagged job pickup:

  1. 1.Go to Settings → CI/CD → Runners
  2. 2.Click the pencil icon on your runner
  3. 3.Check "Run untagged jobs"
  4. 4.Save changes

Fix 3: Runner Paused or Locked

The runner might be paused in GitLab or locked to a specific project.

Symptoms: - Runner shows "paused" in GitLab UI - Runner has lock icon next to it

Diagnosis:

  1. 1.In GitLab UI:
  2. 2.Go to Settings → CI/CD → Runners
  3. 3.Look for a "paused" badge or lock icon

Solution:

Unpause the runner:

  1. 1.Click on the runner
  2. 2.Click "Resume" or uncheck "Paused"
  3. 3.If locked, check "Lock to current projects" is set correctly

To lock/unlock: - Locked: Runner only picks up jobs from the project it was registered to - Unlocked: Runner can pick up jobs from any project in the group/instance

Fix 4: Executor Configuration Issues

The runner's executor might be misconfigured.

Symptoms: - Runner picks up job but fails immediately - Error: "Executor not found" or Docker errors

Diagnosis:

```bash # Check runner config cat /etc/gitlab-runner/config.toml

# Look at executor type # Common executors: docker, shell, kubernetes, virtualbox, ssh ```

Solution for Docker executor:

```bash # Ensure Docker is installed and running sudo systemctl status docker

# Test Docker access docker ps

# If permission denied, add runner user to docker group sudo usermod -aG docker gitlab-runner sudo systemctl restart gitlab-runner ```

Config for Docker executor:

toml
[[runners]]
  name = "docker-runner"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = false
    volumes = ["/cache"]

Solution for shell executor:

bash
# Ensure the runner user has necessary permissions
sudo -u gitlab-runner -H bash -c 'whoami'
sudo -u gitlab-runner -H bash -c 'ls /builds'  # Should be writable

Config for shell executor:

toml
[[runners]]
  name = "shell-runner"
  executor = "shell"
  builds_dir = "/home/gitlab-runner/builds"
  shell = "bash"

Fix 5: Concurrency Limits

The runner might have reached its concurrent job limit.

Symptoms: - Some jobs run but others queue - Jobs stuck pending while runner shows running jobs

Diagnosis:

```bash # Check current concurrent setting cat /etc/gitlab-runner/config.toml | grep concurrent

# Check how many jobs runner is processing ps aux | grep gitlab-runner ```

Solution:

Increase the concurrent limit:

```bash # Edit config sudo nano /etc/gitlab-runner/config.toml

# Add or modify at the top concurrent = 10 # Number of jobs runner can process simultaneously

# Restart sudo gitlab-runner restart ```

  1. 1.Also check GitLab's global limit:
  2. 2.Go to Admin Area → Settings → CI/CD
  3. 3.Look for "Maximum jobs per runner"

Fix 6: Network Connectivity Issues

The runner can't reach GitLab.

Symptoms: - Runner shows offline intermittently - gitlab-runner verify fails with connection errors

Diagnosis:

```bash # Test connectivity curl -I https://gitlab.com

# Test runner endpoint curl -I https://gitlab.com/api/v4/runners

# Check DNS resolution nslookup gitlab.com

# Check if runner is using correct URL cat /etc/gitlab-runner/config.toml | grep url ```

Solution:

Fix network issues:

```bash # If using proxy, configure it export HTTP_PROXY=http://proxy.company.com:8080 export HTTPS_PROXY=http://proxy.company.com:8080 export NO_PROXY=localhost,127.0.0.1,.company.com

# Add to runner environment sudo nano /etc/gitlab-runner/config.toml ```

Add to config:

toml
[[runners]]
  name = "my-runner"
  environment = ["HTTP_PROXY=http://proxy.company.com:8080", "HTTPS_PROXY=http://proxy.company.com:8080"]

For self-hosted GitLab, verify the URL:

bash
# Re-register with correct URL
sudo gitlab-runner unregister --all-runners
sudo gitlab-runner register --url https://gitlab.company.com --registration-token YOUR_TOKEN

Fix 7: Docker Pull Issues

For Docker executors, image pull failures prevent jobs from starting.

Symptoms: - Job shows "Preparing environment" forever - Error: "failed to pull image"

Diagnosis:

```bash # Check if Docker can pull images docker pull alpine:latest

# Check Docker Hub connectivity docker login

# Check for private registry issues docker pull your-private-registry.com/image:latest ```

Solution:

Add Docker registry credentials:

bash
# Edit runner config
sudo nano /etc/gitlab-runner/config.toml
toml
[[runners]]
  [runners.docker]
    # ... existing config ...
    [[runners.docker.services]]
      name = "docker:dind"
    [runners.docker.pull_policies]
      pull_policy = ["if-not-present"]

For private registries, create a Docker config:

```bash # Log in to private registry docker login private-registry.com

# Copy credentials to runner sudo mkdir -p /home/gitlab-runner/.docker sudo cp ~/.docker/config.json /home/gitlab-runner/.docker/ sudo chown gitlab-runner:gitlab-runner /home/gitlab-runner/.docker/config.json ```

Fix 8: Self-Signed Certificate Issues

If your GitLab uses self-signed certificates, the runner won't connect.

Symptoms: - x509: certificate signed by unknown authority - Runner verification fails

Solution:

```bash # Get the certificate echo -n | openssl s_client -showcerts -connect gitlab.company.com:443 2>/dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > gitlab.crt

# Copy to system certificates sudo cp gitlab.crt /usr/local/share/ca-certificates/ sudo update-ca-certificates

# Restart runner sudo systemctl restart gitlab-runner

# Or specify cert in config sudo nano /etc/gitlab-runner/config.toml ```

Add to config:

toml
[[runners]]
  tls-ca-file = "/path/to/gitlab.crt"

Fix 9: Token Issues

The runner token might be invalid or revoked.

Symptoms: - Runner shows "forbidden" or "unauthorized" - Logs show 403 errors

Solution:

Reset the runner token:

  1. 1.Go to Settings → CI/CD → Runners
  2. 2.Find your runner
  3. 3.Click "Reset registration token" or remove and re-register

```bash # Unregister old runner sudo gitlab-runner unregister --name "my-runner"

# Re-register sudo gitlab-runner register --url https://gitlab.com --registration-token NEW_TOKEN ```

Quick Reference: Runner Troubleshooting Commands

```bash # Check runner status sudo gitlab-runner status

# Verify registration sudo gitlab-runner verify

# List runners sudo gitlab-runner list

# View config cat /etc/gitlab-runner/config.toml

# Check logs sudo journalctl -u gitlab-runner -f

# Run in debug mode sudo gitlab-runner --debug run

# Test a job locally sudo gitlab-runner exec docker job_name

# Restart runner sudo systemctl restart gitlab-runner

# Check Docker status (for docker executor) sudo systemctl status docker docker ps docker info ```