Runner Executors

An executor is the mechanism that determines how a GitLab Runner actually runs the jobs assigned to it. When you register a runner, you choose an executor — and that choice shapes everything about how jobs are executed: whether they run directly on the host or in an isolated container, whether they can use Docker-in-Docker, whether they can scale automatically, and what resources they consume.

Understanding executors is crucial because the executor is the biggest determinant of your runner's security, performance, and operational characteristics. The shell executor runs jobs directly on the host — simple but with no isolation. The Docker executor runs each job in a fresh container — isolated but requires Docker. The Kubernetes executor runs jobs as pods — auto-scaling and cloud-native but requires a cluster.

There's no single "best" executor. The right choice depends on your infrastructure, security requirements, and workload. This guide compares all the major executors to help you choose.

The shell executor is the simplest of all executors. It runs job scripts directly on the host machine using the local shell, with no containerization or virtualization. When a job runs, GitLab Runner checks out the repository into a local directory, runs the before_script, script, and after_script commands using the host's shell, and reports the result. There's no image to pull, no container to start, no isolation to configure.

This simplicity is the shell executor's greatest strength and its greatest weakness. It's the fastest executor to start (no container startup overhead) and the easiest to set up (just install the runner and register it). But it provides zero isolation: jobs from different projects share the same host, can see each other's files, and can potentially interfere with each other or with the host's operating system. A malicious build script in a project could, in theory, compromise the runner host.

The shell executor is a reasonable choice for simple, trusted environments — like a personal build server or an internal tool where all code is trusted. It's also useful for debugging (you can run the same commands manually) and for jobs that need direct host access (like deploying to the host or managing local resources). But for anything involving untrusted code, containers are strongly preferred.

The Docker executor is the most widely used executor and for good reason. It runs each job in a fresh Docker container based on the image specified by the job. Every job starts from a clean slate — no leftover dependencies, no conflicting ports, no shared state with other jobs. When the job finishes, the container is discarded. This isolation is exactly what modern CI/CD needs.

The Docker executor is also highly flexible. The job specifies its image, so you can choose the right environment for each job: node:18 for frontend tests, python:3.11 for backend tests, golang:1.21 for a Go microservice. Services (like databases or caches) can be started alongside the job using the services keyword, giving each job a self-contained environment.

The main caveat with the Docker executor is that it requires Docker on the host, and some tasks (like building Docker images inside a job) require either mounting the host's Docker socket or running in privileged mode with Docker-in-Docker (DinD). Both approaches have trade-offs, which we'll cover below.

The Docker Machine executor is an auto-scaling variant of the Docker executor. Instead of using a single Docker host, it uses Docker Machine to provision ephemeral VMs on demand — each job gets its own fresh VM with Docker, which is destroyed after the job completes. This provides maximum isolation and automatic scaling, at the cost of higher complexity and slower job startup (provisioning a VM takes longer than starting a container).

This executor was very popular in the era before Kubernetes was ubiquitous, and it's still useful for teams that don't have a Kubernetes cluster but want auto-scaling runners. It supports many cloud providers (AWS, GCP, Azure, DigitalOcean, OpenStack, etc.) via Docker Machine drivers. When jobs arrive, Docker Machine spins up VMs; when jobs finish, the VMs are torn down. This means you pay only for the compute you actually use.

The main trade-off is startup time. Provisioning a VM can take 30 seconds to several minutes, so Docker Machine is best for jobs that take a while (10+ minutes). For fast jobs, the VM startup overhead dominates, and the standard Docker executor is a better choice.

The Kubernetes executor is the modern, cloud-native choice. It runs each job as a pod in a Kubernetes cluster, which gives you the same isolation as the Docker executor, plus Kubernetes' native auto-scaling and resource management. When a job arrives, the runner creates a pod with the job's image and any services it needs; when the job finishes, the pod is deleted. All of this happens automatically, using the cluster's existing scheduling and autoscaling capabilities.

What makes the Kubernetes executor especially appealing is that it inherits Kubernetes' operational benefits: auto-scaling (via Cluster Autoscaler or Karpenter), resource quotas, node affinity, taints and tolerations, and integrated observability. You define job requirements in terms of Kubernetes resources (CPU, memory, node selectors), and Kubernetes handles the rest. This makes it ideal for teams already operating Kubernetes, who can reuse existing cluster capacity and tooling for CI/CD.

The main requirement is, of course, a Kubernetes cluster — and the runner needs permissions to create pods in a namespace. The runner configuration is more involved than the Docker executor (you specify namespace, service account, resource limits, etc.), but for teams comfortable with Kubernetes, this is familiar territory.