Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 36 ยท Runners and Jobs

Executors and Job Environments

Compare GitLab Runner executors (shell, Docker, Kubernetes, autoscaling, SSH, custom), see how each isolates jobs, and pick the right one for your workload.

The executor is the part of a runner that decides where and how a job's commands run. Same .gitlab-ci.yml, very different behavior: with the shell executor your commands run directly on the runner machine; with the Docker executor each job runs inside a fresh container; with Kubernetes each job becomes a pod. You choose the executor when you register the runner.

The main executors

Shell. Commands run in a shell on the runner host, as the gitlab-runner user. It is the simplest to set up and the fastest to start: no images, no containers, whatever is installed on the machine is available. The downsides are serious: jobs are not isolated from each other or from the host, leftover files and installed tools can leak between jobs, and a job can read anything the runner user can. Use it for trusted code on dedicated machines, for example macOS or Windows build hosts, or deployment machines.

Docker. Each job runs in a new container created from an image (image: in the job or the runner's default). The job sees a clean filesystem every time, and you get exactly the tools in the image: image: node:22 means Node 22 and nothing else. Extra containers can run beside it as services, such as a database (see images and services). This is the most popular executor because it combines isolation with reproducibility.

Kubernetes. The runner runs inside or against a cluster and starts each job as a pod, with the build container and services as containers in the same pod. It scales with the cluster and uses its scheduling, quotas and security policies. It needs Kubernetes knowledge to operate but fits organizations already running clusters.

Docker Autoscaler and Instance executors. Newer autoscaling executors create cloud virtual machines on demand (through plugins for AWS, Google Cloud and Azure), run jobs on them and remove them when idle. The older Docker Machine executor did something similar but is deprecated in favor of these. Autoscaling gives each job a clean VM and good isolation, and you pay only while jobs run.

SSH, VirtualBox, Parallels, Custom. SSH runs commands on a remote machine, VirtualBox and Parallels start virtual machines, and the custom executor lets you write your own scripts to prepare, run and clean up. They are niche but useful for unusual environments.

Comparing them

Executor Isolation Clean state per job Setup effort Typical use
Shell None (host) No Lowest Trusted builds, macOS/Windows hosts, deployments
Docker Container Yes Low General purpose, most projects
Kubernetes Pod Yes Higher Large scale in clusters
Autoscaling VM Virtual machine Yes Higher Elastic capacity, untrusted code
Custom You decide You decide Highest Special platforms

Pick an executor

Shell Fast, no isolation
Docker Clean container per job
Kubernetes A pod per job
Autoscaling Fresh VMs on demand

The more isolation you need, the further right you go.

1 / 2

The next stand-in turns the table into a decision helper. Answer a few questions and it recommends an executor. The rules are an opinionated summary, not an official algorithm.

Python Stand-in: recommend an executor

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

What the Docker executor does for a job

Understanding the sequence helps you debug it:

  1. Pull the helper image (GitLab's own, used for cloning, caches and artifacts) and the job image, according to pull_policy.
  2. Start any service containers.
  3. Create a build container from the job image with the repository volume mounted.
  4. Run before_script and script inside that container, line by line.
  5. Run after_script, upload artifacts and cache with the helper, then remove the containers.
flowchart TD
  A["Pull helper and job images"] --> B["Start service containers"]
  B --> C["Clone repository into a volume"]
  C --> D["Run before_script and script in the job container"]
  D --> E["Upload artifacts and cache"]
  E --> F["Remove containers"]

Everything in steps B to D disappears at step F, which is why jobs are reproducible.

Which image does a job use? The most specific setting wins: the job's own image, otherwise default:image (or the top-level image), otherwise the runner's [runners.docker] image. The stand-in below mirrors this lookup and the pull_policy choice.

Python Stand-in: which image does the job get?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

pull_policy = "always" is the safest for mutable tags like latest but slower and counts against registry rate limits. if-not-present is faster, but you may run a stale image. Pin versions (for example node:22.11) or even digests for repeatable builds.

Working directory, cleanliness and cleanup

  • Every executor clones the project into a build directory and gives it to your script as $CI_PROJECT_DIR. On the shell executor that directory persists between jobs on the same host, so the runner cleans it (git clean) according to the project setting GIT_STRATEGY (fetch reuses the checkout, clone makes a fresh one, none skips it). Set GIT_STRATEGY: clone for maximum cleanliness and GIT_DEPTH: 20 for a shallow, faster clone.
  • Disk fills up on busy shell and Docker hosts: prune unused images and containers regularly (docker system prune) or use autoscaling.
  • Jobs run as different users per executor (the runner user in shell, often root inside containers). Do not assume root; do not run production tools as root unnecessarily.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which executor gives the least isolation between jobs?

    The shell executor runs commands directly on the host as the runner user, so jobs share the machine.
  2. 2. What does the Docker executor use as the environment of your script?

    Each job gets a new container from the specified image, discarded afterward.
  3. 3. No image is set in the job or in .gitlab-ci.yml. What image does a Docker executor job use?

    The runner configuration provides the fallback image.
  4. 4. Which pull_policy always fetches the image from the registry?

    always pulls every time, which keeps mutable tags fresh at the cost of speed.

Summary

  • The executor decides where a job runs: host (shell), container (Docker), pod (Kubernetes), or VM (autoscaling and others).
  • Docker is the sensible default; shell suits trusted builds on special hosts; VMs and pods suit untrusted or large-scale work.
  • The Docker executor pulls images, starts services, runs scripts in the job container and discards everything.
  • The job's image overrides the pipeline default, which overrides the runner's default.
  • Control checkout behavior with GIT_STRATEGY and GIT_DEPTH, and clean up disk regularly.

Next: Docker Images and Services in Jobs