Packaging and Releases

Packaging and Releases

How ScreenGuard ships to users, and how to reproduce a release.

---

The artefacts

Every release publishes the same set of artefacts, built from one source tree:

Artefact	Naming	Target
Debian package	screenguard_<version>_amd64.deb	Debian, Ubuntu, Mint, Zorin, Pop!_OS
RPM package	screenguard-<version>-1.x86_64.rpm	Fedora, RHEL, Rocky
Tarball	screenguard-<version>-x86_64.tar.gz	Any distribution, user-level or system-wide
Source tarball	screenguard-<version>-source.tar.gz	Reproducibility and auditability

Each package contains the GUI, the daemon, the three native C helpers, the Python X11 fallback, the systemd user unit and preset, the desktop entry and the GNOME Shell extension.

Beta builds use a suffix for the build revision — for example screenguard_<version>.betaN-<revision>_amd64.deb and screenguard-<version>.betaN-<revision>.x86_64.tar.gz — because a beta can be re-cut several times while the same version number is being tested.

---

Build

flutter build linux --release
dart compile exe bin/daemon.dart -o build/linux/x64/release/bundle/screenguard-daemon

Native helpers:

gcc -O2 -o screenguard-notify src/notify.c
gcc -O2 -o screenguard-killer   src/killer.c
gcc -O2 -o screenguard-watchdog src/watchdog.c

Deb and rpm packages are produced with nfpm using the configs in packaging/:

nfpm package -f packaging/nfpm.deb.yaml -t dist/screenguard_0.1.1_amd64.deb
nfpm package -f packaging/nfpm.rpm.yaml -t dist/screenguard-0.1.1-1.x86_64.rpm

Arch packages use packaging/PKGBUILD (makepkg), and the RPM spec in packaging/screenguard.spec is kept for distributions that prefer a native spec file.

---

Repositories

Channel	Mechanism	Updated by	Contains
APT	Static repository under apt/ on the gh-pages branch	apt-repo.yml	Stable releases only
Copr	the-amibivert/screenguard	Copr build service	Stable releases only
Arch	Signed static repository under arch/ on the gh-pages branch	arch-repo.yml	Stable releases only
GitHub Releases	Direct download	The release itself	Stable and pre-releases (packages)
beta branch	Git on GitHub	Pushed continuously	The full, public source of every beta
AUR	Manual	—	Pending account availability

Package repositories are stable-only; the source never is. Pre-release packages are never pushed to the APT, Arch or Copr repositories — a beta is only available as a GitHub release asset, and the stable channels keep pointing at the last stable release. This means people who install from the repositories never get an untested build by accident. ScreenGuard itself stays open source throughout: the complete source of every beta is on the public beta branch, and nothing ships in a package that isn't in the repository history.

Both repository workflows run on a published release (or manually), sign the metadata with the project's GPG key and deploy to the gh-pages branch. The public key is at apt/key.asc and arch/key.asc.

---

Release checklist

1. Bump the version in pubspec.yaml, lib/services/app_version.dart, packaging/nfpm.deb.yaml, packaging/nfpm.rpm.yaml, packaging/PKGBUILD, packaging/screenguard.spec and the AppStream metadata.
2. Build the release artefacts: ./tools/build-tarball.sh <version>, then the .deb and .rpm with nfpm. Update packaging/PKGBUILD's sha256sums from the exact tarball you will upload.
3. Update the README/wiki version references and write the GitHub release notes. Upload the artefacts without renaming them, and use those exact filenames in the release notes.
4. Verify locally: flutter analyze, flutter test, then a clean install on at least one X11 desktop and one GNOME Wayland session.
5. Tag the release v<version> and publish it. For a beta, mark it as a pre-release so the repository workflows skip it.
6. The APT workflow downloads the published .deb; the Arch workflow builds from packaging/PKGBUILD. Both update their repositories for stable releases only.
7. Verify https://adityakrishnan005-a11y.github.io/ScreenGuard/apt/dists/apt/Release is signed and the package lists are current.

---

The in-app updater

The updater polls the GitHub Releases API once a day, compares semantic versions (including pre-release tags such as 0.2.0-beta.1), and installs the asset that matches how ScreenGuard was installed:

• /opt/screenguard → the .deb or .rpm, installed through pkexec so you get a normal password prompt,
• ~/.local → the tarball, installed through the bundled install.sh,
• /usr/local → the tarball with --system, also through pkexec.

Details that matter:

• The download is made by the application itself, so a minimal Debian install without curl or wget can still update in place.
• The installer runs in its own systemd service, so it cannot be killed when the app that started it tears down its scope.
• A stale daemon cannot crash-loop or outlive the fresh install, and relogging in no longer restarts the old copy.
• After a successful update you get a desktop notification and the new version opens by itself.
• If elevation is refused, the app shows the exact command to run by hand instead of failing silently.

Beta users must enable Include Beta Versions in Settings → Updates — pre-releases are hidden by default.

---

Related: Development · Installation · Architecture