fix: snapshot publishing race + v4.0 arm64 build failure

fdcastel · fdcastel · commit f63bf31a13ef · 2026-04-28T03:17:02.000Z
The snapshot workflow had two related defects:

1. Multi-arch tags ended up single-arch. Both arch runners pushed the
   same firebirdsql/firebird:6-snapshot tag without manifest assembly;
   whichever runner finished last won. After the 2026-04-28 run,
   6-snapshot and 5-snapshot were arm64-only on Docker Hub, breaking
   amd64 users.

2. The v4.0 leg always failed on arm64 because FirebirdSQL/snapshots
   has no linux-arm64 asset for v4.0 (same root cause as D-015).

Fixes:

- Build-Snapshot now pushes by digest and saves the digest to
  generated/digests-snapshot-{arch}.json (mirrors Push-Digests for
  stable images).
- New Publish-Snapshot-Manifests task assembles a multi-arch (or
  amd64-only) manifest from per-arch digest files.
- snapshot.yaml: per-arch builds upload digests as artifacts, then a
  separate create-manifests job assembles the manifest. Login moved
  before build (push-by-digest needs it). Matrix excludes
  branch=v4.0, arch=arm64.
- publish-fork.yaml uses the same flow (single-arch manifest since
  fork builds are amd64-only).
diff --git a/.github/workflows/publish-fork.yaml b/.github/workflows/publish-fork.yaml
@@ -161,13 +161,11 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          $assets = Get-Content -Raw ./assets.json | ConvertFrom-Json
-          $defaultDistro = $assets.config.defaultDistro
+          # Fork builds are amd64-only — Build-Snapshot pushes by digest, then
+          # Publish-Snapshot-Manifests assembles a single-arch manifest from it.
           foreach ($branch in @('master', 'v5.0-release')) {
             Invoke-Build Build-Snapshot -Branch $branch -Registry '${{ env.REGISTRY }}'
-            $tag = if ($branch -eq 'master') { '6-snapshot' } else { '5-snapshot' }
-            docker push "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:$tag"
-            docker push "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:$tag-$defaultDistro"
+            Invoke-Build Publish-Snapshot-Manifests -Branch $branch -Registry '${{ env.REGISTRY }}'
           }
 
       # Summary only for the amd64-only case (multi-arch summary is in create-manifests).
diff --git a/.github/workflows/snapshot.yaml b/.github/workflows/snapshot.yaml
@@ -6,6 +6,9 @@ name: snapshot
 #
 # Snapshot images use tags like '6-snapshot', '5-snapshot', '4-snapshot'
 # from the FirebirdSQL/snapshots GitHub repository.
+#
+# Multi-arch: each arch builds and pushes by digest, then a final job
+# assembles a multi-arch manifest via `docker buildx imagetools create`.
 
 on:
   schedule:
@@ -40,6 +43,11 @@ jobs:
             runner: ubuntu-latest
           - arch: arm64
             runner: ubuntu-24.04-arm
+        # Firebird 4.x has no linux-arm64 snapshot tarball (FirebirdSQL/snapshots
+        # ships Android arm64 only). Mirrors the FB3/FB4 amd64-only stable rule.
+        exclude:
+          - branch: v4.0
+            arch: arm64
     runs-on: ${{ matrix.runner }}
     steps:
       - name: Checkout
@@ -54,29 +62,62 @@ jobs:
           Install-Module InvokeBuild -Force
           Install-Module PSFirebird -MinimumVersion '1.0.0' -Force
 
-      - name: Build snapshot
+      - name: Login to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push snapshot (by digest)
         shell: pwsh
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           Invoke-Build Build-Snapshot -Branch '${{ matrix.branch }}'
 
+      - name: Upload digest
+        uses: actions/upload-artifact@v7
+        with:
+          name: digests-snapshot-${{ matrix.branch }}-${{ matrix.arch }}
+          path: generated/digests-snapshot-*.json
+          if-no-files-found: error
+          retention-days: 1
+
+  create-manifests:
+    if: ${{ github.repository == 'FirebirdSQL/firebird-docker' }}
+    needs: build-snapshot
+    strategy:
+      fail-fast: false
+      matrix:
+        branch: ${{ github.event_name == 'workflow_dispatch' && fromJSON(format('["{0}"]', inputs.branch)) || fromJSON('["master", "v5.0-release"]') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Download digests
+        uses: actions/download-artifact@v8
+        with:
+          path: generated
+          pattern: digests-snapshot-${{ matrix.branch }}-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Install tools
+        shell: pwsh
+        run: |
+          Install-Module InvokeBuild -Force
+          Install-Module PSFirebird -MinimumVersion '1.0.0' -Force
+
       - name: Login to Docker Hub
         uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      - name: Push snapshot
+      - name: Assemble multi-arch manifest
         shell: pwsh
         run: |
-          $branch = '${{ matrix.branch }}'
-          $tag = switch ($branch) {
-            'master'        { '6-snapshot' }
-            'v5.0-release'  { '5-snapshot' }
-            'v4.0'          { '4-snapshot' }
-          }
-          $assets = Get-Content -Raw ./assets.json | ConvertFrom-Json
-          $defaultDistro = $assets.config.defaultDistro
-          docker push "firebirdsql/firebird:$tag"
-          docker push "firebirdsql/firebird:$tag-$defaultDistro"
+          Invoke-Build Publish-Snapshot-Manifests -Branch '${{ matrix.branch }}'
diff --git a/firebird-docker.build.ps1 b/firebird-docker.build.ps1
@@ -6,7 +6,7 @@ param(
     [string]$TestFilter,          # Filter by test name (e.g., 'FIREBIRD_USER_can_create_user'). Used only in the 'Test' task.
 
     [ValidateSet('master', 'v5.0-release', 'v4.0')]
-    [string]$Branch,              # Snapshot branch. Used only in the 'Build-Snapshot' task.
+    [string]$Branch,              # Snapshot branch. Used by 'Build-Snapshot' / 'Publish-Snapshot-Manifests'.
 
     [string]$Registry             # Image registry/owner prefix. Defaults to 'firebirdsql' (Docker Hub).
                                   # Override for forks: e.g. 'ghcr.io/myusername'
@@ -576,12 +576,34 @@ task Publish-Manifests FilteredAssets, {
     }
 }
 
-# Synopsis: Build a snapshot image from a Firebird pre-release branch.
-task Build-Snapshot LoadAssets, {
+# Helper: produces { snapshotTag, major, defaultDistro } for a given snapshot branch.
+function Get-SnapshotMeta($Branch) {
     if (-not $Branch) {
-        throw "The -Branch parameter is required for Build-Snapshot. Use: Invoke-Build Build-Snapshot -Branch master"
+        throw "The -Branch parameter is required. Use: -Branch master|v5.0-release|v4.0"
+    }
+    $snapshotTag = switch ($Branch) {
+        'master'        { '6-snapshot' }
+        'v5.0-release'  { '5-snapshot' }
+        'v4.0'          { '4-snapshot' }
+        default         { throw "Unknown snapshot branch: $Branch" }
+    }
+    $major = switch ($Branch) {
+        'master'        { '6' }
+        'v5.0-release'  { '5' }
+        'v4.0'          { '4' }
+    }
+    [pscustomobject]@{
+        SnapshotTag   = $snapshotTag
+        Major         = $major
+        DefaultDistro = $script:assetsData.config.defaultDistro
     }
+}
 
+# Synopsis: Build a snapshot image and push it by digest to the registry.
+# Saves the digest to generated/digests-snapshot-{arch}.json so a later
+# Publish-Snapshot-Manifests run can assemble the multi-arch manifest.
+# Caller must be logged into the registry before invoking this task.
+task Build-Snapshot LoadAssets, {
     # PSFirebird is required for this task
     if (-not (Get-Module PSFirebird -ListAvailable)) {
         Install-Module PSFirebird -MinimumVersion '1.0.0' -Force -Scope CurrentUser
@@ -591,7 +613,10 @@ task Build-Snapshot LoadAssets, {
     $PSStyle.OutputRendering = 'PlainText'
     $imagePrefix = $script:imagePrefix
     $imageName = 'firebird'
-    $defaultDistro = $script:assetsData.config.defaultDistro
+    $meta = Get-SnapshotMeta $Branch
+    $snapshotTag = $meta.SnapshotTag
+    $major = $meta.Major
+    $defaultDistro = $meta.DefaultDistro
 
     # Detect host architecture
     $hostArch = if ($IsLinux) { (dpkg --print-architecture 2>$null) ?? 'amd64' } else { 'amd64' }
@@ -602,20 +627,6 @@ task Build-Snapshot LoadAssets, {
 
     Write-Build Cyan "Found: $($snapshot.FileName) (uploaded: $($snapshot.UploadedAt))"
 
-    # Determine version tag from branch
-    $snapshotTag = switch ($Branch) {
-        'master'        { '6-snapshot' }
-        'v5.0-release'  { '5-snapshot' }
-        'v4.0'          { '4-snapshot' }
-    }
-
-    # Determine major version for Dockerfile template
-    $major = switch ($Branch) {
-        'master'        { '6' }
-        'v5.0-release'  { '5' }
-        'v4.0'          { '4' }
-    }
-
     # Prepare snapshot Dockerfile
     $snapshotFolder = Join-Path $outputFolder "snapshot-$Branch" $defaultDistro
     New-Item -ItemType Directory $snapshotFolder -Force > $null
@@ -645,24 +656,71 @@ task Build-Snapshot LoadAssets, {
     Write-GeneratedFile -Content $dockerfile -Destination "$snapshotFolder/Dockerfile"
     Copy-Item './src/entrypoint.sh' $snapshotFolder
 
-    # Tag with both the bare alias (e.g. `6-snapshot`) and the base-qualified form
-    # (e.g. `6-snapshot-trixie`) so users can tell which distro the snapshot was built on.
-    $snapshotTagWithDistro = "$snapshotTag-$defaultDistro"
-
-    # Build
+    # Build and push by digest. Final tags (e.g. `6-snapshot`, `6-snapshot-trixie`)
+    # are assembled from per-arch digests by Publish-Snapshot-Manifests.
+    $metadataFile = Join-Path ([System.IO.Path]::GetTempPath()) "metadata-snapshot-$Branch.json"
     $buildArgs = @(
-        'buildx', 'build', '--load'
-        '--tag', "$imagePrefix/${imageName}:$snapshotTag"
-        '--tag', "$imagePrefix/${imageName}:$snapshotTagWithDistro"
+        'buildx', 'build'
+        '--output', "type=image,name=$imagePrefix/$imageName,push-by-digest=true,name-canonical=true,push=true"
+        '--metadata-file', $metadataFile
         '--label', 'org.opencontainers.image.description=Firebird Database (snapshot)'
         '--label', "org.opencontainers.image.version=$snapshotTag"
         '--progress=plain'
         $snapshotFolder
     )
-    Write-Build Cyan "----- [snapshot / $Branch / $defaultDistro / $hostArch] -----"
+    Write-Build Cyan "----- [snapshot / $Branch / $defaultDistro / $hostArch → push-by-digest] -----"
     exec { & docker $buildArgs *>&1 }
 
-    Write-Build Green "Snapshot image built: $imagePrefix/${imageName}:$snapshotTag (also tagged $snapshotTagWithDistro)"
+    $metadata = Get-Content $metadataFile -Raw | ConvertFrom-Json
+    $digest = $metadata.'containerimage.digest'
+
+    # Save digest for later manifest assembly
+    $digestFile = Join-Path $outputFolder "digests-snapshot-$hostArch.json"
+    New-Item -ItemType Directory (Split-Path $digestFile) -Force > $null
+    @{ $snapshotTag = $digest } | ConvertTo-Json | Out-File $digestFile -Encoding UTF8
+
+    Write-Build Green "Snapshot $snapshotTag pushed by digest: $digest"
+    Write-Build Green "Digest saved to $digestFile"
+}
+
+# Synopsis: Assemble a multi-arch (or single-arch) manifest for a snapshot branch
+# using digests previously written by Build-Snapshot. Reads
+# generated/digests-snapshot-amd64.json (required) and
+# generated/digests-snapshot-arm64.json (optional).
+task Publish-Snapshot-Manifests LoadAssets, {
+    $imagePrefix = $script:imagePrefix
+    $imageName = 'firebird'
+    $meta = Get-SnapshotMeta $Branch
+    $snapshotTag = $meta.SnapshotTag
+    $defaultDistro = $meta.DefaultDistro
+    $snapshotTagWithDistro = "$snapshotTag-$defaultDistro"
+
+    $amd64File = Join-Path $outputFolder 'digests-snapshot-amd64.json'
+    $arm64File = Join-Path $outputFolder 'digests-snapshot-arm64.json'
+
+    if (-not (Test-Path $amd64File)) {
+        throw "Required digest file not found: $amd64File. Run Build-Snapshot on amd64 first."
+    }
+    $amd64Digest = (Get-Content $amd64File -Raw | ConvertFrom-Json).$snapshotTag
+    if (-not $amd64Digest) {
+        throw "No digest for '$snapshotTag' in $amd64File."
+    }
+
+    $sources = @("$imagePrefix/${imageName}@$amd64Digest")
+    if (Test-Path $arm64File) {
+        $arm64Digest = (Get-Content $arm64File -Raw | ConvertFrom-Json).$snapshotTag
+        if ($arm64Digest) {
+            $sources += "$imagePrefix/${imageName}@$arm64Digest"
+        }
+    }
+
+    foreach ($tag in @($snapshotTag, $snapshotTagWithDistro)) {
+        Write-Build Cyan "  $tag → manifest ($($sources.Count) arch)"
+        $tagArgs = @('buildx', 'imagetools', 'create', '--tag', "$imagePrefix/${imageName}:$tag") + $sources
+        exec { & docker $tagArgs *>&1 }
+    }
+
+    Write-Build Green "Snapshot manifests published: $snapshotTag, $snapshotTagWithDistro"
 }
 
 # Synopsis: Default task.
