How to fix This job is stuck because the project doesn't have any runners online in Git

The most common cause on GitLab.com is that shared runners are disabled. Enable them:

1. Go to your project in GitLab
2. Navigate to Settings > CI/CD
3. Expand the Runners section
4. Look for "Shared runners" at the bottom
5. Toggle Enable shared runners for this project to ON

# You should see:
Shared runners
Enable shared runners for this project: [ON]
Available shared runners: X

Note: On GitLab.com free tier, shared runners have usage limits. Check Settings > Usage Quotas to ensure you haven't exceeded your CI/CD minutes.

For self-managed GitLab, ask your administrator if shared runners are available.

Check if any runners are assigned to your project:

1. Go to Settings > CI/CD
2. Expand the Runners section
3. Review the available runners

You should see one of these sections:
- Assigned project runners - Runners specific to this project
- Assigned group runners - Runners shared within your group
- Shared runners - GitLab-provided runners

For each runner, check:
- Green circle: Runner is online and available
- Gray circle: Runner is offline
- Warning icon: Runner has configuration issues

# Healthy runner display:
Runner #12345 (my-runner)
Status: online
Tags: docker, linux

If no runners appear or all are offline, you need to register a new runner or troubleshoot existing ones.

If your job specifies tags but no runner has those tags, the job will be stuck:

Check your .gitlab-ci.yml for tags:

# This job requires a runner with 'docker' and 'linux' tags
build:
  tags:
    - docker
    - linux
  script:
    - echo "Building..."

Option 1: Remove tags to use any available runner:

build:
  # No tags - any runner can pick this up
  script:
    - echo "Building..."

Option 2: Configure runner to accept untagged jobs:
1. Go to Settings > CI/CD > Runners
2. Click the pencil/edit icon on your runner
3. Enable Run untagged jobs
4. Click Save changes

Option 3: Add matching tags to your runner:
1. Edit your runner's config.toml:

[[runners]]
  name = "my-runner"
  tags = ["docker", "linux"]

2. Or update tags in GitLab UI under runner settings

Option 4: Use available tags in your job:

build:
  tags:
    - saas-linux-small-amd64  # GitLab.com shared runner tag
  script:
    - echo "Building..."

If you need a dedicated runner for your project, register one:

Step 1: Get registration token
1. Go to Settings > CI/CD > Runners
2. Click New project runner
3. Configure runner options (tags, description)
4. Click Create runner
5. Copy the registration token shown

Step 2: Install GitLab Runner

# Linux (Debian/Ubuntu)
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt-get install gitlab-runner

# Linux (RHEL/CentOS/Fedora)
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" | sudo bash
sudo yum install gitlab-runner

# macOS
brew install gitlab-runner

# Windows (PowerShell as Administrator)
# Download from https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-windows-amd64.exe

Step 3: Register the runner (GitLab 17.5+)

# IMPORTANT: Use sudo for system-mode runner
sudo gitlab-runner register \
  --url https://gitlab.com \
  --token YOUR_REGISTRATION_TOKEN

# Follow the prompts to configure:
# - Description: my-project-runner
# - Tags: docker,linux (optional)
# - Executor: docker, shell, etc.

Step 4: Start the runner service

# Install and start as system service
sudo gitlab-runner install
sudo gitlab-runner start

# Verify it's running
sudo gitlab-runner status

If your runner shows as offline, check these common issues:

Verify the runner service is running:

# Check service status
sudo gitlab-runner status

# If not running, start it
sudo gitlab-runner start

# View runner logs for errors
sudo gitlab-runner --debug run

Check if runner was registered in user mode:

# List all registered runners
gitlab-runner list

# If registered without sudo, re-register with sudo
sudo gitlab-runner register

Verify network connectivity:

# Test connection to GitLab
curl -v https://gitlab.com/api/v4/version

# For self-managed GitLab
curl -v https://your-gitlab-instance.com/api/v4/version

Check runner configuration:

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

# Verify token is valid
# The runner should show as "online" in GitLab UI

Restart the runner:

sudo gitlab-runner restart

# Or stop and start
sudo gitlab-runner stop
sudo gitlab-runner start

Ensure your runner's executor is properly configured:

Docker executor issues:

# Verify Docker is running
docker info

# Check runner config for Docker executor
cat /etc/gitlab-runner/config.toml

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

Shell executor issues:

[[runners]]
  name = "my-runner"
  executor = "shell"
  shell = "bash"

Common Docker executor fixes:

# Add gitlab-runner user to docker group
sudo usermod -aG docker gitlab-runner

# Restart Docker and runner
sudo systemctl restart docker
sudo gitlab-runner restart

Test runner can execute jobs:

# Verify runner by running a test
sudo gitlab-runner verify

If all runners are busy with other jobs, you may need to wait or add capacity:

Check runner concurrency:

# /etc/gitlab-runner/config.toml
concurrent = 4  # Increase to allow more parallel jobs

[[runners]]
  name = "my-runner"
  limit = 0  # 0 = unlimited, or set a specific limit

Monitor runner capacity:
1. Go to Admin Area > CI/CD > Runners (self-managed)
2. Or Settings > CI/CD > Runners (project level)
3. Check how many jobs each runner is processing

Add more runners:
- Register additional runners on the same or different machines
- Consider using autoscaling runners for variable workloads

Prioritize critical jobs:

# Lower numbers = higher priority (run first)
critical_build:
  tags:
    - docker
  resource_group: production
  script:
    - ./deploy.sh

Cancel stuck or unnecessary jobs:
1. Go to Build > Pipelines
2. Find running pipelines using resources
3. Click Cancel on non-essential jobs

Once you've fixed the runner configuration, retry your stuck job:

Manual retry:
1. Go to your pipeline in Build > Pipelines
2. Click on the stuck/pending job
3. Click Cancel to stop the stuck job
4. Click Retry or Run to restart it

Retry entire pipeline:
1. Navigate to the pipeline
2. Click Retry button (circular arrow) at the top
3. Or push a new commit to trigger a fresh pipeline:

git commit --allow-empty -m "ci: retry pipeline"
git push origin your-branch

Verify job is picked up:
- Job should change from "pending" to "running" within seconds
- Runner name appears in job sidebar showing which runner picked it up
- Log output starts appearing as the job executes

If job is still stuck:
1. Clear runner cache: Settings > CI/CD > General pipelines > Clear runner caches
2. Check if runner went offline again
3. Verify tag configuration matches