Skip to content
Exlogare
← Back to all posts
by Exlogare Team GitLab runner CI/CD troubleshooting

GitLab Runner: docker, shell, and kubernetes executor failure classes

Why the same GitLab job behaves differently on docker, shell, and kubernetes executors: registry auth, volumes/cache, DNS, permissions, and pod scheduling.

GitLab Runner is the machine or process that actually runs your job. The .gitlab-ci.yml may look the same, but behavior changes a lot between docker, shell, and kubernetes executors.

For junior and mid-level engineers, a useful model is: YAML describes intent; the executor defines the environment where that intent runs.

Executor primer

The Docker executor runs the job in a container. The Shell executor runs commands directly on the runner host. The Kubernetes executor creates a pod in a cluster. A failure log often tells you about the environment, not only the code.

Docker executor: registry and filesystem

Common symptoms:

  • pull access denied;
  • no basic auth credentials;
  • Cannot connect to the Docker daemon;
  • an artifact exists in one job but disappears in another.

Check image name, registry URL, credentials, volumes, and cache paths. A common root cause is an expired registry token or a runner that cannot access a private image.

Shell executor: contaminated host state

Shell is fast, but the job inherits host state:

  • old Node/Python/Java versions;
  • files from previous runs;
  • runner user permissions;
  • local cache that “fixes” a problem only on one host.

If it works on a shell runner but fails in Docker, that does not prove the code is correct. It tells you to inspect the environment.

Kubernetes executor: network and scheduling

Kubernetes failures often look like:

  • ImagePullBackOff;
  • DNS failures to registry or services;
  • pod cannot start because of resource limits;
  • volume mount errors;
  • service container is not ready yet.

Here, the job log can be short while the cause is in pod events. Check Kubernetes events and pod description, not only the GitLab UI.

Where Exlogare fits

RCA needs to classify the failure: code, dependency, runner, or infrastructure. Exlogare receives the failed-job log and can highlight the likely class in the MR: “looks like registry auth in the docker executor,” not just “tests failed.” Setup is in GitLab CI ingest.

Related reading

Checklist

  • Identify the executor of the specific runner.
  • Check image pull and registry auth.
  • Compare runtime versions.
  • For shell runners, inspect host state.
  • For Kubernetes runners, read pod events.
  • Do not mix infra failures and code regressions in one conclusion.