Atlassian Stash is known to be highly configurable. But so far, it is not possible to configure repository settings centrally in a Stash project in order to reduce administration efforts. In this blog post, we will first present the various ways a Stash repository can be configured and then show a solution how we can deal with the administration issue.

Overview of Stash’s repository settings

The following paragraphs give you an overview about the various settings we can configure for a Stash repository. If you are already familiar with the administration of Stash repositories, you can jump right to the section about how to manage Stash repositories centrally.

Repository and branch permissions

Let’s start with the first type of repository settings: repository and branch permissions. Stash has a highly customizable permission system. Permissions can be configured on various levels: globally (for the whole Stash server or cluster), on the project level (e.g., to define the core development team for a project), on individual repositories e.g., to allow external developers or consultants to access a repository for special purposes) and even on branches.

Branch permissions are actually restrictions and are used in scenarios where multiple people need write access to a repository but only the ones with WRITE permission for a specific branch are allowed to commit changes to (e.g., to enforce workflows where only a release manager is allowed to merge changes into a release branch).

On every permission hierarchy type, the permissions BROWSE (view files, clone, pull to local), READ (+ creating pull requests and forking to a personal project), WRITE (+ merge pull requests) and ADMIN (+ can edit settings and permissions) can individually be set. The following picture outlines a possible repository permission configuration:

Repository permissions configuration screenshot in Stash.

Stash hooks settings

The next type of settings that can be configured in a repository are Stash hook settings. Stash hooks are configured on a repository basis. There are Stash hooks that do not have a configuration at all (like e.g. the “Reject Force Push” hook), while others provide a dozen of configuration options. See the following picture where we haven chosen to show the settings of the Stash hook “Pull Request Please” (e.g., the field to protect branches from direct pushes with a regular expression):

Pull Request Please hook configuration screen.

Pull request settings

With Stash, we can customize workflows by setting checks which control when a pull request can be merged. These checks can be configured in the pull request settings of a repository. There are three options to configure when Stash should allow pull requests to be merged: The minimum number of successful builds, the minimum number of approvers and if all tasks need to be resolved before the merge can complete. These settings are an important facility to only allow code being merged into the development mainline if it adheres to certain minimum quality standards.

Branching model settings

The last setting type we want to discuss here is the branching model. Stash’s branching model is quite a new concept that was introduced with Stash 2.8. Stash allows us to configure the different types of branches on a repository basis. See the following picture that shows the configuration of a branching model that adopts Gitflow:

Screenshot of the branch model configuration in Stash.

Although Stash does not make heavy use of the branching model yet, there are nevertheless a few interesting applications of it that helps a team to standardize naming conventions and workflows: one application is that the Stash GUI automatically adds a prefix to the branch name depending on the JIRA issue type the branch was created from. See the following example where we create a branch from a JIRA feature request issue, leading to the prefix “feature/”:

Create branch dialog in Stash when coming from the JIRA development panel.

This feature greatly facilitates the adoption of a naming schema for branches of the same type. Another feature where the branching model is used is Stash’s ability to automatically merge changes to newer release branches. This feature reduces the need for manual maintenance of branches by letting Stash do the hard work of merging. Let’s say you have fixed an issue in release 1.4.0 of your software — then you probably also want to have that fix be applied in release 1.4.1, 1.4.2, etc. Stash is able to do this based on the branching model and the semantic versioning of your branch names.

How to manage settings centrally

Organizations and teams typically have settings which should be common to all repositories of a Stash project. An example would be that a team wants to prevent force pushes to a Git repository, hence it enables the Stash hook for it. Other examples are the repository permissions or the rules for when a pull request is allowed to be merged.

As a Stash project administrator, you have to configure all these common settings for every new repository again and also have to keep them in sync. Because this is very hard to achieve without automation, various JIRA issues for Stash have already been raised which request centrally managed repository settings and repository templates: STASH-3597 (Default Stash hook configurations), STASH-4323 (repository templates), STASH-3787 (ability to set default repository settings) and STASH-3614 (support creating a project from a predefined “blueprint”).

These JIRA issues can be summarized into the user stories to allow creating repositories from templates (or blueprints) and the ability to periodically reset the settings of repositories to the one of a template. The first requirement goes beyond repository settings and wants to allow predefined content and branches for newly created repositories. As a Stash project administrator, we probably always want to have certain branches predefined for repositories using the same branching model (e.g., develop and master for Gitflow). In terms of content, we probably always want a README.md and a LICENSE file in our repositories. And maybe we also need the same .gitattributes file in every new repository to deal with line endings.

Centrally managing common settings of Stash repositories is currently not easy to achieve. Although certain settings can be set through Stash’s REST interface (e.g., hook settings) and set by a periodic run of a cronjob, others can only be set internally in Stash itself. And because we don’t want that every company has to start from scratch and implement their own cronjob based solution, we at Mibex Software have released a new add-on called Repository Templates for Bitbucket Server.

This add-on allows a Stash administrator to configure a repository as a template to its liking (set common repository settings, commit default files and branches, etc.). Then, for new repositories either the administrator or the user can define from which template a new repository should be created from. The add-on then copies all of the templates settings and content over to the newly created repository:

Create repository dialog where it is possible to choose a template repository.

You can also configure the add-on to periodically reset settings of associated repositories to the ones of a template. With this feature enabled, you can manage settings centrally and can ensure that your repositories are always correctly configured — so there is no need anymore to configure certain settings all over again:

Repository template settings page.

We hope that this add-on helps organizations to enforce common settings and quality requirements, to help developers setting up new repositories and to reduce administration efforts in general. If you have a setting that is not covered yet by the add-on or if you want other work being done while a new repository is set up, just comment below. Any feedback would be much appreciated.