packaging: signed APT repository and Flatpak remote on GitHub Pages

.github/workflows/repos.yml

@@ -0,0 +1,52 @@
+name: Package repositories
+# Publishes the signed APT repository and Flatpak remote to GitHub Pages
+# after every successful release, from that release's .deb and .flatpak.
+on:
+  workflow_run:
+    workflows: [Release]
+    types: [completed]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: false
+jobs:
+  build:
+    if: github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - id: pages
+        uses: actions/configure-pages@v5
+      - run: sudo apt-get update && sudo apt-get install -y apt-utils flatpak ostree
+      - name: Import signing key
+        env:
+          GPG_PRIVATE_KEY: ${{ secrets.GPG_PRIVATE_KEY }}
+        run: |
+          printf '%s\n' "$GPG_PRIVATE_KEY" | gpg --batch --import
+          echo "GPG_KEY_ID=$(gpg --batch --with-colons --list-secret-keys | awk -F: '/^fpr/{print $10; exit}')" >> "$GITHUB_ENV"
+      - name: Download the latest release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release download --repo "$GITHUB_REPOSITORY" --dir assets \
+            --pattern 'gknowledge_*_all.deb' --pattern 'gknowledge-v*.flatpak'
+          ls -l assets
+      - run: |
+          build-aux/repos/build-site.sh assets "$(ls assets/gknowledge-v*.flatpak)" site \
+            "${{ steps.pages.outputs.base_url }}"
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - id: deploy
+        uses: actions/deploy-pages@v4

README.it.md

@@ -25,17 +25,24 @@
 
 ## Installazione
 
-Su Ubuntu 24.04+ e Debian 13+ basta una riga (sulle altre distribuzioni installa in `~/.local`):
+Su Ubuntu 24.04+ e Debian 13+ basta una riga: aggiunge il repository APT firmato di gknowledge, così gli aggiornamenti arrivano con `apt upgrade` (sulle altre distribuzioni installa in `~/.local`):
 
 ```bash
 curl -fsSL https://github.com/openapi/gknowledge/releases/latest/download/install.sh | bash
 ```
 
-Oppure scarica il pacchetto `.deb`:
+Oppure aggiungi tu il repository APT:
 
 ```bash
-wget https://github.com/openapi/gknowledge/releases/latest/download/gknowledge_all.deb
-sudo apt install ./gknowledge_all.deb
+sudo curl -fsSLo /usr/share/keyrings/gknowledge.gpg https://openapi.github.io/gknowledge/gknowledge.gpg
+sudo curl -fsSLo /etc/apt/sources.list.d/gknowledge.sources https://openapi.github.io/gknowledge/gknowledge.sources
+sudo apt update && sudo apt install gknowledge
+```
+
+Su qualsiasi distribuzione, con Flatpak (il runtime GNOME arriva da Flathub):
+
+```bash
+flatpak install --user https://openapi.github.io/gknowledge/io.gknowledge.Gknowledge.flatpakref
 ```
 
 ## Perché gknowledge

README.md

@@ -48,29 +48,36 @@
 
 ## Install
 
-**One line, on Ubuntu 24.04+ and Debian 13+** (falls back to a per-user install on other distributions):
+**One line, on Ubuntu 24.04+ and Debian 13+.** It adds the signed gknowledge APT repository, so updates arrive with `apt upgrade` (other distributions get a per-user install):
 
 ```bash
 curl -fsSL https://github.com/openapi/gknowledge/releases/latest/download/install.sh | bash
 ```
 
-**Or download the package** and install it with apt, which also pulls GTK 4, Libadwaita and PyGObject:
+**Or add the APT repository yourself.** apt also pulls GTK 4, Libadwaita and PyGObject:
 
-[![Download .deb](https://img.shields.io/badge/download-gknowledge__all.deb-E95420?style=for-the-badge&logo=ubuntu&logoColor=white)](https://github.com/openapi/gknowledge/releases/latest/download/gknowledge_all.deb)
+```bash
+sudo curl -fsSLo /usr/share/keyrings/gknowledge.gpg https://openapi.github.io/gknowledge/gknowledge.gpg
+sudo curl -fsSLo /etc/apt/sources.list.d/gknowledge.sources https://openapi.github.io/gknowledge/gknowledge.sources
+sudo apt update && sudo apt install gknowledge
+```
+
+**On any distribution, with Flatpak** (the GNOME runtime comes from Flathub):
 
 ```bash
-wget https://github.com/openapi/gknowledge/releases/latest/download/gknowledge_all.deb
-sudo apt install ./gknowledge_all.deb
+flatpak install --user https://openapi.github.io/gknowledge/io.gknowledge.Gknowledge.flatpakref
 ```
 
-Then open **gknowledge** from the app grid. To remove it: `sudo apt remove gknowledge`.
+Both repositories are described at [openapi.github.io/gknowledge](https://openapi.github.io/gknowledge).
+
+Then open **gknowledge** from the app grid. To remove it: `sudo apt remove gknowledge` (or `flatpak uninstall io.gknowledge.Gknowledge`).
 
 <details>
 <summary>Other distributions, from source, and release builds</summary>
 
 - **Fedora, Arch and others:** install PyGObject, GTK 4 and Libadwaita with your package manager, then run the one-line installer above. It installs into `~/.local` without root.
 - **From source:** `git clone https://github.com/openapi/gknowledge && cd gknowledge && make install`.
-- **All builds:** every version, including a Flatpak bundle when the build succeeds, is on the [Releases page](https://github.com/openapi/gknowledge/releases).
+- **Single files:** every version's `.deb` and Flatpak bundle is on the [Releases page](https://github.com/openapi/gknowledge/releases), e.g. `sudo apt install ./gknowledge_all.deb` after downloading [gknowledge_all.deb](https://github.com/openapi/gknowledge/releases/latest/download/gknowledge_all.deb).
 
 </details>
 

README.zh-CN.md

@@ -25,17 +25,24 @@
 
 ## 安装
 
-Ubuntu 24.04+ / Debian 13+ 一行命令安装（其他发行版会安装到 `~/.local`）：
+Ubuntu 24.04+ / Debian 13+ 一行命令安装，会添加已签名的 gknowledge APT 软件源，之后用 `apt upgrade` 即可更新（其他发行版会安装到 `~/.local`）：
 
 ```bash
 curl -fsSL https://github.com/openapi/gknowledge/releases/latest/download/install.sh | bash
 ```
 
-或者下载 deb 包：
+或者手动添加 APT 软件源：
 
 ```bash
-wget https://github.com/openapi/gknowledge/releases/latest/download/gknowledge_all.deb
-sudo apt install ./gknowledge_all.deb
+sudo curl -fsSLo /usr/share/keyrings/gknowledge.gpg https://openapi.github.io/gknowledge/gknowledge.gpg
+sudo curl -fsSLo /etc/apt/sources.list.d/gknowledge.sources https://openapi.github.io/gknowledge/gknowledge.sources
+sudo apt update && sudo apt install gknowledge
+```
+
+任意发行版，使用 Flatpak（GNOME 运行时自动从 Flathub 安装）：
+
+```bash
+flatpak install --user https://openapi.github.io/gknowledge/io.gknowledge.Gknowledge.flatpakref
 ```
 
 ## 为什么选择 gknowledge

ROADMAP.md

@@ -49,8 +49,8 @@ Channels we control, in priority order:
 | # | Channel | Why | Status |
 |---|---|---|---|
 | 1 | **`.deb` on GitHub Releases** | One download for Ubuntu and Debian; built in CI | Script and CI job added |
-| 2 | **Own APT repository** (GitHub Pages) | `apt install` without Launchpad or any store | Planned v0.2 |
-| 3 | **Self-hosted Flatpak remote** (GitHub Pages) | Same sandboxed build as Flathub, no review gate | Planned v0.2 |
+| 2 | **Own APT repository** (GitHub Pages) | `apt install` without Launchpad or any store | Signed repo built in CI after each release; `install.sh` adds it |
+| 3 | **Self-hosted Flatpak remote** (GitHub Pages) | Same sandboxed build as Flathub, no review gate | Signed remote and `.flatpakref` built in CI after each release |
 | 4 | **Snap Store** | Ubuntu Software is Snap-first; separate policy from Flathub | Draft `snapcraft.yaml`, untested |
 | 5 | **Launchpad PPA** | Trusted `add-apt-repository` flow for Ubuntu users | Needs a Launchpad account |
 | 6 | **AUR** | Arch users package it themselves anyway | `PKGBUILD` ready |

build-aux/repos/build-site.sh

@@ -0,0 +1,104 @@
+#!/bin/sh
+# Build the static package repositories served from GitHub Pages:
+# an APT repository and a Flatpak remote, both signed with one GPG key.
+#
+# Usage: build-aux/repos/build-site.sh DEB_DIR FLATPAK_BUNDLE OUT_DIR BASE_URL
+#
+#   DEB_DIR         directory with the gknowledge_*_all.deb files to publish
+#   FLATPAK_BUNDLE  gknowledge-vX.Y.Z.flatpak from the release
+#   OUT_DIR         where the site is written (emptied first)
+#   BASE_URL        public URL of the site, e.g. https://openapi.github.io/gknowledge
+#
+# The signing key must already be in the GnuPG keyring; GPG_KEY_ID selects it.
+# Needs: apt-utils (apt-ftparchive), gnupg, flatpak, ostree.
+set -eu
+
+DEB_DIR=$1
+BUNDLE=$2
+OUT=$3
+BASE_URL=${4%/}
+APP_ID=io.gknowledge.Gknowledge
+: "${GPG_KEY_ID:?set GPG_KEY_ID to the signing key}"
+ROOT=$(cd "$(dirname "$0")/../.." && pwd)
+
+rm -rf "$OUT"
+mkdir -p "$OUT"
+
+# Public key, armored for Flatpak and binary for apt's Signed-By.
+gpg --batch --export "$GPG_KEY_ID" > "$OUT/gknowledge.gpg"
+gpg --batch --armor --export "$GPG_KEY_ID" > "$OUT/gknowledge.asc"
+
+# --- APT --------------------------------------------------------------------
+# Architecture "all" packages are indexed for every common architecture so apt
+# finds them without warnings on amd64 and arm64.
+APT="$OUT/apt"
+mkdir -p "$APT/pool/main"
+cp "$DEB_DIR"/gknowledge_*_all.deb "$APT/pool/main/"
+for arch in all amd64 arm64; do
+  d="$APT/dists/stable/main/binary-$arch"
+  mkdir -p "$d"
+  (cd "$APT" && apt-ftparchive --arch "$arch" packages pool) > "$d/Packages"
+  gzip -9nk "$d/Packages"
+done
+apt-ftparchive \
+  -o APT::FTPArchive::Release::Origin=gknowledge \
+  -o APT::FTPArchive::Release::Label=gknowledge \
+  -o APT::FTPArchive::Release::Suite=stable \
+  -o APT::FTPArchive::Release::Codename=stable \
+  -o APT::FTPArchive::Release::Components=main \
+  -o "APT::FTPArchive::Release::Architectures=all amd64 arm64" \
+  -o "APT::FTPArchive::Release::Description=gknowledge packages" \
+  release "$APT/dists/stable" > "$APT/dists/stable/Release"
+gpg --batch --yes --local-user "$GPG_KEY_ID" --clearsign \
+  -o "$APT/dists/stable/InRelease" "$APT/dists/stable/Release"
+gpg --batch --yes --local-user "$GPG_KEY_ID" --armor --detach-sign \
+  -o "$APT/dists/stable/Release.gpg" "$APT/dists/stable/Release"
+
+cat > "$OUT/gknowledge.sources" <<EOF
+Types: deb
+URIs: $BASE_URL/apt
+Suites: stable
+Components: main
+Signed-By: /usr/share/keyrings/gknowledge.gpg
+EOF
+
+# --- Flatpak ----------------------------------------------------------------
+FP="$OUT/flatpak"
+ostree init --mode=archive-z2 --repo="$FP"
+# Only affects building; a nearly full build disk should not abort the import.
+ostree config --repo="$FP" set core.min-free-space-percent 0
+flatpak build-import-bundle --gpg-sign="$GPG_KEY_ID" "$FP" "$BUNDLE"
+flatpak build-update-repo --gpg-sign="$GPG_KEY_ID" --generate-static-deltas \
+  --title=gknowledge --default-branch=master "$FP"
+
+KEY_B64=$(base64 -w0 < "$OUT/gknowledge.gpg")
+cat > "$OUT/gknowledge.flatpakrepo" <<EOF
+[Flatpak Repo]
+Title=gknowledge
+Url=$BASE_URL/flatpak/
+Homepage=https://github.com/openapi/gknowledge
+Comment=Native GNOME knowledge workstation
+Icon=$BASE_URL/$APP_ID.svg
+GPGKey=$KEY_B64
+EOF
+cat > "$OUT/$APP_ID.flatpakref" <<EOF
+[Flatpak Ref]
+Name=$APP_ID
+Branch=master
+Title=gknowledge
+Url=$BASE_URL/flatpak/
+SuggestRemoteName=gknowledge
+Homepage=https://github.com/openapi/gknowledge
+Icon=$BASE_URL/$APP_ID.svg
+RuntimeRepo=https://dl.flathub.org/repo/flathub.flatpakrepo
+IsRuntime=false
+GPGKey=$KEY_B64
+EOF
+cp "$ROOT/data/icons/hicolor/scalable/apps/$APP_ID.svg" "$OUT/"
+
+# --- Landing page -----------------------------------------------------------
+FPR=$(gpg --batch --with-colons --fingerprint "$GPG_KEY_ID" | awk -F: '/^fpr/{print $10; exit}')
+sed -e "s|@BASE_URL@|$BASE_URL|g" -e "s|@FINGERPRINT@|$FPR|g" \
+  "$ROOT/build-aux/repos/index.html" > "$OUT/index.html"
+touch "$OUT/.nojekyll"
+echo "Site written to $OUT"

build-aux/repos/index.html

@@ -0,0 +1,60 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>gknowledge packages</title>
+<link rel="icon" href="io.gknowledge.Gknowledge.svg" type="image/svg+xml">
+<style>
+  :root { --bg: #fafafa; --fg: #1e1e1e; --muted: #5e5e5e; --card: #ffffff; --border: #dedede; --code: #f2f2f2; --accent: #1c71d8; }
+  @media (prefers-color-scheme: dark) {
+    :root { --bg: #1d1d20; --fg: #f6f5f4; --muted: #b0b0b4; --card: #26262a; --border: #3a3a3f; --code: #303035; --accent: #78aeed; }
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--fg); font: 16px/1.55 system-ui, "Cantarell", sans-serif; }
+  main { max-width: 760px; margin: 0 auto; padding: 40px 16px 64px; }
+  header { display: flex; align-items: center; gap: 16px; margin-bottom: 8px; }
+  header img { width: 64px; height: 64px; }
+  h1 { font-size: 28px; margin: 0; }
+  h2 { font-size: 19px; margin: 0 0 8px; }
+  p { margin: 0 0 12px; }
+  .lead { color: var(--muted); margin-bottom: 28px; }
+  section { background: var(--card); border: 1px solid var(--border); border-radius: 12px; padding: 20px; margin-bottom: 16px; }
+  pre { background: var(--code); border-radius: 8px; padding: 12px; overflow-x: auto; margin: 0 0 12px; font-size: 14px; }
+  code { font-family: ui-monospace, "Source Code Pro", monospace; }
+  a { color: var(--accent); }
+  .note { color: var(--muted); font-size: 14px; }
+</style>
+</head>
+<body>
+<main>
+  <header>
+    <img src="io.gknowledge.Gknowledge.svg" alt="">
+    <h1>gknowledge packages</h1>
+  </header>
+  <p class="lead">Signed package repositories for <a href="https://github.com/openapi/gknowledge">gknowledge</a>, a native GNOME app that turns documents into a cited wiki. Add one once and updates arrive with the rest of your system.</p>
+
+  <section>
+    <h2>Ubuntu and Debian (APT)</h2>
+    <p>Ubuntu 24.04 or later, Debian 13 or later.</p>
+<pre><code>sudo curl -fsSLo /usr/share/keyrings/gknowledge.gpg @BASE_URL@/gknowledge.gpg
+sudo curl -fsSLo /etc/apt/sources.list.d/gknowledge.sources @BASE_URL@/gknowledge.sources
+sudo apt update &amp;&amp; sudo apt install gknowledge</code></pre>
+    <p class="note">To remove the repository: <code>sudo rm /etc/apt/sources.list.d/gknowledge.sources /usr/share/keyrings/gknowledge.gpg</code></p>
+  </section>
+
+  <section>
+    <h2>Any distribution (Flatpak)</h2>
+    <p>The GNOME runtime is installed from Flathub automatically.</p>
+<pre><code>flatpak install --user @BASE_URL@/io.gknowledge.Gknowledge.flatpakref</code></pre>
+    <p class="note">Or add the remote: <code>flatpak remote-add --user --if-not-exists gknowledge @BASE_URL@/gknowledge.flatpakrepo</code></p>
+  </section>
+
+  <section>
+    <h2>Signing key</h2>
+    <p>Both repositories are signed with the same key: <a href="gknowledge.asc">gknowledge.asc</a>.</p>
+    <p class="note">Fingerprint: <code>@FINGERPRINT@</code></p>
+  </section>
+</main>
+</body>
+</html>

install.sh

@@ -3,18 +3,22 @@
 #
 #   curl -fsSL https://github.com/openapi/gknowledge/releases/latest/download/install.sh | bash
 #
-# Ubuntu / Debian: downloads the latest .deb and installs it with apt, which
-# also pulls GTK 4, Libadwaita and PyGObject.
+# Ubuntu / Debian: adds the signed gknowledge APT repository and installs from
+# it, so later versions arrive with `apt upgrade`. apt also pulls GTK 4,
+# Libadwaita and PyGObject. If the repository is unreachable, installs the
+# latest .deb from GitHub Releases instead.
 # Other distributions: installs the latest release into ~/.local (no root),
 # after checking that PyGObject, GTK 4 and Libadwaita are present.
 #
 # Environment overrides:
 #   GKNOWLEDGE_REPO   owner/repo (default openapi/gknowledge)
 #   GKNOWLEDGE_MODE   deb | local (default: deb when apt is available)
+#   GKNOWLEDGE_NO_REPO=1  install the release .deb without adding the repository
 set -euo pipefail
 
 REPO="${GKNOWLEDGE_REPO:-openapi/gknowledge}"
 BASE="https://github.com/${REPO}/releases/latest/download"
+PAGES="${GKNOWLEDGE_PAGES:-https://${REPO%%/*}.github.io/${REPO#*/}}"
 
 info() { printf '\033[1;34m==>\033[0m %s\n' "$*"; }
 warn() { printf '\033[1;33m!!\033[0m %s\n' "$*" >&2; }
@@ -29,7 +33,24 @@ sudo_cmd() {
 TMP="$(mktemp -d)"
 trap 'rm -rf "$TMP"' EXIT
 
-install_deb() {
+install_repo() {
+  info "Adding the gknowledge APT repository ($PAGES/apt)"
+  curl -fsSL -o "$TMP/gknowledge.gpg" "$PAGES/gknowledge.gpg" || return 1
+  curl -fsSL -o "$TMP/gknowledge.sources" "$PAGES/gknowledge.sources" || return 1
+  grep -q "^URIs: $PAGES/apt$" "$TMP/gknowledge.sources" || return 1
+  sudo_cmd install -m 644 "$TMP/gknowledge.gpg" /usr/share/keyrings/gknowledge.gpg
+  sudo_cmd install -m 644 "$TMP/gknowledge.sources" /etc/apt/sources.list.d/gknowledge.sources
+  info "Installing with apt (you may be asked for your password)"
+  sudo_cmd apt-get update -o Dir::Etc::sourcelist=sources.list.d/gknowledge.sources \
+    -o Dir::Etc::sourceparts=- -o APT::Get::List-Cleanup=0 || {
+    # A broken source would make every later `apt update` fail.
+    sudo_cmd rm -f /etc/apt/sources.list.d/gknowledge.sources /usr/share/keyrings/gknowledge.gpg
+    return 1
+  }
+  sudo_cmd apt-get install -y gknowledge
+}
+
+install_release_deb() {
   info "Downloading the latest gknowledge .deb"
   curl -fL --progress-bar -o "$TMP/gknowledge_all.deb" "$BASE/gknowledge_all.deb" \
     || die "Download failed from $BASE/gknowledge_all.deb"
@@ -38,6 +59,13 @@ install_deb() {
   chmod 644 "$TMP/gknowledge_all.deb"
   info "Installing with apt (you may be asked for your password)"
   sudo_cmd apt-get install -y "$TMP/gknowledge_all.deb"
+}
+
+install_deb() {
+  if [ "${GKNOWLEDGE_NO_REPO:-}" = 1 ] || ! install_repo; then
+    [ "${GKNOWLEDGE_NO_REPO:-}" = 1 ] || warn "The APT repository is not reachable; installing the release .deb (no automatic updates)."
+    install_release_deb
+  fi
   if [ -e "$HOME/.local/bin/gknowledge" ] || [ -e "$HOME/.local/share/applications/io.gknowledge.Gknowledge.desktop" ]; then
     warn "An older gknowledge in ~/.local shadows this install (old icon and version)."
     warn "Remove it with: rm -rf ~/.local/bin/gknowledge ~/.local/bin/gknowledge-mcp ~/.local/share/gknowledge ~/.local/share/applications/io.gknowledge.Gknowledge.desktop ~/.local/share/icons/hicolor/scalable/apps/io.gknowledge.Gknowledge.svg ~/.local/share/metainfo/io.gknowledge.Gknowledge.metainfo.xml && gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor"