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 f7bc408..dc4d1ea 100644 --- a/doc/index.rst +++ b/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 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`. 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`.