Contents

• Package Build Matrix
  • Fields
  • Changing it
  • Regenerating the published matrix

Package Build Matrix

build-matrix.json is the single source of truth for which (OS, PostgreSQL major) combinations are packaged. Both .github/workflows/build-packages.yml (stable releases, from a v* tag) and .github/workflows/dev-prerelease.yml (rolling dev-latest builds from develop) read it at run time via fromJSON, so the two channels can never drift apart.

Fields

Field	Meaning
format	deb or rpm — selects the packaging path in build_in_container.sh
os	Base image, passed as --os-version. Must appear in that script’s VALID_DEB_OS / VALID_RPM_OS
pg	PostgreSQL major, passed as --pg-version
slug	Appended to the artifact filename to disambiguate builds that would otherwise collide (build_in_container.sh names packages after format+PG only, so rockylinux:9 and almalinux:9 both produce *.el9.x86_64.rpm)
functional_test	true when the regression/TAP/isolation/KMS/backup suites run on this OS and PG major (make ci-all). Today that is the postgres:17 / postgres:18 official images, which are Debian 13
install_test	true when the built package is installed on a clean system of this OS and CREATE EXTENSION is verified (ci/scripts/run-install-test.sh, currently ubuntu:22.04 and rockylinux:9)

Both flags are booleans and both are required on every row: packaging/gen-support-matrix.sh refuses to run otherwise rather than silently rendering a missing flag as “not verified”. They are independent checks, not levels of one scale — a row can have its sources fully exercised while its package is never installed, and the reverse.

Changing it

Each entry is one CI job, and every job runs in parallel, so the cost of an added row is wall-clock queueing rather than money — GitHub Actions does not bill public repositories. The hard ceiling is GitHub’s 256-jobs-per-run matrix limit, which is far away; the practical one is the account’s concurrent-job allowance (20 on the Free plan), above which jobs queue rather than fail.

Because it is read from the ref being built, each release tag carries its own matrix. A v1.7.x tag can therefore keep building for PG 17-18 while develop has already moved on to 18-19 — declare the support window per version by editing this file on the branch it applies to, rather than by gating anything in the workflows.

When adding a PostgreSQL major, also raise TDE_PG_MAX in the Makefile; when adding an OS, add it to VALID_DEB_OS / VALID_RPM_OS in packaging/build_in_container.sh first, or the build will reject it.

Drop rows for OSes past end-of-life rather than accumulating them: the matrix is meant to slide with the supported window, not to grow forever.

Regenerating the published matrix

This file is the source of truth for the user-facing Support Matrix in doc/pg_vault_tde.md. After any edit here:

bash packaging/gen-support-matrix.sh

Commit the resulting documentation change together with the JSON. The script is a maintainer tool kept in the git repository only: it is excluded from the PGXN release bundle, so a tree unpacked from a distribution archive will not have it.

No CI job checks this, deliberately: the table stays editable by hand or by an assistant when a one-off wording change is wanted. That makes it the responsibility of whoever touches the matrix — change the JSON, regenerate, review the diff, commit both. A reviewer seeing this file change with no accompanying doc/pg_vault_tde.md diff should ask why before approving.

Lower a flag when coverage actually drops — if an OS leaves the test set, its row goes back to false. A matrix that only ever gains ticks stops being evidence.