diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index f943e05..76c802c 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -7,11 +7,15 @@ on: - "site/**" - "docs/screenshots/**" - "addons/screenshots/**" + - "packaging/flatpak/repo.sh" - ".github/workflows/pages.yml" pull_request: paths: - "site/**" + - "packaging/flatpak/repo.sh" - ".github/workflows/pages.yml" + # The Packages workflow runs this after each final release, so the + # Flatpak repository gets the new version. workflow_dispatch: permissions: @@ -27,6 +31,40 @@ jobs: steps: - uses: actions/checkout@v4 - run: python3 site/build.py _site + - run: sudo apt-get update && sudo apt-get install -y flatpak ostree + # The Flatpak repository is signed with the key in the + # FLATPAK_GPG_PRIVATE_KEY secret. A pull request without the secret + # signs with a throwaway key, to test the rest; the site is never + # published without it. + - name: Signing key + env: + SIGNING_KEY: ${{ secrets.FLATPAK_GPG_PRIVATE_KEY }} + run: | + export GNUPGHOME="$RUNNER_TEMP/gnupg" + mkdir -m 700 "$GNUPGHOME" + echo "GNUPGHOME=$GNUPGHOME" >> "$GITHUB_ENV" + if [ -n "$SIGNING_KEY" ]; then + printf '%s\n' "$SIGNING_KEY" | gpg --batch --import + elif [ "$GITHUB_EVENT_NAME" = pull_request ]; then + gpg --batch --passphrase '' --quick-gen-key 'Core Rules test key' rsa4096 sign never + else + echo "::error::The FLATPAK_GPG_PRIVATE_KEY secret is missing" + exit 1 + fi + echo "KEY_ID=$(gpg --list-secret-keys --with-colons | awk -F: '/^fpr/ {print $10; exit}')" >> "$GITHUB_ENV" + # The repository holds the .flatpak of the latest release. + - name: Flatpak repository + env: + GH_TOKEN: ${{ github.token }} + run: | + gh release download --repo "$GITHUB_REPOSITORY" --pattern 'CoreRules-[0-9]*.flatpak' --dir "$RUNNER_TEMP/release" + packaging/flatpak/repo.sh "$RUNNER_TEMP"/release/CoreRules-*.flatpak _site https://brahm.github.io/corerules "$KEY_ID" + - name: Check the repository + run: | + gpg --export "$KEY_ID" > "$RUNNER_TEMP/key.gpg" + flatpak remote-add --user --gpg-import="$RUNNER_TEMP/key.gpg" check "file://$PWD/_site/flatpak" + flatpak remote-ls --user check --columns=application,branch,commit | tee "$RUNNER_TEMP/apps" + grep -q '^io.github.brahm.CoreRules' "$RUNNER_TEMP/apps" - uses: actions/upload-pages-artifact@v3 with: path: _site diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 30f04fb..ca1c645 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -126,12 +126,33 @@ jobs: options: --privileged steps: - uses: actions/checkout@v4 + # With the FLATPAK_GPG_PRIVATE_KEY secret, the build is signed and the + # bundle names the website's Flatpak repository and its key, so + # installing the .flatpak also brings the updates published there. + - name: Signing key + env: + SIGNING_KEY: ${{ secrets.FLATPAK_GPG_PRIVATE_KEY }} + run: | + if [ -n "$SIGNING_KEY" ]; then + command -v gpg >/dev/null || dnf install -y gnupg2 + printf '%s\n' "$SIGNING_KEY" | gpg --batch --import + echo "KEY_ID=$(gpg --list-secret-keys --with-colons | awk -F: '/^fpr/ {print $10; exit}')" >> "$GITHUB_ENV" + fi - uses: flatpak/flatpak-github-actions/flatpak-builder@v6 with: - bundle: CoreRules-${{ needs.version.outputs.version }}.flatpak manifest-path: packaging/flatpak/io.github.brahm.CoreRules.yml cache-key: flatpak-builder-${{ github.sha }} + gpg-sign: ${{ env.KEY_ID }} + build-bundle: false upload-artifact: false + - name: Bundle + run: | + set -- --runtime-repo=https://dl.flathub.org/repo/flathub.flatpakrepo + if [ -n "${KEY_ID:-}" ]; then + gpg --export "$KEY_ID" > "$RUNNER_TEMP/key.gpg" + set -- "$@" --repo-url=https://brahm.github.io/corerules/flatpak/ --gpg-keys="$RUNNER_TEMP/key.gpg" + fi + flatpak build-bundle "$@" repo CoreRules-${{ needs.version.outputs.version }}.flatpak io.github.brahm.CoreRules master - uses: actions/upload-artifact@v4 with: name: flatpak @@ -281,3 +302,18 @@ jobs: # the addons release never is. make_latest: ${{ !startsWith(needs.version.outputs.version, '0.') && !contains(needs.version.outputs.version, '-') }} files: dist/* + + # A final release becomes the version in the website's Flatpak + # repository: the Landing page workflow republishes the site from main. + # Releases made with this workflow's token start no workflows by + # themselves, so it is started by hand here. + website: + needs: [version, release] + if: ${{ !startsWith(needs.version.outputs.version, '0.') && !contains(needs.version.outputs.version, '-') }} + runs-on: ubuntu-24.04 + permissions: + actions: write + steps: + - run: gh workflow run pages.yml --repo "$GITHUB_REPOSITORY" --ref main + env: + GH_TOKEN: ${{ github.token }} diff --git a/README.md b/README.md index dba9a11..2e59ae1 100644 --- a/README.md +++ b/README.md @@ -462,11 +462,13 @@ the latest release: | Fedora 44 or newer | [`corerules-1.0.0-1.fc44.x86_64.rpm`](https://github.com/brahm/corerules/releases/download/v1.0.0/corerules-1.0.0-1.fc44.x86_64.rpm) | `sudo dnf install ./corerules-1.0.0-1.fc44.x86_64.rpm` | | Ubuntu 26.04 or newer | [`corerules_1.0.0_amd64.deb`](https://github.com/brahm/corerules/releases/download/v1.0.0/corerules_1.0.0_amd64.deb) | `sudo apt install ./corerules_1.0.0_amd64.deb` | | Arch Linux, CachyOS, Omarchy | [`corerules-1.0.0-1-x86_64.pkg.tar.zst`](https://github.com/brahm/corerules/releases/download/v1.0.0/corerules-1.0.0-1-x86_64.pkg.tar.zst) | `sudo pacman -U ./corerules-1.0.0-1-x86_64.pkg.tar.zst` | -| Any distribution with Flatpak, such as Bazzite | [`CoreRules-1.0.0.flatpak`](https://github.com/brahm/corerules/releases/download/v1.0.0/CoreRules-1.0.0.flatpak) | `flatpak install --user CoreRules-1.0.0.flatpak` | +| Any distribution with Flatpak, such as Bazzite | [`io.github.brahm.CoreRules.flatpakref`](https://brahm.github.io/corerules/io.github.brahm.CoreRules.flatpakref), from the [Flatpak repository](#the-flatpak-repository) | `flatpak install --user https://brahm.github.io/corerules/io.github.brahm.CoreRules.flatpakref` | | Any distribution (glibc 2.43+) | [`CoreRules-1.0.0-x86_64.AppImage`](https://github.com/brahm/corerules/releases/download/v1.0.0/CoreRules-1.0.0-x86_64.AppImage) | `chmod +x CoreRules-1.0.0-x86_64.AppImage`, then run it | | Community add-ons (installer) | [`CoreRules-Community-Addons-x86_64.AppImage`](https://github.com/brahm/corerules/releases/download/addons/CoreRules-Community-Addons-x86_64.AppImage) | `chmod +x CoreRules-Community-Addons-x86_64.AppImage`, then run it | The release also has the +[`CoreRules-1.0.0.flatpak`](https://github.com/brahm/corerules/releases/download/v1.0.0/CoreRules-1.0.0.flatpak) +file, the [`PKGBUILD`](https://github.com/brahm/corerules/releases/download/v1.0.0/PKGBUILD) of the pacman package and [`SHA256SUMS`](https://github.com/brahm/corerules/releases/download/v1.0.0/SHA256SUMS), @@ -496,6 +498,35 @@ and EndeavourOS; update the system (`sudo pacman -Syu`) before installing it. Each release also has its `PKGBUILD`, which builds the package from the release's source with `makepkg -si`. +### The Flatpak repository + +The project has its own Flatpak repository, at +`https://brahm.github.io/corerules/flatpak/` next to the +[website](https://brahm.github.io/corerules/), signed with the project's +key. It always holds the latest release: each new version reaches it when +it is released, and `flatpak update`, GNOME Software and Discover bring it. +The `.flatpakref` above adds the repository as the `corerules` remote, and +Flathub for the GNOME runtime, and installs the app; on a desktop with GNOME +Software or Discover, such as Bazzite, opening the downloaded file does the +same. To add the repository yourself and install from it: + +```sh +flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo +flatpak remote-add --user --if-not-exists corerules https://brahm.github.io/corerules/corerules.flatpakrepo +flatpak install --user corerules io.github.brahm.CoreRules +``` + +The release's `.flatpak` file installs the app without the repository. +From the release after 1.0.0 on, it also adds the repository, so that +installation updates the same way. The `CoreRules-1.0.0.flatpak` file gets no updates; if you +installed it, move to the repository once (your characters, settings and +Core Rules installation stay): + +```sh +flatpak uninstall --user io.github.brahm.CoreRules +flatpak install --user https://brahm.github.io/corerules/io.github.brahm.CoreRules.flatpakref +``` + ## Getting the rules data The app needs the rules data of a Core Rules CD you own (see @@ -672,6 +703,28 @@ a pre-release (a release candidate for `-rc` tags); the `.deb` and `.rpm` write the suffix with a tilde (`1.0.0~rc1`) and the pacman package drops the hyphen (`1.0.0rc1`), so that 1.0.0 sorts after it. +The website's Flatpak repository is built by the Landing page workflow +(`.github/workflows/pages.yml`) each time it publishes the site: +`packaging/flatpak/repo.sh` imports the `.flatpak` of the latest release +into a new repository, signs it and writes `corerules.flatpakrepo` and +`io.github.brahm.CoreRules.flatpakref` next to the page. After a final +release, the Packages workflow starts the Landing page workflow, so the +repository gets the new version without anyone touching it; republishing +the same release changes nothing for installed apps. Both workflows sign +with the key in the `FLATPAK_GPG_PRIVATE_KEY` secret, and the Packages +workflow also writes the repository's address and key into the `.flatpak`. +Without the secret, the `.flatpak` is unsigned and the site is not +published (a pull request signs with a throwaway key to test the rest). +The key has no passphrase and is made once: + +```sh +gpg --batch --passphrase '' --quick-gen-key 'Core Rules Flatpak' rsa4096 sign never +gpg --armor --export-secret-keys 'Core Rules Flatpak' # the secret's value +``` + +Keep a copy of it offline: with a new key, every installation has to add +the repository again. + ### Running from a source checkout Without a folder, the tools use the data package, then a Core Rules diff --git a/docs/decisions.md b/docs/decisions.md index b00b4e8..7c98a4e 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -109,3 +109,4 @@ Reported during testing and kept, because the original does the same: | P13 | 2026-10-24 | 1.0.0 is released as the final version, the repository's latest release: the code of 1.0.0-rc2 with the new About window. The release candidate was confirmed stable by its users on Fedora 45 beta, Ubuntu 26.10, Bazzite, Arch Linux and CachyOS; the release workflow adds Ubuntu 26.10 and Fedora 45 to its test systems. | Decided by Wagner Brahm, 1.0.0 | | P14 | 2026-10-24 | The add-ons AppImage is also published as the file itself on GitHub Packages, in its Maven registry (`io.github.brahm:corerules-community-addons`), since GitHub Packages has no registry for plain files; the OCI artifact on ghcr.io and the addons release stay, the release being the direct download link. | Decided by Wagner Brahm, 1.0.0 | | P15 | 2026-10-24 | Publishing on Flathub is dropped from the plan, after a review of Flathub's current requirements. The Flatpak is still built, tested and attached to every release. Windows and macOS come right after 1.0, and the backend stays free of GTK until then. | Decided by Wagner Brahm, [Roadmap](roadmap.md) | +| P16 | 2026-10-25 | The Flatpak is also distributed from the project's own signed Flatpak repository, published with the landing page on GitHub Pages (`https://brahm.github.io/corerules/flatpak/`), instead of Flathub. It holds the latest final release and is rebuilt from that release's `.flatpak` after every final release; the `.flatpak` files name the repository, so they update from it too. The signing key is the `FLATPAK_GPG_PRIVATE_KEY` secret. | Decided by Wagner Brahm, [README](../README.md#the-flatpak-repository) | diff --git a/docs/roadmap.md b/docs/roadmap.md index 4cea099..13f250f 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -18,7 +18,9 @@ plus #80 and #81 for the items that needed a decision). It ships as a `.deb` (Ubuntu 26.04), an `.rpm` (Fedora 44), a pacman package (Arch Linux, CachyOS, Omarchy), a Flatpak and an AppImage (both on GNOME 51), and the Community Add-ons Collection as its own AppImage, version 1.0.0. The -[website](https://brahm.github.io/corerules/) links every file. +[website](https://brahm.github.io/corerules/) links every file and serves +the project's own Flatpak repository, which gets each final release +(decision P16). The next step is Windows and macOS (step 2). Publishing on Flathub was dropped from the plan (decision P15). No issue is open on GitHub. @@ -51,6 +53,7 @@ taken out of scope. | Real-user fixes | 1.0.0-rc2: saving with the mounted CD opened | Done (PR #85) | | 1.0 | Release candidate confirmed stable by its users, 1.0.0 released with the new About window and the website | Done | | Flathub | Publication on Flathub | Dropped (P15) | +| Flatpak repository | The project's own signed Flatpak repository on the website, updated after each release | Done (P16) | ### Releases diff --git a/packaging/flatpak/repo.sh b/packaging/flatpak/repo.sh new file mode 100755 index 0000000..a4dec49 --- /dev/null +++ b/packaging/flatpak/repo.sh @@ -0,0 +1,62 @@ +#!/bin/sh +# Turns a release's .flatpak into the website's Flatpak repository, so the +# app can be installed and updated with flatpak. It writes, inside the built +# website: +# flatpak/ the signed repository (OSTree) +# corerules.flatpakrepo adds the repository to flatpak +# io.github.brahm.CoreRules.flatpakref installs the app from it, with +# the GNOME runtime from Flathub +# The repository is made anew from the bundle each time, so it holds only +# the latest release and keeps no state between publications. +# Usage: packaging/flatpak/repo.sh BUNDLE SITE URL KEY +# BUNDLE the .flatpak of the latest release +# SITE the built website (python3 site/build.py SITE) +# URL where SITE is served, such as https://brahm.github.io/corerules +# KEY fingerprint of the signing key in GnuPG's keyring ($GNUPGHOME) +set -eu +bundle=$1 +site=$2 +url=${3%/} +key=$4 +app=io.github.brahm.CoreRules +repo=$site/flatpak + +rm -rf "$repo" +ostree init --mode=archive-z2 --repo="$repo" +flatpak build-import-bundle --gpg-sign="$key" "$repo" "$bundle" +flatpak build-update-repo --gpg-sign="$key" --generate-static-deltas \ + --title="Core Rules" "$repo" + +ref=$(ostree refs --repo="$repo" | grep "^app/$app/" | head -n 1) +[ -n "$ref" ] || { echo "No app/$app ref in $bundle" >&2; exit 1; } +branch=${ref##*/} +gpgkey=$(gpg --export "$key" | base64 -w 0) + +cat > "$site/corerules.flatpakrepo" < "$site/$app.flatpakref" <Download Core Rules corerules-1.0.0-1-x86_64.pkg.tar.zst sudo pacman -U ./corerules-1.0.0-1-x86_64.pkg.tar.zst
  • Bazzite, or any distribution with FlatpakFlatpak - CoreRules-1.0.0.flatpak - flatpak install --user CoreRules-1.0.0.flatpak
  • + io.github.brahm.CoreRules.flatpakref + flatpak install --user https://brahm.github.io/corerules/io.github.brahm.CoreRules.flatpakref
  • Any distribution (glibc 2.43+)AppImage CoreRules-1.0.0-x86_64.AppImage chmod +x CoreRules-1.0.0-x86_64.AppImage
  • @@ -188,8 +188,12 @@

    Download Core Rules

    chmod +x CoreRules-Community-Addons-x86_64.AppImage

    Tested by players on Fedora 45 beta · Ubuntu 26.10 · Bazzite · Arch Linux · CachyOS

    -

    The Flatpak needs the GNOME 51 runtime from Flathub, which flatpak install - offers to fetch. The AppImage bundles GTK, libadwaita and the other GNOME 51 libraries. Update +

    The Flatpak comes from this site's own Flatpak repository, signed by the project, + so flatpak update, GNOME Software and Discover bring every new version; it needs the + GNOME 51 runtime from Flathub, which flatpak install offers to fetch. If you installed + the CoreRules-1.0.0.flatpak + file, which gets no updates, run flatpak uninstall --user io.github.brahm.CoreRules and + install from the repository; your files stay. The AppImage bundles GTK, libadwaita and the other GNOME 51 libraries. Update Arch first (sudo pacman -Syu), or build the package from source with its PKGBUILD. The checksums of every file are in SHA256SUMS.