Flatpak

.github/workflows/flatpak-test.yml

@@ -0,0 +1,74 @@
+name: flatpak-test
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-flatpak:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          lfs: true
+
+      - name: Checkout Flathub manifest repo
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          repository: Open-VCS/flathub
+          path: flathub
+
+      - name: Setup Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: '24'
+          cache: 'npm'
+          cache-dependency-path: Frontend/package-lock.json
+
+      - name: Install frontend deps
+        working-directory: Frontend
+        run: npm ci
+
+      - name: Build frontend
+        working-directory: Frontend
+        run: npm run build
+
+      - name: Install Linux build deps
+        shell: bash
+        run: |
+          set -euxo pipefail
+          sudo apt-get update
+          sudo apt-get install -y libappindicator3-dev librsvg2-dev patchelf
+          sudo apt-get install -y libwebkit2gtk-4.1-dev || sudo apt-get install -y libwebkit2gtk-4.0-dev
+
+      - name: Install Flatpak tooling
+        shell: bash
+        run: |
+          set -euxo pipefail
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends flatpak flatpak-builder appstream elfutils
+          flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
+          flatpak install --user -y flathub org.gnome.Platform//49 org.gnome.Sdk//49
+          flatpak install --user -y flathub org.freedesktop.Sdk.Extension.rust-stable//25.08 \
+            || flatpak install --user -y flathub org.freedesktop.Sdk.Extension.rust-stable//24.08 \
+            || flatpak install --user -y flathub org.freedesktop.Sdk.Extension.rust-stable
+          flatpak install --user -y flathub org.freedesktop.Sdk.Extension.node24//25.08 \
+            || flatpak install --user -y flathub org.freedesktop.Sdk.Extension.node24//24.08
+
+      - name: Build Flatpak bundle
+        shell: bash
+        run: |
+          set -euxo pipefail
+          flatpak-builder \
+            --env=OPENVCS_OFFICIAL_RELEASE=1 \
+            --user --force-clean --repo=repo build-flatpak flathub/io.github.jordonbc.OpenVCS.yml
+          flatpak build-bundle repo OpenVCS-test.flatpak io.github.jordonbc.OpenVCS
+
+      - name: Upload Flatpak artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: OpenVCS-flatpak-test
+          path: OpenVCS-test.flatpak

.github/workflows/publish-stable.yml

@@ -34,6 +34,13 @@ jobs:
           lfs: true
           fetch-depth: 0
 
+      - name: Checkout Flathub manifest repo
+        if: matrix.platform == 'ubuntu-24.04' && env.OPENVCS_ENABLE_FLATPAK == '1'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          repository: Open-VCS/flathub
+          path: flathub
+
       - name: Compute version tag
         id: version
         shell: bash
@@ -86,7 +93,7 @@ jobs:
 
       # ---------- Flatpak (Linux only; artifact) ----------
       - name: Install Flatpak tooling
-        if: matrix.platform == 'ubuntu-24.04' && env.OPENVCS_ENABLE_FLATPAK == '1' && hashFiles('packaging/flatpak/io.github.jordonbc.OpenVCS.yml') != ''
+        if: matrix.platform == 'ubuntu-24.04' && env.OPENVCS_ENABLE_FLATPAK == '1' && hashFiles('flathub/io.github.jordonbc.OpenVCS.yml') != ''
         shell: bash
         run: |
           set -euxo pipefail
@@ -103,25 +110,27 @@ jobs:
             || flatpak install --user -y flathub org.freedesktop.Sdk.Extension.node24//24.08
 
       - name: Verify Flatpak manifest exists
-        if: matrix.platform == 'ubuntu-24.04' && env.OPENVCS_ENABLE_FLATPAK == '1' && hashFiles('packaging/flatpak/io.github.jordonbc.OpenVCS.yml') != ''
+        if: matrix.platform == 'ubuntu-24.04' && env.OPENVCS_ENABLE_FLATPAK == '1' && hashFiles('flathub/io.github.jordonbc.OpenVCS.yml') != ''
         shell: bash
         run: |
           set -euxo pipefail
-          ls -la packaging/flatpak
-          test -f packaging/flatpak/io.github.jordonbc.OpenVCS.yml
+          ls -la flathub
+          test -f flathub/io.github.jordonbc.OpenVCS.yml
 
       - name: Build Flatpak bundle
-        if: matrix.platform == 'ubuntu-24.04' && env.OPENVCS_ENABLE_FLATPAK == '1' && hashFiles('packaging/flatpak/io.github.jordonbc.OpenVCS.yml') != ''
+        if: matrix.platform == 'ubuntu-24.04' && env.OPENVCS_ENABLE_FLATPAK == '1' && hashFiles('flathub/io.github.jordonbc.OpenVCS.yml') != ''
         shell: bash
         run: |
           set -euxo pipefail
           # Stable production builds should report the plain package version (not git metadata).
-          export OPENVCS_OFFICIAL_RELEASE='1'
-          flatpak-builder --user --force-clean --repo=repo build-flatpak packaging/flatpak/io.github.jordonbc.OpenVCS.yml
+          # --env is required because flatpak-builder sandboxes don't inherit host env vars.
+          flatpak-builder \
+            --env=OPENVCS_OFFICIAL_RELEASE=1 \
+            --user --force-clean --repo=repo build-flatpak flathub/io.github.jordonbc.OpenVCS.yml
           flatpak build-bundle repo OpenVCS.flatpak io.github.jordonbc.OpenVCS
 
       - name: Upload Flatpak bundle (artifact)
-        if: matrix.platform == 'ubuntu-24.04' && env.OPENVCS_ENABLE_FLATPAK == '1' && hashFiles('packaging/flatpak/io.github.jordonbc.OpenVCS.yml') != ''
+        if: matrix.platform == 'ubuntu-24.04' && env.OPENVCS_ENABLE_FLATPAK == '1' && hashFiles('flathub/io.github.jordonbc.OpenVCS.yml') != ''
         uses: actions/upload-artifact@v7
         with:
           name: OpenVCS-flatpak-stable
@@ -174,7 +183,47 @@ jobs:
           # bundles: ''           # e.g. 'deb,appimage,msi,nsis' if you want to restrict output
 
       - name: Upload Flatpak bundle to GitHub Release
-        if: matrix.platform == 'ubuntu-24.04' && env.OPENVCS_ENABLE_FLATPAK == '1' && hashFiles('packaging/flatpak/io.github.jordonbc.OpenVCS.yml') != ''
+        if: matrix.platform == 'ubuntu-24.04' && env.OPENVCS_ENABLE_FLATPAK == '1' && hashFiles('flathub/io.github.jordonbc.OpenVCS.yml') != ''
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: gh release upload "${{ steps.version.outputs.tag }}" OpenVCS.flatpak --clobber
+
+      # ---------- Update Flathub repo for next PR ----------
+      - name: Install flatpak generator tools
+        if: matrix.platform == 'ubuntu-24.04' && env.OPENVCS_ENABLE_FLATPAK == '1' && hashFiles('flathub/io.github.jordonbc.OpenVCS.yml') != ''
+        shell: bash
+        run: |
+          set -euxo pipefail
+          pip install flatpak-cargo-generator flatpak-node-generator
+
+      - name: Regenerate Flatpak vendor sources
+        if: matrix.platform == 'ubuntu-24.04' && env.OPENVCS_ENABLE_FLATPAK == '1' && hashFiles('flathub/io.github.jordonbc.OpenVCS.yml') != ''
+        shell: bash
+        run: |
+          set -euxo pipefail
+          # cargo-sources.json from workspace Cargo.lock
+          CARGO_GEN="$(python3 -c 'import flatpak_cargo_generator.script; print(flatpak_cargo_generator.script.__file__)')"
+          python3 "$CARGO_GEN" Cargo.lock -o flathub/cargo-sources.json
+          # npm-sources for Frontend
+          python3 -m flatpak_node_generator npm Frontend/package-lock.json -o flathub/npm-sources-frontend.json
+          echo "Vendor sources regenerated."
+
+      - name: Update Flathub manifest and metadata
+        if: matrix.platform == 'ubuntu-24.04' && env.OPENVCS_ENABLE_FLATPAK == '1' && hashFiles('flathub/io.github.jordonbc.OpenVCS.yml') != ''
+        shell: bash
+        run: |
+          set -euxo pipefail
+          node scripts/update-flathub.js flathub \
+            "${{ steps.version.outputs.version }}" \
+            "$(git rev-parse HEAD)"
+
+          # Git operations must run inside the flathub checkout, not the main repo.
+          cd flathub
+          git config user.name  'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+          set +x  # avoid leaking the PAT in logs
+          git remote set-url origin "https://x-access-token:${{ secrets.FLATHUB_REPO_PAT }}@github.com/Open-VCS/flathub.git"
+          set -x
+          git add io.github.jordonbc.OpenVCS.yml io.github.jordonbc.OpenVCS.metainfo.xml cargo-sources.json npm-sources-frontend.json
+          git diff --staged --quiet || git commit -m "chore: bump to openvcs-v${{ steps.version.outputs.version }}"
+          git push

AGENTS.md

@@ -7,7 +7,7 @@
 - `Frontend/`: TypeScript + Vite UI code (`src/scripts/`, `src/styles/`, `src/modals/`), with Vitest tests colocated as `*.test.ts` files.
 - OpenVCS is desktop-only: there is no web app, no standalone browser mode, and no supported web browser/WebView deployment target.
 - `docs/`: UX docs, plugin architecture notes, and plugin/theme packaging guides referenced by contributors.
-- `packaging/flatpak/`: Flatpak manifests and Flatpak-specific build notes.
+- Flatpak packaging is maintained in the sibling [`Open-VCS/flathub`](https://github.com/Open-VCS/flathub) repository.
 - Supporting files at the repo root include the workspace `Cargo.toml`, `Justfile`, `README.md`, `ARCHITECTURE.md`, `SECURITY.md`, and installer scripts.
 
 ## Build, test, and development commands

Justfile

@@ -27,14 +27,15 @@ test:
 tauri-build channel="stable":
   FRONTEND_SKIP_BUILD=1 NO_STRIP=true OPENVCS_UPDATE_CHANNEL={{channel}} node scripts/tauri-build.js
 
+# Requires Open-VCS/flathub cloned as a sibling directory: git clone git@github.com:Open-VCS/flathub.git ../flathub
 build-flatpak install="":
   @if [ "{{install}}" = "-i" ]; then \
-    flatpak-builder --force-clean --user --install build-flatpak packaging/flatpak/io.github.jordonbc.OpenVCS.yml; \
+    flatpak-builder --force-clean --user --install build-flatpak ../flathub/io.github.jordonbc.OpenVCS.yml; \
   elif [ -n "{{install}}" ]; then \
     echo "Usage: just build-flatpak [-i]"; \
     exit 2; \
   else \
-    flatpak-builder --force-clean --user build-flatpak packaging/flatpak/io.github.jordonbc.OpenVCS.yml; \
+    flatpak-builder --force-clean --user build-flatpak ../flathub/io.github.jordonbc.OpenVCS.yml; \
   fi
 
 fix:

README.md

@@ -148,7 +148,7 @@ cargo tauri dev
 
 ### Flatpak
 
-Flatpak packaging exists under `packaging/flatpak/`. Stable-channel Flatpak builds may be published, but they are provided as experimental test builds rather than a recommended install path. See the [Flatpak](#flatpak) section before relying on it for regular use.
+Flatpak packaging lives in the sibling [`Open-VCS/flathub`](https://github.com/Open-VCS/flathub) repo. Stable-channel Flatpak builds may be published, but they are provided as experimental test builds rather than a recommended install path.
 
 > [!NOTE]
 > Desktop builds currently continue to use the legacy shared `OpenVCS` configuration and plugin directories.
@@ -245,7 +245,6 @@ flowchart LR
 ├── Backend/              # Rust + Tauri backend, native logic, and app entry point
 ├── Frontend/             # TypeScript + Vite frontend
 ├── docs/                 # UX, plugin, architecture, and packaging documentation
-├── packaging/flatpak/    # Experimental Flatpak manifests and notes
 ├── scripts/              # Build and plugin-materialisation helpers
 ├── Cargo.toml            # Rust workspace manifest
 ├── Justfile              # Common build/test/fix commands
@@ -306,11 +305,7 @@ These commands wrap the Tauri build flow and set `NO_STRIP=true` to avoid AppIma
 
 ## Flatpak
 
-A Flatpak manifest exists under:
-
-```text
-packaging/flatpak/
-```
+A Flatpak manifest is maintained in the [`Open-VCS/flathub`](https://github.com/Open-VCS/flathub) repository. The stable release pipeline builds and deploys updates automatically.
 
 | Limitation                                 | Impact                                                                  |
 | ------------------------------------------ | ----------------------------------------------------------------------- |
@@ -320,9 +315,7 @@ packaging/flatpak/
 
 In short: Flatpak users are helping test the packaging path. Expect rough edges.
 
-For local Flatpak build notes, see:
-
-[packaging/flatpak/README.md](packaging/flatpak/README.md)
+For local Flatpak builds, clone `Open-VCS/flathub` as a sibling directory and run `just build-flatpak` from this directory.
 
 ---