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.

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 Runner When to Use
tinyland-docker gh-docker Default for most jobs
tinyland-dind gh-dind Jobs requiring Docker daemon
tinyland-nix gh-nix Nix flake builds
tinyland-nix-heavy additive gh-nix variant Memory-heavy Rust/Nix jobs where the heavy lane is enabled; intended for explicit stateless compute capacity on sting

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. 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