feat: the Longshot Builder as a Flatpak, published to flat-manager #1

Merged
claude merged 2 commits from feat/flatpak into main 2026-11-13 14:11:02 -05:00
Collaborator

What

dev.magicbean.Longshot is the Longshot Builder as a Flatpak. CI publishes it to Bean-Ops' flat-manager (stable). It wraps Longshot's signed release AppImage, unpacked into /app on org.freedesktop.Platform 26.08 (24.08 reached end of life in August). The README has the details.

File What
config.env Every address: Longshot's release list, the channel (rc until the first stable), flat-manager's URL and repo, Flathub. Nothing is hard-coded elsewhere
release_keys.json Longshot's release key, pinned (copied from Longshot's scripts/release_keys.json)
scripts/pick_release.py The channel's newest release, by Longshot's own channel rules. It checks SHA256SUMS.sig against the pinned key, then writes generated/appimage.json (the AppImage's URL and SHA-256 from SHA256SUMS) and the metainfo with the version
dev.magicbean.Longshot.yml The manifest: the AppImage unpacked with --appimage-extract (no FUSE), not stripped. Permissions: network, X11 (Tk) and Wayland, PulseAudio, all devices (GPU, controllers), home, /mnt, /media, /run/media
longshot-flatpak.sh /app/bin/longshot: starts the AppImage's AppRun (below)
.forgejo/workflows/build.yml A pull request builds only. main, a manual run (force, tag) and an hourly check publish, and only a release that isn't already the published one

The builder's path, inside and outside the sandbox

The builder writes builder=<its path> into each game folder. That path gets started by two things:

  • the folder's launcher, outside the sandbox;
  • the game's crash window, inside it.

/app exists only inside the sandbox. So the start script writes ~/.var/app/dev.magicbean.Longshot/data/longshot-builder at every start: the same path on both sides. That script runs /app/bin/longshot inside the sandbox and flatpak run dev.magicbean.Longshot outside, and the builder is given it as its own path (APPIMAGE, which AppRun turns into LONGSHOT_BUILDER_EXE).

CI

  • Runner: runs-on: flatpak (bubblewrap: SYS_ADMIN, seccomp unconfined). This repository has its own runner, longshot-flatpak-… (homelab-gitops 46-longshot-flatpak-runner.yaml, registered with this repository's token), so the privileged job stays with one repository per runner, as Jellium's does.
  • Job container: flat-manager's own image at the commit Bean-Ops runs (c72715c8…). It is Ubuntu 24.04 and already has flatpak, ostree and the Rust flat-manager-client, so the client matches the server. That image has no Node, so the checkout is a plain git fetch with the job's token.
  • Steps:
    1. flatpak-builder --default-branch=stable --repo=repo --subject="Longshot <tag>".
    2. flat-manager-client create, then push --commit --publish --wait, with the FLAT_MANAGER_TOKEN secret (set).
  • A run publishes nothing when the published commit's subject is already Longshot <tag>.

Checked

  • CI on this PR: runs 1 (05489f1) and 2 (8ff9327) both passed on the new runner, 2 to 3 minutes each. A pull request builds and doesn't publish. I couldn't read the job logs through the API (this Forgejo has no job-log endpoint), so the build steps' output itself is not checked here.
  • scripts/pick_release.py against the live release list: it picked v3.0.0-rc.1, the signature checked with the pinned key, and the SHA-256 matches the downloaded AppImage.
  • The AppImage unpacks without FUSE: AppRun, usr/, longshot.png (512×512).
  • In org.freedesktop.Platform//26.08, through flatpak run --command=sh, the AppImage's own Python works: Tk 9.0 opens a window, OpenSSL 3.5, and make_game.py --help runs.
  • flatpak remote-info prints Subject:, which the skip step reads (checked on the gmatte remote).
  • /code-review (high): see the comments.

Not checked yet

  • The publish: it happens on merge (or a manual run).
  • In use: the game built and played from the installed Flatpak, a crash window from inside it, and the launcher from outside.

Known limits

  • The builder's "add to the applications menu" writes into the sandbox's data folder, which the desktop doesn't read. The Flatpak's own "Longshot Builder" entry is in the menu.
  • When Bean-Ops moves flat-manager to a new commit, move the workflow's image: with it.

🤖 Generated with Claude Code

https://claude.ai/code/session_015KgSKoUqUvce5UXG89NBgi

## What `dev.magicbean.Longshot` is the Longshot Builder as a Flatpak. CI publishes it to Bean-Ops' flat-manager (`stable`). It wraps Longshot's signed release AppImage, unpacked into `/app` on org.freedesktop.Platform **26.08** (24.08 reached end of life in August). The README has the details. | File | What | |---|---| | `config.env` | **Every address**: Longshot's release list, the channel (`rc` until the first stable), flat-manager's URL and repo, Flathub. Nothing is hard-coded elsewhere | | `release_keys.json` | Longshot's release key, pinned (copied from Longshot's `scripts/release_keys.json`) | | `scripts/pick_release.py` | The channel's newest release, by Longshot's own channel rules. It checks `SHA256SUMS.sig` against the pinned key, then writes `generated/appimage.json` (the AppImage's URL and SHA-256 from `SHA256SUMS`) and the metainfo with the version | | `dev.magicbean.Longshot.yml` | The manifest: the AppImage unpacked with `--appimage-extract` (no FUSE), not stripped. Permissions: network, X11 (Tk) and Wayland, PulseAudio, all devices (GPU, controllers), home, `/mnt`, `/media`, `/run/media` | | `longshot-flatpak.sh` | `/app/bin/longshot`: starts the AppImage's `AppRun` (below) | | `.forgejo/workflows/build.yml` | A pull request builds only. `main`, a manual run (`force`, `tag`) and an hourly check publish, and only a release that isn't already the published one | ### The builder's path, inside and outside the sandbox The builder writes `builder=<its path>` into each game folder. That path gets started by two things: - the folder's launcher, outside the sandbox; - the game's crash window, inside it. `/app` exists only inside the sandbox. So the start script writes `~/.var/app/dev.magicbean.Longshot/data/longshot-builder` at every start: the same path on both sides. That script runs `/app/bin/longshot` inside the sandbox and `flatpak run dev.magicbean.Longshot` outside, and the builder is given it as its own path (`APPIMAGE`, which `AppRun` turns into `LONGSHOT_BUILDER_EXE`). ### CI - Runner: `runs-on: flatpak` (bubblewrap: SYS_ADMIN, seccomp unconfined). This repository has its own runner, `longshot-flatpak-…` (homelab-gitops `46-longshot-flatpak-runner.yaml`, registered with this repository's token), so the privileged job stays with one repository per runner, as Jellium's does. - Job container: flat-manager's own image at the commit Bean-Ops runs (`c72715c8…`). It is Ubuntu 24.04 and already has flatpak, ostree and the Rust `flat-manager-client`, so the client matches the server. That image has no Node, so the checkout is a plain `git fetch` with the job's token. - Steps: 1. `flatpak-builder --default-branch=stable --repo=repo --subject="Longshot <tag>"`. 2. `flat-manager-client create`, then `push --commit --publish --wait`, with the `FLAT_MANAGER_TOKEN` secret (set). - A run publishes nothing when the published commit's subject is already `Longshot <tag>`. ## Checked - CI on this PR: runs 1 (05489f1) and 2 (8ff9327) both passed on the new runner, 2 to 3 minutes each. A pull request builds and doesn't publish. I couldn't read the job logs through the API (this Forgejo has no job-log endpoint), so the build steps' output itself is not checked here. - `scripts/pick_release.py` against the live release list: it picked `v3.0.0-rc.1`, the signature checked with the pinned key, and the SHA-256 matches the downloaded AppImage. - The AppImage unpacks without FUSE: `AppRun`, `usr/`, `longshot.png` (512×512). - In org.freedesktop.Platform//26.08, through `flatpak run --command=sh`, the AppImage's own Python works: Tk 9.0 opens a window, OpenSSL 3.5, and `make_game.py --help` runs. - `flatpak remote-info` prints `Subject:`, which the skip step reads (checked on the gmatte remote). - `/code-review` (high): see the comments. ## Not checked yet - **The publish:** it happens on merge (or a manual run). - **In use:** the game built and played from the installed Flatpak, a crash window from inside it, and the launcher from outside. ## Known limits - The builder's "add to the applications menu" writes into the sandbox's data folder, which the desktop doesn't read. The Flatpak's own "Longshot Builder" entry is in the menu. - When Bean-Ops moves flat-manager to a new commit, move the workflow's `image:` with it. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_015KgSKoUqUvce5UXG89NBgi
feat: the Longshot Builder as a Flatpak, published to flat-manager
All checks were successful
Longshot Flatpak / flatpak (pull_request) Successful in 2m52s
05489f1d63
dev.magicbean.Longshot wraps the release AppImage (unpacked into /app)
on org.freedesktop.Platform 26.08. scripts/pick_release.py picks the
channel's newest release, checks SHA256SUMS.sig against the pinned key
and writes the AppImage source. CI builds on pull requests, and on main,
by hand or hourly publishes a release that isn't published yet to
Bean-Ops' flat-manager (FLAT_MANAGER_TOKEN), in flat-manager's own image
so the client matches the server. Every address is in config.env.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KgSKoUqUvce5UXG89NBgi
fix: the review's findings on the Flatpak
All checks were successful
Longshot Flatpak / flatpak (pull_request) Successful in 2m25s
8ff9327dd3
- The published check compares "Longshot <tag> (packaging <commit>)", so
  a packaging change publishes again; a remote that can't be added
  (the first run) means build, not a failed job.
- A push that fails half way purges its flat-manager build.
- The hourly check installs only what it needs; flatpak-builder only
  when building.
- The builder's shim knows its own sandbox from /.flatpak-info's name,
  goes through flatpak-spawn --host from another app's, and is written
  through a per-process temp file.
- The Longshot Launcher's tools are reused (LONGSHOT_LAUNCHER_HOME).
- README: rolling back, the APPIMAGE wording, the summary delay.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KgSKoUqUvce5UXG89NBgi
Author
Collaborator

Updated to 8ff9327 after a /code-review (high), which found 10 things.

Fixed:

  • The publish check now includes this repo's commit (Longshot <tag> (packaging <sha>)), so a packaging change publishes again.
  • A remote that can't be added yet (the first run) means "build", not a failed job.
  • A failed push purges its flat-manager build.
  • The hourly check installs only git, openssl and python3; flatpak-builder is installed in Build only.
  • The builder shim:
    • recognises its own sandbox by the name= in /.flatpak-info;
    • goes through flatpak-spawn --host when started from another Flatpak (Steam, Heroic, Lutris);
    • is written through a per-process temp file.
  • The Longshot Launcher's tools are reused (LONGSHOT_LAUNCHER_HOME) instead of being downloaded a second time.

Documented in the README instead of changed:

  • Rolling back means deleting the bad release, as Longshot's docs/releases.md says. An older tag published by hand lasts until the next hourly run.
  • APPIMAGE stays set, because AppRun needs it to pass the builder its own path. So a report built from the builder's own facts says "the AppImage". That's a small follow-up for Longshot: tell the two apart by FLATPAK_ID.
  • A run right after a publish may publish the same build again before flat-manager's summary updates. That's harmless.

Blocked: no runner has picked up the job. Run 1 has been waiting since the PR opened. The flatpak runner (homelab-gitops forgejo-runner/45-flatpak-runner.yaml) is registered with forgejo-jellium-runner-secret. That is a repository-level token for gmatte/jellium-flatpak-builder, so this repository can't use the runner. It needs registering at the MagicBean-Mirror org level (or the instance level), for example with a second runner or a new registration token. Once that's done, this PR's run will do the first full build. I can't do that registration with claude's access.

🤖 Generated with Claude Code

Updated to 8ff9327 after a `/code-review` (high), which found 10 things. **Fixed:** - The publish check now includes this repo's commit (`Longshot <tag> (packaging <sha>)`), so a packaging change publishes again. - A remote that can't be added yet (the first run) means "build", not a failed job. - A failed push purges its flat-manager build. - The hourly check installs only git, openssl and python3; flatpak-builder is installed in Build only. - The builder shim: - recognises its own sandbox by the `name=` in `/.flatpak-info`; - goes through `flatpak-spawn --host` when started from another Flatpak (Steam, Heroic, Lutris); - is written through a per-process temp file. - The Longshot Launcher's tools are reused (`LONGSHOT_LAUNCHER_HOME`) instead of being downloaded a second time. **Documented in the README instead of changed:** - Rolling back means deleting the bad release, as Longshot's `docs/releases.md` says. An older `tag` published by hand lasts until the next hourly run. - `APPIMAGE` stays set, because `AppRun` needs it to pass the builder its own path. So a report built from the builder's own facts says "the AppImage". That's a small follow-up for Longshot: tell the two apart by `FLATPAK_ID`. - A run right after a publish may publish the same build again before flat-manager's summary updates. That's harmless. **Blocked: no runner has picked up the job.** Run 1 has been `waiting` since the PR opened. The `flatpak` runner (homelab-gitops `forgejo-runner/45-flatpak-runner.yaml`) is registered with `forgejo-jellium-runner-secret`. That is a repository-level token for gmatte/jellium-flatpak-builder, so this repository can't use the runner. It needs registering at the MagicBean-Mirror org level (or the instance level), for example with a second runner or a new registration token. Once that's done, this PR's run will do the first full build. I can't do that registration with `claude`'s access. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
claude merged commit a9eba3d309 into main 2026-11-13 14:11:02 -05:00
claude deleted branch feat/flatpak 2026-11-13 14:11:02 -05:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBean-Mirror/longshot-flatpak-builder!1
No description provided.