Blueprint - Getting Started

Using the Getting-Started Blueprint built-in script provides you with access to a number of recommended/widely used configurations. It allows you to quickly apply these across a selection of your projects and repositories. The Getting-Started Blueprint built-in script is useful when setting up new Bitbucket instances as it ensures that all projects and repositories have consistent behaviour.

Leaving any fields blank means the corresponding configuration is not created.

Navigate to Built-in Scripts>Blueprint - Getting Started and from there, you can pick and choose the configurations you want to apply to your project/repositories. 

(Optional) Add a Note that relates to the configurations created by the script you are running. You can use this to identify the configurations created as part of running this script. If you prefer not to add a note, a default note that states, 'Added as part of Getting Started Blueprint', is added to each configuration created.

You can choose to set the Configurations State for the new configurations to either disabled or enabled. Once created, you can make further refinements at a later stage.

We recommend creating the configurations in a disabled state. As new configurations do not take effect when created, you can choose to enable them later after refining individual configurations to your liking.

Global Configurations

You can enforce naming standards for projects and repositories using this built-in listener. It allows you to create a Project and Repository Naming Standards Enforcement listener as per your needs.

Define a regular expression for either or both project and repository names, but you must provide a value for at least one of these fields for the listener to be created.

Project/Repository Specific Configs

These specific configurations, once created, will apply to the selected projects/repositories


Merge Strategy

You can choose either Merge Commits or Force Push from the drop down list. If you do not make a selection, then configurations are not created.

Reject Merge Commit

This option creates a pre-hook that enforces a linear workflow policy, meaning that any unnecessary merge commits will be rejected. This forces your users to use rebase rather than merge to keep a linear history. Using this option does not affect pull requests, so branches can still be merged. However, the trivial merge commits will be avoided. You can set up a custom message that displays whilst the push is rejected.

Refer to Reject Merge Commits if you want to refine the newly created pre-hook further

Reject Force Push

This option creates a pre-hook that is the same as the per-repo hook contained within Bitbucket. It is reproduced here to allow system administrators to apply it at a level above the project/repository administrator so they cannot disable it.

You might want to combine this hook with conditions so that you disable force pushing to the default and release branches only, for instance, or allow only on feature branches.

Refer to Reject Force Push if you want to refine the newly created pre-hook further.

Auto-check Delete Branch Checkbox

Once checked, a Check Delete Branch Checkbox listener is created. This automatically checks the Delete source branch after merging checkbox on the pull request merge dialog.

Automatic checking of the checkbox may be useful for teams that want to enforce the deletion of branches once they have been merged into other branches.

Refer to Check Delete Branch Checkbox if you want to refine the newly created listener further

Withdraw Approvals When a Pull Request Changes

Once checked, a listener is created that removes any approvals when new content is pushed to an existing pull request if the condition matches. 


This listener helps manage your approvals process, as by default, a user can push more content to a pull request even after it has been approved, yet the approvals remain.

Refer to  Withdraw Approvals When a Pull Request Changes if you want to refine the newly created listener further.

Minimum Number of Approvers

Specifying a value in this field creates a merge check which requires that the specified number of reviewers have approved the pull request. This is already available on a per-repo basis, where you can require that pull requests are reviewed by, say, two reviewers. What makes this different is that you can combine it with the conditions to create a powerful git workflow. 

Refer to Require a Minimum Number of Approvers if you want to refine the newly created merge check further.

Maximum File Size

Specifying a value in this field creates a pre-hook that restricts the maximum file size of an individual file. This is important because, once pushed and accepted, all files will stay in the repo forever. It will be transmitted to anyone who clones the repo, increasing the time for the checkout operation and their disk space requirements.

Refer to Restrict File Size if you want to refine the newly created pre-hook further.

Branch and Tag Naming Patterns

Specifying a regular expression in any of these fields will create a pre-hook that enforces a naming standard for branches and tags using regular expressions.

You may want different naming standards for different types of branches. For example, for your feature and bugfix branches, you may want them to contain a Jira issue ID. You may require that hotfix branches begin with a Change Request ID. Therefore you can specify multiple regular expressions for both branches and tags. If none of them matches, the supplied error message (or a default one) will be returned to the user. 

Refer to Branch and Tag Naming Standards Enforcement if you want to refine the newly created pre-hook further.

Click the Create Configurations button, and the configurations created will be displayed as shown below:

You can click on any of the configurations created (which will open a new tab) to refine them further.

On this page