logo

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
  • gnupg
  • lsb-release
  • zip
  • build-essential
  • zstd
  • libcurl4-openssl-dev
  • inetutils-ping
  • jq
  • locales
  • python3-pip
  • python3-setuptools
  • python3
  • python3-venv
  • rsync
  • tmux
  • libyaml-dev
  • libffi-dev
  • libpq-dev
  • tzdata
  • pkg-config
  • brotli
  • netcat-openbsd
  • skopeo
  • buildah
  • gettext
  • gcc
  • bash
  • moreutils
  • libpng-dev
  • libpixman-1-dev
  • libcairo2-dev
  • librsvg2-dev
  • libpango1.0-dev
  • libjpeg8-dev
  • libgif-dev
  • libgeos-dev
  • lsof
  • wget
  • ca-certificates
  • cmake
  • libgit2-dev
  • pkg-config
  • xvfb
  • x11-xserver-utils
  • libnss3
  • libgbm-dev
  • libatk1.0-0
  • libatk-bridge2.0-0
  • libcups2
  • libgtk-3-0
  • temurin-11-jdk
  • maven
  • nodejs
  • yarn
  • (amd64 only) google-chrome-stable

Extra software:

  • aws-cli
  • Docker
  • Docker Compose
  • Docker Buildx
  • Rust
  • Cargo

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