Self Hosted Runners

Self-Hosted Runners

Self-hosted runners provide builds on real Linux distributions that cannot be adequately reproduced in GitHub-hosted containers.

---

Infrastructure Overview

All self-hosted runners are Proxmox VMs running on the internal host pve05.

Runner Label	OS	Architecture	RAM	Purpose
pve05-ubuntu22	Ubuntu 22.04 LTS	x64	8 GB	AppImage + .deb
pve05-ubuntu24	Ubuntu 24.04 LTS	x64	8 GB	AppImage + .deb
pve05-opensuse	openSUSE Tumbleweed	x64	8 GB	AppImage + .rpm (offline)
pve05-arch	Arch Linux	x64	8 GB	AppImage + .pkg.tar.zst (offline)

Runners are referenced in workflow files as:

runs-on: [self-hosted, pve05-ubuntu22]

---

Runner Registration

Each VM runs the GitHub Actions runner agent. To register a new runner:

# On the target VM:
mkdir -p ~/actions-runner && cd ~/actions-runner

# Download runner (check https://github.com/BenJule/BambuStudio/settings/actions/runners for latest URL)
curl -O -L https://github.com/actions/runner/releases/download/v2.x.x/actions-runner-linux-x64-2.x.x.tar.gz
tar xzf ./actions-runner-linux-x64-*.tar.gz

# Configure
./config.sh --url https://github.com/BenJule/BambuStudio \
            --token <RUNNER_TOKEN> \
            --labels pve05-ubuntu22 \
            --name pve05-ubuntu22 \
            --unattended

# Install as systemd service
sudo ./svc.sh install && sudo ./svc.sh start

---

Runner Requirements

Self-hosted runners need the following packages to build BambuStudio:

# Ubuntu/Debian
sudo ./BuildLinux.sh -ur

# This installs: cmake, gcc, g++, ninja-build, libgtk-3-dev, libgl1-mesa-dev,
# libglu1-mesa-dev, libdbus-1-dev, libssl-dev, libcurl4-openssl-dev, git, git-lfs,
# gettext, fuse (for AppImage), and more.

Important

The runner user must be in the docker group if Docker-based steps are used. For AppImage builds, the FUSE kernel module must be loaded on the host VM.

---

Docker Socket Access

Some CI steps use Docker containers. The runner must have access to the Docker socket:

sudo usermod -aG docker $USER
# Log out and back in, or: newgrp docker

The --security-opt apparmor=unconfined flag is required for containers that need AF_UNIX sockets and HTTPS git operations:

container:
  image: debian:trixie
  options: --security-opt apparmor=unconfined

---

Workflow Configuration for Self-Hosted

Self-hosted runner jobs in cd-packages.yml:

build_selfhosted:
  runs-on: ${{ matrix.runner }}
  timeout-minutes: 360
  continue-on-error: true     # runner offline does not fail the release
  strategy:
    fail-fast: false
    max-parallel: 4

continue-on-error: true means a runner going offline or crashing does not block the nightly or release. Artifacts from failed jobs are simply absent.

---

Deps Cache

Build dependencies are cached per-runner using GitHub Actions cache keyed on deps/CMakeLists.txt and all deps/**/*.cmake:

- uses: actions/cache@...
  with:
    path: deps/build/destdir
    key: pkg-deps-ubuntu2204-${{ hashFiles('deps/CMakeLists.txt', 'deps/**/*.cmake') }}

A full deps build takes ~90 min. With a cache hit it is skipped entirely.

---

Maintenance

Check runner status

In the GitHub UI: Settings → Actions → Runners

Or via CLI:

gh api repos/BenJule/BambuStudio/actions/runners \
  --jq '.runners[] | {name, status, busy}'

Restart a runner service

# On the affected VM:
sudo systemctl restart actions.runner.BenJule-BambuStudio.<runner-name>.service

# Check status:
sudo systemctl status actions.runner.*

Runner logs

journalctl -u actions.runner.BenJule-BambuStudio.<runner-name>.service -f

Disk cleanup

Build artifacts accumulate in ~/actions-runner/_work/. Clean periodically:

# Remove old work directories (safe when no job is running)
ls ~/actions-runner/_work/BambuStudio/
rm -rf ~/actions-runner/_work/BambuStudio/BambuStudio/build/

---

Currently Offline Runners

Runner	Reason	ETA
pve05-opensuse	VM maintenance	Unknown
pve05-arch	VM maintenance	Unknown

These runners are commented out in cd-packages.yml:

# TODO: re-enable once pve05-opensuse runner is back online
# - name: openSUSE Tumbleweed AppImage + .rpm
#   runner: [self-hosted, pve05-opensuse]

---

Adding a New Runner VM

1. Create a new Proxmox VM on pve05 with the target OS
2. Install build dependencies: sudo ./BuildLinux.sh -ur
3. Register the runner with a new unique label (e.g. pve05-fedora42)
4. Add a matrix entry in cd-packages.yml
5. Test by manually triggering cd-packages.yml with skip-ubuntu=false