// OPENBOX DOCS
Releasing
Cut and publish an OpenBox release and its verified artifacts.
This page is for maintainers publishing a release from master. The AppImage, Windows portable, macOS app bundle, and Flatpak artifacts are built in CI when a v* tag is pushed; the steps below prepare the version, changelog, and metadata before that tag.
Before you tag
- Work from a clean
masterthat tracksorigin/master; confirm the target tag does not already exist. - Bump
updates.pyVERSIONto the new semver. - Add a dated section to
docs/CHANGELOG.md(Keep a Changelog format) and the comparison links, and updatedocs/RELEASE_NOTES.md(CI publishes it as the release body). - Prepend release metadata to
openbox.metainfo.xml. - Update the README release badge,
PARITY.mdlatest-release text, the bug-report template's version field, and any branch/version references that should track the current release. ReviewSUPPORT.md, the Flathub checklist, installer architecture examples, and this page. Leave historical version references in old changelog/metainfo entries and completed specs unchanged. - Run the local gates:
./run_all_tests.sh
python3 -B tests/test_packaging.py
appstreamcli validate --no-net openbox.metainfo.xml # when available
desktop-file-validate openbox.desktop # when available
git diff --check
Build and verify the artifact locally
Prerequisites: Rust 1.92+ (the pinned toolchain is 1.99.1), gcc, pkg-config, and the WebKitGTK dev package (libwebkit2gtk-4.1-dev on Debian/Ubuntu, webkit2gtk-4.1 on Fedora). The build compiles openbox-server with Cargo and native_host.c against webkit2gtk-4.1, and bundles no Python interpreter.
bash build_appimage.sh
OPENBOX_ARCH overrides architecture detection (x86_64 or aarch64); the output is OpenBox-$arch.AppImage (default OpenBox-x86_64.AppImage). Build each architecture separately when testing locally:
OPENBOX_ARCH=x86_64 ./build_appimage.sh OpenBox-x86_64.AppImage
OPENBOX_ARCH=aarch64 ./build_appimage.sh OpenBox-aarch64.AppImage
The build produces the architecture-specific AppImage and .zsync pair, but does not regenerate the .sha256 sidecar. Regenerate it explicitly:
sha256sum OpenBox-x86_64.AppImage > OpenBox-x86_64.AppImage.sha256
sha256sum -c OpenBox-x86_64.AppImage.sha256
Confirm the embedded version matches the release with openbox-server --dump-contracts (or GET /api/v2/version from the running build). updates.py is a build-time/installer file and is not installed into the AppDir.
Push and tag
- Commit the version/changelog/metadata changes, push directly to
master, and wait for the Rust workspace checks and the Python 3.11/3.12 CI jobs to pass for that exact commit. - Create and push an annotated tag:
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z
What CI does
Pushing a v* tag triggers the AppImage/Windows release workflow and the Flatpak release workflow. The two publish jobs share a per-tag concurrency group because both update the same GitHub Release.
release.yml defines ten jobs: test, build, attest, build-windows, attest-windows, build-windows-arm64, attest-windows-arm64, build-macos, attest-macos, and one shared publish. The Windows and macOS artifacts are uploaded by that same publish job, not by a separate one.
test (contents read): installs the build dependencies, compiles the native host, and runs the full test suite on the host.
build (contents read, needs test): validates the tag against updates.py VERSION, compiles the native host, and builds both OpenBox-x86_64.AppImage and OpenBox-aarch64.AppImage on architecture-matched runners. Each build is checked against the glibc floor, and gets a .zsync, .sha256, and architecture-appropriate CycloneDX SBOM, then uploads unsigned outputs as workflow artifacts.
attest (id-token and attestations write, needs build): downloads each build output and attests provenance for both AppImages.
build-windows (contents read): builds the portable runtime, compiles native_host.exe, packages OpenBox-x86_64-windows.zip with one top-level OpenBox/ folder, and produces the standalone OpenBox-x86_64-windows-native-host.exe that source checkouts can drop in.
attest-windows (id-token and attestations write, needs build-windows): attests provenance for the zip and the standalone host. It only attests — the signing and the upload happen in the shared publish job.
build-macos (contents read): runs the test suite on the macOS runner, builds the universal app bundle with scripts/build_macos_app.sh, smoke-tests it, and produces the per-release SBOM. attest-macos (id-token and attestations write, needs build-macos): attests provenance for OpenBox-macos.zip. It only attests; the signing and upload happen in the shared publish job.
publish (requires the release environment, contents write; needs all eight upstream jobs: build, attest, build-windows, attest-windows, build-windows-arm64, attest-windows-arm64, build-macos, and attest-macos): checks out the exact tagged commit, confirms the annotated tag points at the build commit, signs and verifies the AppImages, the x86_64 and ARM64 Windows zips, and both standalone hosts, compares the derived public key against the committed openbox-release.pub, re-checks each SHA-256, and verifies each signature. If OPENBOX_SIGNING_KEY is missing or the derived key does not match, the job fails before anything is published. It then copies scripts/install.sh, scripts/install.ps1, and scripts/install-macos.sh and uploads both signed AppImages with their .zsync, .sha256, and .sig, the x86_64 and ARM64 Windows zips and hosts with their sidecars, the release key, and the architecture-specific SBOMs — so the release publishes all three installers. A tag containing - is marked prerelease.
For the macOS bundle, the same publish job signs OpenBox-macos.zip with the release key, verifies the signature against the committed openbox-release.pub, and uploads it with its .sha256 and .sig, together with install-macos.sh and verify_release.py.
The Flatpak workflow (release-flatpak.yml) has two jobs:
build: validates packaging metadata, compiles the native host, runs packaging tests, installs the GNOME 51 runtime/SDK, and creates OpenBox-x86_64.flatpak.
publish (requires the release environment, contents write): uploads the x86_64 Flatpak to the same release and uses the same docs/RELEASE_NOTES.md body. Its publish job is serialized with the shared publish job for that tag.
The release body is docs/RELEASE_NOTES.md, so update it before tagging; GitHub does not generate the notes.
Verify after publishing
- Confirm GitHub's latest-release API returns the new version and the architecture matrix: x86_64 and aarch64 AppImages with
.zsync,.sha256, and.sig, the release key, architecture-specific SBOMs,install.sh,install.ps1,install-macos.sh,verify_release.py,OpenBox-x86_64.flatpak, the signedOpenBox-x86_64-windows.zipandOpenBox-x86_64-windows-native-host.exewith their sidecars, and the signedOpenBox-macos.zipwith its sidecars. - Download each AppImage and its
.sha256remotely and runsha256sum -c. - Verify both signatures with
scripts/verify_release.py --key openbox-release.pub OpenBox-x86_64.AppImage OpenBox-x86_64.AppImage.sigand the matching aarch64 paths, then repeat for the Windows zip and standalone host. - Check that the Windows zip contains a single top-level
OpenBox/folder withopenbox-server.exe,web_app.py(the fallback), and the compilednative_host.exe. - Start the AppImage and confirm the updater reports the new version as current with no update available.
Pitfalls
build_appimage.shdoes not regenerate the.sha256sidecar; a stale checksum must be replaced manually.- Release artifacts are Git-ignored and must be uploaded explicitly via the release workflow.
- Do not tag or publish before CI succeeds for the exact release commit.
- OpenBoxGL ships from
master; there is no release branch or worktree for releases (CI checks out arelease/1.19branch only as the perf baseline).