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
- The Releases page, under Apps in the repository sidebar: every tag, newest first, with the latest final release and pre-releases marked. Open one to see its notes, changes, evidence, artifacts and export.
- The Latest release card on the repository's Source page: the newest final release, its date, its headline and how many tags the repository has.
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
- As a workspace administrator, install Releases for Bitbucket on your workspace. Atlassian's install page asks which workspace.
- 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:
-
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. -
The version's section of the changelog at the tagged commit:
CHANGELOG.md,CHANGES.md,HISTORY.md,RELEASE_NOTES.mdorNEWS.md. The section is the one whose heading carries the version, with or without a leadingv. - 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.
2.0.0counts from1.9.0, not from2.0.0-rc.3.- A
1.4.2tagged after2.0.0counts from1.4.1. -
Tags with a different prefix are separate lines:
pipe-v1.3.0andv1.3.0never count from each other. - The first tag on a line counts every commit up to it.
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:
- how many pull requests were approved by someone other than their author;
- which were merged by their author with no other approval, or while a reviewer was still asking for changes;
- commits without a pull request, release automation counted separately;
- whether the tagged commit built, from its build statuses;
- every Code Insights report on the tagged commit, such as coverage or a security scan;
- a lightweight tag, which records neither who tagged it nor when.
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
- The newest 1,000 tags are listed.
- 500 commits and 60 pull requests per release. Past that, the release says it was cut short.
- Bitbucket Cloud only. Bitbucket Data Center has no Forge apps.
Permissions the app requests
| Scope | Why |
|---|---|
read:repository:bitbucket | tags, commits, the changelog at a tag, Downloads, build statuses and Code Insights reports |
read:pullrequest:bitbucket | merged 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.