release/3.x -> main, release/4.x -> next, master -> archive/v2-legacy
(retired, was byte-identical to release/2.x). Branch identity is now
role-based, not version-numbered -- main and next are fixed names
that never get renamed at a major-version cutover; release/N.x is
reserved exclusively for already-superseded majors, created only at
the moment they're archived.
This directly fixes the structural cause of the bug found 2026-08-30:
build.yml hardcoded literal branch-name comparisons for the
testing/beta channel, and ADR-006's original "master -> beta channel"
rule was never superseded when release/3.x took over as the active
branch, leaving master as a silent, stale duplicate of release/2.x
that CI still treated as a legitimate publish source. Rewrote the
version-resolution logic to match roles instead: refs/heads/main,
refs/heads/next, and a refs/heads/release/*.x pattern that auto-
catches any future archived major with zero code changes needed.
Also tightened the push/PR triggers from a bare wildcard to an
explicit allowlist, and switched the release-notes CHANGELOG link to
a tag-relative permalink instead of a floating branch reference.
Research (DEP-14, openedx/frontend-base #273, semantic-release's
branch-pattern config) is cited in ADR-013; the openedx precedent in
particular fixed this identical bug the same way.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Multipath (truenas-proxmox-multipath, shipped v3.2.0/#256) had zero
coverage in README.md and was actively described as unsupported/future
work in docs/architecture.md and docs/migration-advanced.md. Added:
- README: Prerequisites, Installation, and Configuration sections for
the multipath package and its truenas-multipath storage type
- architecture.md: new §9 covering what TrueNASMultipath.pm overrides
vs. inherits, and the live failover behavior confirmed 2026-08-29
- migration-advanced.md: points to the multipath package instead of
calling it unsupported
- truenas-storage-help.html: single-path note pointing to the
multipath alternative
Also fixed README content that was stale from the v3.0 beta era: the
PVE 9 blockdev issue (#266) was fixed in v3.1.0 but still read as
open, "v3.0 (beta)" headings never updated to v3.x, a broken internal
anchor link, and a note claiming WebSocket support was "v3.0.0" scope
when ADR-009 placed it at v4.0.0.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Debian trixie recommends deb822-style .sources files over the one-liner
.list format, and PVE 9 ships on trixie. Show deb822 as the primary form
in README (stable, v2 track, Cloudsmith migration, testing) and
getting-started.md/upgrade-paths.md, keeping the one-liner .list format
as a fallback for PVE 8 / bookworm users.
Fixes#285
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
README and getting-started.md still described the legacy v2.x "ZFS over
iSCSI" storage type and pre-25.04 TrueNAS SCALE UI locations. Update both
to match the actual v3 "TrueNAS (ZFS/iSCSI)" panel fields, document the
SCALE 25.04+ API key location and the throwaway-share workaround for the
now-missing standalone portal/initiator-group screen, and sync the help
HTML per the same-commit doc-sync rule.
Fixes#286
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Users who had the v3 repo configured before v3.2.2 see an apt security
prompt when the Codename field changed from unset to 'error'. Document
the --allow-releaseinfo-change one-liner in README, getting-started.md
(new section 6.8), and upgrade-paths.md (codename column + callout).
Closes#284.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
build.yml: testing dist publish condition used 'beta'/'alpha' but the
workflow channel values are 'testing'/'development' — step was always
skipped. Corrected to match actual channel names.
README: badge URLs referenced TheGrandWazoo/truenas-proxmox (repo not yet
renamed); corrected to freenas-proxmox. Workflow badge now includes
branch=release/3.x so it tracks the default branch explicitly.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
build.yml:
- New "Publish to GitHub Pages testing dist" step — runs on beta/alpha
channel builds (pushes to release/3.x and master); replaces pool/testing/
with the latest build so the dist always has exactly one version
- Cloudsmith now receives v2.x stable only; beta/alpha no longer published
to Cloudsmith testing channel
README:
- Replace Cloudsmith testing install instructions with GitHub Pages testing
dist track; same GPG key as stable, just different dist name
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- README: new "Migrating from Cloudsmith" section with v2 and v3
command sequences and a one-line reason (Cloudsmith being phased out)
- docs/upgrade-paths.md: full matrix of every starting version × repo
combination with links to the right guide; v4.x rows stubbed with
placeholder instructions so users know what's coming and where to look
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
README: v2.x Prerequisites relabeled legacy (not 'current stable');
condensed to three items. v3.0 does not require SSH.
architecture.md: remove incorrect claim that the Add Storage wizard
requires SSH via ZFSPoolPlugin.pm. Verified in truenas-storage.js:
truenas_pool is a plain text field. Pool is validated at runtime via
GET /pool/dataset, not SSH.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
v3.0 requires no SSH — QEMU connects directly via iscsi://. README "How It
Works" and troubleshooting sections had v2.x SSH carryover. Compatibility
matrix now shows v3.x as stable with PVE 9 confirmed.
All install instructions updated from Cloudsmith to the GitHub Pages apt
repo (thegrandwazoo.github.io/freenas-proxmox, v3 dist track). Cloudsmith
testing channel retained for beta builds only.
architecture.md updated to reflect ADR-010 and the live GitHub Pages publish
step in CI.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Implements ADR-010: stable releases are now published to
https://thegrandwazoo.github.io/freenas-proxmox/ in addition to Cloudsmith.
Dist tracks:
v3 main — v3.x releases (new installs)
main main — v2.x only (backward-compat, never auto-promoted to v3)
v2 main — v2.x alias (explicit pin)
CI: new "Publish to GitHub Pages APT repo" step in the publish job runs on
tagged stable releases. Downloads the built .deb, places it in pool/v{major},
regenerates Packages.gz and a GPG-signed InRelease for the relevant dist(s),
and pushes to the gh-pages branch.
Setup: scripts/setup-apt-signing-key.sh generates the GPG key pair and prints
the exact `gh secret set` commands to run. Requires APT_SIGNING_KEY and
APT_SIGNING_KEY_PASSPHRASE secrets to be added to the repo before the first
tagged release.
README updated to point new installs at GitHub Pages; Cloudsmith testing
channel retained for beta builds.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- v3.x beta: tested on PVE 8.4.x, CORE 13.0-U6, SCALE 24.10 + 25.04 + 25.10
- v3.x PVE 9.x: split to planned row with known issue ref (#266)
- Version notices: PVE 8 now points to beta, PVE 9 warns of known issue
- Drop untested SCALE Cobia/Dragonfish from tested column
- "upcoming" → "beta", "In development" → "Beta — active development"
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Introduces truenas-proxmox as the real package and freenas-proxmox as a
transitional meta-package that Depends on truenas-proxmox. Existing
users running apt upgrade automatically pull in the new package; the
migration one-liner (apt install truenas-proxmox && apt purge
freenas-proxmox) completes the transition. The freenas-proxmox package
name will not exist in v4.0.
Changes:
- packaging/DEBIAN/: Package renamed to truenas-proxmox, INSTALL_DIR
and LOG_FILE updated to /usr/share/truenas-proxmox and
/var/log/truenas-proxmox-install.log; Replaces/Breaks fields added
- packaging/DEBIAN-transitional/: new empty meta-package that pulls in
truenas-proxmox and prints a deprecation notice on configure
- build.yml: PACKAGE_NAME=truenas-proxmox; both debs built and
published to Cloudsmith; transitional postinst added to shellcheck
- All GitHub repo URLs updated to TheGrandWazoo/truenas-proxmox
- apt install/remove/purge commands in docs updated to truenas-proxmox
- GitHub repo rename to truenas-proxmox pending (gh repo rename step)
Closes#262
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Move sponsor ask above the fold with context (4M downloads, ISP/MSP
production use) so it reaches users who never scroll to the bottom.
Expand the Support section with tier descriptions and remove PayPal
in favour of GitHub Sponsors which has no platform fee.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add TPM state disk known limitation to v3.0 Prerequisites with clear
workaround (local-lvm or NFS for tpmstate0, shared storage for live
migration with TPM)
- Expand Upgrading section with v2.x→v3.0 Move Disk migration path,
confirmed tested on PVE 8.4 with CORE 13.0-U6 and SCALE 24.10
- Note in-place rename is not supported; Move Disk is the supported path
Closes#260, #228, #252
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Cobia and Dragonfish remain listed as compatible but are not yet tested
against v3.0 — would require reinstalling those versions in the lab.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
v3.0 is fully API-driven: no SSH keys, no pre-created iSCSI targets.
v2.x still requires both. Separating them prevents confusion for users
on either version and removes incorrect guidance from the v3.0 path.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Closes#257. Many support issues are misrouted because users don't know
which layer generated the error — the plugin (REST API orchestration),
the iSCSI/QEMU data path, or the Proxmox core storage stack. Added a
new section at the top of Troubleshooting that explains all three layers
with example log lines and a quick-triage table.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Proxmox enters and allocates disk sizes in GiB (base-2) while TrueNAS
and many storage UIs display sizes in GB (base-10). This causes the
reported size to appear ~7% larger than the number entered, which is
correct and expected behaviour. Adds a reference table for common sizes.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- New troubleshooting entry: SCALE 25.04 revokes existing API keys on
upgrade; users must regenerate and update truenas_secret in PVE config.
Also notes HTTPS enforcement and links to #243 for REST deprecation.
- Updated volblocksize entry: v2.4.0 auto-corrects blocksize, so the
"fix" is now informational rather than a manual step.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
ZFSPlugin's free_image deletes the zvol via SSH after calling our
run_delete_lu. Our earlier addition of freenas_delete_zvol in
run_delete_lu caused a double-delete: SSH would fail, free_image's
error recovery would call run_create_lu on the now-missing zvol,
producing a spurious "Unable to create lun (rolled back)" in the task
log even though the migration had already succeeded.
freenas_delete_zvol remains in run_create_lu's rollback path where it
correctly cleans up zvols orphaned by a failed LUN creation (#239).
Also documents ZFS blocksize requirements for TrueNAS SCALE (16k) vs
CORE (8k) in README configuration and troubleshooting sections (#241).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Users on unsupported PVE versions now get clear guidance at every
layer — README, install time, and GitHub release notes — rather than
silently failing or getting confusing patch errors.
- README: replace bare compatibility table with a full matrix and
prominent callout blocks for PVE 7 (last v2.x), PVE 8 (EOL
2026-08-31), PVE 9+ (use v3.0), and PVE ≤6 (unsupported)
- postinst: add check_pve_version() that exits on PVE < 7, warns
loudly on PVE 7 (stay on v2.x, do not upgrade to v3.0), notes
the PVE 8 EOL date, and warns on PVE 9+ (v2.x not supported)
- build.yml release template: add a version compatibility table so
every GitHub release prominently states who should and should not
install it
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Update README.md to be more structured and selective from a visitors view.
- Update the Roadmap section.
- Update the Donators list.
- Update the New Install Instructions section to allow the visitor to select the GPG location they want to use.
- Update the Activity section.
- Fix spelling errors.
- Updated new repo install.
- Updated Roadmap.
- Cleanup old information.
- Updated Donation list.
- Changed FreeNAS to TrueNAS in most of the instructions.
