Sign the automated version bump commit in CI

main now requires signed commits, and Gitea refuses to merge a pull request
carrying an unsigned one, so the post-release bump PR could not be merged
without disabling the protection first.

The runner now signs that commit with a dedicated release-bot SSH key held as
an organisation Actions secret, trusted by the instance through
[repository.signing] TRUSTED_SSH_KEYS. The key Gitea signs merge commits with
lives on the server and no runner can reach it.

The step fails fast when the secret is missing, unparseable or passphrase
protected, and the commit is re-read before pushing so an unsigned one is
caught here rather than days later at merge time.

Co-Authored-By: Claude Opus 5 <[email protected]>

.gitea/workflows/ci.yml

@@ -7,56 +7,31 @@ on:
       - develop
   pull_request:
 
+# Jobs that need PHP run inside the shared CI images maintained in the
+# Unsupervised/ci-php repository. PHP, Composer, the intl and zip extensions
+# and the GNU CLI tools are already in the image, so there is no toolchain
+# setup step in any job here.
+#
+# The registry path is written out at each use because
+# jobs.<id>.container.image cannot read the `env` context.
+
 jobs:
-  # PHPCS and PHPStan share a job so the two of them draw once on Setup PHP
-  # rather than twice. That step is slow and intermittently fails on 8.3
-  # (see #178), so every job that can be folded into another is one less
-  # chance for a run to fall over. They run as separate steps, and PHPCS
-  # failing stops the job before PHPStan reports.
-  quality:
-    name: Coding Standards & Static Analysis
+  phpcs:
+    name: Coding Standards
     runs-on: ubuntu-latest
+    container:
+      image: git.unsupervised.ca/unsupervised/ci-php:8.3
     steps:
       - uses: actions/checkout@v4
 
-      # setup-php installs PHP 8.3+ through php-builder, which apt-installs ~70
-      # -dev packages before unpacking the build (#178). Ubuntu's image deletes
-      # the .debs after install, so every job re-downloads them. Keeping them
-      # and restoring them from the cache server, which lives in the cluster,
-      # turns a WAN download into a local one.
-      #
-      # Keyed per PHP version because the install path differs by version and
-      # the package sets are not interchangeable: 8.3+ pulls the ~70 -dev
-      # packages through php-builder, while 8.1 and 8.2 come from the ondrej
-      # PPA as a handful of runtime packages. Sharing one key across both lets
-      # whichever job finishes first decide what the others restore, and 8.1 is
-      # always first.
-      #
-      # Only the .debs are cached, never /var/lib/apt/lists — a stale index is
-      # how you get 404s mid-install.
-      - name: Keep downloaded .debs
-        run: |
-          sudo rm -f /etc/apt/apt.conf.d/docker-clean
-          echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' \
-            | sudo tee /etc/apt/apt.conf.d/99keep-downloaded-packages >/dev/null
-
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: /var/cache/apt/archives/*.deb
-          key: apt-php8.3-${{ runner.arch }}-v1
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: '8.3'
-          tools: composer:v2
-
+      # COMPOSER_HOME is /composer in the image, so that is where the
+      # download cache lives. composer.lock is what fingerprints the
+      # dependency set.
       - name: Cache Composer packages
         uses: actions/cache@v4
         with:
-          path: ~/.composer/cache
-          key: composer-${{ hashFiles('composer.json') }}
+          path: /composer/cache
+          key: composer-${{ hashFiles('composer.lock') }}
 
       - name: Install dependencies
         run: composer install --prefer-dist --no-progress --no-interaction
@@ -64,15 +39,36 @@ jobs:
       - name: Run PHPCS
         run: composer cs
 
+  phpstan:
+    name: Static Analysis
+    runs-on: ubuntu-latest
+    container:
+      image: git.unsupervised.ca/unsupervised/ci-php:8.3
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cache Composer packages
+        uses: actions/cache@v4
+        with:
+          path: /composer/cache
+          key: composer-${{ hashFiles('composer.lock') }}
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-interaction
+
       - name: Run PHPStan
         run: composer lint
 
   test:
     name: Tests (PHP ${{ matrix.php }})
     runs-on: ubuntu-latest
+    container:
+      image: git.unsupervised.ca/unsupervised/ci-php:${{ matrix.php }}
     strategy:
       fail-fast: false
       matrix:
+        # A version can only be added here once ci-php publishes the matching
+        # tag.
         php:
           - '8.1'
           - '8.2'
@@ -81,46 +77,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      # setup-php installs PHP 8.3+ through php-builder, which apt-installs ~70
-      # -dev packages before unpacking the build (#178). Ubuntu's image deletes
-      # the .debs after install, so every job re-downloads them. Keeping them
-      # and restoring them from the cache server, which lives in the cluster,
-      # turns a WAN download into a local one.
-      #
-      # Keyed per PHP version because the install path differs by version and
-      # the package sets are not interchangeable: 8.3+ pulls the ~70 -dev
-      # packages through php-builder, while 8.1 and 8.2 come from the ondrej
-      # PPA as a handful of runtime packages. Sharing one key across both lets
-      # whichever job finishes first decide what the others restore, and 8.1 is
-      # always first.
-      #
-      # Only the .debs are cached, never /var/lib/apt/lists — a stale index is
-      # how you get 404s mid-install.
-      - name: Keep downloaded .debs
-        run: |
-          sudo rm -f /etc/apt/apt.conf.d/docker-clean
-          echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' \
-            | sudo tee /etc/apt/apt.conf.d/99keep-downloaded-packages >/dev/null
-
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: /var/cache/apt/archives/*.deb
-          key: apt-php${{ matrix.php }}-${{ runner.arch }}-v1
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: ${{ matrix.php }}
-          extensions: mbstring, intl
-          coverage: none
-          tools: composer:v2
-
       - name: Cache Composer packages
         uses: actions/cache@v4
         with:
-          path: ~/.composer/cache
-          key: ${{ matrix.php }}-composer-${{ hashFiles('composer.json') }}
+          path: /composer/cache
+          key: ${{ matrix.php }}-composer-${{ hashFiles('composer.lock') }}
 
       - name: Install dependencies
         run: composer install --prefer-dist --no-progress --no-interaction
@@ -128,6 +89,8 @@ jobs:
       - name: Run PHPUnit
         run: composer test
 
+  # Runs on the runner image rather than a container: it needs no PHP, and it
+  # uses GNU grep's --include.
   no-debug:
     name: No Debug Code
     runs-on: ubuntu-latest
@@ -144,46 +107,15 @@ jobs:
   build:
     name: Build Plugin Zip
     runs-on: ubuntu-latest
+    container:
+      image: git.unsupervised.ca/unsupervised/ci-php:8.3
     # Only build a shippable artifact once changes land on main, and only
     # after the quality gates pass.
-    needs: [quality, test, no-debug]
+    needs: [phpcs, phpstan, test, no-debug]
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     steps:
       - uses: actions/checkout@v4
 
-      # setup-php installs PHP 8.3+ through php-builder, which apt-installs ~70
-      # -dev packages before unpacking the build (#178). Ubuntu's image deletes
-      # the .debs after install, so every job re-downloads them. Keeping them
-      # and restoring them from the cache server, which lives in the cluster,
-      # turns a WAN download into a local one.
-      #
-      # Keyed per PHP version because the install path differs by version and
-      # the package sets are not interchangeable: 8.3+ pulls the ~70 -dev
-      # packages through php-builder, while 8.1 and 8.2 come from the ondrej
-      # PPA as a handful of runtime packages. Sharing one key across both lets
-      # whichever job finishes first decide what the others restore, and 8.1 is
-      # always first.
-      #
-      # Only the .debs are cached, never /var/lib/apt/lists — a stale index is
-      # how you get 404s mid-install.
-      - name: Keep downloaded .debs
-        run: |
-          sudo rm -f /etc/apt/apt.conf.d/docker-clean
-          echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' \
-            | sudo tee /etc/apt/apt.conf.d/99keep-downloaded-packages >/dev/null
-
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: /var/cache/apt/archives/*.deb
-          key: apt-php8.3-${{ runner.arch }}-v1
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: '8.3'
-          tools: composer:v2
-
       - name: Build plugin zip
         run: composer build
 

.gitea/workflows/release.yml

@@ -15,15 +15,13 @@ jobs:
   release:
     name: Build and Publish Release
     runs-on: ubuntu-latest
+    # The shared CI image carries composer, curl, jq and the GNU coreutils
+    # the steps below shell out to. See docs/ci.md.
+    container:
+      image: git.unsupervised.ca/unsupervised/ci-php:8.3
     steps:
       - uses: actions/checkout@v4
 
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: '8.3'
-          tools: composer:v2
-
       # A tag that disagrees with the plugin header would make sites see a
       # phantom update forever (or never see a real one), so fail fast.
       - name: Verify tag matches plugin version
@@ -37,6 +35,14 @@ jobs:
           fi
           echo "version=${header_version}" >> "$GITHUB_OUTPUT"
 
+      # COMPOSER_HOME is /composer in the image, so that is where the
+      # download cache lives.
+      - name: Cache Composer packages
+        uses: actions/cache@v4
+        with:
+          path: /composer/cache
+          key: composer-${{ hashFiles('composer.lock') }}
+
       - name: Install dependencies
         run: composer install --prefer-dist --no-progress --no-interaction
 
@@ -143,6 +149,50 @@ jobs:
             { print }
           ' CHANGELOG.md > CHANGELOG.md.tmp && mv CHANGELOG.md.tmp CHANGELOG.md
 
+      # main requires signed commits, and Gitea refuses to merge a pull request
+      # that carries an unsigned one. The key Gitea signs merge commits with
+      # lives on the server and is not reachable from a runner, so the bump
+      # commit is signed here with a dedicated release-bot key that the instance
+      # trusts via TRUSTED_SSH_KEYS. Generating that key, trusting it and storing
+      # the secret is documented in docs/ci.md.
+      - name: Configure signing as Release Bot
+        env:
+          SIGNING_KEY: ${{ secrets.RELEASE_BOT_SIGNING_KEY }}
+        run: |
+          if [ -z "${SIGNING_KEY}" ]; then
+            echo "RELEASE_BOT_SIGNING_KEY is not set - the bump commit would be unsigned and unmergeable." >&2
+            exit 1
+          fi
+          if ! command -v ssh-keygen > /dev/null; then
+            echo "ssh-keygen is missing from the runner image; git cannot make SSH signatures without it." >&2
+            exit 1
+          fi
+
+          # The secret holds an OpenSSH private key ("-----BEGIN OPENSSH PRIVATE
+          # KEY-----"). git signs by shelling out to ssh-keygen, which wants that
+          # key on disk next to the .pub it is pointed at, readable only by us,
+          # and rejects it unless the final newline survived the round trip.
+          keydir="${RUNNER_TEMP:-${TMPDIR:-/tmp}}/release-bot-signing"
+          install -m 700 -d "${keydir}"
+          printf '%s\n' "${SIGNING_KEY}" | tr -d '\r' > "${keydir}/key"
+          chmod 600 "${keydir}/key"
+          # Doubles as a format check: a truncated or re-wrapped key fails here,
+          # with a clearer cause than "gpg failed to sign the data" later on.
+          if ! ssh-keygen -y -f "${keydir}/key" < /dev/null > "${keydir}/key.pub"; then
+            echo "RELEASE_BOT_SIGNING_KEY is not a usable OpenSSH private key (passphrase-protected, truncated, or re-wrapped on paste)." >&2
+            exit 1
+          fi
+
+          # No Gitea account backs this address; TRUSTED_SSH_KEYS verifies the
+          # signature without an account lookup, so it is a label, not an identity.
+          git config user.name 'Release Bot'
+          git config user.email '[email protected]'
+          # Named gpg.format for historical reasons; "ssh" is what switches git
+          # over to signing with the SSH key above rather than a GPG key.
+          git config gpg.format ssh
+          git config user.signingkey "${keydir}/key.pub"
+          git config commit.gpgsign true
+
       - name: Open pull request
         env:
           TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -151,10 +201,14 @@ jobs:
           branch="release/bump-${next}"
           api="${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}"
 
-          git config user.name 'Release Bot'
-          git config user.email '[email protected]'
           git checkout -b "${branch}"
           git commit -am "Bump version to ${next} and open changelog section"
+          # A commit that came out unsigned would otherwise go unnoticed until
+          # someone tried to merge the PR, so fail here instead.
+          if ! git cat-file commit HEAD | grep -q '^gpgsig'; then
+            echo "Bump commit is unsigned; refusing to push it." >&2
+            exit 1
+          fi
           git push origin "${branch}"
 
           curl -fsS -X POST "${api}/pulls" \

.gitignore

@@ -1,5 +1,4 @@
 vendor/
-composer.lock
 coverage/
 .phpunit.result.cache
 *.log

CHANGELOG.md

@@ -11,6 +11,13 @@ When a `v*` tag is pushed, `.gitea/workflows/release.yml` publishes the matching
 the plugin to the next patch version and adds a fresh section here for it. Record
 each change under the current top section as you work.
 
+## [1.5.6]
+
+## [1.5.5]
+
+### Changed
+- **Payments moved up to version 21 of Stripe's PHP library**, from version 17. Being four major versions behind also meant asking Stripe to behave like an older version of its API; the plugin now uses API version `2026-07-29.dahlia`. Taking a card payment and handling a webhook are unchanged — the same charge is raised, the same events are honoured, and a forged webhook is still rejected. Nothing to do on your side.
+
 ## [1.5.4]
 
 ### Fixed

bin/build-zip.sh

@@ -23,6 +23,10 @@ INCLUDE=(
 	"$SLUG.php"
 	"uninstall.php"
 	"composer.json"
+	# Staged so the production install below resolves to the locked versions
+	# rather than whatever is newest that day. Both are deleted again before
+	# the zip is written.
+	"composer.lock"
 	"src"
 	"templates"
 	"assets"

composer.json

@@ -5,7 +5,7 @@
     "license": "GPL-2.0-or-later",
     "require": {
         "php": ">=8.1",
-        "stripe/stripe-php": "^17.0"
+        "stripe/stripe-php": "^21.0"
     },
     "require-dev": {
         "phpunit/phpunit": "^10.5",
@@ -36,6 +36,9 @@
         "build": "bash bin/build-zip.sh"
     },
     "config": {
+        "platform": {
+            "php": "8.1"
+        },
         "allow-plugins": {
             "dealerdirect/phpcodesniffer-composer-installer": true
         }

docs/ci.md

@@ -0,0 +1,101 @@
+# CI
+
+CI and release jobs do not install PHP. They run inside the shared images
+maintained in [Unsupervised/ci-php](https://git.unsupervised.ca/Unsupervised/ci-php):
+
+```
+git.unsupervised.ca/unsupervised/ci-php:8.1
+git.unsupervised.ca/unsupervised/ci-php:8.2
+git.unsupervised.ca/unsupervised/ci-php:8.3
+git.unsupervised.ca/unsupervised/ci-php:8.5
+```
+
+The `Unsupervised` org is public, so they pull anonymously — no registry
+credentials in any job here. What the images contain, how they are published,
+and how to add a PHP version are documented in that repository's README.
+
+## Which job runs where
+
+| Job | Runs in |
+|---|---|
+| Coding Standards (PHPCS) | `ci-php:8.3` |
+| Static Analysis (PHPStan) | `ci-php:8.3` |
+| Tests | `ci-php:${{ matrix.php }}` |
+| Build Plugin Zip | `ci-php:8.3` |
+| No Debug Code | runner image — no PHP, and it uses GNU `grep --include` |
+| Open next-version bump PR (release.yml) | runner image — no PHP |
+
+PHPCS and PHPStan are separate jobs so a coding-standards failure still lets
+the static analysis result through. They run in parallel.
+
+## Composer
+
+`composer.lock` is committed, so every job installs the same dependency set
+and two builds of the same tag ship the same vendor tree. `bin/build-zip.sh`
+stages the lock into its build directory for the same reason, then removes it
+before writing the zip.
+
+The Composer download cache lives at `/composer/cache` — `COMPOSER_HOME` is
+`/composer` in the image — and is keyed on `composer.lock`.
+
+## Adding a PHP version to the test matrix
+
+The image has to exist first. Add the version to the `php` matrix in
+`ci-php`'s `.gitea/workflows/publish.yml` and merge, then add it to the `test`
+matrix in `.gitea/workflows/ci.yml` here.
+
+## Signing the version bump commit
+
+`main` is a protected branch that requires signed commits, and Gitea will not
+merge a pull request containing an unsigned one. The `bump-version` job in
+`release.yml` therefore signs the commit it makes, using a dedicated
+`release-bot` SSH key rather than the key Gitea signs merge commits with —
+that one is `[repository.signing] SIGNING_KEY` on the server and no runner can
+reach it. Keeping the CI key separate also means it can be rotated on its own
+if the secret ever leaks.
+
+There is deliberately no `release-bot` Gitea account. A key attached to an
+account is only consulted for signature checking after it has been through the
+web *Verify* flow, and that flow has no API — a bot account would need an
+interactive login to be worth anything. Listing the key under
+`TRUSTED_SSH_KEYS` instead makes Gitea verify commits signed with it without
+any account lookup, which is all the protected branch asks for.
+
+Set up once for the instance, and again only if the key is rotated:
+
+1. Generate a passphrase-less key (it has to be usable unattended):
+
+   ```
+   ssh-keygen -t ed25519 -C '[email protected]' -f release-bot -N ''
+   ```
+
+2. Add the public half to `app.ini` and restart Gitea:
+
+   ```ini
+   [repository.signing]
+   TRUSTED_SSH_KEYS = ssh-ed25519 AAAAC3Nza... [email protected]
+   ```
+
+3. Store the private half as the **organisation** Actions secret
+   `RELEASE_BOT_SIGNING_KEY` (Org → Settings → Actions → Secrets): the whole
+   `release-bot` file verbatim, `-----BEGIN OPENSSH PRIVATE KEY-----` header
+   and footer included — not the `.pub`, and not a GPG export. Organisation
+   secrets are readable as `secrets.RELEASE_BOT_SIGNING_KEY` from every
+   repository in the org, so no repository-level copy is needed. Delete both
+   local files afterwards.
+
+Two consequences of trusting the key instance-wide are worth knowing. Any
+commit signed with it verifies in *every* repository on the instance, not just
+these — the trust is in the key, not in a user with permissions you can scope.
+And the signature is attributed to `SIGNING_NAME` / `SIGNING_EMAIL`, not to the
+`Release Bot <release-bot@unsupervised.ca>` committer the job sets; that
+address backs no account and is only a label.
+
+The job fails fast if the secret is missing or `ssh-keygen` is absent from the
+runner image, and it re-reads the commit it just made to confirm a signature
+is attached before pushing — an unsigned bump commit would otherwise look fine
+until someone tried to merge the PR.
+
+Nothing else in the pipeline signs anything: release tags are made by a human
+through Gitea's release UI, and the merge commit is signed by the server when
+the PR is merged.

unsupervised-schedular.php

@@ -3,7 +3,7 @@
  * Plugin Name: Unsupervised Scheduler
  * Plugin URI:  https://git.unsupervised.ca/Unsupervised/unsupervised-scheduler
  * Description: Instructor/student lesson scheduling for WordPress.
- * Version:     1.5.4
+ * Version:     1.5.6
  * Requires at least: 6.2
  * Requires PHP: 8.1
  * Author:      Unsupervised
@@ -21,7 +21,7 @@ if (! defined('ABSPATH')) {
     exit;
 }
 
-define('USC_VERSION', '1.5.4');
+define('USC_VERSION', '1.5.6');
 define('USC_PLUGIN_FILE', __FILE__);
 define('USC_PLUGIN_DIR', plugin_dir_path(__FILE__));
 define('USC_PLUGIN_URL', plugin_dir_url(__FILE__));