Runner Selection Guide

Runner Selection Guide

Choose the smallest runner that meets the requirements of your CI job. Lighter runners start faster and consume fewer cluster resources.

Decision Tree

Runner Capabilities

Three runner types are available on both GitLab CI and GitHub Actions:

Type Base Image Privileged Docker Builds Package Manager Use Case
docker Alpine No No apk General CI: linting, testing, builds
dind Alpine + Docker Yes Yes apk Container image builds
nix Nix-oriented runner lane No No nix Reproducible builds and flake workflows

Selecting a Runner

  • Default choice: docker. Lightweight Alpine base with the fastest startup time. Suitable for most CI jobs that do not have special requirements.
  • Need Docker builds? Use dind. This runner is privileged and provides a Docker-in-Docker sidecar. See Docker Builds for configuration details.
  • Need reproducible builds? Use nix. Flakes are enabled and the Attic cache/runtime hints are available. Self-hosted workflows should still bootstrap or verify Nix explicitly. See Nix Builds for the recommended pipeline pattern.
  • Need reproducible builds that are also memory-heavy? Start with nix, but do not assume ARC will resize that lane on demand. If the workload regularly exceeds the baseline 8Gi envelope, use or request a heavier additive Nix lane instead of silently relying on cluster-wide free RAM.
  • Need KVM-backed VM execution? Do not overload tinyland-nix or dind. Use or request a shared additive Nix lane with explicit host-device mounts, node placement, and security review. Treat that as a separate capability boundary from ordinary Nix builds. See KVM Capacity Policy before changing KVM scale-set count, placement, or resource envelopes.

GitLab CI Tags

Use these tags in your .gitlab-ci.yml to select a runner:

Primary Tag Runner When to Use
docker {prefix}-docker Default for most jobs
dind {prefix}-dind Jobs requiring Docker daemon
nix {prefix}-nix Nix flake builds

Additional tags (linux, amd64, flakes, privileged) are available for finer matching but the primary tag is sufficient for most use cases.

GitHub Actions Labels

Use these runs-on values in your GitHub Actions workflows:

Label Capability family When to Use
tinyland-docker docker Default for most stateless jobs; currently admitted to sting as a bounded compute-expansion lane
tinyland-dind dind Jobs requiring Docker daemon
tinyland-nix nix Nix flake builds
tinyland-nix-heavy nix Memory-heavy Rust/Nix jobs where the heavy lane is enabled; currently honey-backed with a larger scratch envelope
tinyland-nix-kvm nix Shared KVM-backed VM-execution lane, Honey-first with gated Sting overflow; use for graphical VM and hardware-virtualization workloads

See GitHub Actions Runners for composite actions and cache integration details.

Performance Tip

Always use the smallest runner that meets your needs. The docker runner has the lowest overhead and fastest pod scheduling, and now has bounded stateless relief on sting. Reserve dind for jobs that genuinely require a Docker daemon, and nix for jobs that benefit from Nix’s reproducibility guarantees and binary cache.

GloriousFlywheel