ci: create a GitHub release for each tag, with notes from its pull requests

[earakely-scale]

What and why

The repo has 14 version tags and no GitHub Releases, so the sidebar says "No releases published" on a project that ships several times a day. From now on, every tag gets a release. Existing tags aren't backfilled.

• A release job in publish-pypi.yml. It runs after framework succeeds, so a release only appears once both packages are on PyPI. It runs gh release create <tag> --verify-tag --generate-notes. Each release looks like this (this is real generate-notes output for v0.9.1265):

  On PyPI: agentenv-framework 0.9.1265 · agentenv-framework-protocol 0.1.280

  What's Changed

  • docs: add a feature request issue template by @earakely-scale in docs: add a feature request issue template #42
  • docs: add README badges and PyPI classifiers, and point CONTRIBUTING at Q&A and the bug form by @earakely-scale in docs: add README badges and PyPI classifiers, and point CONTRIBUTING at Q&A and the bug form #47

  Full Changelog: v0.9.1264...v0.9.1265

  • The header line gives both PyPI versions, because the protocol has no tag of its own.
  • The notes are the PR titles, which already follow Conventional Commits. PRs merged without bump-version roll into the next release. The bot's bump commit isn't a PR, so it doesn't appear.
  • The previous tag is passed explicitly (--notes-start-tag). Otherwise GitHub counts from the previous release, and since there are none, the first release would list every PR ever merged.
  • Safety:
    • Only this job gets contents: write; the PyPI jobs keep their current permissions.
    • The tag comes from $GITHUB_REF_NAME in the environment, not ${{ }} interpolated into the script, to avoid script injection.
    • It uses the gh CLI already on the runner, not a third-party action.
    • An existing release is skipped, keeping the workflow's "a rerun is safe" promise.

• .github/release.yml splits the notes into Changes and Dependencies, using the dependencies label Dependabot already applies (build(deps): bump the python-minor-and-patch group across 1 directory with 15 updates #33 and build(deps): bump mcp from 1.28.1 to 2.3.0 #34 carry it). Library bumps won't bury features.

• A Changelog project URL on both packages, pointing to GitHub Releases, so PyPI's sidebar links it.

• Docs: the README's Releases section and CONTRIBUTING now say where release notes come from. CONTRIBUTING adds that a clear PR title is also the release note.

Left out on purpose: wheels as release assets (PyPI is the canonical download, and trusted publishing already records provenance there), release-please and semantic-release (they would replace the CircleCI bump flow), and a Discussions post per release (too noisy at this cadence).

How it was tested

• check-jsonschema passes for publish-pypi.yml (vendor.github-workflows) and .github/release.yml (SchemaStore github-release-config). actionlint with shellcheck reports no findings.
• I ran the job's exact script locally with a stub gh:
  • v0.9.1265: previous tag v0.9.1264, and the header names agentenv-framework 0.9.1265 and agentenv-framework-protocol 0.1.280
  • v0.9.1252, the first tag: no start tag is passed
  • An existing release: prints "already exists" and exits 0
• uv build for both packages: the wheels' METADATA include Project-URL: Changelog, and twine check --strict passes on all four files. uv lock --check passes.
• The categorised notes can't be previewed before merge, because GitHub reads .github/release.yml only from the default branch.

bump-version is set, so merging tags a release. That release is the new job's first real run, and its notes should list this PR under Changes. I'll check it after the merge.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no actionable issue was established.

What we checked:

• Release after a failed publish: No. The framework job waits for the protocol job, and the release job waits for the framework job.

Summary

The PyPI publishing workflow now creates a GitHub release after publishing both packages, with notes covering pull requests since the previous tag. Release notes separate dependency updates, and the package pages and contributor docs point readers to them.

• Adds links to both PyPI package versions in each release.
• Groups notes under Changes and Dependencies.
• Adds GitHub Releases links to both packages’ PyPI metadata.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Tag["Version tag"] --> Protocol["Publish protocol to PyPI"]
  Protocol --> Framework["Publish framework to PyPI"]
  Framework --> Release["Create GitHub release"]
  Release --> Notes["Notes since previous tag"]

Loading

_{Reviews (1) · Last reviewed commit: "ci: create a GitHub release for each tag..."}