launchpad PPA workflow

.github/workflows/release.yml

@@ -0,0 +1,87 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build-deb:
+    name: Build .deb and create GitHub Release
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install build dependencies
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y \
+            build-essential debhelper devscripts fakeroot \
+            qt5-qmake qtbase5-dev qtbase5-dev-tools libqt5sql5-sqlite \
+            libpoppler-qt5-dev libpodofo-dev \
+            libtiff-dev libsane-dev libjpeg-dev zlib1g-dev \
+            imagemagick tesseract-ocr tesseract-ocr-eng
+
+      - name: Prepare debian packaging files
+        run: |
+          sed -e 's/VENDOR_VERSION//' \
+              -e 's/UNRELEASED/noble/' \
+              debian/changelog.in > debian/changelog
+          cp debian/control.in debian/control
+          cp debian/rules.in debian/rules
+          chmod a+x debian/rules
+
+      - name: Build binary .deb
+        run: dpkg-buildpackage -us -uc -b
+
+      - name: Create GitHub Release
+        run: |
+          DEB=$(ls ../paperman_*.deb | head -1)
+          gh release create "$GITHUB_REF_NAME" "$DEB" \
+            --title "$GITHUB_REF_NAME" \
+            --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  ppa-upload:
+    name: Sign and upload to Launchpad PPA
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install packaging tools
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y \
+            debhelper devscripts dput fakeroot bzip2
+
+      - name: Import GPG key
+        run: echo "$GPG_PRIVATE_KEY" | gpg --batch --import
+        env:
+          GPG_PRIVATE_KEY: ${{ secrets.GPG_PRIVATE_KEY }}
+
+      - name: Configure gpg-agent for non-interactive signing
+        run: |
+          echo "allow-preset-passphrase" >> ~/.gnupg/gpg-agent.conf
+          gpg-connect-agent reloadagent /bye
+          KEYGRIP=$(gpg --list-secret-keys --with-keygrip \
+            | sed -n 's/.*Keygrip = \(.*\)/\1/p' | head -1)
+          gpg-connect-agent "PRESET_PASSPHRASE $KEYGRIP -1 \
+            $(echo -n "$GPG_PASSPHRASE" | xxd -p -c 256)" /bye
+        env:
+          GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
+
+      - name: Configure dput
+        run: |
+          cat > ~/.dput.cf <<'EOF'
+          [ppa]
+          fqdn = ppa.launchpad.net
+          method = ftp
+          incoming = ~sjg20/ubuntu/ppa/
+          login = anonymous
+          allow_unsigned_uploads = 0
+          EOF
+
+      - name: Upload to PPA
+        run: scripts/ppa-upload

doc/index.rst

@@ -8,6 +8,7 @@ Paperman
    :caption: Introduction
 
    introduction
+   install
 
 .. toctree::
    :maxdepth: 2
@@ -34,6 +35,7 @@ Paperman
 
    develop
    build
+   releasing
    ppa
    testing
    claude-setup-nginx

doc/install.rst

@@ -0,0 +1,27 @@
+Installation
+============
+
+Ubuntu PPA
+----------
+
+On Ubuntu, the easiest way to install Paperman is from the PPA:
+
+.. code:: bash
+
+   sudo add-apt-repository ppa:sjg1/ppa
+   sudo apt update
+   sudo apt install paperman
+
+This provides pre-built packages for the following Ubuntu releases:
+
+- Bionic (18.04 LTS)
+- Focal (20.04 LTS)
+- Jammy (22.04 LTS)
+- Noble (24.04 LTS)
+- Questing (25.10)
+
+Building from Source
+--------------------
+
+For other distributions or to get the latest development version, see
+:doc:`build`.

doc/releasing.rst

@@ -0,0 +1,63 @@
+Releasing
+=========
+
+Paperman uses a GitHub Actions workflow to automate releases.  Pushing a
+version tag triggers two parallel jobs: one builds a ``.deb`` package and
+publishes a GitHub Release, the other signs and uploads source packages to
+the Launchpad PPA.
+
+Creating a Release
+------------------
+
+1. Update ``debian/changelog.in`` with the new version and changes.
+
+2. Commit and push the changelog update.
+
+3. Tag the release and push the tag:
+
+   .. code:: bash
+
+      git tag v1.3.3
+      git push origin v1.3.3
+
+The workflow (``.github/workflows/release.yml``) runs automatically on any
+tag matching ``v*``.
+
+What the Workflow Does
+----------------------
+
+**build-deb** — Build ``.deb`` and create GitHub Release
+   Installs Qt5/C++ build dependencies and Debian packaging tools, generates
+   ``debian/changelog``, ``control`` and ``rules`` from the ``.in`` templates,
+   builds a binary ``.deb`` with ``dpkg-buildpackage``, then creates a GitHub
+   Release with the ``.deb`` attached.
+
+**ppa-upload** — Sign and upload to Launchpad PPA
+   Imports the GPG signing key from repository secrets, configures
+   ``gpg-agent`` for non-interactive signing and sets up ``dput``, then runs
+   ``scripts/ppa-upload`` which handles building, signing and uploading
+   source packages for all target distributions.
+
+Required Secrets
+----------------
+
+The PPA job needs two secrets configured in the GitHub repository settings
+(Settings > Secrets and variables > Actions):
+
+``GPG_PRIVATE_KEY``
+   The ASCII-armoured GPG private key.  Export it with:
+
+   .. code:: bash
+
+      gpg --armor --export-secret-keys <KEY_ID>
+
+``GPG_PASSPHRASE``
+   The passphrase for the GPG key.
+
+Without these secrets the PPA job fails, but the ``.deb`` / GitHub Release
+job still succeeds independently.
+
+Manual PPA Upload
+-----------------
+
+To upload to the PPA without the CI workflow, see :doc:`ppa`.