Building pi-gen on CRACI

pi-gen builds Raspberry Pi OS images using debootstrap, which downloads hundreds of ARM .deb packages. On the CRACI runner (x86), this requires QEMU user-mode emulation via binfmt_misc.

Minimal workflow

name: pigen

on:
  workflow_dispatch:

env:
  PIGEN_REF: 2025-05-13-raspios-bookworm-armhf

jobs:
  pi-gen:
    runs-on: craci
    steps:
      - name: Build Raspberry Pi OS image
        run: |
          set -eo pipefail

          echo "127.0.0.1 $(hostname)" | sudo tee -a /etc/hosts

          sudo apt-get update
          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \
            coreutils quilt parted debootstrap zerofree zip \
            dosfstools e2fsprogs libarchive-tools libcap2-bin grep rsync xz-utils \
            file git curl bc gpg pigz xxd arch-test bmap-tools kmod \
            qemu-user-static

          sudo ln -sf /usr/bin/qemu-arm-static /usr/bin/qemu-arm
          if [ -e /proc/sys/fs/binfmt_misc/qemu-arm ]; then
            echo -1 | sudo tee /proc/sys/fs/binfmt_misc/qemu-arm
          fi
          printf '%s' ':qemu-arm:M::\x7fELF\x01\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x28\x00:\xff\xff\xff\xff\xff\xff\xff\x00\x00\x00\x00\x00\x00\x00\x00\x00\xfe\xff\xff\xff:/usr/bin/qemu-arm-static:OCF' | sudo tee /proc/sys/fs/binfmt_misc/register

          git clone --depth 1 --branch "$PIGEN_REF" https://github.com/RPi-Distro/pi-gen.git
          cd pi-gen

          cat > config <<'EOF'
          IMG_NAME='test-raspios'
          RELEASE='bookworm'
          FIRST_USER_NAME='pi'
          FIRST_USER_PASS='raspberry'
          ENABLE_SSH=1
          STAGE_LIST="stage0 stage1"
          EOF

          CONTINUE=0 sudo -E ./build.sh

Notes

Builds run under QEMU emulation and are significantly slower than native ARM. Stage0 and stage1 can take tens of minutes depending on runner size and upstream package download speed.
The binfmt_misc filesystem is pre-mounted by the kernel — no modprobe needed.
The symlink from qemu-arm-static to qemu-arm satisfies pi-gen’s dependency check.
The F flag in the binfmt registration ensures the interpreter works inside debootstrap chroots.
Pin PIGEN_REF to the pi-gen branch or tag that matches the Raspberry Pi OS release being built. For example, Bookworm armhf builds should use a Bookworm armhf tag rather than floating master.
If debootstrap fails while downloading one .deb, check pi-gen/work/<image-name>/stage0/debootstrap.log. That usually indicates an upstream Raspbian mirror, package metadata, or proxy fetch issue rather than a QEMU setup problem.

Building pi-gen on CRACI

Minimal workflow

Notes

Product

Company

Resources

Legal