From 42fb88f84d42f0bf39149e83148907bacd2c5c4a Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sat, 21 Feb 2026 06:40:38 -0700 Subject: [PATCH 1/2] doc: Add PPA installation instructions Add a standalone installation page with PPA instructions and supported Ubuntu releases. Link it from the documentation index after the introduction. Co-developed-by: Claude Opus 4.6 --- doc/index.rst | 1 + doc/install.rst | 27 +++++++++++++++++++++++++++ 2 files changed, 28 insertions(+) create mode 100644 doc/install.rst diff --git a/doc/index.rst b/doc/index.rst index f7bc408..7ff3a16 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -8,6 +8,7 @@ Paperman :caption: Introduction introduction + install .. toctree:: :maxdepth: 2 diff --git a/doc/install.rst b/doc/install.rst new file mode 100644 index 0000000..cd36567 --- /dev/null +++ b/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`. From 2eb691e766b4c6e4a690e49fc45d296a6c893552 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sat, 21 Feb 2026 07:34:30 -0700 Subject: [PATCH 2/2] github: Add release workflow for .deb and PPA uploads On a tag push (v*), this workflow: - Builds a binary .deb package and creates a GitHub Release with it attached - Signs and uploads source packages to the Launchpad PPA using the existing scripts/ppa-upload script The PPA job requires GPG_PRIVATE_KEY and GPG_PASSPHRASE secrets to be configured in the repository settings. Co-developed-by: Claude Opus 4.6 --- .github/workflows/release.yml | 87 +++++++++++++++++++++++++++++++++++ doc/index.rst | 1 + doc/releasing.rst | 63 +++++++++++++++++++++++++ 3 files changed, 151 insertions(+) create mode 100644 .github/workflows/release.yml create mode 100644 doc/releasing.rst diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..b6e2a0e --- /dev/null +++ b/.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 diff --git a/doc/index.rst b/doc/index.rst index 7ff3a16..dc4d1ea 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -35,6 +35,7 @@ Paperman develop build + releasing ppa testing claude-setup-nginx diff --git a/doc/releasing.rst b/doc/releasing.rst new file mode 100644 index 0000000..621d005 --- /dev/null +++ b/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 + +``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`.