Put upgrade notes from the release pull request into the GitHub release #6

Problem

gh-release.yaml publishes each release with GitHub's generated notes, which list the merged pull requests by title. Upgrade notes have nowhere to go: a setting to change, a monitoring URL to update, a Tomcat version to move to. Today they're written in the release pull request's description, and someone pastes them into the release after it's published.

Example: epics2web v2.3.0. Its upgrade notes, including a required Nagios change, were written in JeffersonLab/epics2web#54 and pasted in by hand about two minutes after the release was published. Anyone reading the release in between, or if the paste were forgotten, would miss the required change.

The JLab GitLab release workflow already handles this. With notes-from-commit, the body of the commit that changes VERSION goes above the generated notes, and a preview-release-notes job shows the result in the merge request (Managing releases → Release notes). The coding-agents guide currently tells agents to put GitHub upgrade notes in the pull request description for a maintainer to copy (git-workflow.md → Releasing).

Goal

When a release's pull request has upgrade notes, gh-release.yaml puts them at the top of the GitHub release, above the generated notes, with no manual step. Optionally, the pull request shows a preview before merging, as on GitLab.

What's available

Combining the text with the generated notes: already possible. gh-release.yaml uses softprops/action-gh-release@v2 with generate_release_notes: true. Its README says that when body (or body_path) is also given, "the body will be pre-pended to the automatically generated notes". So the only missing piece is getting the notes text. (Its latest release is v3.0.3, if a version bump is wanted at the same time.)

Where the notes could come from:

1. The merged pull request's description (recommended). GitHub's REST API lists the pull requests associated with a commit: GET /repos/{owner}/{repo}/commits/{sha}/pulls. A gh api call in a run step can fetch the description of the merged pull request that produced GITHUB_SHA, and extract a marked section. This keeps the notes editable until merge, and needs no third-party action. Third-party actions do the lookup too, such as 8BitJonny/gh-get-current-pr and jwalton/gh-find-current-pr, but adding a dependency to the release path for a single API call doesn't seem worth it.
2. The body of the commit that changes VERSION, as GitLab does. This works for a VERSION change pushed straight to main, with no pull request. But with squash merging, the pull request description only reaches that commit if the repository's squash commit message is set to the PR description. epics2web uses the default (COMMIT_MESSAGES), so its v2.3.0 commit body is just a trailer. The two sources could be combined: the pull request's section if there is one, otherwise the commit body without its trailers.

Marking the section: the description holds more than the notes, such as checks and an agent footer, so only a marked part should be used. Two options:

• a ## Upgrade notes heading, running to the next heading of the same level;
• explicit HTML comments, such as <!-- upgrade-notes --> … <!-- /upgrade-notes -->, which don't show when the description is rendered and don't depend on heading levels.

The comment markers seem more robust. epics2web#54's notes, for example, have ### subheadings and end with a horizontal rule before the footer.

Whole tools considered and not recommended, since each replaces the current flow rather than adding to it:

• Release Drafter keeps a draft release updated from pull request titles, labels and bodies ($BODY in its templates), and you publish the draft;
• Release Please is driven by Conventional Commits, with release pull requests and a CHANGELOG.md;
• GitHub's .github/release.yml only groups the generated notes by label, and can't include text from a pull request.

Proposed change

In gh-release.yaml, before the Release step, untested:

      - name: Read upgrade notes from the merged pull request
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh api "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/pulls" \
            --jq '[.[] | select(.merged_at != null)][0].body // ""' \
            | awk '/<!-- upgrade-notes -->/{f=1; next} /<!-- \/upgrade-notes -->/{f=0} f' \
            > upgrade-notes.md

Then pass body_path: upgrade-notes.md to softprops/action-gh-release, and check that an empty file leaves the generated notes unchanged.

To check while implementing:

• Permissions: callers grant the release job only contents: write (epics2web's cd.yaml does), and a reusable workflow can't get more than its caller grants. Reading pull requests may need pull-requests: read added in each caller. It may also work without it for public repositories; that needs testing.
• container-workflows has a gh-release workflow too, and would need the same change.
• Related: Release only from the default branch: a VERSION change pushed to any branch publishes a release #5, which limits releases to the default branch, touches the same workflow and could go into the same release of these workflows.

Optional preview, like GitLab's preview-release-notes: a job on pull requests that change VERSION. It would call POST /repos/{owner}/{repo}/releases/generate-notes (with tag_name: v<VERSION>), prepend the marked notes, and write the result to the job summary. It would be read-only and never block the merge.

Done when

• A release whose merged pull request has marked upgrade notes is published with those notes above GitHub's generated notes, with no edit after publishing.
• A release without marked notes is published exactly as today.
• The README of this repository says how to mark the notes. The coding-agents guide's Releasing section can then point there instead of asking for a manual copy.