David E. Wheeler: Build, Test and Release Extensions with the New PGXN GitHub Actions

I’ve made three new GitHub actions in the past few months to replace the venerable Docker-based pgxn/pgxn-tools, which has become bloated and requires more work to maintain than I’d like. The new actions require much less maintenance, support all GitHub runner OSes and architectures, and run more quickly. What they do:
- pgxn/postgres-action starts a local, specific version of Postgres server
- pgxn/matrix-action generates a matrix of Postgres versions to test
- pgxn/release-action releases an extension on PGXN
Make a Release
Starting simple, here’s how to use the release action:
name: 🚀 Release on: push: jobs: release: name: Release on PGXN runs-on: ubuntu-latest steps: uses: actions/checkout@v7 uses: pgxn/release-action@v0 with: username: ${{ secrets.PGXN_USERNAME }} password: ${{ secrets.PGXN_PASSWORD }} dry-run: ${{ !startsWith( github.ref, 'refs/tags/v' ) }} Yep, that’s it. The pgxn/release-action action will use git archive to create a PGXN bundle and release it on PGXN. (Want to omit some files, such as GitHub workflows, from the release? Use gitattributes to exclude them!) The value passed for the dry-run option prevents publishing the bundle on PGXN except when pushing a Git tag starting with v.
The action also outputs the archive name, so you can use it elsewhere, such as a GitHub release on the last line of this workflow:
name: 🚀 Release on: push: jobs: release: name: Release on GitHub and PGXN runs-on: ubuntu-latest steps: - name: Check out the repo uses: actions/checkout@v7 - name: Release on PGXN uses: pgxn/release-action@v0 id: pgxn with: username: ${{ secrets.PGXN_USERNAME }} password: ${{ secrets.PGXN_PASSWORD }} dry-run: ${{ !startsWith( github.ref, 'refs/tags/v' ) }} - name: Create GitHub Release uses: softprops/action-gh-release@v3 if: startsWith( github.ref, 'refs/tags/v' ) env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: name: "Release ${{ github.ref_name }}" files: ${{ steps.pgxn.outputs.archive }} It again checks github.ref to only release on a tag starting with v. Then it includes the archive output from the pgxn step in the release. Simple, right? Want to include a changelog in the release? Consider using a Keep a Changelog file and theory/changelog-version-notes-action to generate a file to pass to the softprops/action-gh-release body_path option.
Test Supported Versions & Platforms
This example, from pg-hostname, uses the pgxn/matrix-action action to generate the test matrix, and pgxn/postgres-action to start Postgres. Then it builds and tests the extension:
| |

Workout.
The resulting output resembles the image on to the right.
I admit it seems like a lot; let’s break it down:
- The
matrixjob starting on line 7 generates the test matrix- Lines 10-11 define the output for the matrix
- Lines 13-20 use pgxn/matrix-action to generate the matrix
- The options on line 17-20 set the minimum Postgres version to 9.0, allow the inclusion of beta and deprecated releases (e.g, those provided by but deprecated by the packager), and exclude
windows
- The
buildjob starting on line 22 builds and tests the extension- Line 23 requires that the
matrixjob finish before this one starts - Line 27 generates the
pgmatrix, usingfromJson()to extract the output of thematrixjob - Various matrix fields construct the
nameon line 28 - Line 29 specifies the runner provided by the matrix
- Lines 32-33 use the pgxn/postgres-action to start the matrix-specified version of Postgres on the runner — no more Docker container!
- Lines 34-37 define the typical PGXS pattern to build and test the extension; note the use of
sudoto install the extension, required because the Linux runner does not own the Postgres install (and is harmless on other OSes) - The
Show Diffsstep starting on line 38 shows the contents ofregression.diffsif the test failed - And the upload action from line 41 on upload
regression.diffsand the test result files if the test failed
- Line 23 requires that the
A daily pgxn/matrix-action workflow updates its list of all candidate configurations, so it should always be up-to date. Practically that means you automatically start testing the next Postgres version within a day of its first beta release, unless you set max-version.
Install, Build, Then Start
The pgxn/matrix-action and pgxn/postgres-action actions feature a number of input options to define the runners, Postgres versions, and various configurations.
Let’s say that your extension requires loading a module in shared_preload_libraries, but you have to install Postgres to build the module first. Use no-start to install but not start Postgres, then build the extension, and finally use pgxn/postgres-action again with the desired configuration:
# Install but don't start Postgres - uses: pgxn/postgres-action@v0 with: version: ${{ matrix.pg.version }} no-start: true # Build and install the extension. - run: make -j $(nproc) && sudo make install # Now start Postgres with the module in shared_preload_libraries - uses: pgxn/postgres-action@v0 with: version: ${{ matrix.pg.version }} config: | shared_preload_libraries = 'my_module' # Continue testing - run: make installcheck To Dos
I’ve been using these actions for a few months with a variety of extensions. Some examples:
But there remain a few things left to do:
- Proper Windows support. The pgxn/postgres-action workflow successfully tests a SQL-only extension on Windows Postgres 17-18, but not earlier versions due to a path issue. C extensions simply don’t work at all. I’m not sure whether the EDB Windows Postgres binaries installed by Chocolatey need adjusting or if the issues can be fixed by further configuration. Help wanted!
- I’d like to add a pgrx action, probably separate from the others. I’ll likely get to it sometime in the next few months unless someone beats me to it.
Thanks & Enjoy
Thanks for reading, I hope you find the new actions useful.
Props to Peter Eisentraut for demonstrating the use of the PGDG Apt repo for starting Postgres on Linux runners, to the ikalnytskyi/action-setup-postgres action for how to install and start Postgres on macOS and Windows runners, and to Apt maintainer Christoph Berg for patiently answering my questions about starting and running Postgres on Linux.