Introduction

GitHub Actions Self-hosted Runner #

A simple self-hosted GitHub Actions runner. No Operator, no CRD, and no need to apply a pile of YAML before a runner can register. A small KMS service holds the Personal Access Token, so the runner instance never stores that long-lived credential.

Use the navbar on the left for single-node and Kubernetes setup.

Images #

Each tag is multi-arch (amd64 and arm64), published to Docker Hub and GHCR:

  • knatnetwork/github-runner:jammy-<tag>
  • ghcr.io/knatnetwork/github-runner:jammy-<tag>
  • knatnetwork/github-runner:noble-<tag>
  • ghcr.io/knatnetwork/github-runner:noble-<tag>
  • knatnetwork/github-runner:resolute-<tag>
  • ghcr.io/knatnetwork/github-runner:resolute-<tag>

<tag> follows actions/runner. Runner v2.338.0 is published as knatnetwork/github-runner:noble-2.338.0.

Specs #

  • github-runner:jammy-<tag> images are based on Ubuntu 22.04. This line is deprecated: GitHub retires the ubuntu-22.04 hosted image on 17 April 2027, and Ubuntu 22.04 standard support ends in May 2027. New deployments should use noble or resolute.
  • github-runner:noble-<tag> images are based on Ubuntu 24.04
  • github-runner:resolute-<tag> images are based on Ubuntu 26.04
  • github-runner:latest tracks github-runner:noble-<tag>

Usage #

  1. Prepare your GitHub Personal Access Token, which looks like ghp_xxxxxxxxxxxxx with admin:org permission (if you’d like to register a runner to a repo, your user must have Admin permission on that repo). See Creating a personal access token.
  2. To register a runner on a single machine, follow the quick start here.
  3. To spread runners across Kubernetes nodes, see Kubernetes.

Topology #

The design keeps the PAT off the runner. A service called KMS handles registration, and the PAT is stored only there.