Skip to content

[Linux] Publish an installable Flatpak bundle with GitHub releases #618

Description

@TheZupZup

Part of #376.

Goal

Publish a user-installable .flatpak bundle with Linthra's normal GitHub releases so Linux users can install Linthra like a real desktop application instead of extracting the current x86_64 tar archive manually.

This is intentionally separate from Flathub submission. The goal is to improve the GitHub Releases experience now, even before Linthra is accepted on Flathub.

User experience

A Linux user should be able to:

  1. Open a Linthra GitHub release.
  2. Download something like Linthra-0.2.7-x86_64.flatpak.
  3. Open/install it through their Flatpak-aware software center or with the normal Flatpak CLI.
  4. Find Linthra in the GNOME/KDE application launcher with the correct name and icon.
  5. Launch it without extracting a tar archive or manually creating desktop files.

The existing x86_64 tar artifact may remain available for users who want a portable/native bundle, but the .flatpak should become the recommended easy-install artifact for supported Linux desktops until Flathub is available.

Existing foundation

Linthra already has the important packaging pieces from the Flatpak milestone:

Reuse those existing files and build paths. Do not create a second Flatpak implementation just for releases.

Requirements

  • Build the Flatpak from the exact release/tagged source used by the release workflow.
  • Produce a standalone installable .flatpak bundle using the existing validated manifest.
  • Name the artifact predictably and include the Linthra version and architecture where useful.
  • Upload the bundle automatically to GitHub Releases alongside the existing Linux artifacts.
  • Preserve the existing desktop file, icon, application ID and AppStream identity.
  • Verify that an installed bundle launches from GNOME/KDE application menus.
  • Ensure the bundle uses the packaged runtime and does not silently depend on host-installed libmpv.
  • Keep build inputs reproducible and declared; no hidden network downloads during the packaging step.
  • Generate and publish a SHA-256 for the final bundle, consistent with Linthra's existing release-artifact verification approach.
  • Do not change Android/F-Droid release behavior.
  • Do not submit anything to Flathub as part of this issue.

Release workflow

Integrate this into the existing reviewed release process rather than adding a separate manual release path.

A normal stable release should be able to publish, where supported:

  • Android APK/AAB artifacts already produced by Linthra
  • Linux native/x86_64 archive if still retained
  • Linux .flatpak install bundle
  • hashes / release verification metadata

No auto-merge is required or desired.

Validation

Before considering this complete, validate at least:

  • clean Flatpak build from a release/tag checkout;
  • bundle creation succeeds;
  • bundle installs successfully in a clean test environment;
  • Linthra appears in the desktop application launcher;
  • correct Linthra icon and application name are shown;
  • app launches to a usable first frame;
  • real packaged audio backend can initialize using the Flatpak runtime;
  • uninstall removes the application cleanly without affecting user music files;
  • release artifact hash matches the uploaded file.

Where full GUI installation cannot run in CI, keep deterministic packaging checks in CI and document the small real-desktop smoke test separately.

Acceptance criteria

  • Stable GitHub releases automatically include an installable .flatpak bundle.
  • The bundle is built from the exact intended release source.
  • Installing it creates a normal GNOME/KDE launcher entry with the correct Linthra icon/name.
  • Linthra launches successfully after installation.
  • Flatpak playback uses the packaged runtime rather than relying on host libmpv.
  • The final bundle has a published SHA-256 / artifact verification record.
  • Existing Android/F-Droid and Linux-native release artifacts are not regressed.
  • Documentation tells users that the .flatpak is the easiest GitHub-install option until Flathub is available.

Non-goal

This issue does not submit Linthra to Flathub. Flathub submission remains tracked separately in #456.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions