Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down
38 changes: 37 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 }}
55 changes: 54 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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),
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
5 changes: 4 additions & 1 deletion docs/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand Down
62 changes: 62 additions & 0 deletions packaging/flatpak/repo.sh
Original file line number Diff line number Diff line change
@@ -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" <<EOF
[Flatpak Repo]
Title=Core Rules
Url=$url/flatpak/
Homepage=$url/
Comment=The Core Rules app for AD&D Core Rules 2.0
Icon=$url/icons/corerules.png
GPGKey=$gpgkey
EOF

cat > "$site/$app.flatpakref" <<EOF
[Flatpak Ref]
Name=$app
Branch=$branch
Title=Core Rules
Url=$url/flatpak/
SuggestRemoteName=corerules
Homepage=$url/
Icon=$url/icons/corerules.png
RuntimeRepo=https://dl.flathub.org/repo/flathub.flatpakrepo
IsRuntime=false
GPGKey=$gpgkey
EOF

commit=$(ostree rev-parse --repo="$repo" "$ref")
# Leftovers of the tools that the website must not serve.
rm -rf "$repo/tmp" "$repo/.lock"
echo "Published $ref at $commit in $repo"
13 changes: 8 additions & 5 deletions packaging/release-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,11 +51,14 @@ content; you need your own copy of Core Rules.
| Any distribution (glibc 2.43+) | `CoreRules-1.0.0-x86_64.AppImage` | `chmod +x CoreRules-1.0.0-x86_64.AppImage` and run it |

The Flatpak needs the GNOME 51 runtime from Flathub, which `flatpak install`
offers to fetch. The AppImage bundles the GTK, libadwaita and other
libraries of GNOME 51 and runs on Fedora 44, Ubuntu 26.04 and newer. The
pacman package needs an up-to-date system (`sudo pacman -Syu`), and
`PKGBUILD` builds it from source with `makepkg -si`. `SHA256SUMS` lists the
checksums of every file.
offers to fetch. It also installs from the project's own Flatpak repository,
which brings every new version through `flatpak update`, GNOME Software and
Discover:
`flatpak install --user https://brahm.github.io/corerules/io.github.brahm.CoreRules.flatpakref`.
The AppImage bundles the GTK, libadwaita and other libraries of GNOME 51
and runs on Fedora 44, Ubuntu 26.04 and newer. The pacman package needs an
up-to-date system (`sudo pacman -Syu`), and `PKGBUILD` builds it from
source with `makepkg -si`. `SHA256SUMS` lists the checksums of every file.

The [Community Add-ons Collection](https://github.com/brahm/corerules/blob/main/addons/README.md),
672 community add-ons in one self-installing AppImage, has its own
Expand Down
12 changes: 8 additions & 4 deletions site/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -178,8 +178,8 @@ <h2>Download Core Rules</h2>
<a class="file" href="https://github.com/brahm/corerules/releases/download/v1.0.0/corerules-1.0.0-1-x86_64.pkg.tar.zst">corerules-1.0.0-1-x86_64.pkg.tar.zst</a>
<code>sudo pacman -U ./corerules-1.0.0-1-x86_64.pkg.tar.zst</code></li>
<li><span class="system">Bazzite, or any distribution with Flatpak</span><span class="kind">Flatpak</span>
<a class="file" href="https://github.com/brahm/corerules/releases/download/v1.0.0/CoreRules-1.0.0.flatpak">CoreRules-1.0.0.flatpak</a>
<code>flatpak install --user CoreRules-1.0.0.flatpak</code></li>
<a class="file" href="io.github.brahm.CoreRules.flatpakref">io.github.brahm.CoreRules.flatpakref</a>
<code>flatpak install --user https://brahm.github.io/corerules/io.github.brahm.CoreRules.flatpakref</code></li>
<li><span class="system">Any distribution (glibc 2.43+)</span><span class="kind">AppImage</span>
<a class="file" href="https://github.com/brahm/corerules/releases/download/v1.0.0/CoreRules-1.0.0-x86_64.AppImage">CoreRules-1.0.0-x86_64.AppImage</a>
<code>chmod +x CoreRules-1.0.0-x86_64.AppImage</code></li>
Expand All @@ -188,8 +188,12 @@ <h2>Download Core Rules</h2>
<code>chmod +x CoreRules-Community-Addons-x86_64.AppImage</code></li>
</ul>
<p class="tested"><span>Tested by players on</span> Fedora 45 beta · Ubuntu 26.10 · Bazzite · Arch Linux · CachyOS</p>
<p class="small">The Flatpak needs the GNOME 51 runtime from Flathub, which <code>flatpak install</code>
offers to fetch. The AppImage bundles GTK, libadwaita and the other GNOME 51 libraries. Update
<p class="small">The Flatpak comes from this site's own Flatpak repository, signed by the project,
so <code>flatpak update</code>, GNOME Software and Discover bring every new version; it needs the
GNOME 51 runtime from Flathub, which <code>flatpak install</code> offers to fetch. If you installed
the <a href="https://github.com/brahm/corerules/releases/download/v1.0.0/CoreRules-1.0.0.flatpak">CoreRules-1.0.0.flatpak</a>
file, which gets no updates, run <code>flatpak uninstall --user io.github.brahm.CoreRules</code> and
install from the repository; your files stay. The AppImage bundles GTK, libadwaita and the other GNOME 51 libraries. Update
Arch first (<code>sudo pacman -Syu</code>), or build the package from source with its
<a href="https://github.com/brahm/corerules/releases/download/v1.0.0/PKGBUILD">PKGBUILD</a>. The checksums of every file are in
<a href="https://github.com/brahm/corerules/releases/download/v1.0.0/SHA256SUMS">SHA256SUMS</a>.</p>
Expand Down
Loading