Build your own GPU ready GitHub Actions Runner: A Dockerfile guide
A guide on why and how to build a custom GitHub Actions Runner that uses GPU.
GitHub Actions is a powerful tool for automating your development workflow. While GitHub provides hosted runners, sometimes you need a custom environment. In this post, we'll walk through creating a Dockerfile to build your own GitHub Actions runner.
Why Build a Custom Runner?
Before we dive into the technical details, let's consider why you might want to create your own runner:
Specific software requirements.
Enhanced security and control.
Cost optimization for high-volume workflows.
Access to specialized hardware.
Custom runners give you the flexibility to tailor your CI/CD environment to your exact needs.
Notes
There are a few examples online of Github Runner Dockerfiles, and the goal of this article is to provide added value. I found it hard to find good examples to build a Github Runner that could use a GPU within Kubernetes at the time.
Even though the focus of this article is to make a GPU capable Github Runner, it’s not hard to switch back to a normal Github Runner by changing:
FROM nvidia/cuda:12.5.1-runtime-ubuntu24.04 to FROM ubuntu:latest
Remove the RUN block that install the nvidia drivers for Docker.
The Dockerfile: Building Blocks
Let's break down our Dockerfile into manageable sections. I was inspired greatly by this Dockerfile from myoung34/docker-github-actions-runner and therefore use the same environment variables.
You can find our version here.
Base Image and Environment Setup
We start with an Ubuntu base image and set some essential environment variables:
FROM nvidia/cuda:12.5.1-runtime-ubuntu24.04
ENV DEBIAN_FRONTEND=noninteractive
ENV LANG=en_US.UTF-8
ENV LANGUAGE=en_US.UTF-8
ENV LC_ALL=en_US.UTF-8
ENV AGENT_TOOLSDIRECTORY=/opt/hostedtoolcache
ARG GH_RUNNER_VERSION="2.317.0"
ARG TARGETPLATFORM
RUN echo en_US.UTF-8 UTF-8 >> /etc/locale.gen
RUN mkdir -p /opt/hostedtoolcacheInstalling Dependencies
This section ensures we have all the necessary tools installed.
Some of these dependencies are necessary for the next steps of this Dockerfile, things like Kubectl, Helm, Docker will need to be installed semi manually and requires to import GPG keys etc.
If you have other needs like other languages that need to be installed natively on your Github Runner, that’s where you should do it.
