GitLab CI/CD Troubleshooting Guide: Fix Runner, YAML, Docker, Cache, Artifacts, and Deployment Issues

GitLab CI/CD Troubleshooting Guide#

Learn how to debug common GitLab CI/CD issues including YAML errors, stuck jobs, runner problems, variable issues, cache and artifact failures, Docker build errors, Kubernetes deployment failures, and security scanning problems.

Table of contents#

• Quick answer
• YAML syntax errors
• Jobs stuck in pending
• Runner errors
• Variables and secrets issues
• Artifacts and cache issues
• Docker build errors
• Kubernetes deployment errors
• Security scanning issues
• Debug checklist
• Related Melochip guides

Quick answer#

Read the job log first#

The job log usually shows the exact command, error message, missing variable, or failed step.

Validate YAML#

Use GitLab CI Lint before committing complex .gitlab-ci.yml changes.

Check runner status#

If jobs stay pending, check runner availability, runner tags, executor, and project/group runner settings.

Check variables#

If deployments or Docker logins fail, check masked/protected variables, branch protection, and variable names.

1. YAML syntax errors#

YAML errors are one of the most common GitLab CI/CD problems. A small indentation mistake, wrong quote, or invalid keyword can stop the pipeline from starting.

Common YAML error example#

build_job: stage: build script: - echo "Build"

The indentation is inconsistent. Correct version:

build_job: stage: build script: - echo "Build"

2. GitLab job stuck in pending#

If a job stays in pending, GitLab created the job but no runner is available to pick it up.

Common reasons#

• No active runner is assigned to the project or group.
• Runner tags do not match job tags.
• Runner is offline.
• Runner is paused.
• Runner is locked to another project.
• Protected runner cannot run unprotected branch jobs.

Example tag mismatch#

test_job: tags: - docker script: - echo "Testing"

If no runner has the docker tag, this job may stay pending. Either add the tag to a runner or update the job tags.

3. GitLab Runner errors#

On an Ubuntu runner host, useful commands include:

gitlab-runner --version sudo gitlab-runner status sudo gitlab-runner list sudo gitlab-runner verify sudo gitlab-runner restart

If the runner service is not active, restart it and check system logs:

sudo systemctl status gitlab-runner sudo journalctl -u gitlab-runner -n 100 --no-pager

4. Variables and secrets issues#

If a job works locally but fails in GitLab CI/CD, a missing or protected variable is often the reason.

5. Artifacts and cache issues#

Artifacts and cache solve different problems. If you mix them up, pipelines become unreliable.

Artifact not found#

Common causes:

• The artifact path is wrong.
• The folder was never created.
• The artifact expired.
• The next job did not download artifacts.

Cache not working#

Common causes:

• Wrong cache path.
• Unstable cache key.
• Runner cache storage not configured properly.
• Expecting cache to behave like required build output.

6. Docker build errors#

Docker pipeline failures usually come from Docker daemon access, registry authentication, image tags, or Dockerfile problems.

7. Kubernetes deployment errors#

Kubernetes deployment failures often happen because of kubeconfig, RBAC permissions, image pull errors, namespace problems, or rollout failures.

Useful kubectl debugging commands#

kubectl get pods kubectl get deployment kubectl describe deployment demo-app kubectl rollout status deployment/demo-app kubectl logs deployment/demo-app kubectl get events --sort-by=.metadata.creationTimestamp

Common Kubernetes CI/CD errors#

8. Security scanning issues#

Security scanning jobs can fail when templates are added incorrectly, the project language is unsupported, lock files are missing, or the container image does not exist before scanning.

• For SAST, confirm the language and analyzer support.
• For dependency scanning, commit lock files where possible.
• For secret detection, rotate real exposed secrets immediately.
• For container scanning, build and push the image before scanning it.
• Review security reports instead of ignoring failed scan jobs.

GitLab CI/CD troubleshooting checklist#

Best practices to avoid future issues#

• Validate YAML before merging pipeline changes.
• Use clear job names and simple stages.
• Use runner tags intentionally.
• Keep variables organized and documented.
• Use artifacts for required outputs and cache for dependencies.
• Use commit SHA tags for Docker images.
• Use manual protected jobs for production deployment.
• Review failed job logs before changing random settings.
• Keep GitLab Runner updated.
• Document known fixes for your team.

Screenshot checklist#

You can add your own screenshots later from a safe test project:

1. Pipeline failed job page.
2. Job log with sensitive values hidden.
3. Runner settings showing active runner and tags.
4. CI Lint validation result.
5. Artifacts download or missing artifact message.
6. Docker build error example with secrets hidden.
7. Kubernetes rollout failure example with safe sample names.

• GitLab CI/CD Learning Path
• GitLab CI/CD YAML Syntax Explained
• GitLab Runner Setup on Ubuntu
• GitLab Artifacts vs Cache Explained
• GitLab CI/CD Docker Build Pipeline
• GitLab CI/CD Deploy to Kubernetes

Official references#

• GitLab CI Lint documentation
• GitLab Runner documentation
• GitLab CI/CD YAML reference
• GitLab CI/CD debugging documentation

Conclusion#

GitLab CI/CD troubleshooting becomes easier when you follow a clear process: validate YAML, check runner status, read job logs, confirm variables, verify artifacts/cache, and debug Docker or Kubernetes steps separately.

Do not guess blindly. The fastest fix usually starts with the exact error message in the job log.