Make a release

Ask for a release

Tell your agent “let’s release.” It works through the release procedure on its own and opens a pull request titled Release v<version>. The pull request adds one file with the release notes. The agent’s part of its description is one sentence on why it chose the version, and any change it left out of the notes that you might expect to see.

The agent never merges its own release pull request.

Release Planner’s GitHub Actions workflow writes the rest of the description around that sentence, and updates it on every push:

• at the top, a link to edit the notes on GitHub, what merging does, and the version, the release commit, and the previous release
• at the bottom, each job with a link to it, including your release checks, any release notes rules the notes break, and any release assets with a link to download them

It leaves the agent’s sentence, and anything you add around it, alone.

Review the notes

Use the link in the pull request description to edit the notes file on GitHub. Rewrite anything you like: the notes you merge are published exactly as written. Check that:

• the version is right for the changes, especially if anything breaks compatibility
• the notes lead with what matters most
• nothing important is missing

To change the version, ask the agent to redo the release for the version you want, or rename the file yourself, for example from _releases/v1.1.0.md to _releases/v2.0.0.md, and update the Full Changelog link at the end. You can also ask the agent to revise the notes; it keeps your edits.

Saving edits publishes nothing, and doesn’t change the release commit.

The release contains the changes up to the commit the pull request branched from. If you want changes merged since then in the release, ask the agent to include them; it merges the main branch into the pull request and adds them to the notes.

Merge to publish

Merging the pull request is the approval. Wait for the release status to show the checks passed first. The workflow then tags the release commit and publishes the notes as the GitHub release, with the files the pull request built, and updates the description with a link to it. If you configured post-publish workflows, it runs them next.

If anything fails, the top of the description names the failed jobs and how to retry, and the workflow comments on the pull request to mention you, since GitHub doesn’t notify anyone about an edited description.

If publishing fails

Open the run the description links to. Once the problem is fixed, use Re-run failed jobs on that run. Re-running is always safe: it publishes the same release commit and files, and if the release was already published, the workflow changes nothing.

If the release commit itself is broken, for example because a pre-publish workflow failed on it, re-running can’t help. Withdraw the release instead: delete its notes file, such as _releases/v1.1.0.md, in the pull request that fixes the cause, then ask your agent for a release again. It can reuse the version, since it was never tagged. If the old run had started attaching files, it left an unpublished draft release for that version: delete the draft on GitHub before you merge the new release pull request, or its run stops and asks you to. Its old run checks immediately before each write, so once the withdrawal merges, re-running that run publishes nothing.

If publishing failed with Resource not accessible by integration, the release commit’s workflow files match no branch any more, and the workflow’s own token can’t tag it. Publish with a release GitHub App, then use Re-run failed jobs.

Correct published notes

Published tags and files never change, but notes can. Ask your agent to fix the notes of a release, or edit its file, such as _releases/v1.1.0.md, in a pull request of its own. Its description says merging updates that release’s notes, and warns if someone edited them on GitHub since, because merging replaces those edits. Merging updates the release on GitHub. Deleting a published release’s notes file isn’t allowed.