GitHub Runners Architecture

Namespace offers managed GitHub Runners using a combination of components:

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


The Manager is responsible for orchestrating requests it obtains from GitHub. When a new workflow job is scheduled, and it is determined that it is a workflow job managed by Namespace, it creates a new Runner instance (see below) to handle it.

The Manager is capable of handling GitHub events out-of-order, and is also capable of catching 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 is done to facilitate software packaging, and support custom base images in the future.

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 package you'd expect to be available but isn't, reach out to us at support@namespace.so.

Differences from GitHub Managed runners

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

But there are a few known differences:

  • The set of installed software may differ (specially the software that GitHub doesn't explicitly lists as supported).
  • docker build by default behaves as docker buildx (i.e. it uses the Buildkit build backend).
  • Namespace Remote Builders are used by default.