GitHub Runners Architecture

Namespace offers managed GitHub Runners using a combination of components:

GitHub Manager: a multi-tenant workflow job scheduler run by the Namespace team.
Container Instances: used to run each workflow job.

Manager

The Manager is responsible for orchestrating requests it obtains from GitHub. When GitHub sends an event informing the Manager about a new workflow job, the Manager determines if Namespace should handle the workflow job and creates a new Runner instance (see below).

The Manager can handle GitHub events out-of-order and catch up with missed event deliveries (due to network partitions, GitHub, or Manager unavailability).

Runner Instances

Each Runner runs as an individual Container Instance, using a Runner image prepared by the Namespace team. That means that the runner software itself runs in a container. This approach facilitates software packaging and enables custom base images. See how to use custom base images.

All of the properties of Container Instances apply, with the following configuration:

The Docker API is enabled in the GitHub runner container.
Workload Identity credentials are made available to the GitHub runner container.

This base image has been setup to closely track the images that GitHub maintains, so users may find most of the software they'd expect.

If there's a missing package you'd expect to be available, contact us at support@namespace.so.

Differences from GitHub-managed runners

We aim to maintain an environment as close to GitHub's managed runners as possible.

But there are a few known differences:

The installed software set may differ (especially the software that GitHub doesn't explicitly list as supported).
docker build by default behaves as docker buildx (i.e., it uses the Buildkit build backend).
Docker builds use Namespace Remote Builders by default.
docker buildx build -t foo will load the image if no other output is specified, even when using a remote build driver.

Default Runner Base Image

The Namespace's default runner image is based on Ubuntu 22.04 container image, with the following list of additional software preinstalled.

Ubuntu packages:

openssh-client: 1:8.9p1-3ubuntu0.4
gnupg: 2.2.27-3ubuntu2.1
lsb-release: 11.1.0ubuntu4
zip: 3.0-12build2
build-essential: 12.9ubuntu3
zstd: 1.4.8+dfsg-3build1
libcurl4-openssl-dev: 7.81.0-1ubuntu1.14
inetutils-ping: 2:2.2-2ubuntu0.1
jq: 1.6-2.1ubuntu3
locales: 2.35-0ubuntu3.4
python3-pip: 22.0.2+dfsg-1ubuntu0.4
python3-setuptools: 59.6.0-1.2ubuntu0.22.04.1
python3: 3.10.6-1~22.04
python3-venv: 3.10.6-1~22.04
rsync: 3.2.7-0ubuntu0.22.04.2
tmux: 3.2a-4ubuntu0.2
libyaml-dev: 0.2.2-1build2
libffi-dev: 3.4.2-4
libpq-dev: 14.9-0ubuntu0.22.04.1
tzdata: 2023c-0ubuntu0.22.04.2
pkg-config: 0.29.2-1ubuntu3
brotli: 1.0.9-2build6
netcat-openbsd: 1.218-4ubuntu1
skopeo: 1.4.1+ds1-1
buildah: 1.23.1+ds1-2
gettext: 0.21-4ubuntu4
gcc: 4:11.2.0-1ubuntu1
bash: 5.1-6ubuntu1
moreutils: 0.66-1
libpng-dev: 1.6.37-3build5
libpixman-1-dev: 0.40.0-1ubuntu0.22.04.1
libcairo2-dev: 1.16.0-5ubuntu2
librsvg2-dev: 2.52.5+dfsg-3ubuntu0.2
libpango1.0-dev: 1.50.6+ds-2ubuntu1
libjpeg8-dev: 8c-2ubuntu10
libgif-dev: 5.1.9-2build2
libgeos-dev: 3.10.2-1
lsof: 4.93.2+dfsg-1.1build2
wget: 1.21.2-2ubuntu1
ca-certificates: 20230311ubuntu0.22.04.1
cmake: 3.22.1-1ubuntu1.22.04.1
libgit2-dev: 1.1.0+dfsg.1-4.1build1
pkg-config: 0.29.2-1ubuntu3
xvfb: 2:21.1.4-2ubuntu1.7~22.04.2
x11-xserver-utils: 7.7+9build1
libnss3: 2:3.68.2-0ubuntu1.2
libgbm-dev: 23.0.4-0ubuntu1~22.04.1
libatk1.0-0: 2.36.0-3build1
libatk-bridge2.0-0: 2.38.0-3
libcups2: 2.4.1op1-1ubuntu4.7
libgtk-3-0: 3.24.33-1ubuntu2
temurin-11-jdk: 11.0.21.0.0+9
maven: 3.6.3-5
nodejs: 18.18.2-1nodesource1
yarn: 1.22.19-1
(amd64 only) google-chrome-stable: 119.0.6045.159-1

Extra software:

aws-cli: v2.11.10
Docker: v23.0.5
Docker Compose: v2.17.3
Docker Buildx: v0.10.4
Rust: v1.74.0
Cargo: v1.74.0

If there's a missing package you'd expect to be available, contact us at support@namespace.so.