Everything Axon ships that changes between releases (services, apps, the
GNOME Shell extension, theme, helper scripts and their systemd units) is one
package, axon-os, built by packaging/build-deb.sh. The ISO build installs
it, and installed systems upgrade it from the Axon apt repository:
https://projectdev-git.github.io/Axon-OS/apt stable main
The package itself adds that source and its signing key, so axon-update
(the daily timer, or the Axon OS Updater app) picks up new releases along
with Ubuntu's updates. Running Axon services restart on upgrade; the voice
service restarts at the next login.
Not in the package: the live-session installer, the GRUB and Plymouth themes, GNOME default settings and anything else that only matters when the image is built. Changes there still need a new ISO.
Actions → Release → Run workflow, and enter the new version (e.g. 1.2.0).
It refuses a version that isn't higher than the one in pyproject.toml or
whose tag exists, then:
- bumps
pyproject.toml, commits tomainand tagsvX.Y.Z; - creates the GitHub release with generated notes;
- runs Publish apt repo, which builds the package, signs the repository
with the
APT_SIGNING_KEYsecret, pushes it togh-pagesand attaches the.debto the release (the newest five versions stay in the repo); - starts Build ISO for the tag, which attaches the ISO to the release.
GitHub caps release files at 2 GiB, so a larger ISO goes up in
.partNNpieces and the release notes say how to join them (cat axon-os-*.iso.part* > axon-os-X.Y.Z-amd64.iso, then check the.sha256).
Pushing a v* tag yourself also publishes the package, but the tag must match
the version in pyproject.toml.
-
Create a signing key and keep the private half only as a secret:
export GNUPGHOME="$(mktemp -d)" gpg --batch --passphrase '' --quick-gen-key "Axon OS Archive <axon-os@users.noreply.github.com>" rsa4096 sign 5y gpg --armor --export > packaging/axon-os-archive-keyring.asc gpg --armor --export-secret-keys | gh secret set APT_SIGNING_KEY --repo ProjectDEV-git/Axon-OS rm -rf "${GNUPGHOME}"
Commit
packaging/axon-os-archive-keyring.asc. (Done on 2026-10-07: key20D7784AF91A03B7668F28DB65A4FEB86DD57517.) Every installed system trusts this key, so rotating it later means shipping the new public key in a release signed with the old one first. -
Enable GitHub Pages for the
gh-pagesbranch (root folder) after the first publish creates it.
The daily update never changes the Ubuntu release. sudo axon-update --release-upgrade does, after
taking a BTRFS snapshot you can boot from; see ubuntu-26.04.md.
Installs from ISOs before the update channel have no axon-os package and
no Axon apt source. Install the package once from a release and the updater
takes over from there:
sudo apt install ./axon-os_<version>_all.deb