Best when used together with the Semver Pull Request Checker Plugin to enforce Semver labels on all pull requests.
yarn global add bitbucket-semver
npm install bitbucket-semver --global
You must be running Node v7.6+
bbsemver \ --url https://bitbucket.company.com/projects/foo/repos/bar \ --username bitbucket-username \ --password bitbucket-password
Any of these parameters may also be provided via environment variables.
The output of this command will be the incremented semver version printed to stdout (e.g.
1.3.6) or if unchanged then the string
unchanged. Both return an exit code of
If you want to see verbose output add the
-v option. With this enabled you can look at the last line of output to determine the version.
Here's an example of how a bash script may look which calls this, assuming all environment variables are set.
echo "determining Semver version based on merged pull requests"output="$(bbsemver -v)"echo "$output"# get new version from the last line of outputsemverVersion=$(echo "$output" | tail -n1)# if there's no version change then exit# otherwise we can use the version to generate a changelog, tag a release etc.# e.g. if versioning an npm packagenpm version $semverVersion
The tool is also available as a Docker image.
docker run --rm stead/bitbucket-semver --help
Bitbucket Semver works based on the previous highest non pre-release tag of your repository. We'll call this a base tag.
Given a base tag, it will examine the titles of merged pull requests (PRs) to a target branch since this tag was created. By default the target branch is
master but you may override it via the
--branch [name] option.
For each merged PR title it looks for one of the following keyword prefixes.
Major: Breaking change
Minor: Backwards compatible feature
Patch: Backwards compatible fix
Upkeep: General housekeeping which doesn't require a release e.g. improved tests or documentation.
If any merged PR is discovered without a semver title prefix then the tool will exit with code
1 printing the offending PR title.
Note that we'd prefer to look for semver labels on a PR but these are still unsupported.
Scanning of pull requests will go one level deep unless a custom depth is specified via the
--depth [depth] option. This means that any PR merged directly to
master will be examined but any PR merged to another branch which then merged to master won't.
The reason for this default is to ensure high accuracy. For example a
major PR may have been opened and merged to another branch months previously. If the branch it merged into only just made its way to master but in that time the
major it referred to has already gone in via another PR then we'd end up with an invalid
major bump. This issue is exacerbated by the inability to edit the metadata of a merged PR in Bitbucket Server.
You may feel this is an unduly cautious setting so are free to define your own more liberal scanning depth. Remember though that the semver tag on a PR going into
master should reflect any PR's which have merged into it.
Here are some examples of generated version increments based on merged PRs.
1.0.0 - patch - patch > bbsemver = 1.0.1 1.0.0 - patch - minor - patch > bbsemver = 1.1.0 1.0.0 - minor - major - patch > bbsemver = 2.0.0
A pre-release can be generated via one of the following options.
The first three will add their respective pre-release tag to the base version, the last allows for a custom tag.
For any of these options a count will also be added to the tag. This will auto increment if the same pre-release is applied to the same calculated version.
It's important to note that each pre-release tag is generated from all merged PRs since the last full (base) release. If the semver increment increases between two consecutive pre-releases of the same type then the pre-release counter is reset to
Here's an example to help clarify.
1.0.0 - patch - patch > bbsemver --beta = 1.0.1-beta.1 - patch > bbsemver --beta = 1.0.1-beta.2 - minor - patch > bbsemver --beta = 1.1.0-beta.1
You can add metadata to the outputted version via the
--meta [tag] option.
1.0.0 - patch > bbsemver --meta build21 = 1.0.1+build21
Usage: bbsemver [options] Options: -V, --version output the version number --url [url] bitbucket project url e.g. https://bitbucket.company.com/projects/foo/repos/bar -u, --username [username] bitbucket username. Can be defined via BITBUCKET_USER env variable -p, --password [password] bitbucket password. Can be defined via BITBUCKET_PASSWORD env variable -b, --branch [name] root branch to scan for merged pull requests since last release. Defaults to "master" -c, --current [version] current base semver version. If undefined will be searched for in tag history. --alpha add an alpha pre-release tag --beta add a beta pre-release tag --rc add a release candidate (rc) pre-release tag --pre [tag] add a custom pre-release tag --meta [tag] add a metadata tag --json output incremented version in json format --dev maintain a semver major of zero during initial development -d, --depth [int] depth of child pull requests to walk. Defaults to 1 which inspects PRs merged into the root branch only -v, --verbose enable verbose logging -h, --help output usage information
const bbsemver =
/** * bitbucket project url e.g. https://bitbucket.company.com/projects/foo/repos/bar */ url: string /** * bitbucket username. Can be defined via BITBUCKET_USER env variable */ username: string /** * bitbucket password. Can be defined via BITBUCKET_PASSWORD env variable */ password: string /** * root branch to scan for merged pull requests since last release. Defaults to "master" */ branch: string /** * current base semver version. If undefined will be searched for in tag history. */ current: string /** * add an alpha pre-release tag */ alpha: boolean /** * add a beta pre-release tag */ beta: boolean /** * add a release candidate (rc) pre-release tag */ rc: boolean /** * add a custom pre-release tag */ pre: string /** * add a metadata tag */ meta: string /** * maintain a semver major of zero during initial development */ dev: boolean /** * depth of child pull requests to walk. Defaults to 1 which inspects PRs merged into the root branch only */ depth: number /** * enable verbose logging */ verbose: boolean