Support immutable multi-arch image releases

Split the upstream PostgreSQL base version from the published image version so image rebuilds can use revision tags without changing the postgres:<version> base image.

Publish local builds through Buildx for linux/amd64 and linux/arm64, and refuse to overwrite existing release tags in both the local script and GitHub Actions workflow.

Add revision-based release ergonomics via update.sh -r/--revision and document the normal base-version release flow versus image-only rebuilds.

Author: fidalgo

.github/workflows/publish.yml

@@ -8,9 +8,11 @@ on:
   workflow_dispatch:
     inputs:
       postgres_version:
-        description: 'PostgreSQL version to build'
-        required: true
-        default: '18.1'
+        description: 'PostgreSQL base image version to build from'
+        required: false
+      revision:
+        description: 'Image rebuild revision, e.g. 1 publishes <postgres_version>-r1'
+        required: false
 
 env:
   REGISTRY_DOCKER: docker.io
@@ -50,9 +52,49 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Read VERSION
+      - name: Read versions
         id: version
-        run: echo "VERSION=$(cat VERSION)" >> $GITHUB_OUTPUT
+        run: |
+          POSTGRES_VERSION="${{ github.event.inputs.postgres_version }}"
+          REVISION="${{ github.event.inputs.revision }}"
+
+          if [ -z "$POSTGRES_VERSION" ]; then
+            POSTGRES_VERSION="$(cat POSTGRES_VERSION)"
+          fi
+
+          if [ -n "$REVISION" ]; then
+            if ! [[ "$REVISION" =~ ^[1-9][0-9]*$ ]]; then
+              echo "Revision must be a positive integer." >&2
+              exit 1
+            fi
+
+            IMAGE_VERSION="$POSTGRES_VERSION-r$REVISION"
+          else
+            IMAGE_VERSION="$(cat VERSION)"
+          fi
+
+          echo "POSTGRES_VERSION=$POSTGRES_VERSION" >> "$GITHUB_OUTPUT"
+          echo "IMAGE_VERSION=$IMAGE_VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Refuse existing release tag
+        if: github.event_name != 'pull_request'
+        run: |
+          IMAGE_VERSION="${{ steps.version.outputs.IMAGE_VERSION }}"
+
+          for image in \
+            "${{ env.REGISTRY_DOCKER }}/ethoslink/postgres-backrest" \
+            "${{ env.REGISTRY_GHCR }}/${{ env.IMAGE_NAME }}"
+          do
+            if docker buildx imagetools inspect "$image:$IMAGE_VERSION" >/dev/null 2>&1; then
+              echo "Refusing to overwrite existing image tag: $image:$IMAGE_VERSION" >&2
+              exit 1
+            fi
+          done
+
+          if git ls-remote --exit-code --tags origin "refs/tags/$IMAGE_VERSION" >/dev/null 2>&1; then
+            echo "Refusing to recreate existing git tag: $IMAGE_VERSION" >&2
+            exit 1
+          fi
 
       - name: Extract metadata (tags, labels) for Docker
         id: meta
@@ -62,15 +104,13 @@ jobs:
             ${{ env.REGISTRY_DOCKER }}/ethoslink/postgres-backrest
             ${{ env.REGISTRY_GHCR }}/${{ env.IMAGE_NAME }}
           tags: |
-            type=schedule
-            type=ref,event=branch
-            type=ref,event=tag
             type=ref,event=pr
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
             type=raw,value=latest,enable={{is_default_branch}}
-            type=raw,value=${{ steps.version.outputs.VERSION }}
+            type=raw,value=${{ steps.version.outputs.IMAGE_VERSION }}
             type=sha
+          labels: |
+            org.opencontainers.image.version=${{ steps.version.outputs.IMAGE_VERSION }}
+            org.opencontainers.image.base.name=docker.io/library/postgres:${{ steps.version.outputs.POSTGRES_VERSION }}
 
       - name: Extract first Docker tag
         id: extract_tag
@@ -92,7 +132,7 @@ jobs:
           push: ${{ github.event_name != 'pull_request' }}
           platforms: ${{ github.event_name == 'pull_request' && 'linux/amd64' || 'linux/amd64,linux/arm64' }}
           build-args: |
-            POSTGRES_VERSION=${{ steps.version.outputs.VERSION }}
+            POSTGRES_VERSION=${{ steps.version.outputs.POSTGRES_VERSION }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
@@ -112,7 +152,7 @@ jobs:
       - name: Create Git Tag
         if: github.event_name == 'push' && github.ref == 'refs/heads/master'
         run: |
-          VERSION="${{ steps.version.outputs.VERSION }}"
+          VERSION="${{ steps.version.outputs.IMAGE_VERSION }}"
           git tag "$VERSION"
           git push origin "$VERSION"
 
@@ -122,10 +162,10 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
-          tag_name: ${{ steps.version.outputs.VERSION }}
-          release_name: PostgreSQL ${{ steps.version.outputs.VERSION }}
+          tag_name: ${{ steps.version.outputs.IMAGE_VERSION }}
+          release_name: Image ${{ steps.version.outputs.IMAGE_VERSION }} for PostgreSQL ${{ steps.version.outputs.POSTGRES_VERSION }}
           body: |
-            PostgreSQL ${{ steps.version.outputs.VERSION }}
+            PostgreSQL base image: ${{ steps.version.outputs.POSTGRES_VERSION }}
+            Image version: ${{ steps.version.outputs.IMAGE_VERSION }}
           draft: false
           prerelease: false
-

POSTGRES_VERSION

@@ -0,0 +1 @@
+18.3

README.md

@@ -133,12 +133,47 @@ To build the image locally with a specific PostgreSQL version:
 ```bash
 # Using update.sh (recommended)
 ./update.sh <version>
-docker build -t ethoslink/postgres-backrest:<version> .
+docker build --build-arg POSTGRES_VERSION=<version> -t ethoslink/postgres-backrest:<version> .
 
 # Or directly with build-arg
 docker build --build-arg POSTGRES_VERSION=18.2 -t ethoslink/postgres-backrest:18.2 .
 ```
 
+To publish the multi-arch image for `linux/amd64` and `linux/arm64`, use
+Buildx:
+
+```bash
+docker login docker.io
+docker login ghcr.io
+./build.sh
+```
+
+The script pushes both the version tag and `latest` to Docker Hub and GHCR.
+`POSTGRES_VERSION` is the upstream base image tag. `IMAGE_VERSION` is this
+image's published release tag. Keep them separate when rebuilding this image on
+the same PostgreSQL release.
+
+For image-only rebuilds, prefer a revision suffix such as `18.3-r1` over
+`18.3.1`, because `18.3.1` can be mistaken for an upstream PostgreSQL patch
+version.
+
+Override `PLATFORMS`, `POSTGRES_VERSION`, `IMAGE_VERSION`, `PUBLISH_LATEST`,
+or `IMAGES` when needed:
+
+```bash
+PLATFORMS=linux/amd64,linux/arm64 \
+POSTGRES_VERSION=18.3 \
+IMAGE_VERSION=18.3-r1 \
+IMAGES="docker.io/ethoslink/postgres-backrest ghcr.io/ethos-link/postgres-backrest" \
+./build.sh
+```
+
+`build.sh` refuses to publish an image version that already exists in any
+target registry. Use a new `IMAGE_VERSION` for normal releases.
+
+The GitHub Actions publish workflow also builds and pushes
+`linux/amd64,linux/arm64` on `master`.
+
 ## Security & Maintenance
 
 The image is based on the official Debian-based PostgreSQL image and installs `pgbackrest` from the official apt repositories.
@@ -159,7 +194,7 @@ The image is published to:
 To bump the PostgreSQL version and create a new release:
 
 ```bash
-# Bump the version (updates Dockerfile + VERSION file)
+# Bump the base and image versions
 ./update.sh 18.3
 
 # Commit and push
@@ -169,16 +204,26 @@ git push origin <branch>
 
 Then create a PR and merge to `master`. GitHub Actions will:
 
-1. Build and push the Docker image with the new version tag
-2. Create a git tag (e.g., `18.3`)
-3. Create a GitHub Release with "PostgreSQL 18.3"
+1. Refuse to publish if the image version tag already exists
+2. Build and push the Docker image with the new image version tag
+3. Create a git tag (e.g., `18.3`)
+4. Create a GitHub Release
+
+For an image-only rebuild on the same PostgreSQL base version, pass a revision:
+
+```bash
+./update.sh 18.3 -r=1
+```
+
+This keeps `POSTGRES_VERSION=18.3` and sets `IMAGE_VERSION=18.3-r1`.
 
-You can also pass a version manually to trigger a workflow dispatch:
+You can also pass a base version and revision manually to trigger a workflow
+dispatch:
 
 ```bash
 # Via GitHub UI to manually trigger a build
 # Or via CLI:
-gh workflow run publish.yml -f postgres_version=18.3
+gh workflow run publish.yml -f postgres_version=18.3 -f revision=1
 ```
 
 ## License

build.sh

@@ -1,46 +1,50 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Build and push the postgres-backrest image to multiple registries
+# Build and push a multi-arch postgres-backrest image to multiple registries.
 
 # Default values
-POSTGRES_VERSION="${POSTGRES_VERSION:-18.1}"
-IMAGE_NAME="${IMAGE_NAME:-postgres-backrest}"
-REGISTRIES="${REGISTRIES:-docker.io ghcr.io}"
+POSTGRES_VERSION="${POSTGRES_VERSION:-$(cat POSTGRES_VERSION)}"
+IMAGE_VERSION="${IMAGE_VERSION:-$(cat VERSION)}"
+PLATFORMS="${PLATFORMS:-linux/amd64,linux/arm64}"
+IMAGES="${IMAGES:-docker.io/ethoslink/postgres-backrest ghcr.io/ethos-link/postgres-backrest}"
+BUILDER="${BUILDER:-postgres-backrest-builder}"
+ALLOW_TAG_OVERWRITE="${ALLOW_TAG_OVERWRITE:-0}"
+PUBLISH_LATEST="${PUBLISH_LATEST:-1}"
+
+for image in $IMAGES; do
+    if [ "${ALLOW_TAG_OVERWRITE}" != "1" ] && docker buildx imagetools inspect "${image}:${IMAGE_VERSION}" >/dev/null 2>&1; then
+        echo "Refusing to overwrite existing image tag: ${image}:${IMAGE_VERSION}" >&2
+        echo "Use a new IMAGE_VERSION, or set ALLOW_TAG_OVERWRITE=1 for an explicit overwrite." >&2
+        exit 1
+    fi
+done
 
-# Function to build and push to a registry
-build_and_push() {
-    local registry="$1"
-    local full_image="${registry}/${IMAGE_NAME}:${POSTGRES_VERSION}"
+if ! docker buildx inspect "${BUILDER}" >/dev/null 2>&1; then
+    docker buildx create --name "${BUILDER}" --driver docker-container --use
+else
+    docker buildx use "${BUILDER}"
+fi
 
-    echo "Building ${full_image}..."
-    DOCKER_BUILDKIT=1 docker build --build-arg POSTGRES_VERSION="${POSTGRES_VERSION}" -t "${full_image}" .
+docker buildx inspect --bootstrap >/dev/null
 
-    echo "Pushing ${full_image}..."
-    docker push "${full_image}"
+build_args=(
+    --platform "${PLATFORMS}"
+    --build-arg "POSTGRES_VERSION=${POSTGRES_VERSION}"
+    --label "org.opencontainers.image.version=${IMAGE_VERSION}"
+    --label "org.opencontainers.image.base.name=docker.io/library/postgres:${POSTGRES_VERSION}"
+    --push
+)
 
-    # Also tag as latest if it's the default version
-    if [ "${POSTGRES_VERSION}" = "18.1" ]; then
-        docker tag "${full_image}" "${registry}/${IMAGE_NAME}:latest"
-        docker push "${registry}/${IMAGE_NAME}:latest"
-    fi
-}
-
-# Login to registries (you need to set credentials)
-for registry in $REGISTRIES; do
-    echo "Logging into ${registry}..."
-    # You need to set DOCKER_USERNAME and DOCKER_PASSWORD or use docker login manually
-    if [ -n "${DOCKER_USERNAME:-}" ] && [ -n "${DOCKER_PASSWORD:-}" ]; then
-        echo "${DOCKER_PASSWORD}" | docker login "${registry}" -u "${DOCKER_USERNAME}" --password-stdin
-    else
-        echo "Please set DOCKER_USERNAME and DOCKER_PASSWORD or login manually to ${registry}"
-        exit 1
+for image in $IMAGES; do
+    build_args+=(--tag "${image}:${IMAGE_VERSION}")
+
+    if [ "${PUBLISH_LATEST}" = "1" ]; then
+        build_args+=(--tag "${image}:latest")
     fi
 done
 
-# Build and push to each registry
-for registry in $REGISTRIES; do
-    build_and_push "$registry"
-done
+echo "Building ${IMAGES}:${IMAGE_VERSION} from postgres:${POSTGRES_VERSION} for ${PLATFORMS}..."
+docker buildx build "${build_args[@]}" .
 
-echo "Done."
+echo "Published ${IMAGE_VERSION} for ${PLATFORMS}."

update.sh

@@ -1,21 +1,65 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Update the PostgreSQL version in the Dockerfile
+# Update the PostgreSQL base image version and image release tag.
 
-if [ $# -ne 1 ]; then
-    echo "Usage: $0 <postgres_version>"
-    echo "Example: $0 17.0"
+usage() {
+    echo "Usage: $0 <postgres_version> [-r=<revision>|--revision=<revision>]"
+    echo "Examples:"
+    echo "  $0 18.4"
+    echo "  $0 18.3 -r=1"
     exit 1
+}
+
+if [ $# -lt 1 ]; then
+    usage
+fi
+
+NEW_POSTGRES_VERSION="$1"
+REVISION=""
+
+shift
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        -r=*|--revision=*)
+            REVISION="${1#*=}"
+            ;;
+        -r|--revision)
+            shift
+            if [ $# -eq 0 ]; then
+                usage
+            fi
+            REVISION="$1"
+            ;;
+        -*)
+            usage
+            ;;
+        *)
+            usage
+            ;;
+    esac
+    shift
+done
+
+if [ -n "${REVISION}" ]; then
+    if ! [[ "${REVISION}" =~ ^[1-9][0-9]*$ ]]; then
+        echo "Revision must be a positive integer." >&2
+        exit 1
+    fi
+
+    NEW_IMAGE_VERSION="${NEW_POSTGRES_VERSION}-r${REVISION}"
 fi
 
-NEW_VERSION="$1"
+NEW_IMAGE_VERSION="${NEW_IMAGE_VERSION:-$NEW_POSTGRES_VERSION}"
 
 # Update the default ARG in Dockerfile
-sed -i "s/ARG POSTGRES_VERSION=.*/ARG POSTGRES_VERSION=${NEW_VERSION}/" Dockerfile
+sed -i "s/ARG POSTGRES_VERSION=.*/ARG POSTGRES_VERSION=${NEW_POSTGRES_VERSION}/" Dockerfile
 
-# Update VERSION file
-echo "${NEW_VERSION}" > VERSION
+# Update version files
+echo "${NEW_POSTGRES_VERSION}" > POSTGRES_VERSION
+echo "${NEW_IMAGE_VERSION}" > VERSION
 
-echo "Updated Dockerfile and VERSION file to use PostgreSQL version ${NEW_VERSION}"
-echo "You can now build and test the image."
+echo "Updated PostgreSQL base version to ${NEW_POSTGRES_VERSION}"
+echo "Updated image release version to ${NEW_IMAGE_VERSION}"
+echo "You can now build and test the image."