bguetter · Sep 17, 2026
@@ -0,0 +1,88 @@
+name: Linux Package
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'linux/**'
+      - '.github/workflows/linux-package.yml'
+  pull_request:
+    paths:
+      - 'linux/**'
+      - '.github/workflows/linux-package.yml'
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  package:
+    if: github.repository == 'vinzdg/codenotch' || github.event_name == 'workflow_dispatch'
+    name: AppImage
+    permissions:
+      contents: write
+    runs-on: ubuntu-22.04
+    defaults:
+      run:
+        working-directory: linux
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install WebKitGTK and AppImage tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev \
+            libayatana-appindicator3-dev librsvg2-dev patchelf libssl-dev \
+            pkg-config build-essential fuse libfuse2 file libsoup-3.0-dev
+
+      - uses: dtolnay/rust-toolchain@6bed0761d98439e5a578e2877258200ad565ba87 # stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: linux
+
+      - name: Build the hook
+        run: cargo build --release --locked -p codenotch-hook --target-dir target/hook
+
+      - name: Build the AppImage
+        working-directory: linux/codenotch
+        run: npx --yes @tauri-apps/cli@2.11.4 build --config tauri.bundle.conf.json -- --locked
+
+      - name: Drop bundled Ubuntu WebKit so the host WebKitGTK is used
+        run: bash pack-appimage-host-webkit.sh
+
+      - name: Name the AppImage
+        run: |
+          shopt -s nullglob
+          images=(target/release/bundle/appimage/*.AppImage)
+          if [ "${#images[@]}" -ne 1 ]; then
+            echo "expected one AppImage, found ${#images[@]}" >&2
+            ls -la target/release/bundle/appimage || true
+            exit 1
+          fi
+          cp "${images[0]}" Codenotch.AppImage
+          chmod +x Codenotch.AppImage
+
+      - name: Run doctor
+        env:
+          APPIMAGE_EXTRACT_AND_RUN: "1"
+        run: |
+          ./Codenotch.AppImage doctor | tee doctor.txt
+          if ! grep -q 'Codenotch doctor' doctor.txt; then
+            echo 'AppImage doctor did not run:' >&2
+            cat doctor.txt || true
+            exit 1
+          fi
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: Codenotch-AppImage-${{ github.sha }}
+          path: linux/Codenotch.AppImage
+          if-no-files-found: error
+
+      - name: Attach to the release
+        if: github.event_name == 'release' && startsWith(github.event.release.tag_name, 'v')
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.event.release.tag_name }}
+        run: gh release upload "$TAG" Codenotch.AppImage --clobber
+        working-directory: linux
@@ -0,0 +1,50 @@
+name: Linux
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'linux/**'
+      - '.github/workflows/linux.yml'
+  pull_request:
+    paths:
+      - 'linux/**'
+      - '.github/workflows/linux.yml'
+
+jobs:
+  build:
+    if: github.repository == 'vinzdg/codenotch'
+    name: Build and test
+    runs-on: ubuntu-22.04
+    defaults:
+      run:
+        working-directory: linux
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Check the UI pages parse
+        run: node scripts/check-ui-scripts.mjs
+
+      - name: Install WebKitGTK
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev \
+            libayatana-appindicator3-dev librsvg2-dev patchelf libssl-dev \
+            pkg-config build-essential libsoup-3.0-dev
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: linux
+
+      - name: Build
+        run: cargo build --locked
+
+      - name: Test
+        run: cargo test --locked
+
+      - name: Clippy
+        run: cargo clippy --all-targets --locked
@@ -33,6 +33,21 @@ certificate, notarizes with Apple, and regenerates the Sparkle auto-update
 feed. That's the maintainer's job for cutting an official build, and it needs
 credentials only the maintainer has. You won't need it to contribute.
 
+## Linux (AppImage)
+
+The Linux port lives in `linux/` and is built as a thin x86_64 AppImage on Ubuntu 22.04.
+See [`linux/README.md`](linux/README.md) for where it runs, host packages, and Distrobox
+build steps. From that directory:
+
+```sh
+node scripts/check-ui-scripts.mjs
+cargo test --locked
+./build-appimage.sh
+```
+
+Do not mix Linux packaging into `windows/`. Do not commit `linux/target/` or `.AppImage`
+files; CI uploads the artifact.
+
 ## Before opening a PR
 
 - `make test` passes.
@@ -66,8 +81,7 @@ credentials only the maintainer has. You won't need it to contribute.
 - Don't freeze `L10n.t` in a `static let` — lookup has to see the current
   language.
 - Follow System plus the in-app Language setting; don't set `AppleLanguages`.
-- Windows `windows/codenotch/src/i18n.rs` is a separate system — don't merge
-  the two.
+- Windows `windows/codenotch/src/i18n.rs` and Linux `linux/codenotch/src/i18n.rs` are separate systems — don't merge the two (or the Mac catalog) together.
 
 ## Adding a provider
 

@@ -59,6 +59,24 @@ The installer is not code-signed, so the first time it runs SmartScreen says *Wi
 your PC*. Choose **More info**, then **Run anyway**. Every Windows change also leaves an
 installer on its [Windows Package run](../../actions/workflows/windows-package.yml).
 
+## Linux
+
+An **x86_64 AppImage** — Rust/Tauri 2 / WebKitGTK, same design and providers as the
+Windows port — lives in [`linux/`](linux/README.md). It is built on Ubuntu 22.04 so the
+glibc is old enough for **Bazzite, Fedora, Ubuntu 22.04+ and Debian 12+**. It is not a
+universal Linux binary: no ARM, no musl/Alpine, no Ubuntu 20.04.
+
+The file is a **thin** AppImage (~5 MB). It uses the host’s `webkit2gtk-4.1` rather than
+shipping Ubuntu’s WebKit (that helper crashes on Fedora/Bazzite and leaves Settings blank).
+Install the distro package (`webkit2gtk4.1` on Fedora, `libwebkit2gtk-4.1-0` on Ubuntu/Debian)
+and FUSE, then `chmod +x` and run it on the host.
+
+Every Linux packaging change leaves an AppImage on its
+[Linux Package run](../../actions/workflows/linux-package.yml). The overlay notch is
+best-effort on GNOME Wayland; the tray icon and Settings window still show usage.
+Config: `~/.config/codenotch`. See [linux/README.md](linux/README.md) for the full
+compatibility table.
+
 ## Connect your phone
 
 The Codenotch phone app (iOS and Android) can show the same usage

@@ -0,0 +1,4 @@
+* text=auto eol=lf
+*.ico binary
+*.png binary
+*.ps1 text eol=crlf
@@ -0,0 +1,4 @@
+target/
+*.log
+*.AppImage
+codenotch/gen/