Runner Executors: Shell, Docker, Docker Autoscaler, Kubernetes, SSH, and Custom Execution Models: Configuration, Design Choices, and Tradeoffs

1. Start with workload and trust requirements, not executor names

Executor selection should begin with a short contract: who can modify the code; whether merge-request/fork code is untrusted; required OS/architecture/devices; whether a container image can represent the toolchain; expected job duration and concurrency; network destinations; secrets/identities; filesystem persistence; required service containers; startup latency; elasticity; and which team owns the underlying platform.

A GPU firmware test on a physically attached device may justify a tightly scoped trusted Shell runner. Ordinary Linux build/test workloads usually benefit from containerized execution. A large cloud-native organization may prefer Kubernetes because it already owns cluster policy and observability. Burst-heavy jobs that need strong cross-job destruction may favor ephemeral autoscaled instances.

2. Decision matrix: compare the boundary that actually matters

3. Shell simplicity versus host risk

Shell minimizes executor layers and can expose local devices/tools directly. The cost is that the runner host becomes part of every job’s trust boundary. If multiple projects or untrusted contributors can schedule work, the host may become a cross-project data and credential boundary.

A defensible Shell design therefore uses narrow project scope, trusted refs/users, least-privileged runner account, network segmentation, no broad host credentials, deterministic workspace cleanup, dedicated hardware where possible, and an explicit reason containerized/ephemeral execution cannot meet the requirement.

4. Docker isolation versus daemon trust

Docker is often the best default for ordinary CI because the job image captures much of the userland, services are supported, and a container can be discarded after each job. The hard part is protecting the host daemon and mounts.

Non-privileged execution with minimal capabilities and no sensitive host mounts is substantially safer than privileged Docker. Mounting /var/run/docker.sock gives the job powerful control over the host Docker daemon; do not describe that pattern as “non-privileged and therefore safe.” If image builds require elevated capability, isolate them onto dedicated ephemeral workers and keep ordinary test jobs separate.

5. Kubernetes scalability versus cluster complexity

Kubernetes can offer high scheduling density, resource requests/limits, namespace controls, autoscaling integrations, pod-level observability, and familiar cloud-native primitives. But every benefit comes through cluster policy that someone must own: runner service-account RBAC, namespaces, pod security, node pools, host mounts, network policy, admission controls, quotas, image pulling, DNS, storage and cluster upgrades.

Do not place general untrusted CI pods next to sensitive production workloads merely because Kubernetes can schedule both. Separate trust domains through clusters/node pools/namespaces and policy appropriate to your threat model.

6. Static capacity versus ephemeral autoscaled workers

Static workers reduce startup latency and operational moving parts, but reuse creates residue and compromise-persistence questions. Ephemeral workers reduce cross-job residue when each worker is destroyed, but add provisioning latency, cloud dependencies, image lifecycle, quota/capacity failures, and cost-control requirements.

Docker Autoscaler and Instance make ephemeral policies first-class through Fleeting and task scaling. A high-isolation design can set one job per worker. That does not eliminate all risk: the manager, provider credentials, base image, network and artifact/cache services still need hardening.

7. Docker Autoscaler versus Instance executor

8. Maintenance-mode executors require lifecycle justification

Shell, SSH and Custom can remain correct for existing systems, but current GitLab documentation marks them maintenance mode. A new platform should avoid building strategic dependencies on a maintenance-mode executor unless an explicit requirement justifies it and an owner accepts migration/compatibility risk.

For SSH, document remote-host identity, credentials, patching, workspace cleanup, network trust and feature gaps. For Custom, version the driver, test its lifecycle against Runner upgrades, preserve driver logs, validate cleanup idempotency, and define what happens when prepare/run/cleanup phases fail independently.

9. Tier, offering, and platform constraints

The executor implementations themselves are available across GitLab Free, Premium, and Ultimate according to current executor documentation, but infrastructure is not free simply because the GitLab feature is. Docker hosts, Kubernetes clusters, VM autoscaling, cloud APIs, GPUs, storage and network egress have their own ownership/cost model.

GitLab.com-hosted runners are a service option distinct from operating your own self-managed executor fleet. On Self-Managed GitLab, your organization supplies runner capacity. Never hard-code current GitLab-hosted compute quotas or price assumptions into an architecture decision; verify current offering and billing documentation.

10. Worked choices: justify with evidence

11. Minimal executor decision record

executor_decision:
  workload: "trusted integration tests"
  code_trust: "protected branches; no fork code"
  required_platform: "linux/amd64"
  devices: "none"
  selected_executor: "docker"
  privilege: "non-privileged"
  sensitive_mounts: "none"
  network_scope: "package mirrors + GitLab only"
  worker_reuse: "host persistent; job containers disposable"
  image_identity: "human-readable release + verified digest"
  owner: "platform-ci"
  evidence_retention: "pipeline/job/runner/image logs for 30 days"
  residual_risk: "shared kernel and persistent runner host"
  reevaluate_when: "untrusted fork execution or privileged builds are introduced"

The value is not the exact schema; it is forcing the platform to state assumptions that are otherwise hidden inside config.toml, cloud consoles, cluster RBAC, and tribal knowledge.

Knowledge check

Official references and version notes

• GitLab Runner executors — current executor selection guidance, compatibility matrix, actively developed paths, and maintenance-mode executors.
• Shell executor — host-local execution, shell selection, process termination, maintenance-mode status, and security warnings.
• Docker executor — image/service model, container lifecycle, volumes, image pull behavior, and executor configuration.
• Docker Autoscaler executor — Fleeting-based autoscaling, Docker feature compatibility, autoscaling resources, capacity and ephemeral-worker patterns.
• Instance executor — Fleeting-based instance provisioning, full host access, worker images, capacity, and native-step considerations.
• Kubernetes executor — per-job Pod creation, build/helper/service containers, RBAC requirements, entrypoint behavior, and executor configuration.
• SSH executor and Custom executor — exceptional/maintenance-mode execution models and operational constraints.
• Security for self-managed runners — Shell risk, Docker privilege/capability guidance, network segmentation, and trust-boundary recommendations.
• Use Docker to build Docker images — security and executor implications for Docker-in-Docker and socket/pipe binding.