keelapps Releases for Bitbucket

keelapps/Releases for Bitbucket/Documentation

Documentation

Releases for Bitbucket turns every git tag in a Bitbucket Cloud repository into a release: its notes, the pull requests it brought, the evidence behind it, and its files in Downloads. It reads what git and Bitbucket already recorded, as the person looking, and stores nothing.

How it works

A release here is a git tag. There is nothing to create in the app and nothing to configure: tag a commit, push the tag, and it is on the page.

Setting it up

  1. As a workspace administrator, install Releases for Bitbucket on your workspace. Atlassian's install page asks which workspace.
  2. Open any repository and choose Releases under Apps in its sidebar.

A repository with no tags yet shows the two commands for a first release:

git tag -a v1.0.0 -m "First release"
git push origin v1.0.0

Where the notes come from

Notes come from git, never from the app, so nobody can change them after the fact. In order:

  1. The annotated tag's message (git tag -a). Messages that only repeat the version, such as Tagging for release 1.2.0, and signatures are skipped.
  2. The version's section of the changelog at the tagged commit: CHANGELOG.md, CHANGES.md, HISTORY.md, RELEASE_NOTES.md or NEWS.md. The section is the one whose heading carries the version, with or without a leading v.
  3. Neither: the page says so, and lists the titles of the pull requests in the release instead.

Which release a release is compared with

Changes are counted from the previous release: the next lower version on the same line.

Changes

The pull requests whose commits are in the release, each with its author, who approved it, and the Jira work item keys in its title or branch name. Then the commits that went in without a pull request, with commits from release bots (Bitbucket Pipelines, Dependabot, Renovate and the like) told apart.

Evidence

Plain findings a reviewer or an auditor asks for, each marked good, to check, or a note:

Artifacts

The files in the repository's Downloads whose names carry the version: app-1.2.0.zip belongs to v1.2.0, app-11.2.0.zip does not. Upload them from your pipeline, for example with the atlassian/bitbucket-upload-file pipe, and they show on the release.

Export

Each release copies out as Markdown, for a wiki page, a customer or a change ticket, or as JSON, for an audit file. Both say which repository it came from and when it was read.

Limits

Permissions the app requests

ScopeWhy
read:repository:bitbuckettags, commits, the changelog at a tag, Downloads, build statuses and Code Insights reports
read:pullrequest:bitbucketmerged pull requests, their approvals and their commits

Everything is read as the person viewing the page, so Bitbucket's own repository permissions decide what each person sees. The app has no write scope and no storage, and there is no permissions.external block: it cannot make an outbound call, which Atlassian enforces at the platform level.

Support

Questions, bug reports and feature requests: raise a support request. Security issues: report privately.