{"id":16596527,"url":"https://github.com/mikestead/bitbucket-semver","last_synced_at":"2025-03-21T13:32:19.533Z","repository":{"id":24733825,"uuid":"102317239","full_name":"mikestead/bitbucket-semver","owner":"mikestead","description":"Auto-generate a Semver version based on merged pull requests since the previous release","archived":false,"fork":false,"pushed_at":"2023-01-12T09:56:02.000Z","size":345,"stargazers_count":5,"open_issues_count":17,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-01T06:51:09.911Z","etag":null,"topics":["bitbucket-server","continuous-delivery","continuous-deployment","continuous-integration","semver","versioning"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikestead.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-04T04:01:57.000Z","updated_at":"2025-02-17T16:14:03.000Z","dependencies_parsed_at":"2023-01-14T01:30:50.595Z","dependency_job_id":null,"html_url":"https://github.com/mikestead/bitbucket-semver","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikestead%2Fbitbucket-semver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikestead%2Fbitbucket-semver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikestead%2Fbitbucket-semver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikestead%2Fbitbucket-semver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikestead","download_url":"https://codeload.github.com/mikestead/bitbucket-semver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244141580,"owners_count":20404835,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitbucket-server","continuous-delivery","continuous-deployment","continuous-integration","semver","versioning"],"created_at":"2024-10-11T23:53:32.064Z","updated_at":"2025-03-21T13:32:19.267Z","avatar_url":"https://github.com/mikestead.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bitbucket Semver\n\n[![Build Status](https://travis-ci.org/mikestead/bitbucket-semver.svg?branch=master)](https://travis-ci.org/mikestead/bitbucket-semver)\n\nA tool for [Bitbucket Server](https://www.atlassian.com/software/bitbucket/server) to automatically determine the next [Semver](http://semver.org/) version of a repository based on merged pull requests.\n\nBest when used together with the [Semver Pull Request Checker Plugin](https://marketplace.atlassian.com/plugins/mikestead.bitbucket.bitbucket-semver/server/overview) to enforce Semver labels on all pull requests.\n\n### Installation\n\nvia yarn\n\n    yarn global add bitbucket-semver\n\nor npm\n\n    npm install bitbucket-semver --global\n\n*You must be running Node v7.6+*\n\n### Usage\n\n    bbsemver \\\n        --url https://bitbucket.company.com/projects/foo/repos/bar \\\n        --username bitbucket-username \\\n        --password bitbucket-password\n\nAny of these parameters may also be provided via environment variables.\n\n- `BITBUCKET_PROJECT_URL`\n- `BITBUCKET_USER`\n- `BITBUCKET_PASSWORD`\n\nThe 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 `0`.\n\nIf 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.\n\nHere's an example of how a bash script may look which calls this, assuming all environment variables are set.\n\n```bash\necho \"determining Semver version based on merged pull requests\"\noutput=\"$(bbsemver -v)\"\necho \"$output\"\n# get new version from the last line of output\nsemverVersion=$(echo \"$output\" | tail -n1)\n\n# if there's no version change then exit\nif [ \"$semverVersion\" = \"unchanged\" ]; then\n  echo \"no version change found, aborting release\"\n  exit 0\nfi\n\n# otherwise we can use the version to generate a changelog, tag a release etc.\n# e.g. if versioning an npm package\nnpm version $semverVersion\n```\n\n#### Docker\n\nThe tool is also available as a [Docker image](https://hub.docker.com/r/stead/bitbucket-semver). \n\n    docker run --rm stead/bitbucket-semver --help\n\n### Versioning\n\nBitbucket Semver works based on the previous highest *non pre-release* tag of your repository. We'll call this a *base* tag.\n\nExamples\n\n- base:   `1.0.0`\n- base:   `1.0.0+metadata`\n- non-base: `1.0.0-rc.1`\n- non-base: `1.0.0-beta.1+metadata`\n\nGiven 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.\n\nFor each merged PR title it looks for one of the following keyword prefixes.\n\n- `Major`: Breaking change\n- `Minor`: Backwards compatible feature\n- `Patch`: Backwards compatible fix\n- `Upkeep`: General housekeeping which doesn't require a release e.g. improved tests or documentation.\n\n**If any merged PR is discovered without a semver title prefix then the tool will exit with code `1` printing the offending PR title.**\n\nNote that we'd prefer to look for semver _labels_ on a PR but these are [still unsupported](https://bitbucket.org/site/master/issues/11976/ability-to-add-labels-to-pull-requests-bb#). \n\nScanning 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.\n\nThe 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.\n\nYou 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.\n\nHere are some examples of generated version increments based on merged PRs.\n\n    1.0.0\n    - patch\n    - patch\n    \u003e bbsemver\n    = 1.0.1\n\n    1.0.0\n    - patch\n    - minor\n    - patch\n    \u003e bbsemver\n    = 1.1.0\n\n    1.0.0\n    - minor\n    - major\n    - patch\n    \u003e bbsemver\n    = 2.0.0\n\n#### Pre-release\n\nA pre-release can be generated via one of the following options.\n\n- `--alpha`\n- `--beta`\n- `--rc`\n- `--pre [tag]`\n\nThe first three will add their respective pre-release tag to the base version, the last allows for a custom tag.\n\nFor 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.\n\nIt'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 `1`.\n\nHere's an example to help clarify.\n\n    1.0.0\n    - patch\n    - patch\n    \u003e bbsemver --beta\n    = 1.0.1-beta.1\n    - patch\n    \u003e bbsemver --beta\n    = 1.0.1-beta.2\n    - minor\n    - patch\n    \u003e bbsemver --beta\n    = 1.1.0-beta.1\n\n#### Metadata\n\nYou can add metadata to the outputted version via the `--meta [tag]` option.\n\n    1.0.0\n    - patch\n    \u003e bbsemver --meta build21\n    = 1.0.1+build21\n\n### CLI Options\n\n```\n  Usage: bbsemver [options]\n\n\n  Options:\n\n    -V, --version              output the version number\n    --url [url]                bitbucket project url e.g. https://bitbucket.company.com/projects/foo/repos/bar\n    -u, --username [username]  bitbucket username. Can be defined via BITBUCKET_USER env variable\n    -p, --password [password]  bitbucket password. Can be defined via BITBUCKET_PASSWORD env variable\n    -b, --branch [name]        root branch to scan for merged pull requests since last release. Defaults to \"master\"\n    -c, --current [version]    current base semver version. If undefined will be searched for in tag history.\n    --alpha                    add an alpha pre-release tag\n    --beta                     add a beta pre-release tag\n    --rc                       add a release candidate (rc) pre-release tag\n    --pre [tag]                add a custom pre-release tag\n    --meta [tag]               add a metadata tag\n    --json                     output incremented version in json format\n    --dev                      maintain a semver major of zero during initial development\n    -d, --depth [int]          depth of child pull requests to walk. Defaults to 1 which inspects PRs merged into the root branch only\n    -v, --verbose              enable verbose logging\n    -h, --help                 output usage information\n```\n\n### Programmatic Usage\n\nFor JavaScript developers you can also use the library programmatically.\n\n```javascript\nconst bbsemver = require('bitbucket-semver')\nbbsemver({\n  url: 'https://bitbucket.company.com/projects/foo/repos/bar',\n  username: 'bitbucket-username',\n  password: 'bitbucket-password'\n})\n.then({ current, next, isFirstTag } =\u003e {\n  console.log(current, next, isFirstTag)\n})\n.catch(error =\u003e {\n  console.error(error)\n})\n```\n\n#### Options\n\n```\n/**\n * bitbucket project url e.g. https://bitbucket.company.com/projects/foo/repos/bar\n */\nurl: string\n/**\n * bitbucket username. Can be defined via BITBUCKET_USER env variable\n */\nusername: string\n/**\n * bitbucket password. Can be defined via BITBUCKET_PASSWORD env variable\n */\npassword: string\n/**\n * root branch to scan for merged pull requests since last release. Defaults to \"master\"\n */\nbranch: string\n/**\n * current base semver version. If undefined will be searched for in tag history.\n */\ncurrent: string\n/**\n * add an alpha pre-release tag\n */\nalpha: boolean\n/**\n * add a beta pre-release tag\n */\nbeta: boolean\n/**\n * add a release candidate (rc) pre-release tag\n */\nrc: boolean\n/**\n * add a custom pre-release tag\n */\npre: string\n/**\n * add a metadata tag\n */\nmeta: string\n/**\n * maintain a semver major of zero during initial development\n */\ndev: boolean\n/**\n * depth of child pull requests to walk. Defaults to 1 which inspects PRs merged into the root branch only\n */\ndepth: number\n/**\n * enable verbose logging\n */\nverbose: boolean\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikestead%2Fbitbucket-semver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikestead%2Fbitbucket-semver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikestead%2Fbitbucket-semver/lists"}