P3-8: Linux packaging and release workflow #37

New issue

Open

opened 2026-09-10 17:45:03 +00:00 by Cordy · 0 comments

Cordy commented

2026-09-10 17:45:03 +00:00

Owner

Depends on P3-7. Do this platform first — it builds and tests entirely on the arm64 Pi runner you already own, with no certificate, no Mac and no store account.

Files

Create: .forgejo/workflows/release-linux.yml, build/linux/cairn.desktop, build/linux/AppImageBuilder.yml (or Flatpak manifest)

Formats

AppImage — primary. One file, runs anywhere, no root, no repository to maintain. The right default for a small team.
Flatpak — secondary, if time allows. Better desktop integration and sandboxing, more packaging work.
.deb / .rpm — only if a customer asks. Maintaining repositories is an ongoing commitment, not a one-off build step.

Build matrix

Build amd64 and arm64. Cairn users self-host on Raspberry Pis and ARM servers, so an arm64 desktop build is not exotic here — and your CI runner is arm64 anyway.

Desktop integration

.desktop entry with icon and correct categories.
Register the cairn:// URL scheme for zero-touch enrolment (P3-4).
XDG autostart file (P3-6).

No auto-updater

Ship none on Linux — the package manager or AppImage updater owns it (P3-7). Make sure the in-app update setting reflects that honestly rather than showing a dead toggle.

Workflow

Triggered by a v* tag.
Cross-compile CGO_ENABLED=0 for both architectures.
Package, generate checksums, attach to a Forgejo release.
Same runner constraints as ci.yml: host mode, arch detection, plain-git checkout, no TTY.

Steps

Write the workflow and packaging files.
Tag a test release; confirm artifacts build for both architectures.
Install the AppImage on a clean machine and complete setup end to end. Building is not shipping.
Dogfood against the .249 instance for at least a week before moving on.
Commit: git commit -s -m "build: Linux AppImage packaging and release workflow"

Acceptance criteria

Tagging produces signed-checksum artifacts for amd64 and arm64.
The AppImage runs on a clean machine with no dependencies installed.
cairn:// links open the app.
A week of real dogfooding with no data loss.

Depends on P3-7. **Do this platform first** — it builds and tests entirely on the arm64 Pi runner you already own, with no certificate, no Mac and no store account. ## Files - Create: `.forgejo/workflows/release-linux.yml`, `build/linux/cairn.desktop`, `build/linux/AppImageBuilder.yml` (or Flatpak manifest) ## Formats - **AppImage** — primary. One file, runs anywhere, no root, no repository to maintain. The right default for a small team. - **Flatpak** — secondary, if time allows. Better desktop integration and sandboxing, more packaging work. - **.deb / .rpm** — only if a customer asks. Maintaining repositories is an ongoing commitment, not a one-off build step. ## Build matrix Build **amd64 and arm64**. Cairn users self-host on Raspberry Pis and ARM servers, so an arm64 desktop build is not exotic here — and your CI runner is arm64 anyway. ## Desktop integration - `.desktop` entry with icon and correct categories. - Register the `cairn://` URL scheme for zero-touch enrolment (P3-4). - XDG autostart file (P3-6). ## No auto-updater Ship none on Linux — the package manager or AppImage updater owns it (P3-7). Make sure the in-app update setting reflects that honestly rather than showing a dead toggle. ## Workflow - [ ] Triggered by a `v*` tag. - [ ] Cross-compile `CGO_ENABLED=0` for both architectures. - [ ] Package, generate checksums, attach to a Forgejo release. - [ ] Same runner constraints as `ci.yml`: host mode, arch detection, plain-git checkout, no TTY. ## Steps - [ ] Write the workflow and packaging files. - [ ] Tag a test release; confirm artifacts build for both architectures. - [ ] **Install the AppImage on a clean machine and complete setup end to end.** Building is not shipping. - [ ] Dogfood against the `.249` instance for at least a week before moving on. - [ ] Commit: `git commit -s -m "build: Linux AppImage packaging and release workflow"` ## Acceptance criteria - Tagging produces signed-checksum artifacts for amd64 and arm64. - The AppImage runs on a clean machine with no dependencies installed. - `cairn://` links open the app. - A week of real dogfooding with no data loss.