Version 2 · Updated 26 October 2026

Releases

Drafting and publishing releases, their tags made through the push guard, notes, change maps and who can do what.

A release is Branchscope's record of a git tag, such as v1.4.0, with a title and Markdown notes. It can be a draft, a pre-release or published. The Releases tab lists a repository's releases, newest first; the newest published one that isn't a pre-release is marked Latest.

Making a release#

New release on the Releases tab, for anyone with write access:

Tag: an existing tag, or a new name. A new tag is made only when the release is published.
New tag from: for a new tag, the branch, or a commit by its SHA, to make it at.
Compare with: The latest release (the default), another tag, or Nothing (the first release).
Generate notes offers notes listing the changes merged since that release, each with its author, and the agent if one wrote it. Edit them as you like.
Release title, Notes (Markdown), and This is a pre-release if it is one.
Publish release, or Save draft.

A draft writes nothing to git, and only people with write access see it. Publish it later from its page.

Publishing#

Publishing a release whose tag doesn't exist yet makes the tag, at the release's commit, through the push guard, as a push of the tag by the person publishing. If the guard refuses, or can't be reached, nothing is published and nothing is saved.

The tag's tag rulesets apply:

Restrict creations and Block agent updates apply as to a push of the tag.
Require status checks to pass: the checks named must have passed on the commit first, or publishing is refused with those that haven't, such as the tag v1.4.0 needs these checks to have passed on 3fb9414 first: CI / test.
Require deployments to succeed: the commit's latest deployment to each environment named must have succeeded, such as the tag v1.4.0 needs 3fb9414 to have been deployed to staging first.

A tag with required checks or deployments can only be made this way: a git push of it is refused, unless the pusher is on the ruleset's bypass list. A release of a tag that already exists writes nothing to git.

When a release is published:

the release.published webhook event is sent;
workflows with on: release start at its tag's commit (published, or prereleased for a pre-release), and a newly made tag starts the on: tag ones, once each (see Branchscope actions).

Who can do what#

	People with write access	Agents and apps
Draft a release, change or delete a draft	yes	yes
Publish a release	yes	no
Change or delete a published release	yes	no

Agents only draft. An agent's draft waits for a person to read it and publish it. Agents draft over MCP with create_release, or with bscope release create --draft. Nothing can be released in an archived repository.

Pre-releases#

A pre-release is published like any release, makes its tag, and starts on: release workflows of type prereleased. It's never marked Latest, and a new release compares with the latest release that isn't one.

Editing and deleting#

Edit changes the title, the notes and whether it's a pre-release; a draft can be published from there too. What it compares with changes through the API (previousTag). A release's tag and commit don't change.
A published release can't become a draft again: delete it and draft a new one.
Delete removes the release and its notes. The tag stays in git; delete it with git if you mean to, as its tag rulesets allow.

The change map#

A release that compares with an earlier one has a change map: the diagrams of what changed between the two, derived from the code like a change's review, from where the two releases' histories meet to this release's commit. It's built once the release is saved, draft or not, and the release's page refreshes itself until it's ready. The first release has none, and neither has one whose previous release already contains its commit.

Agents read it over the API (GET …/releases/{tag}/views, which apps need reviews:read for).

Where it's deployed#

The Releases tab and each release's page show Deployed to: the environments its tag has been deployed to, and how each deployment went. See Deployments.

The CLI and the API#

bscope release list
bscope release view v1.4.0
bscope release create v1.4.0 --target main --generate-notes      # published at once
bscope release create v1.5.0-rc.1 --target main --prerelease --draft
bscope release publish v1.5.0-rc.1                                  # a person publishes the draft
bscope release edit v1.5.0-rc.1 --notes-file NOTES.md --prerelease=false
bscope release delete v1.5.0-rc.1                                   # the tag stays

`bscope release create <tag>`
`--target`	For a new tag: the branch or commit to make it at
`-t`, `--title`	The title; the tag if left out
`-n`, `--notes`, `-F`, `--notes-file`, `--generate-notes`	The notes: given, from a file, or offered from the merged changes
`--previous`, `--no-previous`	The release to compare with (the latest by default), or none
`-d`, `--draft`	Save it as a draft; agents must
`-p`, `--prerelease`	Mark it a pre-release

`bscope release edit <tag>`
`-t`, `--title`	The new title
`-n`, `--notes`, `-F`, `--notes-file`	The new notes, given or from a file
`-p`, `--prerelease`	Mark it a pre-release; `--prerelease=false` unmarks it

Only what you pass changes. bscope release publish <tag> publishes a draft (people only), and bscope release delete <tag> deletes a release; its tag stays in git.

Generated notes look at up to 1,000 commits since the previous release (the newest 1,000 for a first release); when that cuts them short, the notes say so.


`GET /repos/{owner}/{name}/releases`, `GET …/releases/{tag}`	releases, newest first (drafts too, with write access); one release
`POST …/releases/generate-notes`	the notes offered for a tag (`{tag, target, previousTag}`)
`POST …/releases`, `PUT …/releases/{tag}`, `DELETE …/releases/{tag}`	make one (`{tag, target, title, notes, previousTag, draft, prerelease}`), change it (`{"draft": false}` publishes a draft), delete it
`GET …/releases/{tag}/views`	its change map