sebas/pxvirt
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Page: Submodule pin conventions
Pages
CLI - proxmox-boot-tool CLI - pvebcache CLI - pvessh CLI - qm CLI CVE-2026-31431 Ceph - Deployment Ceph - Maintenance Ceph - RDMA DirtyFrag Hardware Requirements Home Install from Debian Install from ISO Install from openEuler Issue - ARM 32-bit Issue - IPv6 Issue - MSIx PBA Outside of Specified BAR Issue - PCI Passthrough Issue - Raspberry Pi Issue - Rockchip Issue - Win7 Internal Error Proxmox Memory Resources Download Roadmap SPDK Setup - Linux on ARM64-Loongson Setup - Migrate from Proxmox VE Setup - Windows on x86 Software Repository (Upstream Lierfang) Submodule pin conventions UI eNFS vGPU - Moore Threads vGPU - Nvidia
1 Submodule pin conventions
Sebastiaan Koetsier edited this page 2026-08-22 14:26:58 +02:00
Table of Contents

Submodule pin conventions

This repo vendors ~84 upstream packages as git submodules under packages/. Each submodule is pinned to one commit. That pin can be right or wrong for our target (arm64, Debian 12/bookworm) independently of whether it builds — a package can build fine against the wrong distro branch and only fail later, at install or at runtime. This page documents what "right" looks like per upstream source, and how to check.

Two upstream sources, two branch vocabularies

git.proxmox.com (official Proxmox packages). Branch names are distro-suffixed: master tracks the current unstable/next release, stable-bookworm tracks Debian 12 (Proxmox VE 8), stable-N tracks older numbered releases. We want stable-bookworm wherever one exists.

github.com/jiangcuo/* (PXVIRT's own forks, arm64/loongarch patches on top of Proxmox). Branch names are PXVIRT-version-suffixed, not distro-suffixed: pxvirt is the original (Proxmox VE 7/8-era) line, pxvirt8 targets Proxmox VE 8/bookworm, pxvirt9 targets the newer Proxmox VE 9/trixie line. We want pxvirt8 for anything we build against bookworm. pxvirt (no suffix) also shows up correctly as the current branch for a few packages (e.g. pve-qemu, pve-installer) where jiangcuo hasn't split out a separate pxvirt8 line — that's fine, verified case by case, not a rule to apply blindly.

Some jiangcuo forks use neither convention — e.g. pve-lxc-syscalld and proxmox-kernel-helper have branches named arm64, master, Port, rpm, rhel9. There's no distro signal in those names at all; picking the right one requires cross-checking against the version actually running on piprox (see below), not pattern-matching the name.

branch = in .gitmodules means "audited", not "correct forever"

A submodule with an explicit branch = ... line in .gitmodules means someone checked it and pinned it deliberately. A submodule with no branch = line means nobody has looked — it is not evidence the pin is fine, it's the absence of any evidence at all. As of 2026-08-22, 16 of 84 submodules have a declared branch. The other 68 have never been individually verified.

This isn't hypothetical: the 16 that do have a branch were only added after we found, by accident, that pve-manager and proxmox-widget-toolkit were pinned to stock upstream master (Debian 13/trixie-track) instead of jiangcuo's pxvirt8 (bookworm) branch — found because a rebuild silently pulled in trixie-targeted code onto a bookworm build image. The same bug class can be sitting undetected in any of the other 68.

Checking a pin: scripts/audit-pins.sh

scripts/audit-pins.sh              # expects bookworm
scripts/audit-pins.sh trixie       # override the expected distro

For every submodule it reports, cheaply and without cloning anything new:

  • whether branch = is declared, and if so whether that branch still exists on the remote (git ls-remote) and whether our pinned commit is currently its tip (AT_TIP) or behind it (BEHIND_TIP — normal, pins are supposed to lag)
  • if the submodule happens to already be checked out locally, the target distro from its own debian/changelog first line, compared against the expected distro

It runs in CI (.forgejo/workflows/audit-pins.yml) on every push that touches .gitmodules, catching typos and renamed/deleted branches immediately. CI does a bare checkout (no submodules initialized), so it only gets the cheap branch-existence check; the deeper changelog check needs the submodule actually checked out and is meant to be run locally before committing a pin change, the same way it was run for this page.

Known open findings (2026-08-22 audit run)

Confirmed diverged from stable-bookworm (currently on the trixie/master line, git merge-base --is-ancestor fails against origin/stable-bookworm in both directions):

  • vncterm — already built and published by us; a re-pin means a rebuild + republish + re-verify cycle on a package already live.
  • novnc-pve — same caveat, already live.
  • pve-firewall
  • proxmox-biome

Declared no branch, changelog targets trixie, no stable-bookworm branch exists upstream to switch to (pve-ha-manager, pve-guest-common only have master/stable-4/stable-7) — these may simply not need a distro-specific branch (pure-Perl, no ABI dependency on the base distro), but that's an assumption, not a verified fact yet:

  • pve-ha-manager
  • pve-guest-common

Non-standard branch naming, needs the piprox-installed-version heuristic used for the original 12, not name-pattern-matching:

  • pve-lxc-syscalld
  • proxmox-kernel-helper

Not a bug: proxmox-ve's changelog legitimately targets trixie (it's PVE9-track upstream, changelog literally says "bump for Proxmox VE 9.1") and pve-qemu's changelog target field is jiangcuo's own custom suite name (pxvirt), not a real distro codename — both are expected, not drift.

The remaining ~64 unaudited submodules have not been checked at all.