GitHub Actions Runner Image Builder for LXD, Incus, Docker, Podman and VMs
Formerly known as GapLib, this repo is a robust collection of setup scripts for configuring custom GitHub Actions runners. These scripts are designed to seamlessly adapt to updates in actions/runner, ensuring compatibility and optimal performance across diverse environments, including VM (host machine), LXD Containers, LXD VMs, Incus Containers, Incus VMs, Docker, and Podman.
This repository also includes source code to create VM images for GitHub-hosted runners widely used in Actions workflows. The software installed by a Complete setup follows the upstream actions/runner-images build templates in images/ubuntu/templates/, adapted for ppc64le and s390x.
- Overview
- Scripts
- Usage
- Upgrading Runner Binary (VM/Host Machine)
- Setup Options
- Software on ppc64le and s390x
- Further Documentation
- Requirements
This runner image supports multiple environments on IBM hardware for a seamless runner setup:
- VM (host machine): Direct setup on virtual or host machines.
- LXD Container: Lightweight, system container-based virtualization.
- LXD VM: Full virtual machines managed via LXD for enhanced isolation.
- Incus Container: System containers managed by Incus, the community fork of LXD.
- Incus VM: Full virtual machines managed by Incus.
- Docker: Industry-standard containerization platform.
- Podman: Docker-compatible, daemonless container management.
- ppc64le
- s390x
- x86_64
| Environment | Ubuntu 22.04 | Ubuntu 24.04 | Ubuntu 26.04 | CentOS / AlmaLinux 9 | RHEL (UBI) 9 / 10 |
|---|---|---|---|---|---|
| VM (host machine) | ✓ | ✓ | ✓ | ✓ (minimal only) | – |
| LXD Container / LXD VM | ✓ | ✓ | ✓ | – | – |
| Incus Container / Incus VM | ✓ ¹ | ✓ | ✓ | – | – |
| Docker / Podman | ✓ | ✓ | ✓ | ✓ | ✓ ² |
¹ Ubuntu 22.04 ppc64le Incus VMs cannot be built from Incus Images (distrobuilder): GRUB 2.06 in 22.04 does not install in the distrobuilder chroot. Use 24.04/26.04, or the Cloud Images source.
² Built from the Red Hat Universal Base Image; no RHEL subscription is needed. UBI 10 needs POWER10, z15 or x86-64-v3 and later; use UBI 9 on older hardware. See the OCI guide.
run.sh is the primary script for setting up GitHub Actions runners. It provides an interactive, menu-driven interface for selecting environments, operating systems, versions, and setup types, and then calls the matching script in scripts/:
| Environment | Script |
|---|---|
| VM (host machine) | scripts/vm.sh |
| LXD Container | scripts/lxd_container.sh |
| LXD VM | scripts/lxd_vm.sh |
| Incus Container | scripts/incus_container.sh |
| Incus VM | scripts/incus_vm.sh |
| Docker | scripts/docker.sh |
| Podman | scripts/podman.sh |
- Interactive Menu: Guides users through setup options (VM, LXD Container, LXD VM, Incus Container, Incus VM, Docker, or Podman).
- Architecture Detection: Ensures compatibility with supported architectures.
- Custom OS and Version Selection: Allows users to tailor setup to specific environments.
- Setup Type Options: Supports Minimal (basic setup) and Complete (full setup) configurations.
- Idempotent image builds: LXD and Incus images are tagged with the build commit, OS, version and setup type; a rebuild is skipped when a matching image already exists.
-
Clone the repository and change into it (the scripts expect to run from the repository root).
-
Execute the setup script:
bash run.sh
-
Follow the prompts to:
- Select your environment (VM, LXD Container, LXD VM, Incus Container, Incus VM, Docker, or Podman).
- Choose your OS and version.
- Specify the setup type (Minimal or Complete).
- For Incus, choose the base image source (Cloud Images or Incus Images).
- For LXD and Incus, choose the worker category.
Set GITHUB_TOKEN in the environment to avoid GitHub API rate limits during the build; run.sh passes it through to the build scripts.
Every environment script can also be called directly (this is what run.sh does):
sudo ./scripts/<environment>.sh <os> <version> [worker_type] [worker_cpu] [setup_type] [flags]| Argument | Description |
|---|---|
os |
ubuntu, centos or ubi (ubi: Docker and Podman only) |
version |
22.04, 24.04, 26.04 (Ubuntu), 9 (CentOS) or 9, 10 (UBI) |
worker_type |
Optional image-name suffix, e.g. -2xlarge (pass "" to skip) |
worker_cpu |
Optional image-name suffix, e.g. -p10 (pass "" to skip) |
setup_type |
minimal (default) or complete |
Example, a complete Ubuntu 26.04 Incus container from the Ubuntu cloud image:
sudo ./scripts/incus_container.sh ubuntu 26.04 "" "" complete --use-cloud-imgThe optional flags (--skip-snap-lxd, --use-incus-img, --delete-incus-img, …) are listed in the LXD and Incus guides.
This upgrade feature is specifically designed for VM (host machine) setups. For container-based, LXD-based or Incus-based deployments, please rebuild the image instead.
If you need to upgrade the GitHub Actions runner binary to the latest version on your VM or host machine, simply rerun the setup script:
bash run.shThe script will automatically:
- Detect the existing runner installation on the host
- Download and install the latest runner binary
- Fix any configuration issues
- Preserve your existing runner registration and settings
Note: For VM (host machine) setups, snap and LXD installation are disabled by default to avoid conflicts. The upgrade process will maintain this configuration.
The script provides the following main options:
1) VM (host machine)
2) LXD Container
3) LXD VM
4) Incus Container
5) Incus VM
6) Docker
7) Podman
8) Exit
Select an option to proceed with the setup.
- VM (host machine): the OS and version are detected from
/etc/os-releaseof the host. - LXD / Incus: Ubuntu
26.04,24.04or22.04. - Docker / Podman: Ubuntu
26.04,24.04,22.04, CentOS/AlmaLinux9, or RHEL (UBI)10,9.
- Minimal Setup: Installs only the essential components: the runner, .NET, git, git-lfs, GitHub CLI, Python, zstd and the actions cache. Docker, pipx packages and Homebrew are installed by every setup, and snap/LXD inside the image unless
--skip-snap-lxdis passed. - Complete Setup: Performs a full installation that mirrors the upstream runner-images template for the selected Ubuntu version (
images/ubuntu/templates/build.ubuntu-<version>.pkr.hcl).
CentOS, Docker and Podman builds always use the minimal setup.
Incus builds start from a base image that is imported into Incus once and reused:
| Source | Flag | x86_64 | ppc64le / s390x |
|---|---|---|---|
| Cloud Images (default) | --use-cloud-img |
Ubuntu cloud images | Ubuntu cloud images |
| Incus Images | --use-incus-img |
Containers: Incus image server (images:ubuntu/<version>); VMs: built with distrobuilder |
Built locally with distrobuilder |
LXD and Incus builds ask for a worker category (default, 2xlarge, 4xlarge). The choice, plus -p10 on POWER10 hosts, is appended to the image name, for example ubuntu-26.04-ppc64le-2xlarge-p10.
If the script encounters an unsupported architecture, it will provide these options:
1. Return to main menu
2. Exit
A Complete setup runs the same scripts on every architecture. Tools that have no ppc64le/s390x builds are skipped on those architectures, and a few are installed differently:
| Behaviour on ppc64le / s390x | Tools |
|---|---|
| Skipped (no ppc64le/s390x builds published) | Agentic Workflow Firewall (AWF), Alibaba Cloud CLI, Android SDK, AWS CLI/SAM, AzCopy, Azure CLI, Azure DevOps CLI, Bazel, Bicep, CodeQL bundle, GitHub Copilot CLI, Firefox, GitHub CLI, Google Chrome, Google Cloud CLI, Haskell, Heroku, Homebrew, Microsoft Edge, MS SQL tools, PowerShell, Pulumi, R, SqlPackage, Swift, vcpkg |
| Installed from the Ubuntu archive instead | CMake, Ninja, PyPy (ppc64le), Ruby (no toolcache versions), .NET SDK 8.0 (from ppa:dotnet/backports on 26.04) |
| ppc64le only (skipped on s390x) | Julia, Packer, Terraform |
| Built from source | GitHub Actions runner (latest release patched with patches/runner-sdk8-<arch>.patch; if that fails to patch or build, upstream main patched with patches/runner-main-sdk8-<arch>.patch), kind |
- LXD image used by the GitHub Actions runner
- Incus image used by the GitHub Actions runner
- OCI (Docker/Podman) image used as a self-hosted runner
- Bash Shell: Required to execute the scripts.
- Sudo Privileges: Necessary for certain setup tasks depending on the chosen environment.
- LXD / Incus / Docker / Podman: Installed automatically when missing (LXD via snap, Incus built from source, Docker via the host OS installer, Podman on CentOS hosts only).
This repo was previously hosted here: https://github.com/ppc64le/gaplib