From 09d444c7ab4f77b7596a33ed84488d7ad6fae030 Mon Sep 17 00:00:00 2001
From: Alan George <alan.george@livekit.io>
Date: Wed, 17 Jun 2026 18:39:48 -0600
Subject: [PATCH 1/3] Minimize docker build

---
 .github/workflows/builds.yml        | 253 ---------------------------
 .github/workflows/ci.yml            |  13 +-
 .github/workflows/docker-builds.yml | 262 ++++++++++++++++++++++++++++
 3 files changed, 274 insertions(+), 254 deletions(-)
 create mode 100644 .github/workflows/docker-builds.yml

diff --git a/.github/workflows/builds.yml b/.github/workflows/builds.yml
index 9f6436fd..0396421a 100644
--- a/.github/workflows/builds.yml
+++ b/.github/workflows/builds.yml
@@ -330,256 +330,3 @@ jobs:
           else
             ./build.sh clean-all || true
           fi
-
-  docker-build-x64:
-    name: Build (docker-linux-x64)
-    runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request'
-
-    steps:
-      - name: Checkout (with submodules)
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          submodules: recursive
-          fetch-depth: 0
-
-      - name: Check if Dockerfile.base changed
-        id: base_changed
-        shell: bash
-        run: |
-          set -euo pipefail
-          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -q '^docker/Dockerfile\.base$'; then
-            echo "changed=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "changed=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Free disk space
-        uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
-        with:
-          tool-cache: false
-          android: true
-          dotnet: true
-          haskell: true
-          large-packages: true
-          docker-images: true
-          swap-storage: true
-
-      - name: Pull base image from GHCR
-        if: steps.base_changed.outputs.changed == 'false'
-        shell: bash
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -euxo pipefail
-          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
-          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
-          docker pull "ghcr.io/${owner}/client-sdk-cpp-base:base-main-amd64"
-          docker tag "ghcr.io/${owner}/client-sdk-cpp-base:base-main-amd64" \
-            "livekit-cpp-sdk-base-x64:${{ github.sha }}"
-
-      - name: Build base Docker image
-        if: steps.base_changed.outputs.changed == 'true'
-        run: |
-          docker build \
-            --build-arg TARGETARCH=amd64 \
-            -t livekit-cpp-sdk-base-x64:${{ github.sha }} \
-            -f docker/Dockerfile.base \
-            docker
-
-      - name: Build SDK Docker image
-        run: |
-          docker build \
-            --build-arg BASE_IMAGE=livekit-cpp-sdk-base-x64:${{ github.sha }} \
-            -t livekit-cpp-sdk-x64:${{ github.sha }} \
-            . \
-            -f docker/Dockerfile.sdk
-
-      - name: Verify installed SDK inside image
-        run: |
-          docker run --rm livekit-cpp-sdk-x64:${{ github.sha }} bash -c \
-            'test -f /opt/livekit-sdk/lib/cmake/LiveKit/LiveKitConfig.cmake'
-
-      - name: Save Docker image artifact
-        run: |
-          docker save livekit-cpp-sdk-x64:${{ github.sha }} | gzip > livekit-cpp-sdk-x64-docker.tar.gz
-
-      - name: Upload Docker image artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: livekit-cpp-sdk-docker-x64
-          path: livekit-cpp-sdk-x64-docker.tar.gz
-          retention-days: 7
-
-  docker-build-linux-arm64:
-    name: Build (docker-linux-arm64)
-    runs-on: ubuntu-24.04-arm
-    if: github.event_name == 'pull_request'
-
-    steps:
-      - name: Checkout (with submodules)
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          submodules: recursive
-          fetch-depth: 0
-
-      - name: Check if Dockerfile.base changed
-        id: base_changed
-        shell: bash
-        run: |
-          set -euo pipefail
-          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -q '^docker/Dockerfile\.base$'; then
-            echo "changed=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "changed=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Free disk space
-        uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
-        with:
-          tool-cache: false
-          android: true
-          dotnet: true
-          haskell: true
-          large-packages: true
-          docker-images: true
-          swap-storage: true
-
-      - name: Pull base image from GHCR
-        if: steps.base_changed.outputs.changed == 'false'
-        shell: bash
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -euxo pipefail
-          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
-          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
-          docker pull "ghcr.io/${owner}/client-sdk-cpp-base:base-main-arm64"
-          docker tag "ghcr.io/${owner}/client-sdk-cpp-base:base-main-arm64" \
-            "livekit-cpp-sdk-base-arm64:${{ github.sha }}"
-
-      - name: Build base Docker image
-        if: steps.base_changed.outputs.changed == 'true'
-        run: |
-          docker build \
-            --build-arg TARGETARCH=arm64 \
-            -t livekit-cpp-sdk-base-arm64:${{ github.sha }} \
-            -f docker/Dockerfile.base \
-            docker
-
-      - name: Build SDK Docker image
-        run: |
-          docker build \
-            --build-arg BASE_IMAGE=livekit-cpp-sdk-base-arm64:${{ github.sha }} \
-            -t livekit-cpp-sdk:${{ github.sha }} \
-            . \
-            -f docker/Dockerfile.sdk
-
-      - name: Verify installed SDK inside image
-        run: |
-          docker run --rm livekit-cpp-sdk:${{ github.sha }} bash -c \
-            'test -f /opt/livekit-sdk/lib/cmake/LiveKit/LiveKitConfig.cmake'
-
-      - name: Save Docker image artifact
-        run: |
-          docker save livekit-cpp-sdk:${{ github.sha }} | gzip > livekit-cpp-sdk-arm64-docker.tar.gz
-
-      - name: Upload Docker image artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: livekit-cpp-sdk-docker-arm64
-          path: livekit-cpp-sdk-arm64-docker.tar.gz
-          retention-days: 7
-
-  build-collections-linux-arm64:
-    name: Build (cpp-example-collection-linux-arm64)
-    runs-on: ubuntu-24.04-arm
-    needs: docker-build-linux-arm64
-    if: github.event_name == 'pull_request'
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          fetch-depth: 1
-
-      # Reclaim ~30GB before loading the multi-GB SDK image and building the
-      # example collection inside it. Mirrors the docker-build jobs; without it
-      # the x64 collection build has hit "no space left on device".
-      - name: Free disk space
-        uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
-        with:
-          tool-cache: false
-          android: true
-          dotnet: true
-          haskell: true
-          large-packages: true
-          docker-images: true
-          swap-storage: true
-
-      - name: Download Docker image artifact
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: livekit-cpp-sdk-docker-arm64
-
-      - name: Load Docker image
-        run: gzip -dc livekit-cpp-sdk-arm64-docker.tar.gz | docker load
-
-      - name: Build cpp-example-collection against installed SDK
-        run: |
-          cpp_ex_ref="$(git rev-parse HEAD:cpp-example-collection)"
-          docker run -e CPP_EX_REF="${cpp_ex_ref}" --rm livekit-cpp-sdk:${{ github.sha }} bash -lc '
-            set -euxo pipefail
-            git clone https://github.com/livekit-examples/cpp-example-collection.git /tmp/cpp-example-collection
-            cd /tmp/cpp-example-collection
-            git fetch --depth 1 origin "$CPP_EX_REF"
-            git checkout "$CPP_EX_REF"
-            cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR=/opt/livekit-sdk
-            cmake --build build --parallel
-          '
-  build-collections-x64:
-    name: Build (cpp-example-collection-x64)
-    runs-on: ubuntu-latest
-    needs: docker-build-x64
-    if: github.event_name == 'pull_request'
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          fetch-depth: 1
-
-      # Reclaim ~30GB before loading the multi-GB SDK image and building the
-      # example collection inside it. The standard ubuntu-latest runner has hit
-      # "no space left on device" here without this step.
-      - name: Free disk space
-        uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
-        with:
-          tool-cache: false
-          android: true
-          dotnet: true
-          haskell: true
-          large-packages: true
-          docker-images: true
-          swap-storage: true
-
-      - name: Download Docker image artifact
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: livekit-cpp-sdk-docker-x64
-
-      - name: Load Docker image
-        run: gzip -dc livekit-cpp-sdk-x64-docker.tar.gz | docker load
-
-      - name: Build cpp-example-collection against installed SDK
-        run: |
-          cpp_ex_ref="$(git rev-parse HEAD:cpp-example-collection)"
-          docker run -e CPP_EX_REF="${cpp_ex_ref}" --rm livekit-cpp-sdk-x64:${{ github.sha }} bash -lc '
-            set -euxo pipefail
-            git clone https://github.com/livekit-examples/cpp-example-collection.git /tmp/cpp-example-collection
-            cd /tmp/cpp-example-collection
-            git fetch --depth 1 origin "$CPP_EX_REF"
-            git checkout "$CPP_EX_REF"
-            cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR=/opt/livekit-sdk
-            cmake --build build --parallel
-          '
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index aaf35bd8..91e0c695 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -27,6 +27,7 @@ jobs:
       docs:   ${{ steps.filter.outputs.docs }}
       cpp_checks: ${{ steps.filter.outputs.cpp_checks }}
       rust_release_check: ${{ steps.filter.outputs.rust_release_check }}
+      docker: ${{ steps.filter.outputs.docker }}
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
       - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d  # v4.0.1
@@ -41,7 +42,6 @@ jobs:
               - cpp-example-collection/**
               - client-sdk-rust/**
               - cmake/**
-              - docker/**
               - CMakeLists.txt
               - CMakePresets.json
               - build*
@@ -49,6 +49,9 @@ jobs:
               - vcpkg.json
               - .github/workflows/ci.yml
               - .github/workflows/builds.yml
+            docker:
+              - docker/**
+              - .github/workflows/docker-builds.yml
             tests:
               - src/**
               - include/**
@@ -94,6 +97,13 @@ jobs:
     uses: ./.github/workflows/builds.yml
     secrets: inherit
 
+  docker-builds:
+    name: Docker Builds
+    needs: changes
+    if: ${{ (github.event_name == 'pull_request' && needs.changes.outputs.docker == 'true') || github.event_name == 'workflow_dispatch' }}
+    uses: ./.github/workflows/docker-builds.yml
+    secrets: inherit
+
   tests:
     name: Tests
     needs: changes
@@ -142,6 +152,7 @@ jobs:
     needs:
       - changes
       - builds
+      - docker-builds
       - tests
       - license-check
       - cpp-checks
diff --git a/.github/workflows/docker-builds.yml b/.github/workflows/docker-builds.yml
new file mode 100644
index 00000000..80fbbaa1
--- /dev/null
+++ b/.github/workflows/docker-builds.yml
@@ -0,0 +1,262 @@
+name: Docker Builds
+
+# Called by top-level ci.yml
+on:
+  workflow_call: {}
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  actions: read
+  packages: read
+
+jobs:
+  docker-build-x64:
+    name: Build (docker-linux-x64)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout (with submodules)
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Check if Dockerfile.base changed
+        id: base_changed
+        shell: bash
+        run: |
+          set -euo pipefail
+          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -q '^docker/Dockerfile\.base$'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Free disk space
+        uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
+        with:
+          tool-cache: false
+          android: true
+          dotnet: true
+          haskell: true
+          large-packages: true
+          docker-images: true
+          swap-storage: true
+
+      - name: Pull base image from GHCR
+        if: steps.base_changed.outputs.changed == 'false'
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euxo pipefail
+          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
+          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+          docker pull "ghcr.io/${owner}/client-sdk-cpp-base:base-main-amd64"
+          docker tag "ghcr.io/${owner}/client-sdk-cpp-base:base-main-amd64" \
+            "livekit-cpp-sdk-base-x64:${{ github.sha }}"
+
+      - name: Build base Docker image
+        if: steps.base_changed.outputs.changed == 'true'
+        run: |
+          docker build \
+            --build-arg TARGETARCH=amd64 \
+            -t livekit-cpp-sdk-base-x64:${{ github.sha }} \
+            -f docker/Dockerfile.base \
+            docker
+
+      - name: Build SDK Docker image
+        run: |
+          docker build \
+            --build-arg BASE_IMAGE=livekit-cpp-sdk-base-x64:${{ github.sha }} \
+            -t livekit-cpp-sdk-x64:${{ github.sha }} \
+            . \
+            -f docker/Dockerfile.sdk
+
+      - name: Verify installed SDK inside image
+        run: |
+          docker run --rm livekit-cpp-sdk-x64:${{ github.sha }} bash -c \
+            'test -f /opt/livekit-sdk/lib/cmake/LiveKit/LiveKitConfig.cmake'
+
+      - name: Save Docker image artifact
+        run: |
+          docker save livekit-cpp-sdk-x64:${{ github.sha }} | gzip > livekit-cpp-sdk-x64-docker.tar.gz
+
+      - name: Upload Docker image artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: livekit-cpp-sdk-docker-x64
+          path: livekit-cpp-sdk-x64-docker.tar.gz
+          retention-days: 7
+
+  docker-build-linux-arm64:
+    name: Build (docker-linux-arm64)
+    runs-on: ubuntu-24.04-arm
+
+    steps:
+      - name: Checkout (with submodules)
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Check if Dockerfile.base changed
+        id: base_changed
+        shell: bash
+        run: |
+          set -euo pipefail
+          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -q '^docker/Dockerfile\.base$'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Free disk space
+        uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
+        with:
+          tool-cache: false
+          android: true
+          dotnet: true
+          haskell: true
+          large-packages: true
+          docker-images: true
+          swap-storage: true
+
+      - name: Pull base image from GHCR
+        if: steps.base_changed.outputs.changed == 'false'
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euxo pipefail
+          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
+          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+          docker pull "ghcr.io/${owner}/client-sdk-cpp-base:base-main-arm64"
+          docker tag "ghcr.io/${owner}/client-sdk-cpp-base:base-main-arm64" \
+            "livekit-cpp-sdk-base-arm64:${{ github.sha }}"
+
+      - name: Build base Docker image
+        if: steps.base_changed.outputs.changed == 'true'
+        run: |
+          docker build \
+            --build-arg TARGETARCH=arm64 \
+            -t livekit-cpp-sdk-base-arm64:${{ github.sha }} \
+            -f docker/Dockerfile.base \
+            docker
+
+      - name: Build SDK Docker image
+        run: |
+          docker build \
+            --build-arg BASE_IMAGE=livekit-cpp-sdk-base-arm64:${{ github.sha }} \
+            -t livekit-cpp-sdk:${{ github.sha }} \
+            . \
+            -f docker/Dockerfile.sdk
+
+      - name: Verify installed SDK inside image
+        run: |
+          docker run --rm livekit-cpp-sdk:${{ github.sha }} bash -c \
+            'test -f /opt/livekit-sdk/lib/cmake/LiveKit/LiveKitConfig.cmake'
+
+      - name: Save Docker image artifact
+        run: |
+          docker save livekit-cpp-sdk:${{ github.sha }} | gzip > livekit-cpp-sdk-arm64-docker.tar.gz
+
+      - name: Upload Docker image artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: livekit-cpp-sdk-docker-arm64
+          path: livekit-cpp-sdk-arm64-docker.tar.gz
+          retention-days: 7
+
+  build-collections-linux-arm64:
+    name: Build (cpp-example-collection-linux-arm64)
+    runs-on: ubuntu-24.04-arm
+    needs: docker-build-linux-arm64
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          fetch-depth: 1
+
+      # Reclaim ~30GB before loading the multi-GB SDK image and building the
+      # example collection inside it. Mirrors the docker-build jobs; without it
+      # the x64 collection build has hit "no space left on device".
+      - name: Free disk space
+        uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
+        with:
+          tool-cache: false
+          android: true
+          dotnet: true
+          haskell: true
+          large-packages: true
+          docker-images: true
+          swap-storage: true
+
+      - name: Download Docker image artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: livekit-cpp-sdk-docker-arm64
+
+      - name: Load Docker image
+        run: gzip -dc livekit-cpp-sdk-arm64-docker.tar.gz | docker load
+
+      - name: Build cpp-example-collection against installed SDK
+        run: |
+          cpp_ex_ref="$(git rev-parse HEAD:cpp-example-collection)"
+          docker run -e CPP_EX_REF="${cpp_ex_ref}" --rm livekit-cpp-sdk:${{ github.sha }} bash -lc '
+            set -euxo pipefail
+            git clone https://github.com/livekit-examples/cpp-example-collection.git /tmp/cpp-example-collection
+            cd /tmp/cpp-example-collection
+            git fetch --depth 1 origin "$CPP_EX_REF"
+            git checkout "$CPP_EX_REF"
+            cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR=/opt/livekit-sdk
+            cmake --build build --parallel
+          '
+
+  build-collections-x64:
+    name: Build (cpp-example-collection-x64)
+    runs-on: ubuntu-latest
+    needs: docker-build-x64
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          fetch-depth: 1
+
+      # Reclaim ~30GB before loading the multi-GB SDK image and building the
+      # example collection inside it. The standard ubuntu-latest runner has hit
+      # "no space left on device" here without this step.
+      - name: Free disk space
+        uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
+        with:
+          tool-cache: false
+          android: true
+          dotnet: true
+          haskell: true
+          large-packages: true
+          docker-images: true
+          swap-storage: true
+
+      - name: Download Docker image artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: livekit-cpp-sdk-docker-x64
+
+      - name: Load Docker image
+        run: gzip -dc livekit-cpp-sdk-x64-docker.tar.gz | docker load
+
+      - name: Build cpp-example-collection against installed SDK
+        run: |
+          cpp_ex_ref="$(git rev-parse HEAD:cpp-example-collection)"
+          docker run -e CPP_EX_REF="${cpp_ex_ref}" --rm livekit-cpp-sdk-x64:${{ github.sha }} bash -lc '
+            set -euxo pipefail
+            git clone https://github.com/livekit-examples/cpp-example-collection.git /tmp/cpp-example-collection
+            cd /tmp/cpp-example-collection
+            git fetch --depth 1 origin "$CPP_EX_REF"
+            git checkout "$CPP_EX_REF"
+            cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR=/opt/livekit-sdk
+            cmake --build build --parallel
+          '

From 38f5638da6d319cb8846e579eb8fe2cb2cb2c694 Mon Sep 17 00:00:00 2001
From: Alan George <alan.george@livekit.io>
Date: Thu, 18 Jun 2026 10:00:23 -0600
Subject: [PATCH 2/3] Further cleanup

---
 .github/workflows/ci.yml            |  10 +-
 .github/workflows/docker-builds.yml | 262 ------------------
 .github/workflows/docker-images.yml | 406 +++++++++++-----------------
 AGENTS.md                           |   4 +-
 4 files changed, 158 insertions(+), 524 deletions(-)
 delete mode 100644 .github/workflows/docker-builds.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 91e0c695..1824a3a7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -51,7 +51,7 @@ jobs:
               - .github/workflows/builds.yml
             docker:
               - docker/**
-              - .github/workflows/docker-builds.yml
+              - .github/workflows/docker-images.yml
             tests:
               - src/**
               - include/**
@@ -97,11 +97,11 @@ jobs:
     uses: ./.github/workflows/builds.yml
     secrets: inherit
 
-  docker-builds:
-    name: Docker Builds
+  docker-images:
+    name: Docker Images
     needs: changes
     if: ${{ (github.event_name == 'pull_request' && needs.changes.outputs.docker == 'true') || github.event_name == 'workflow_dispatch' }}
-    uses: ./.github/workflows/docker-builds.yml
+    uses: ./.github/workflows/docker-images.yml
     secrets: inherit
 
   tests:
@@ -152,7 +152,7 @@ jobs:
     needs:
       - changes
       - builds
-      - docker-builds
+      - docker-images
       - tests
       - license-check
       - cpp-checks
diff --git a/.github/workflows/docker-builds.yml b/.github/workflows/docker-builds.yml
deleted file mode 100644
index 80fbbaa1..00000000
--- a/.github/workflows/docker-builds.yml
+++ /dev/null
@@ -1,262 +0,0 @@
-name: Docker Builds
-
-# Called by top-level ci.yml
-on:
-  workflow_call: {}
-  workflow_dispatch: {}
-
-permissions:
-  contents: read
-  actions: read
-  packages: read
-
-jobs:
-  docker-build-x64:
-    name: Build (docker-linux-x64)
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout (with submodules)
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          submodules: recursive
-          fetch-depth: 0
-
-      - name: Check if Dockerfile.base changed
-        id: base_changed
-        shell: bash
-        run: |
-          set -euo pipefail
-          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -q '^docker/Dockerfile\.base$'; then
-            echo "changed=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "changed=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Free disk space
-        uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
-        with:
-          tool-cache: false
-          android: true
-          dotnet: true
-          haskell: true
-          large-packages: true
-          docker-images: true
-          swap-storage: true
-
-      - name: Pull base image from GHCR
-        if: steps.base_changed.outputs.changed == 'false'
-        shell: bash
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -euxo pipefail
-          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
-          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
-          docker pull "ghcr.io/${owner}/client-sdk-cpp-base:base-main-amd64"
-          docker tag "ghcr.io/${owner}/client-sdk-cpp-base:base-main-amd64" \
-            "livekit-cpp-sdk-base-x64:${{ github.sha }}"
-
-      - name: Build base Docker image
-        if: steps.base_changed.outputs.changed == 'true'
-        run: |
-          docker build \
-            --build-arg TARGETARCH=amd64 \
-            -t livekit-cpp-sdk-base-x64:${{ github.sha }} \
-            -f docker/Dockerfile.base \
-            docker
-
-      - name: Build SDK Docker image
-        run: |
-          docker build \
-            --build-arg BASE_IMAGE=livekit-cpp-sdk-base-x64:${{ github.sha }} \
-            -t livekit-cpp-sdk-x64:${{ github.sha }} \
-            . \
-            -f docker/Dockerfile.sdk
-
-      - name: Verify installed SDK inside image
-        run: |
-          docker run --rm livekit-cpp-sdk-x64:${{ github.sha }} bash -c \
-            'test -f /opt/livekit-sdk/lib/cmake/LiveKit/LiveKitConfig.cmake'
-
-      - name: Save Docker image artifact
-        run: |
-          docker save livekit-cpp-sdk-x64:${{ github.sha }} | gzip > livekit-cpp-sdk-x64-docker.tar.gz
-
-      - name: Upload Docker image artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: livekit-cpp-sdk-docker-x64
-          path: livekit-cpp-sdk-x64-docker.tar.gz
-          retention-days: 7
-
-  docker-build-linux-arm64:
-    name: Build (docker-linux-arm64)
-    runs-on: ubuntu-24.04-arm
-
-    steps:
-      - name: Checkout (with submodules)
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          submodules: recursive
-          fetch-depth: 0
-
-      - name: Check if Dockerfile.base changed
-        id: base_changed
-        shell: bash
-        run: |
-          set -euo pipefail
-          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -q '^docker/Dockerfile\.base$'; then
-            echo "changed=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "changed=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Free disk space
-        uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
-        with:
-          tool-cache: false
-          android: true
-          dotnet: true
-          haskell: true
-          large-packages: true
-          docker-images: true
-          swap-storage: true
-
-      - name: Pull base image from GHCR
-        if: steps.base_changed.outputs.changed == 'false'
-        shell: bash
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -euxo pipefail
-          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
-          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
-          docker pull "ghcr.io/${owner}/client-sdk-cpp-base:base-main-arm64"
-          docker tag "ghcr.io/${owner}/client-sdk-cpp-base:base-main-arm64" \
-            "livekit-cpp-sdk-base-arm64:${{ github.sha }}"
-
-      - name: Build base Docker image
-        if: steps.base_changed.outputs.changed == 'true'
-        run: |
-          docker build \
-            --build-arg TARGETARCH=arm64 \
-            -t livekit-cpp-sdk-base-arm64:${{ github.sha }} \
-            -f docker/Dockerfile.base \
-            docker
-
-      - name: Build SDK Docker image
-        run: |
-          docker build \
-            --build-arg BASE_IMAGE=livekit-cpp-sdk-base-arm64:${{ github.sha }} \
-            -t livekit-cpp-sdk:${{ github.sha }} \
-            . \
-            -f docker/Dockerfile.sdk
-
-      - name: Verify installed SDK inside image
-        run: |
-          docker run --rm livekit-cpp-sdk:${{ github.sha }} bash -c \
-            'test -f /opt/livekit-sdk/lib/cmake/LiveKit/LiveKitConfig.cmake'
-
-      - name: Save Docker image artifact
-        run: |
-          docker save livekit-cpp-sdk:${{ github.sha }} | gzip > livekit-cpp-sdk-arm64-docker.tar.gz
-
-      - name: Upload Docker image artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: livekit-cpp-sdk-docker-arm64
-          path: livekit-cpp-sdk-arm64-docker.tar.gz
-          retention-days: 7
-
-  build-collections-linux-arm64:
-    name: Build (cpp-example-collection-linux-arm64)
-    runs-on: ubuntu-24.04-arm
-    needs: docker-build-linux-arm64
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          fetch-depth: 1
-
-      # Reclaim ~30GB before loading the multi-GB SDK image and building the
-      # example collection inside it. Mirrors the docker-build jobs; without it
-      # the x64 collection build has hit "no space left on device".
-      - name: Free disk space
-        uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
-        with:
-          tool-cache: false
-          android: true
-          dotnet: true
-          haskell: true
-          large-packages: true
-          docker-images: true
-          swap-storage: true
-
-      - name: Download Docker image artifact
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: livekit-cpp-sdk-docker-arm64
-
-      - name: Load Docker image
-        run: gzip -dc livekit-cpp-sdk-arm64-docker.tar.gz | docker load
-
-      - name: Build cpp-example-collection against installed SDK
-        run: |
-          cpp_ex_ref="$(git rev-parse HEAD:cpp-example-collection)"
-          docker run -e CPP_EX_REF="${cpp_ex_ref}" --rm livekit-cpp-sdk:${{ github.sha }} bash -lc '
-            set -euxo pipefail
-            git clone https://github.com/livekit-examples/cpp-example-collection.git /tmp/cpp-example-collection
-            cd /tmp/cpp-example-collection
-            git fetch --depth 1 origin "$CPP_EX_REF"
-            git checkout "$CPP_EX_REF"
-            cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR=/opt/livekit-sdk
-            cmake --build build --parallel
-          '
-
-  build-collections-x64:
-    name: Build (cpp-example-collection-x64)
-    runs-on: ubuntu-latest
-    needs: docker-build-x64
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          fetch-depth: 1
-
-      # Reclaim ~30GB before loading the multi-GB SDK image and building the
-      # example collection inside it. The standard ubuntu-latest runner has hit
-      # "no space left on device" here without this step.
-      - name: Free disk space
-        uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
-        with:
-          tool-cache: false
-          android: true
-          dotnet: true
-          haskell: true
-          large-packages: true
-          docker-images: true
-          swap-storage: true
-
-      - name: Download Docker image artifact
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: livekit-cpp-sdk-docker-x64
-
-      - name: Load Docker image
-        run: gzip -dc livekit-cpp-sdk-x64-docker.tar.gz | docker load
-
-      - name: Build cpp-example-collection against installed SDK
-        run: |
-          cpp_ex_ref="$(git rev-parse HEAD:cpp-example-collection)"
-          docker run -e CPP_EX_REF="${cpp_ex_ref}" --rm livekit-cpp-sdk-x64:${{ github.sha }} bash -lc '
-            set -euxo pipefail
-            git clone https://github.com/livekit-examples/cpp-example-collection.git /tmp/cpp-example-collection
-            cd /tmp/cpp-example-collection
-            git fetch --depth 1 origin "$CPP_EX_REF"
-            git checkout "$CPP_EX_REF"
-            cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR=/opt/livekit-sdk
-            cmake --build build --parallel
-          '
diff --git a/.github/workflows/docker-images.yml b/.github/workflows/docker-images.yml
index 84467558..bda7a2a5 100644
--- a/.github/workflows/docker-images.yml
+++ b/.github/workflows/docker-images.yml
@@ -1,116 +1,38 @@
 name: Docker Images
 
+# Called by top-level ci.yml
 on:
-  push:
-    branches: ["main"]
-    paths:
-      - src/**
-      - include/**
-      - client-sdk-rust/**
-      - CMakeLists.txt
-      - build.sh
-      - build.cmd
-      - build.h.in
-      - .build-info.json.in
-      - CMakePresets.json
-      - cmake/**
-      - data/**
-      - cpp-example-collection
-      - docker/Dockerfile.base
-      - docker/Dockerfile.sdk
-      - .github/workflows/docker-images.yml
-      - .github/workflows/docker-validate.yml
+  workflow_call: {}
+  workflow_dispatch: {}
 
 permissions:
   contents: read
-  packages: write
+  actions: read
+  packages: read
 
 jobs:
-  detect-changes:
-    name: Detect Docker image changes
+  docker-build-x64:
+    name: Build (docker-linux-x64)
     runs-on: ubuntu-latest
-    outputs:
-      base_changed: ${{ steps.changes.outputs.base_changed }}
-      sdk_changed: ${{ steps.changes.outputs.sdk_changed }}
-      base_hash: ${{ steps.hash.outputs.base_hash }}
-      base_image: ${{ steps.refs.outputs.base_image }}
-      sdk_image: ${{ steps.refs.outputs.sdk_image }}
+
     steps:
-      - name: Checkout
+      - name: Checkout (with submodules)
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
+          submodules: recursive
           fetch-depth: 0
 
-      - name: Resolve GHCR image names
-        id: refs
-        shell: bash
-        run: |
-          set -euo pipefail
-          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
-          echo "base_image=ghcr.io/${owner}/client-sdk-cpp-base" >> "$GITHUB_OUTPUT"
-          echo "sdk_image=ghcr.io/${owner}/client-sdk-cpp" >> "$GITHUB_OUTPUT"
-
-      - name: Hash base Dockerfile
-        id: hash
+      - name: Check if Dockerfile.base changed
+        id: base_changed
         shell: bash
         run: |
           set -euo pipefail
-          base_hash="$(shasum -a 256 docker/Dockerfile.base | awk '{print substr($1,1,12)}')"
-          echo "base_hash=${base_hash}" >> "$GITHUB_OUTPUT"
-
-      - name: Detect changed inputs
-        id: changes
-        shell: bash
-        run: |
-          set -euo pipefail
-
-          if [[ "${{ github.event.before }}" == "0000000000000000000000000000000000000000" ]]; then
-            changed_files="$(git ls-tree -r --name-only "${{ github.sha }}")"
-          else
-            changed_files="$(git diff --name-only "${{ github.event.before }}" "${{ github.sha }}")"
-          fi
-
-          echo "Changed files:"
-          if [[ -n "${changed_files}" ]]; then
-            while IFS= read -r path; do
-              [[ -z "${path}" ]] && continue
-              echo "  ${path}"
-            done <<< "${changed_files}"
+          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -q '^docker/Dockerfile\.base$'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
           else
-            echo "  <none>"
+            echo "changed=false" >> "$GITHUB_OUTPUT"
           fi
 
-          base_changed=false
-          sdk_changed=false
-
-          while IFS= read -r path; do
-            [[ -z "${path}" ]] && continue
-
-            if [[ "${path}" == "docker/Dockerfile.base" ]]; then
-              base_changed=true
-              sdk_changed=true
-            fi
-
-            case "${path}" in
-              docker/Dockerfile.sdk|src/*|include/*|client-sdk-rust/*|cmake/*|data/*|cpp-example-collection|CMakeLists.txt|build.sh|build.cmd|build.h.in|.build-info.json.in|CMakePresets.json|.github/workflows/docker-images.yml|.github/workflows/docker-validate.yml)
-                sdk_changed=true
-                ;;
-            esac
-          done <<< "${changed_files}"
-
-          echo "base_changed=${base_changed}" >> "$GITHUB_OUTPUT"
-          echo "sdk_changed=${sdk_changed}" >> "$GITHUB_OUTPUT"
-
-  build-base-amd64:
-    name: Publish base image (amd64)
-    runs-on: ubuntu-latest
-    needs: detect-changes
-    if: needs.detect-changes.outputs.base_changed == 'true'
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-
       - name: Free disk space
         uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
         with:
@@ -122,38 +44,73 @@ jobs:
           docker-images: true
           swap-storage: true
 
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
-
-      - name: Login to GHCR
+      - name: Pull base image from GHCR
+        if: steps.base_changed.outputs.changed == 'false'
         shell: bash
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          set -euo pipefail
+          set -euxo pipefail
+          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
           echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+          docker pull "ghcr.io/${owner}/client-sdk-cpp-base:base-main-amd64"
+          docker tag "ghcr.io/${owner}/client-sdk-cpp-base:base-main-amd64" \
+            "livekit-cpp-sdk-base-x64:${{ github.sha }}"
 
-      - name: Build and push base image
-        shell: bash
+      - name: Build base Docker image
+        if: steps.base_changed.outputs.changed == 'true'
         run: |
-          set -euxo pipefail
-          docker buildx build \
-            --platform linux/amd64 \
-            --push \
-            -t "${{ needs.detect-changes.outputs.base_image }}:base-${{ needs.detect-changes.outputs.base_hash }}-amd64" \
-            -t "${{ needs.detect-changes.outputs.base_image }}:base-main-amd64" \
+          docker build \
+            --build-arg TARGETARCH=amd64 \
+            -t livekit-cpp-sdk-base-x64:${{ github.sha }} \
             -f docker/Dockerfile.base \
             docker
 
-  build-base-arm64:
-    name: Publish base image (arm64)
+      - name: Build SDK Docker image
+        run: |
+          docker build \
+            --build-arg BASE_IMAGE=livekit-cpp-sdk-base-x64:${{ github.sha }} \
+            -t livekit-cpp-sdk-x64:${{ github.sha }} \
+            . \
+            -f docker/Dockerfile.sdk
+
+      - name: Verify installed SDK inside image
+        run: |
+          docker run --rm livekit-cpp-sdk-x64:${{ github.sha }} bash -c \
+            'test -f /opt/livekit-sdk/lib/cmake/LiveKit/LiveKitConfig.cmake'
+
+      - name: Save Docker image artifact
+        run: |
+          docker save livekit-cpp-sdk-x64:${{ github.sha }} | gzip > livekit-cpp-sdk-x64-docker.tar.gz
+
+      - name: Upload Docker image artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: livekit-cpp-sdk-docker-x64
+          path: livekit-cpp-sdk-x64-docker.tar.gz
+          retention-days: 7
+
+  docker-build-linux-arm64:
+    name: Build (docker-linux-arm64)
     runs-on: ubuntu-24.04-arm
-    needs: detect-changes
-    if: needs.detect-changes.outputs.base_changed == 'true'
 
     steps:
-      - name: Checkout
+      - name: Checkout (with submodules)
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Check if Dockerfile.base changed
+        id: base_changed
+        shell: bash
+        run: |
+          set -euo pipefail
+          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -q '^docker/Dockerfile\.base$'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
 
       - name: Free disk space
         uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
@@ -166,79 +123,66 @@ jobs:
           docker-images: true
           swap-storage: true
 
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
-
-      - name: Login to GHCR
+      - name: Pull base image from GHCR
+        if: steps.base_changed.outputs.changed == 'false'
         shell: bash
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          set -euo pipefail
+          set -euxo pipefail
+          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
           echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+          docker pull "ghcr.io/${owner}/client-sdk-cpp-base:base-main-arm64"
+          docker tag "ghcr.io/${owner}/client-sdk-cpp-base:base-main-arm64" \
+            "livekit-cpp-sdk-base-arm64:${{ github.sha }}"
 
-      - name: Build and push base image
-        shell: bash
+      - name: Build base Docker image
+        if: steps.base_changed.outputs.changed == 'true'
         run: |
-          set -euxo pipefail
-          docker buildx build \
-            --platform linux/arm64 \
-            --push \
-            -t "${{ needs.detect-changes.outputs.base_image }}:base-${{ needs.detect-changes.outputs.base_hash }}-arm64" \
-            -t "${{ needs.detect-changes.outputs.base_image }}:base-main-arm64" \
+          docker build \
+            --build-arg TARGETARCH=arm64 \
+            -t livekit-cpp-sdk-base-arm64:${{ github.sha }} \
             -f docker/Dockerfile.base \
             docker
 
-  publish-base-manifest:
-    name: Publish base manifest
-    runs-on: ubuntu-latest
-    needs:
-      - detect-changes
-      - build-base-amd64
-      - build-base-arm64
-    if: needs.detect-changes.outputs.base_changed == 'true'
-
-    steps:
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+      - name: Build SDK Docker image
+        run: |
+          docker build \
+            --build-arg BASE_IMAGE=livekit-cpp-sdk-base-arm64:${{ github.sha }} \
+            -t livekit-cpp-sdk:${{ github.sha }} \
+            . \
+            -f docker/Dockerfile.sdk
 
-      - name: Login to GHCR
-        shell: bash
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Verify installed SDK inside image
         run: |
-          set -euo pipefail
-          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+          docker run --rm livekit-cpp-sdk:${{ github.sha }} bash -c \
+            'test -f /opt/livekit-sdk/lib/cmake/LiveKit/LiveKitConfig.cmake'
 
-      - name: Publish base manifest tags
-        shell: bash
+      - name: Save Docker image artifact
         run: |
-          set -euxo pipefail
-          docker buildx imagetools create \
-            -t "${{ needs.detect-changes.outputs.base_image }}:base-${{ needs.detect-changes.outputs.base_hash }}" \
-            -t "${{ needs.detect-changes.outputs.base_image }}:base-main" \
-            "${{ needs.detect-changes.outputs.base_image }}:base-${{ needs.detect-changes.outputs.base_hash }}-amd64" \
-            "${{ needs.detect-changes.outputs.base_image }}:base-${{ needs.detect-changes.outputs.base_hash }}-arm64"
-
-  build-sdk-amd64:
-    name: Publish SDK image (amd64)
-    runs-on: ubuntu-latest
-    needs:
-      - detect-changes
-      - build-base-amd64
-    if: |
-      always() &&
-      needs.detect-changes.outputs.sdk_changed == 'true' &&
-      needs.build-base-amd64.result != 'failure' &&
-      needs.build-base-amd64.result != 'cancelled'
+          docker save livekit-cpp-sdk:${{ github.sha }} | gzip > livekit-cpp-sdk-arm64-docker.tar.gz
+
+      - name: Upload Docker image artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: livekit-cpp-sdk-docker-arm64
+          path: livekit-cpp-sdk-arm64-docker.tar.gz
+          retention-days: 7
+
+  build-collections-linux-arm64:
+    name: Build (cpp-example-collection-linux-arm64)
+    runs-on: ubuntu-24.04-arm
+    needs: docker-build-linux-arm64
 
     steps:
       - name: Checkout
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
-          submodules: recursive
-          fetch-depth: 0
+          fetch-depth: 1
 
+      # Reclaim ~30GB before loading the multi-GB SDK image and building the
+      # example collection inside it. Mirrors the docker-build jobs; without it
+      # the x64 collection build has hit "no space left on device".
       - name: Free disk space
         uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
         with:
@@ -250,49 +194,41 @@ jobs:
           docker-images: true
           swap-storage: true
 
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+      - name: Download Docker image artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: livekit-cpp-sdk-docker-arm64
 
-      - name: Login to GHCR
-        shell: bash
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -euo pipefail
-          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+      - name: Load Docker image
+        run: gzip -dc livekit-cpp-sdk-arm64-docker.tar.gz | docker load
 
-      - name: Build and push SDK image
-        shell: bash
+      - name: Build cpp-example-collection against installed SDK
         run: |
-          set -euxo pipefail
-          docker buildx build \
-            --platform linux/amd64 \
-            --build-arg BASE_IMAGE="${{ needs.detect-changes.outputs.base_image }}:base-${{ needs.detect-changes.outputs.base_hash }}-amd64" \
-            --push \
-            -t "${{ needs.detect-changes.outputs.sdk_image }}:sha-${{ github.sha }}-amd64" \
-            -t "${{ needs.detect-changes.outputs.sdk_image }}:main-amd64" \
-            . \
-            -f docker/Dockerfile.sdk
-
-  build-sdk-arm64:
-    name: Publish SDK image (arm64)
-    runs-on: ubuntu-24.04-arm
-    needs:
-      - detect-changes
-      - build-base-arm64
-    if: |
-      always() &&
-      needs.detect-changes.outputs.sdk_changed == 'true' &&
-      needs.build-base-arm64.result != 'failure' &&
-      needs.build-base-arm64.result != 'cancelled'
+          cpp_ex_ref="$(git rev-parse HEAD:cpp-example-collection)"
+          docker run -e CPP_EX_REF="${cpp_ex_ref}" --rm livekit-cpp-sdk:${{ github.sha }} bash -lc '
+            set -euxo pipefail
+            git clone https://github.com/livekit-examples/cpp-example-collection.git /tmp/cpp-example-collection
+            cd /tmp/cpp-example-collection
+            git fetch --depth 1 origin "$CPP_EX_REF"
+            git checkout "$CPP_EX_REF"
+            cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR=/opt/livekit-sdk
+            cmake --build build --parallel
+          '
+
+  build-collections-x64:
+    name: Build (cpp-example-collection-x64)
+    runs-on: ubuntu-latest
+    needs: docker-build-x64
 
     steps:
       - name: Checkout
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
-          submodules: recursive
-          fetch-depth: 0
+          fetch-depth: 1
 
+      # Reclaim ~30GB before loading the multi-GB SDK image and building the
+      # example collection inside it. The standard ubuntu-latest runner has hit
+      # "no space left on device" here without this step.
       - name: Free disk space
         uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
         with:
@@ -304,63 +240,23 @@ jobs:
           docker-images: true
           swap-storage: true
 
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
-
-      - name: Login to GHCR
-        shell: bash
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -euo pipefail
-          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
-
-      - name: Build and push SDK image
-        shell: bash
-        run: |
-          set -euxo pipefail
-          docker buildx build \
-            --platform linux/arm64 \
-            --build-arg BASE_IMAGE="${{ needs.detect-changes.outputs.base_image }}:base-${{ needs.detect-changes.outputs.base_hash }}-arm64" \
-            --push \
-            -t "${{ needs.detect-changes.outputs.sdk_image }}:sha-${{ github.sha }}-arm64" \
-            -t "${{ needs.detect-changes.outputs.sdk_image }}:main-arm64" \
-            . \
-            -f docker/Dockerfile.sdk
-
-  publish-sdk-manifest:
-    name: Publish SDK manifest
-    runs-on: ubuntu-latest
-    needs:
-      - detect-changes
-      - build-sdk-amd64
-      - build-sdk-arm64
-    if: |
-      always() &&
-      needs.detect-changes.outputs.sdk_changed == 'true' &&
-      needs.build-sdk-amd64.result != 'failure' &&
-      needs.build-sdk-amd64.result != 'cancelled' &&
-      needs.build-sdk-arm64.result != 'failure' &&
-      needs.build-sdk-arm64.result != 'cancelled'
+      - name: Download Docker image artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: livekit-cpp-sdk-docker-x64
 
-    steps:
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+      - name: Load Docker image
+        run: gzip -dc livekit-cpp-sdk-x64-docker.tar.gz | docker load
 
-      - name: Login to GHCR
-        shell: bash
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build cpp-example-collection against installed SDK
         run: |
-          set -euo pipefail
-          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
-
-      - name: Publish SDK manifest tags
-        shell: bash
-        run: |
-          set -euxo pipefail
-          docker buildx imagetools create \
-            -t "${{ needs.detect-changes.outputs.sdk_image }}:sha-${{ github.sha }}" \
-            -t "${{ needs.detect-changes.outputs.sdk_image }}:main" \
-            "${{ needs.detect-changes.outputs.sdk_image }}:sha-${{ github.sha }}-amd64" \
-            "${{ needs.detect-changes.outputs.sdk_image }}:sha-${{ github.sha }}-arm64"
+          cpp_ex_ref="$(git rev-parse HEAD:cpp-example-collection)"
+          docker run -e CPP_EX_REF="${cpp_ex_ref}" --rm livekit-cpp-sdk-x64:${{ github.sha }} bash -lc '
+            set -euxo pipefail
+            git clone https://github.com/livekit-examples/cpp-example-collection.git /tmp/cpp-example-collection
+            cd /tmp/cpp-example-collection
+            git fetch --depth 1 origin "$CPP_EX_REF"
+            git checkout "$CPP_EX_REF"
+            cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR=/opt/livekit-sdk
+            cmake --build build --parallel
+          '
diff --git a/AGENTS.md b/AGENTS.md
index 9bf3afd7..f167b8c6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -398,8 +398,8 @@ all filtered stages; normal pull requests and pushes use the path filters.
  feedback.
 - `.github/workflows/license_check.yml` — Cheap license check, run on every CI
   invocation.
-- `.github/workflows/docker-images.yml` — Docker image build/publish workflow,
-  outside PR-review aggregation.
+- `.github/workflows/docker-images.yml` — Reusable Docker image build workflow
+  used by the top-level CI aggregator for Docker PR checks and manual runs.
 - `.github/workflows/docker-validate.yml` — Docker image validation workflow,
   outside PR-review aggregation.
 

From 640ca8226e199b1f0127c8f671b4f82ef6d363c8 Mon Sep 17 00:00:00 2001
From: Alan George <alan.george@livekit.io>
Date: Thu, 18 Jun 2026 10:28:01 -0600
Subject: [PATCH 3/3] More cleanup

---
 .github/workflows/ci.yml              |   2 +
 .github/workflows/docker-images.yml   | 383 ++++++++++++++++++++++++--
 .github/workflows/docker-validate.yml | 119 --------
 .github/workflows/make-release.yml    |  17 +-
 AGENTS.md                             |   4 +-
 5 files changed, 373 insertions(+), 152 deletions(-)
 delete mode 100644 .github/workflows/docker-validate.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1824a3a7..22334642 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -102,6 +102,8 @@ jobs:
     needs: changes
     if: ${{ (github.event_name == 'pull_request' && needs.changes.outputs.docker == 'true') || github.event_name == 'workflow_dispatch' }}
     uses: ./.github/workflows/docker-images.yml
+    with:
+      push_images: false
     secrets: inherit
 
   tests:
diff --git a/.github/workflows/docker-images.yml b/.github/workflows/docker-images.yml
index bda7a2a5..efc59ce4 100644
--- a/.github/workflows/docker-images.yml
+++ b/.github/workflows/docker-images.yml
@@ -1,38 +1,118 @@
 name: Docker Images
 
-# Called by top-level ci.yml
+# Called by top-level ci.yml and make-release.yml
 on:
-  workflow_call: {}
-  workflow_dispatch: {}
+  workflow_call:
+    inputs:
+      push_images:
+        description: "When true, publish built images to GHCR."
+        required: true
+        type: boolean
+      push_tag:
+        description: "Primary image tag to publish when push_images is true (for example v1.2.3)."
+        required: false
+        default: ""
+        type: string
+  workflow_dispatch:
+    inputs:
+      push_images:
+        description: "When true, publish built images to GHCR."
+        required: true
+        default: false
+        type: boolean
+      push_tag:
+        description: "Primary image tag to publish when push_images is true (for example v1.2.3)."
+        required: false
+        default: ""
+        type: string
 
 permissions:
   contents: read
   actions: read
-  packages: read
+  packages: write
 
 jobs:
-  docker-build-x64:
-    name: Build (docker-linux-x64)
+  detect-changes:
+    name: Detect Docker input changes
     runs-on: ubuntu-latest
+    outputs:
+      base_changed: ${{ steps.detect.outputs.base_changed }}
+      sdk_changed: ${{ steps.detect.outputs.sdk_changed }}
 
     steps:
-      - name: Checkout (with submodules)
+      - name: Checkout
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
-          submodules: recursive
           fetch-depth: 0
 
-      - name: Check if Dockerfile.base changed
-        id: base_changed
+      - name: Detect changed inputs
+        id: detect
         shell: bash
         run: |
           set -euo pipefail
-          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -q '^docker/Dockerfile\.base$'; then
-            echo "changed=true" >> "$GITHUB_OUTPUT"
+
+          base_ref="${{ github.base_ref }}"
+          if [[ -z "${base_ref}" ]]; then
+            base_ref="${{ github.event.pull_request.base.ref }}"
+          fi
+
+          before_sha="${{ github.event.before }}"
+          changed_files=""
+          has_diff_context=false
+
+          if [[ -n "${base_ref}" ]]; then
+            git fetch --no-tags --depth=1 origin "${base_ref}" >/dev/null 2>&1 || true
+          fi
+
+          if [[ -n "${base_ref}" ]] && git rev-parse --verify --quiet "origin/${base_ref}" >/dev/null; then
+            changed_files="$(git diff --name-only "origin/${base_ref}...HEAD")"
+            has_diff_context=true
+          elif [[ -n "${before_sha}" ]] && [[ "${before_sha}" != "0000000000000000000000000000000000000000" ]]; then
+            changed_files="$(git diff --name-only "${before_sha}" "${{ github.sha }}")"
+            has_diff_context=true
+          fi
+
+          if [[ "${has_diff_context}" != "true" ]]; then
+            # Tag/manual workflow calls do not always have an obvious diff base.
+            # Fall back to full docker flow for deterministic smoke/publish behavior.
+            base_changed=true
+            sdk_changed=true
           else
-            echo "changed=false" >> "$GITHUB_OUTPUT"
+            base_changed=false
+            sdk_changed=false
+
+            while IFS= read -r path; do
+              [[ -z "${path}" ]] && continue
+
+              if [[ "${path}" == "docker/Dockerfile.base" ]]; then
+                base_changed=true
+                sdk_changed=true
+              fi
+
+              case "${path}" in
+                docker/Dockerfile.sdk|src/*|include/*|client-sdk-rust/*|cmake/*|data/*|cpp-example-collection|CMakeLists.txt|build.sh|build.cmd|build.h.in|.build-info.json.in|CMakePresets.json|.github/workflows/docker-images.yml|.github/workflows/docker-validate.yml)
+                  sdk_changed=true
+                  ;;
+              esac
+            done <<< "${changed_files}"
           fi
 
+          echo "base_changed=${base_changed}" >> "$GITHUB_OUTPUT"
+          echo "sdk_changed=${sdk_changed}" >> "$GITHUB_OUTPUT"
+
+  docker-build-x64:
+    name: Build (docker-linux-x64)
+    runs-on: ubuntu-latest
+    needs: detect-changes
+    if: ${{ needs.detect-changes.outputs.sdk_changed == 'true' }}
+
+    steps:
+      - name: Checkout (with submodules)
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
       - name: Free disk space
         uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
         with:
@@ -45,7 +125,7 @@ jobs:
           swap-storage: true
 
       - name: Pull base image from GHCR
-        if: steps.base_changed.outputs.changed == 'false'
+        if: needs.detect-changes.outputs.base_changed == 'false'
         shell: bash
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -58,7 +138,7 @@ jobs:
             "livekit-cpp-sdk-base-x64:${{ github.sha }}"
 
       - name: Build base Docker image
-        if: steps.base_changed.outputs.changed == 'true'
+        if: needs.detect-changes.outputs.base_changed == 'true'
         run: |
           docker build \
             --build-arg TARGETARCH=amd64 \
@@ -79,6 +159,64 @@ jobs:
           docker run --rm livekit-cpp-sdk-x64:${{ github.sha }} bash -c \
             'test -f /opt/livekit-sdk/lib/cmake/LiveKit/LiveKitConfig.cmake'
 
+      - name: Resolve image refs for push
+        if: ${{ inputs.push_images }}
+        id: push_refs
+        shell: bash
+        run: |
+          set -euo pipefail
+          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
+          resolved_tag="${{ inputs.push_tag }}"
+          if [[ -z "${resolved_tag}" ]]; then
+            resolved_tag="sha-${GITHUB_SHA}"
+          fi
+          echo "base_image=ghcr.io/${owner}/client-sdk-cpp-base" >> "$GITHUB_OUTPUT"
+          echo "sdk_image=ghcr.io/${owner}/client-sdk-cpp" >> "$GITHUB_OUTPUT"
+          echo "resolved_tag=${resolved_tag}" >> "$GITHUB_OUTPUT"
+
+      - name: Login to GHCR (push)
+        if: ${{ inputs.push_images }}
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+
+      - name: Push base image (amd64)
+        if: ${{ inputs.push_images && needs.detect-changes.outputs.base_changed == 'true' }}
+        shell: bash
+        run: |
+          set -euxo pipefail
+          primary_tag="${{ steps.push_refs.outputs.resolved_tag }}"
+          sha_tag="sha-${GITHUB_SHA}"
+          base_image="${{ steps.push_refs.outputs.base_image }}"
+
+          docker tag livekit-cpp-sdk-base-x64:${{ github.sha }} "${base_image}:${primary_tag}-amd64"
+          docker push "${base_image}:${primary_tag}-amd64"
+
+          if [[ "${primary_tag}" != "${sha_tag}" ]]; then
+            docker tag livekit-cpp-sdk-base-x64:${{ github.sha }} "${base_image}:${sha_tag}-amd64"
+            docker push "${base_image}:${sha_tag}-amd64"
+          fi
+
+      - name: Push SDK image (amd64)
+        if: ${{ inputs.push_images }}
+        shell: bash
+        run: |
+          set -euxo pipefail
+          primary_tag="${{ steps.push_refs.outputs.resolved_tag }}"
+          sha_tag="sha-${GITHUB_SHA}"
+          sdk_image="${{ steps.push_refs.outputs.sdk_image }}"
+
+          docker tag livekit-cpp-sdk-x64:${{ github.sha }} "${sdk_image}:${primary_tag}-amd64"
+          docker push "${sdk_image}:${primary_tag}-amd64"
+
+          if [[ "${primary_tag}" != "${sha_tag}" ]]; then
+            docker tag livekit-cpp-sdk-x64:${{ github.sha }} "${sdk_image}:${sha_tag}-amd64"
+            docker push "${sdk_image}:${sha_tag}-amd64"
+          fi
+
       - name: Save Docker image artifact
         run: |
           docker save livekit-cpp-sdk-x64:${{ github.sha }} | gzip > livekit-cpp-sdk-x64-docker.tar.gz
@@ -93,6 +231,8 @@ jobs:
   docker-build-linux-arm64:
     name: Build (docker-linux-arm64)
     runs-on: ubuntu-24.04-arm
+    needs: detect-changes
+    if: ${{ needs.detect-changes.outputs.sdk_changed == 'true' }}
 
     steps:
       - name: Checkout (with submodules)
@@ -101,17 +241,6 @@ jobs:
           submodules: recursive
           fetch-depth: 0
 
-      - name: Check if Dockerfile.base changed
-        id: base_changed
-        shell: bash
-        run: |
-          set -euo pipefail
-          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -q '^docker/Dockerfile\.base$'; then
-            echo "changed=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "changed=false" >> "$GITHUB_OUTPUT"
-          fi
-
       - name: Free disk space
         uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
         with:
@@ -124,7 +253,7 @@ jobs:
           swap-storage: true
 
       - name: Pull base image from GHCR
-        if: steps.base_changed.outputs.changed == 'false'
+        if: needs.detect-changes.outputs.base_changed == 'false'
         shell: bash
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -137,7 +266,7 @@ jobs:
             "livekit-cpp-sdk-base-arm64:${{ github.sha }}"
 
       - name: Build base Docker image
-        if: steps.base_changed.outputs.changed == 'true'
+        if: needs.detect-changes.outputs.base_changed == 'true'
         run: |
           docker build \
             --build-arg TARGETARCH=arm64 \
@@ -158,6 +287,64 @@ jobs:
           docker run --rm livekit-cpp-sdk:${{ github.sha }} bash -c \
             'test -f /opt/livekit-sdk/lib/cmake/LiveKit/LiveKitConfig.cmake'
 
+      - name: Resolve image refs for push
+        if: ${{ inputs.push_images }}
+        id: push_refs
+        shell: bash
+        run: |
+          set -euo pipefail
+          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
+          resolved_tag="${{ inputs.push_tag }}"
+          if [[ -z "${resolved_tag}" ]]; then
+            resolved_tag="sha-${GITHUB_SHA}"
+          fi
+          echo "base_image=ghcr.io/${owner}/client-sdk-cpp-base" >> "$GITHUB_OUTPUT"
+          echo "sdk_image=ghcr.io/${owner}/client-sdk-cpp" >> "$GITHUB_OUTPUT"
+          echo "resolved_tag=${resolved_tag}" >> "$GITHUB_OUTPUT"
+
+      - name: Login to GHCR (push)
+        if: ${{ inputs.push_images }}
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+
+      - name: Push base image (arm64)
+        if: ${{ inputs.push_images && needs.detect-changes.outputs.base_changed == 'true' }}
+        shell: bash
+        run: |
+          set -euxo pipefail
+          primary_tag="${{ steps.push_refs.outputs.resolved_tag }}"
+          sha_tag="sha-${GITHUB_SHA}"
+          base_image="${{ steps.push_refs.outputs.base_image }}"
+
+          docker tag livekit-cpp-sdk-base-arm64:${{ github.sha }} "${base_image}:${primary_tag}-arm64"
+          docker push "${base_image}:${primary_tag}-arm64"
+
+          if [[ "${primary_tag}" != "${sha_tag}" ]]; then
+            docker tag livekit-cpp-sdk-base-arm64:${{ github.sha }} "${base_image}:${sha_tag}-arm64"
+            docker push "${base_image}:${sha_tag}-arm64"
+          fi
+
+      - name: Push SDK image (arm64)
+        if: ${{ inputs.push_images }}
+        shell: bash
+        run: |
+          set -euxo pipefail
+          primary_tag="${{ steps.push_refs.outputs.resolved_tag }}"
+          sha_tag="sha-${GITHUB_SHA}"
+          sdk_image="${{ steps.push_refs.outputs.sdk_image }}"
+
+          docker tag livekit-cpp-sdk:${{ github.sha }} "${sdk_image}:${primary_tag}-arm64"
+          docker push "${sdk_image}:${primary_tag}-arm64"
+
+          if [[ "${primary_tag}" != "${sha_tag}" ]]; then
+            docker tag livekit-cpp-sdk:${{ github.sha }} "${sdk_image}:${sha_tag}-arm64"
+            docker push "${sdk_image}:${sha_tag}-arm64"
+          fi
+
       - name: Save Docker image artifact
         run: |
           docker save livekit-cpp-sdk:${{ github.sha }} | gzip > livekit-cpp-sdk-arm64-docker.tar.gz
@@ -172,7 +359,14 @@ jobs:
   build-collections-linux-arm64:
     name: Build (cpp-example-collection-linux-arm64)
     runs-on: ubuntu-24.04-arm
-    needs: docker-build-linux-arm64
+    needs:
+      - detect-changes
+      - docker-build-linux-arm64
+    if: |
+      always() &&
+      needs.detect-changes.outputs.sdk_changed == 'true' &&
+      needs.docker-build-linux-arm64.result != 'failure' &&
+      needs.docker-build-linux-arm64.result != 'cancelled'
 
     steps:
       - name: Checkout
@@ -218,7 +412,14 @@ jobs:
   build-collections-x64:
     name: Build (cpp-example-collection-x64)
     runs-on: ubuntu-latest
-    needs: docker-build-x64
+    needs:
+      - detect-changes
+      - docker-build-x64
+    if: |
+      always() &&
+      needs.detect-changes.outputs.sdk_changed == 'true' &&
+      needs.docker-build-x64.result != 'failure' &&
+      needs.docker-build-x64.result != 'cancelled'
 
     steps:
       - name: Checkout
@@ -260,3 +461,125 @@ jobs:
             cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR=/opt/livekit-sdk
             cmake --build build --parallel
           '
+
+  publish-base-manifest:
+    name: Publish base manifest
+    runs-on: ubuntu-latest
+    needs:
+      - detect-changes
+      - docker-build-x64
+      - docker-build-linux-arm64
+    if: |
+      always() &&
+      inputs.push_images &&
+      needs.detect-changes.outputs.base_changed == 'true' &&
+      needs.docker-build-x64.result != 'failure' &&
+      needs.docker-build-x64.result != 'cancelled' &&
+      needs.docker-build-linux-arm64.result != 'failure' &&
+      needs.docker-build-linux-arm64.result != 'cancelled'
+
+    steps:
+      - name: Resolve image refs for push
+        id: push_refs
+        shell: bash
+        run: |
+          set -euo pipefail
+          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
+          resolved_tag="${{ inputs.push_tag }}"
+          if [[ -z "${resolved_tag}" ]]; then
+            resolved_tag="sha-${GITHUB_SHA}"
+          fi
+          echo "base_image=ghcr.io/${owner}/client-sdk-cpp-base" >> "$GITHUB_OUTPUT"
+          echo "resolved_tag=${resolved_tag}" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+
+      - name: Login to GHCR
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+
+      - name: Publish base manifest tags
+        shell: bash
+        run: |
+          set -euxo pipefail
+          base_image="${{ steps.push_refs.outputs.base_image }}"
+          primary_tag="${{ steps.push_refs.outputs.resolved_tag }}"
+          sha_tag="sha-${GITHUB_SHA}"
+
+          docker buildx imagetools create \
+            -t "${base_image}:${primary_tag}" \
+            "${base_image}:${primary_tag}-amd64" \
+            "${base_image}:${primary_tag}-arm64"
+
+          if [[ "${primary_tag}" != "${sha_tag}" ]]; then
+            docker buildx imagetools create \
+              -t "${base_image}:${sha_tag}" \
+              "${base_image}:${sha_tag}-amd64" \
+              "${base_image}:${sha_tag}-arm64"
+          fi
+
+  publish-sdk-manifest:
+    name: Publish SDK manifest
+    runs-on: ubuntu-latest
+    needs:
+      - detect-changes
+      - docker-build-x64
+      - docker-build-linux-arm64
+    if: |
+      always() &&
+      inputs.push_images &&
+      needs.detect-changes.outputs.sdk_changed == 'true' &&
+      needs.docker-build-x64.result != 'failure' &&
+      needs.docker-build-x64.result != 'cancelled' &&
+      needs.docker-build-linux-arm64.result != 'failure' &&
+      needs.docker-build-linux-arm64.result != 'cancelled'
+
+    steps:
+      - name: Resolve image refs for push
+        id: push_refs
+        shell: bash
+        run: |
+          set -euo pipefail
+          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
+          resolved_tag="${{ inputs.push_tag }}"
+          if [[ -z "${resolved_tag}" ]]; then
+            resolved_tag="sha-${GITHUB_SHA}"
+          fi
+          echo "sdk_image=ghcr.io/${owner}/client-sdk-cpp" >> "$GITHUB_OUTPUT"
+          echo "resolved_tag=${resolved_tag}" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+
+      - name: Login to GHCR
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+
+      - name: Publish SDK manifest tags
+        shell: bash
+        run: |
+          set -euxo pipefail
+          sdk_image="${{ steps.push_refs.outputs.sdk_image }}"
+          primary_tag="${{ steps.push_refs.outputs.resolved_tag }}"
+          sha_tag="sha-${GITHUB_SHA}"
+
+          docker buildx imagetools create \
+            -t "${sdk_image}:${primary_tag}" \
+            "${sdk_image}:${primary_tag}-amd64" \
+            "${sdk_image}:${primary_tag}-arm64"
+
+          if [[ "${primary_tag}" != "${sha_tag}" ]]; then
+            docker buildx imagetools create \
+              -t "${sdk_image}:${sha_tag}" \
+              "${sdk_image}:${sha_tag}-amd64" \
+              "${sdk_image}:${sha_tag}-arm64"
+          fi
diff --git a/.github/workflows/docker-validate.yml b/.github/workflows/docker-validate.yml
deleted file mode 100644
index 12b6a439..00000000
--- a/.github/workflows/docker-validate.yml
+++ /dev/null
@@ -1,119 +0,0 @@
-name: Docker Validate
-
-on:
-  workflow_run:
-    workflows: ["Docker Images"]
-    types: [completed]
-
-permissions:
-  contents: read
-  packages: read
-
-jobs:
-  validate-x64:
-    name: Validate Docker image (linux-x64)
-    runs-on: ubuntu-latest
-    if: |
-      github.event.workflow_run.conclusion == 'success' &&
-      github.event.workflow_run.event == 'push' &&
-      github.event.workflow_run.head_branch == 'main'
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          fetch-depth: 1
-
-      - name: Resolve image name
-        id: refs
-        shell: bash
-        run: |
-          set -euo pipefail
-          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
-          echo "sdk_image=ghcr.io/${owner}/client-sdk-cpp:sha-${{ github.event.workflow_run.head_sha }}" >> "$GITHUB_OUTPUT"
-
-      - name: Login to GHCR
-        shell: bash
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -euo pipefail
-          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
-
-      - name: Pull SDK image
-        shell: bash
-        run: |
-          set -euxo pipefail
-          time docker pull "${{ steps.refs.outputs.sdk_image }}"
-
-      - name: Verify installed SDK inside image
-        run: |
-          docker run --rm "${{ steps.refs.outputs.sdk_image }}" bash -c \
-            'test -f /opt/livekit-sdk/lib/cmake/LiveKit/LiveKitConfig.cmake'
-
-      - name: Build cpp-example-collection against installed SDK
-        run: |
-          cpp_ex_ref="$(git rev-parse HEAD:cpp-example-collection)"
-          docker run -e CPP_EX_REF="${cpp_ex_ref}" --rm "${{ steps.refs.outputs.sdk_image }}" bash -lc '
-            set -euxo pipefail
-            git clone https://github.com/livekit-examples/cpp-example-collection.git /tmp/cpp-example-collection
-            cd /tmp/cpp-example-collection
-            git fetch --depth 1 origin "$CPP_EX_REF"
-            git checkout "$CPP_EX_REF"
-            cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR=/opt/livekit-sdk
-            cmake --build build --parallel
-          '
-
-  validate-arm64:
-    name: Validate Docker image (linux-arm64)
-    runs-on: ubuntu-24.04-arm
-    if: |
-      github.event.workflow_run.conclusion == 'success' &&
-      github.event.workflow_run.event == 'push' &&
-      github.event.workflow_run.head_branch == 'main'
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          fetch-depth: 1
-
-      - name: Resolve image name
-        id: refs
-        shell: bash
-        run: |
-          set -euo pipefail
-          owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
-          echo "sdk_image=ghcr.io/${owner}/client-sdk-cpp:sha-${{ github.event.workflow_run.head_sha }}" >> "$GITHUB_OUTPUT"
-
-      - name: Login to GHCR
-        shell: bash
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -euo pipefail
-          echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
-
-      - name: Pull SDK image
-        shell: bash
-        run: |
-          set -euxo pipefail
-          time docker pull "${{ steps.refs.outputs.sdk_image }}"
-
-      - name: Verify installed SDK inside image
-        run: |
-          docker run --rm "${{ steps.refs.outputs.sdk_image }}" bash -c \
-            'test -f /opt/livekit-sdk/lib/cmake/LiveKit/LiveKitConfig.cmake'
-
-      - name: Build cpp-example-collection against installed SDK
-        run: |
-          cpp_ex_ref="$(git rev-parse HEAD:cpp-example-collection)"
-          docker run -e CPP_EX_REF="${cpp_ex_ref}" --rm "${{ steps.refs.outputs.sdk_image }}" bash -lc '
-            set -euxo pipefail
-            git clone https://github.com/livekit-examples/cpp-example-collection.git /tmp/cpp-example-collection
-            cd /tmp/cpp-example-collection
-            git fetch --depth 1 origin "$CPP_EX_REF"
-            git checkout "$CPP_EX_REF"
-            cmake -S . -B build -DLIVEKIT_LOCAL_SDK_DIR=/opt/livekit-sdk
-            cmake --build build --parallel
-          '
diff --git a/.github/workflows/make-release.yml b/.github/workflows/make-release.yml
index 81bc49a7..4c6b1806 100644
--- a/.github/workflows/make-release.yml
+++ b/.github/workflows/make-release.yml
@@ -323,11 +323,26 @@ jobs:
           name: livekit-sdk-${{ matrix.name }}-${{ steps.version.outputs.version }}
           path: sdk-out/livekit-sdk-${{ matrix.name }}-${{ steps.version.outputs.version }}
 
+  docker-images:
+    name: Docker Images
+    if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
+    permissions:
+      contents: read
+      actions: read
+      packages: write
+    uses: ./.github/workflows/docker-images.yml
+    with:
+      push_images: ${{ github.ref_type == 'tag' }}
+      push_tag: ${{ github.ref_type == 'tag' && github.ref_name || '' }}
+    secrets: inherit
+
   # ---------- Release Job ----------
   release:
     name: Create GitHub Release
     runs-on: ubuntu-latest
-    needs: build
+    needs:
+      - build
+      - docker-images
     permissions:
       contents: write
     if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
diff --git a/AGENTS.md b/AGENTS.md
index f167b8c6..d0f980c8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -398,8 +398,8 @@ all filtered stages; normal pull requests and pushes use the path filters.
  feedback.
 - `.github/workflows/license_check.yml` — Cheap license check, run on every CI
   invocation.
-- `.github/workflows/docker-images.yml` — Reusable Docker image build workflow
-  used by the top-level CI aggregator for Docker PR checks and manual runs.
+- `.github/workflows/docker-images.yml` — Reusable Docker image smoke-test
+  workflow (optional push via input), called by CI and release workflows.
 - `.github/workflows/docker-validate.yml` — Docker image validation workflow,
   outside PR-review aggregation.