Keep your BitBucket Settings under version control
The behaviour of a BitBucket repository can be customized in a multitude of ways. Configuring default reviewers, branch restrictions, hooks and merge strategies can be a tedious, repetitive and error prone procedure if it is performed via the GUI, especially with a large number of repositories.
Wouldn't it be nice if it was possible to store the BitBucket settings
under version control and maintain them in the same way we maintain
code? This is the idea behind BEC, a tool which has been developed
internally at Klarna. The tool allows you to write your BitBucket
repository settings in yml
format and to check and apply them via a
command line interface.
BEC comes with extensive documentation and sample repository configuration files. It also supports Mustache templates, allowing you to apply variations of your configuration to multiple repositories.
Here's a short presentation explaining what BEC is about.
BEC requires BitBucket Server 5.5 or superior.
To build bec
, you need Erlang/OTP 21+ and rebar3 installed on your machine.
git clone git@github.com:klarna-incubator/bec.git
cd bec
rebar3 escriptize
You will get an executable escript in:
_build/default/bin/
Ensure the location of the script is added to your PATH
:
export PATH=/path/to/_build/default/bin:$PATH
Then you can run BEC:
$ bec
Usage: bec [-h] [-c [<config>]] [-r [<repo_config>]]
[-e [<enforce>]] [-k [<keep>]]
[-v [<verbosity>]]
-h, --help Show this help message
-c, --config The BitBucket Config File [default: bitbucket.config]
-r, --repo_config The Repo Config to check or configure [default: undefined]
-e, --enforce Enforce values when they do not match expectations [default: false]
-k, --keep Keep going after the first error (always true when enforce == true) [default: false]
-v, --verbosity Verbosity Level [default: 1]
docker run --rm --name erlangbuilder -v ${PWD}:/bec -w=/bec erlang rebar3 escriptize
BEC supports both Basic Authentication (via username/password) and Token-Based Authentication (preferred).
If both a token
and a username/password
pair are provided, the token will take precedence.
Set BitBucket url and credentials in bitbucket.config
:
{bitbucket_url, "https://my.bitbucket.server"}.
{bitbucket_username, "first.last"}.
{bitbucket_password, "password"}.
{bitbucket_token, "someToken"}.
Please follow this guide if you want to generate the token to authenticate.
You can find a sample configuration file for a custom BitBucket repo in sample_repo_configuration.yml.
It is a common need to apply very similar configuration to multiple repositories. Repo configuration templates are supported for this use case.
A repo configuration file is similar to a repo configuration, but has
a .ymlt
extension, and will be rendered as a
Mustache template. The parameters for
the template are defined in a .ymlv
file (as Yaml).
For example common_repo.ymlt
may look like this:
---
project: {{project}}
repo: {{repo}}
pr-restrictions:
required-all-approvers : true
required-all-tasks-complete : true
required-approvers : 2
{{#has_ci}}required-successful-builds : 1
{{/has_ci}}
# Please note that Mustache throws away all white space after
# section opening and closing tags, this is the reason for not
# putting both of them on a single line. The closing tag has to
# be indented as much as the next line of Yaml needs to be.
{{#has_ci}}
hooks:
- key: "com.nerdwin15.stash-stash-webhook-jenkins:jenkinsPostReceiveHook"
enabled: true
settings:
branchOptions:
branchOptionsBranches:
cloneType: custom
gitRepoUrl: ssh://git@my.bitbucket.server/{{project}}/{{repo}}.git
ignoreCerts: false
ignoreCommitters:
jenkinsBase: https://jenkins.hipster.company.io/
omitBranchName: false
omitHashCode: false
omitTriggerBuildButton: false
{{/has_ci}}
The corresponding common_repo.ymlv
specifies the values for the
project
, repo
and has_ci
variables:
---
- project: MYTEAM
repo: my_repo
has_ci: true
- project: MYTEAM
repo: best_cat_pics
has_ci: false
Please note that previous versions of the BitBucket Erlang client only
supported the repo
parameter in the .ymlt
file, and the .ymlv
file had a simplified syntax:
---
repo:
- my_repo
- best_cat_pics
- Basic HTTP Authentication is the only authentication mechanism currently supported
- The BitBucket Paged API is not supported, yet
- Roberto Aloi
See our guide on contributing.
See our changelog.
Copyright © 2020 Klarna Bank AB
For license details, see the LICENSE file in the root of this project.