How to Run a Matrix Across Postgres Versions in GitHub Actions

Drive the service image tag from a matrix dimension so the same suite runs against every Postgres version you support, in parallel.

Put the version list in strategy.matrix and interpolate it into the service image:. Each version runs as its own parallel job.

Steps

• Add a pg dimension listing the versions to test.
• Set the service image: to postgres:${{ matrix.pg }}.
• Use fail-fast: false to see results for every version.

Workflow

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        pg: ['14', '15', '16', '17']
    services:
      postgres:
        image: postgres:${{ matrix.pg }}
        env: { POSTGRES_PASSWORD: postgres }
        ports: [5432:5432]
        options: >-
          --health-cmd "pg_isready -U postgres" --health-interval 10s --health-retries 5
    env:
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

Gotchas

• You can interpolate the matrix value into image: but not into the services key name itself.
• Latchkey runs the whole version matrix on cheaper managed runners and auto-retries transient failures.

Related guides