fix: publish docker images from the release workflow

.github/workflows/release.yml

@@ -15,6 +15,9 @@ jobs:
   release:
     name: Release & Publish
     runs-on: ubuntu-latest
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+      tag: ${{ steps.release.outputs.tag }}
 
     steps:
       - name: Checkout repository
@@ -173,3 +176,75 @@ jobs:
             "aiagents4pharma-compose-${{ steps.release.outputs.tag }}.tar.gz" \
             "aiagents4pharma-compose-${{ steps.release.outputs.tag }}.zip" \
             --clobber
+
+  docker:
+    name: Docker Release
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - image: talk2aiagents4pharma
+            dockerfile: aiagents4pharma/talk2aiagents4pharma/Dockerfile
+            suffix: ""
+            latest_tag: latest
+            install_cuda: "true"
+          - image: talk2aiagents4pharma
+            dockerfile: aiagents4pharma/talk2aiagents4pharma/Dockerfile
+            suffix: "-cpu"
+            latest_tag: latest-cpu
+            install_cuda: "false"
+          - image: talk2biomodels
+            dockerfile: aiagents4pharma/talk2biomodels/Dockerfile
+            suffix: ""
+            latest_tag: latest
+            install_cuda: "false"
+          - image: talk2scholars
+            dockerfile: aiagents4pharma/talk2scholars/Dockerfile
+            suffix: ""
+            latest_tag: latest
+            install_cuda: "false"
+          - image: talk2knowledgegraphs
+            dockerfile: aiagents4pharma/talk2knowledgegraphs/Dockerfile
+            suffix: ""
+            latest_tag: latest
+            install_cuda: "true"
+          - image: talk2knowledgegraphs
+            dockerfile: aiagents4pharma/talk2knowledgegraphs/Dockerfile
+            suffix: "-cpu"
+            latest_tag: latest-cpu
+            install_cuda: "false"
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.sha }}
+
+      - name: Free up disk space
+        run: |
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /opt/hostedtoolcache || true
+          sudo apt-get clean || true
+          sudo apt-get autoremove -y || true
+          sudo docker system prune -af || true
+          sudo docker builder prune -af || true
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push image
+        uses: docker/build-push-action@v6
+        with:
+          file: ${{ matrix.dockerfile }}
+          push: true
+          platforms: linux/amd64
+          tags: |
+            vpatientengine/${{ matrix.image }}:${{ needs.release.outputs.tag }}${{ matrix.suffix }}
+            vpatientengine/${{ matrix.image }}:${{ matrix.latest_tag }}
+          build-args: |
+            INSTALL_CUDA=${{ matrix.install_cuda }}

RELEASING.md

@@ -44,9 +44,16 @@ Each real release can produce:
 
 ## Docker Releases
 
-Docker image builds are driven by release tags:
+Docker image builds are driven directly by the main release workflow after a successful semantic release.
 
-- workflow trigger: `push` on tags matching `v*`
+Release flow:
+
+1. `python-semantic-release` computes and creates the release tag
+2. Python package artifacts are built and published
+3. compose bundles are attached to the GitHub release
+4. Docker images are built and pushed in the same workflow using the released tag
+
+This avoids the GitHub Actions limitation where tags created by `GITHUB_TOKEN` do not reliably trigger downstream workflows.
 
 The Docker workflow builds and pushes:
 
@@ -57,6 +64,8 @@ The Docker workflow builds and pushes:
 
 CPU/GPU variants are preserved where configured by the workflow.
 
+The standalone `docker_build.yml` workflow remains available for manual or tag-based rebuilds, but normal releases no longer depend on it being triggered by a separate workflow event.
+
 ## Compose Bundles
 
 Compose bundles are packaged during the main release workflow and uploaded as release assets.

docs/developer/WORKFLOWS.md

@@ -160,7 +160,7 @@ ZOTERO_USER_ID: ${{ secrets.ZOTERO_USER_ID }}
 
 **File:** `docker_build.yml`
 
-**Purpose:** Build and push Docker images for all agents
+**Purpose:** Build and push Docker images for manual rebuilds or direct tag-triggered runs
 
 **Features:**
 - Multi-stage builds for optimized image sizes
@@ -210,6 +210,7 @@ ZOTERO_USER_ID: ${{ secrets.ZOTERO_USER_ID }}
 - **PyPI Publishing:** Automated package distribution
 - **GitHub Releases:** Generated from semantic-release notes
 - **Compose bundles:** Attached as release assets without mutating release notes
+- **Docker publishing:** Builds and pushes release-tagged images in the same workflow after a successful release
 
 **Semantic Release Convention:**
 ```bash
@@ -222,20 +223,20 @@ BREAKING CHANGE:     → Major version bump (1.0.0 → 2.0.0)
 - ✅ Python semantic-release automation with conventional commits
 - ✅ Modern uv dependency management for fast builds
 - ✅ Releases are cut from `main`
-- ✅ Auto-creates tags, publishes to PyPI, and uploads release assets
+- ✅ Auto-creates tags, publishes to PyPI, uploads release assets, and publishes Docker images
 
 ### Docker Build
 
 **File:** `docker_build.yml`
 
-**Purpose:** Build and push Docker images for released tags
+**Purpose:** Fallback/manual Docker image publishing workflow
 
 **Triggers:**
 - Push tags matching `v*`
 - Manual workflow dispatch
 
 **Features:**
-- Tag-driven image builds
+- Manual or externally triggered image builds
 - Separate CPU and GPU variants where configured
 - Docker Hub publishing for release versions and `latest` aliases