@le-space/rootfs 0.11.0 → 0.12.1

package/README.md

@@ -13,6 +13,8 @@ Shared rootfs contract parsing, reference profile assets, and build helpers.
   ports and consumer env expectations
 - added an ephemeral `playwright-runner` profile with Node.js 24, exact
   Playwright/Chromium `1.61.1`, authenticated WSS, bounded logs, and a guest TTL
+- added an ephemeral `github-runner` profile: a one-job GitHub Actions runner
+  that forgets its own INSTANCE after the job
 
 ## Reference assets
 
@@ -26,3 +28,5 @@ Current shared reference profiles live under:
 - `reference/ucan-store/rootfs/*`
 - `reference/playwright-runner/contract.json`
 - `reference/playwright-runner/rootfs/*`
+- `reference/github-runner/contract.json`
+- `reference/github-runner/rootfs/*`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/rootfs",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Shared rootfs contract parsing, reference profile assets, and build helpers.",
   "license": "MIT",
   "type": "module",

package/reference/github-runner/README.md

@@ -0,0 +1,23 @@
+# GitHub runner RootFS
+
+Ubuntu 24.04 (as GitHub's own runners) with the GitHub `actions-runner` (pinned, sha256-checked, updates
+off), Node.js 24, Docker, git, jq and rootfs build tools. It contains no
+credential.
+
+After boot, `scripts/aleph-github-runner.mjs` (`pnpm relay-button gh-runner up`)
+writes over SSH, in this order:
+
+- `/etc/github-runner/ttl`: maximum lifetime in minutes (default 360);
+- `/etc/github-runner/forget.env` (optional): `ALEPH_FORGET_KEY`, `ALEPH_OWNER`,
+  `ALEPH_INSTANCE`, a delegate key authorized for INSTANCE and FORGET (Aleph
+  lets a delegate forget only what it could have created);
+- `/etc/github-runner/jitconfig`: a one-job just-in-time runner config.
+
+`github-runner.service` waits for the jitconfig, deletes it once read, and runs
+one job as the `runner` user (passwordless sudo, docker group). When the runner
+exits, `github-runner-finish` forgets the VM's own INSTANCE (if a forget key was
+given) and powers off. The TTL timer runs the same path as a last resort.
+
+Self-hosted runners execute workflow code with root rights on this VM: use them
+for private repositories, or public ones whose workflows never run for forks.
+See the docs page `architecture/aleph-github-runner`.

package/reference/github-runner/contract.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": 1,
+  "id": "github-runner",
+  "displayName": "Ephemeral GitHub Actions Runner",
+  "source": {
+    "repository": "NiKrause/relay-button",
+    "subdirectory": "packages/rootfs/reference/github-runner"
+  },
+  "rootfs": {
+    "profile": "github-runner",
+    "installMode": "prebaked",
+    "installDir": "/opt/actions-runner",
+    "binaryPath": "/opt/actions-runner/run.sh",
+    "dataDir": "/var/lib/github-runner",
+    "envFile": "/etc/github-runner/runner.env"
+  },
+  "services": {
+    "bootstrap": "github-runner.service",
+    "main": "github-runner.service",
+    "autotlsRefresh": "github-runner-ttl.timer"
+  },
+  "ports": [
+    {
+      "port": 22,
+      "tcp": true,
+      "udp": false,
+      "purpose": "SSH bootstrap and diagnostics"
+    }
+  ],
+  "manifest": {
+    "copyTarget": "packages/rootfs/reference/github-runner/latest.json",
+    "notes": "GitHub actions-runner 2.338.0, Node.js 24, Docker and rootfs build tools are prebaked. A one-job just-in-time runner config must be injected after boot; the image contains no credential. After its job the runner forgets its own INSTANCE when a forget key was injected, and powers off; a bounded TTL timer is the last resort."
+  }
+}

package/reference/github-runner/rootfs/Dockerfile.rootfs

@@ -0,0 +1,16 @@
+FROM debian:12
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV LIBGUESTFS_BACKEND=direct
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    curl \
+    libguestfs-tools \
+    linux-image-amd64 \
+    qemu-system-x86 \
+    qemu-utils \
+  && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace/shared-rootfs

package/reference/github-runner/rootfs/build-rootfs-image.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUT_DIR="${OUT_DIR:-${SCRIPT_DIR}/../dist-rootfs}"
+# Ubuntu 24.04, the system of GitHub's own ubuntu-24.04 runners: jobs bring
+# tools built for it, such as the aleph CLI release binary, which needs glibc
+# 2.38 (Debian 12 has 2.36). Debian 13's cloud image did not boot on Aleph
+# nodes (reboot loop after GRUB); Aleph offers ubuntu24 as a preset.
+BASE_URL="${BASE_URL:-https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img}"
+BASE_IMAGE="${OUT_DIR}/noble-server-cloudimg-amd64.img"
+IMAGE="${OUT_DIR}/aleph-github-runner.qcow2"
+ROOTFS_IMAGE_SIZE="${ROOTFS_IMAGE_SIZE:-10G}"
+# Pinned on purpose: the runner is started with --disableupdate, so the image
+# decides the version. Bump both lines together.
+RUNNER_VERSION="${RUNNER_VERSION:-2.338.0}"
+RUNNER_SHA256="${RUNNER_SHA256:-af4b794c1bc41d73d40535e3fe092a39f9679cd8d965954c2aca25a05ca41d32}"
+ETHERS_VERSION="6.16.0"
+HOST_UID="${HOST_UID:-}"
+HOST_GID="${HOST_GID:-}"
+ROOTFS_SPARSIFY_TMPDIR=""
+
+require() {
+  command -v "$1" >/dev/null 2>&1 || { echo "Missing required command: $1" >&2; exit 1; }
+}
+
+for command in curl qemu-img virt-customize sha256sum; do require "${command}"; done
+
+cleanup() {
+  if [ -n "${ROOTFS_SPARSIFY_TMPDIR}" ] && [ -d "${ROOTFS_SPARSIFY_TMPDIR}" ]; then
+    rm -rf "${ROOTFS_SPARSIFY_TMPDIR}"
+  fi
+}
+trap cleanup EXIT
+
+mkdir -p "${OUT_DIR}"
+if [ ! -f "${BASE_IMAGE}" ]; then
+  curl --fail --show-error --location --retry 5 --retry-all-errors \
+    --connect-timeout 20 --max-time 300 "${BASE_URL}" -o "${BASE_IMAGE}"
+fi
+
+RUNNER_TARBALL="${OUT_DIR}/actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz"
+if [ ! -f "${RUNNER_TARBALL}" ]; then
+  curl --fail --show-error --location --retry 5 --retry-all-errors \
+    --connect-timeout 20 --max-time 300 \
+    "https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz" \
+    -o "${RUNNER_TARBALL}"
+fi
+echo "${RUNNER_SHA256}  ${RUNNER_TARBALL}" | sha256sum --check --strict
+
+cp "${BASE_IMAGE}" "${IMAGE}"
+qemu-img resize "${IMAGE}" "${ROOTFS_IMAGE_SIZE}"
+# Growing the file alone leaves the cloud image's ~2.5 GB root partition full
+# before Docker is unpacked. The root partition is the last one on the disk,
+# so growpart extends it in place; virt-resize would rewrite the partition
+# table, and Ubuntu's cloud image finds its root by partition UUID (a resized
+# image never brought up SSH on Aleph).
+virt-customize -a "${IMAGE}" --run-command "growpart /dev/sda 1 && resize2fs /dev/sda1"
+
+virt-customize \
+  -a "${IMAGE}" \
+  --network \
+  --mkdir /opt/actions-runner \
+  --mkdir /opt/github-runner \
+  --mkdir /etc/github-runner \
+  --mkdir /etc/systemd/journald.conf.d \
+  --mkdir /var/lib/github-runner \
+  --copy-in "${RUNNER_TARBALL}:/opt/github-runner" \
+  --copy-in "${SCRIPT_DIR}/forget-self.mjs:/opt/github-runner" \
+  --copy-in "${SCRIPT_DIR}/github-runner-start:/usr/local/sbin" \
+  --copy-in "${SCRIPT_DIR}/github-runner-finish:/usr/local/sbin" \
+  --copy-in "${SCRIPT_DIR}/github-runner.service:/etc/systemd/system" \
+  --copy-in "${SCRIPT_DIR}/github-runner-ttl.service:/etc/systemd/system" \
+  --copy-in "${SCRIPT_DIR}/github-runner-ttl.timer:/etc/systemd/system" \
+  --run-command "apt-get update && apt-get install -y --no-install-recommends ca-certificates curl gnupg git jq unzip zip xz-utils zstd sudo python3 rsync e2fsprogs openssh-client qemu-utils cryptsetup debootstrap docker.io" \
+  --run-command "apt-get purge -y --auto-remove snapd lxd-installer || true" \
+  --run-command "curl -fsSL https://deb.nodesource.com/setup_24.x | bash -" \
+  --run-command "apt-get install -y --no-install-recommends nodejs" \
+  --run-command "useradd --create-home --home-dir /home/runner --shell /bin/bash --groups docker runner" \
+  --run-command "printf 'runner ALL=(ALL) NOPASSWD:ALL\\n' >/etc/sudoers.d/runner && chmod 0440 /etc/sudoers.d/runner" \
+  --run-command "tar -xzf /opt/github-runner/actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz -C /opt/actions-runner && rm /opt/github-runner/actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz" \
+  --run-command "/opt/actions-runner/bin/installdependencies.sh" \
+  --run-command "chown -R runner:runner /opt/actions-runner /var/lib/github-runner" \
+  --run-command "cd /opt/github-runner && npm init -y >/dev/null && npm install --omit=dev --no-audit --no-fund ethers@${ETHERS_VERSION}" \
+  --run-command "chmod 0700 /etc/github-runner && chmod 0755 /usr/local/sbin/github-runner-start /usr/local/sbin/github-runner-finish" \
+  --run-command "printf '[Journal]\\nSystemMaxUse=256M\\nRuntimeMaxUse=64M\\nMaxRetentionSec=2day\\n' >/etc/systemd/journald.conf.d/github-runner.conf" \
+  --run-command "npm cache clean --force" \
+  --run-command "apt-get clean && rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/* /root/.npm /tmp/* /var/tmp/*" \
+  --run-command "systemctl enable docker.service github-runner.service github-runner-ttl.timer"
+
+if command -v virt-sparsify >/dev/null 2>&1; then
+  SPARSE_IMAGE="${IMAGE%.qcow2}.sparse.qcow2"
+  ROOTFS_SPARSIFY_TMPDIR="$(mktemp -d "${OUT_DIR}/virt-sparsify-tmp.XXXXXX")"
+  TMPDIR="${ROOTFS_SPARSIFY_TMPDIR}" virt-sparsify --check-tmpdir=continue --compress \
+    "${IMAGE}" "${SPARSE_IMAGE}"
+  mv "${SPARSE_IMAGE}" "${IMAGE}"
+fi
+
+if [ -n "${HOST_UID}" ] && [ -n "${HOST_GID}" ]; then
+  chown -R "${HOST_UID}:${HOST_GID}" "${OUT_DIR}"
+fi
+
+echo "Compressed RootFS size: $(stat -c '%s bytes' "${IMAGE}") ($(du -h "${IMAGE}" | cut -f1) on disk)"
+echo "GitHub runner ${RUNNER_VERSION} RootFS ready: ${IMAGE}"

package/reference/github-runner/rootfs/forget-self.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// Sends FORGET for this VM's own INSTANCE on behalf of the wallet that pays
+// for it. The key is a delegate the owner authorized for INSTANCE and FORGET:
+// Aleph lets a delegate forget only messages it could have created itself. Usage: forget-self.mjs <env-file> [reason]
+//
+// env file: ALEPH_FORGET_KEY, ALEPH_OWNER, ALEPH_INSTANCE, optional ALEPH_API_HOST
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+
+export function parseEnv(text) {
+  const env = {}
+  for (const line of text.split('\n')) {
+    const match = /^\s*([A-Z_][A-Z0-9_]*)=(.*)$/u.exec(line)
+    if (match) env[match[1]] = match[2].trim().replace(/^(['"])(.*)\1$/u, '$2')
+  }
+  return env
+}
+
+export function buildForget({ sender, owner, instance, reason, now = Date.now() / 1000 }) {
+  if (!/^[a-f0-9]{64}$/u.test(instance)) throw new Error('ALEPH_INSTANCE must be a 64-hex item hash')
+  if (!/^0x[0-9a-fA-F]{40}$/u.test(owner)) throw new Error('ALEPH_OWNER must be an 0x address')
+  const itemContent = JSON.stringify({
+    address: owner,
+    time: now,
+    hashes: [instance],
+    aggregates: [],
+    reason
+  })
+  return {
+    sender,
+    chain: 'ETH',
+    type: 'FORGET',
+    item_hash: createHash('sha256').update(itemContent).digest('hex'),
+    item_type: 'inline',
+    item_content: itemContent,
+    time: now,
+    channel: 'ALEPH-CLOUDSOLUTIONS'
+  }
+}
+
+export function signaturePayload(message) {
+  return [message.chain, message.sender, message.type, message.item_hash].join('\n')
+}
+
+async function main() {
+  const [envFile, reason = 'github-runner finished'] = process.argv.slice(2)
+  const env = parseEnv(readFileSync(envFile, 'utf8'))
+  const { Wallet } = await import('ethers')
+  const wallet = new Wallet(env.ALEPH_FORGET_KEY)
+  const message = buildForget({
+    sender: wallet.address,
+    owner: env.ALEPH_OWNER,
+    instance: env.ALEPH_INSTANCE,
+    reason: `github-runner: ${reason}`
+  })
+  message.signature = await wallet.signMessage(signaturePayload(message))
+  const api = env.ALEPH_API_HOST || 'https://api2.aleph.im'
+  const response = await fetch(`${api}/api/v0/messages`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ sync: false, message }),
+    signal: AbortSignal.timeout(20_000)
+  })
+  const body = await response.json().catch(() => ({}))
+  console.log(`FORGET ${message.item_hash}: HTTP ${response.status} ${body.message_status ?? ''}`)
+  if (![200, 202].includes(response.status) || body.message_status === 'rejected') process.exit(1)
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) await main()

package/reference/github-runner/rootfs/github-runner-finish

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Runs once the runner has exited (its one job is done, or it failed to
+# start) and from the TTL timer. Powering off alone keeps the INSTANCE
+# allocated and billed, so when the launcher injected a forget key the VM
+# first sends FORGET for its own INSTANCE on behalf of the owner.
+set -uo pipefail
+
+reason="${1:-runner-exited}"
+FORGET_ENV=/etc/github-runner/forget.env
+MARKER=/run/github-runner-finished
+
+# The TTL path powers off, which stops the runner, which runs this again.
+[ -e "${MARKER}" ] && exit 0
+touch "${MARKER}"
+
+LOG=/var/lib/github-runner/finish.log
+
+# Every attempt is bounded, and the whole loop stays well inside the unit's
+# TimeoutStopSec: if systemd kills this script, the poweroff below never runs.
+echo "$(date -Is) finish: ${reason}" | tee -a "${LOG}"
+if [ -s "${FORGET_ENV}" ]; then
+  for attempt in 1 2 3; do
+    # pipefail: the pipeline fails when node does.
+    if timeout 30 node /opt/github-runner/forget-self.mjs "${FORGET_ENV}" "${reason}" 2>&1 | tee -a "${LOG}"; then
+      break
+    fi
+    sleep $((attempt * 5))
+  done
+fi
+echo "$(date -Is) poweroff" | tee -a "${LOG}"
+systemctl --no-block poweroff

package/reference/github-runner/rootfs/github-runner-start

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Waits for the launcher to inject a one-job just-in-time config, then runs
+# exactly one job as the unprivileged runner user. The config is removed as
+# soon as the runner has read it, so a job cannot find it on disk.
+set -euo pipefail
+
+CONF_DIR=/etc/github-runner
+JIT="${CONF_DIR}/jitconfig"
+
+until [ -s "${JIT}" ]; do sleep 2; done
+
+if [ -s "${CONF_DIR}/ttl" ]; then
+  ttl="$(tr -dc '0-9' <"${CONF_DIR}/ttl")"
+  if [ -n "${ttl}" ] && [ "${ttl}" -gt 0 ]; then
+    mkdir -p /run/systemd/system/github-runner-ttl.timer.d
+    printf '[Timer]\nOnActiveSec=\nOnActiveSec=%smin\n' "${ttl}" \
+      >/run/systemd/system/github-runner-ttl.timer.d/ttl.conf
+    systemctl daemon-reload
+  fi
+fi
+# The timer already runs from boot (a VM that never gets a config still powers
+# off); restarting it counts the TTL from now.
+systemctl restart github-runner-ttl.timer
+
+config="$(cat "${JIT}")"
+rm -f "${JIT}"
+
+cd /opt/actions-runner
+exec runuser -u runner -- ./run.sh --jitconfig "${config}"

package/reference/github-runner/rootfs/github-runner-ttl.service

@@ -0,0 +1,6 @@
+[Unit]
+Description=Stop an expired ephemeral GitHub runner
+
+[Service]
+Type=oneshot
+ExecStart=/usr/local/sbin/github-runner-finish ttl

package/reference/github-runner/rootfs/github-runner-ttl.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Maximum lifetime for an ephemeral GitHub runner
+
+[Timer]
+OnActiveSec=360min
+AccuracySec=1min
+Unit=github-runner-ttl.service
+
+[Install]
+WantedBy=timers.target

package/reference/github-runner/rootfs/github-runner.service

@@ -0,0 +1,17 @@
+[Unit]
+Description=Ephemeral GitHub Actions runner (one job, then forget and power off)
+After=network-online.target docker.service
+Wants=network-online.target docker.service
+
+[Service]
+Type=simple
+ExecStart=/usr/local/sbin/github-runner-start
+ExecStopPost=/usr/local/sbin/github-runner-finish
+Restart=no
+# Room for github-runner-finish: three bounded FORGET attempts, then poweroff.
+TimeoutStopSec=180
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target