From 2588863b5e51e8916a4ccf17eb58dd2c16ac43ef Mon Sep 17 00:00:00 2001
From: dgenio <diogo.ansantos@nos.pt>
Date: Mon, 9 Mar 2026 06:46:08 +0000
Subject: [PATCH 1/2] feat: add GitHub Release step to publish workflow

---
 .github/workflows/publish.yml | 48 +++++++++++++++++++++++++++++++----
 CHANGELOG.md                  |  3 +++
 RELEASE.md                    |  3 ++-
 3 files changed, 48 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 09baafa..e545f02 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -9,14 +9,12 @@ jobs:
     name: "CI gate"
     uses: ./.github/workflows/ci.yml
 
-  publish:
-    name: "Build & publish"
+  build:
+    name: "Build"
     needs: ci
     runs-on: ubuntu-latest
-    environment: pypi
     permissions:
-      contents: read   # required for actions/checkout
-      id-token: write  # required for Trusted Publisher (OIDC)
+      contents: read
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4.3.1
 
@@ -31,5 +29,45 @@ jobs:
       - name: Build sdist and wheel
         run: python -m build
 
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@ea165f8d65b6db9a6b7c67862cd61e31b2b2b817  # v4.6.2
+        with:
+          name: dist
+          path: dist/
+
+  release:
+    name: "GitHub Release"
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # required to create releases
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b  # v2.5.0
+        with:
+          generate_release_notes: true
+          files: dist/*
+
+  publish:
+    name: "Publish to PyPI"
+    needs: release
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write  # required for Trusted Publisher (OIDC)
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
+        with:
+          name: dist
+          path: dist/
+
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e  # v1.13.0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b766306..c49b14e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- GitHub Release step in publish workflow — creates a release with auto-generated notes and artifacts before publishing to PyPI.
+
 ## [0.3.0] - 2026-03-09
 
 ### Added
diff --git a/RELEASE.md b/RELEASE.md
index e4cbf21..7bb253c 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -53,7 +53,8 @@ Pushing the `v*` tag triggers `.github/workflows/publish.yml`, which:
 
 1. Runs the full CI suite (`make ci` equivalent) as a gate.
 2. Builds the sdist and wheel with `python -m build`.
-3. Publishes to PyPI using Trusted Publisher (OIDC — no API tokens stored).
+3. Creates a GitHub Release with auto-generated notes and the built artifacts attached.
+4. Publishes to PyPI using Trusted Publisher (OIDC — no API tokens stored).
 
 Monitor the workflow run at:
 <https://github.com/dgenio/agent-kernel/actions/workflows/publish.yml>

From 18ffb6d511811dfe0e304526fce5a13946e66188 Mon Sep 17 00:00:00 2001
From: Diogo Andre Passagem Santos <dandrsantos@corporativo.pt>
Date: Sat, 14 Mar 2026 11:16:57 +0000
Subject: [PATCH 2/2] fix: fail release on missing dist artifacts

---
 .github/workflows/publish.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index e545f02..6cec1d7 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -52,6 +52,7 @@ jobs:
         uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b  # v2.5.0
         with:
           generate_release_notes: true
+          fail_on_unmatched_files: true
           files: dist/*
 
   publish: