ADR 0001 — Base Image Selection

Status: Accepted

Context

The runner needs a base OS image that provides:

A working apt package ecosystem for installing git, curl, jq, tini, ca-certificates, tzdata.
Compatibility with Docker's official apt repository (for Docker CLI).
Compatibility with NodeSource (for Node.js 20 LTS).
A label environment the existing workflows reference: ubuntu-latest.

Candidates considered:

ubuntu:22.04 — LTS, wide ecosystem support, good compatibility.
ubuntu:24.04 — Newer LTS, some tooling still stabilizing.
debian:bookworm-slim — Smaller footprint, good compatibility, but ubuntu-latest label mismatch.
debian:bullseye-slim — Older, stable, but further from ubuntu-latest expectations.

Decision

Use ubuntu:22.04 as the base image, pinned by exact tag.

Rationale

Existing Gitea workflows use runs-on: ubuntu-latest. Basing the runner image on Ubuntu 22.04 maximizes compatibility with GitHub Actions steps written for that environment.
Ubuntu 22.04 LTS has long-term support through 2027, reducing forced base image churn.
Docker's apt repository and NodeSource both officially support Ubuntu 22.04.
Ubuntu 22.04 is the most common self-hosted runner base image in community examples, so troubleshooting resources are abundant.

Consequences

Final image size will be larger than a minimal Alpine or Debian slim base, which is acceptable given the goal of bundling all runtime dependencies.
When the workflow ecosystem moves to ubuntu-24.04, the base image can be bumped with a version argument change (ARG UBUNTU_VERSION=24.04).

Alternatives considered

Debian bookworm-slim: Smaller image, but the ubuntu-latest label in existing workflows creates an expectation of Ubuntu compatibility. Switching to Debian may cause subtle incompatibilities with actions that check the OS ID.

Ubuntu 24.04: Not yet the default for ubuntu-latest as of the initial build date; 22.04 remains the more tested choice for self-hosted runners.

2.0 KiB Raw Blame History