New Branch and Merge Permissions

In a previous blog post about the new First Class Branches that we have added in TFS 2010, I mentioned the addition of two new permissions related to branching and merging.  In this post, I want to go into a bit more detail about these permissions, explaining what each enables, the motivation for adding each permission, and how users upgrading from TFS 2008 are impacted.

Manage Branch

The first of these new permissions is the Manage Branch permission.  Users that have this permission set to Allow for a given path can do the following:

  • Convert folders to branches (and branches back to folders)
  • Update metadata for a branch (i.e. owner, description)
  • Create additional child branches from the original branch
  • Change the relationships between branches with merge relationships (i.e. reparenting branches)

One very interesting point about this permission is that it is only relevant for folders that have been converted to Branches – it does not prevent users from branching ordinary folders for which this permission has been denied.

The primary motivation for adding this permission was to enable which users could create new branches.  In many organizations, there is a desire to establish a branching structure, and then have developers work in the branches the team has agreed they need.  Because the permission is path scoped, and branches can still be organized in folders, this still enables teams to group branches such that some branches can be further branched by users but other cannot. 

An example scenario around this permission would be to deny Contributors the ability to Manage Branch under $/TeamProj/Main and $/TeamProj/Releases, but grant the permission under $/TeamProj/FeatureBranches.  That way, users could create sub branches for their feature branches, but couldn’t branch off of release branches or Main.


The Merge permission is the second new permission we have added for version control.  Users that have this permission set to Allow for a given path can do the following:

  • Pend merge operations on branches, folders, and files under the specified path

Note that this Merge permission is only for the target path of a merge operation.  There is no permission to prevent a particular branch or folder from being merged to another path.  Unlike the Manage Branch permission, the Merge permission is not tied to branches – it has the same behavior for folders and branches under a given path.

The motivation for adding the Merge permission was similar to that of the Manage Branch permission.  In some teams, there is a desire to have certain developers handle the task of merging code between branches, while other developers will always work on one branch or another. 

Upgrading from 2008

Adding new permissions to the 2010 release presented the problem of how to assign these permissions on upgrade.  When we added these new permissions, we had one clear goal for the upgrade:

After upgrading, users should be able to continue using all features they had permissions to prior to the upgrade.

Following this guideline, users upgrading to 2010 will be granted the new permissions as follows:

For a given path, users that are granted the Pend Change (aka Edit) permission will be granted both the Manage Branch and Merge permission.  Likewise, users that have been denied the Pend Change permission will be denied the new permissions.

This effectively means that users that were granted Pend Change permission before upgrade would be able to branch and merge, and after upgrade they will still have the permissions to branch and merge. 

It is also important to note that during upgrade, folders with branch relationships to other folders are automatically converted to branches.  Due to an oversight, this created a problem during Beta 2…

Bug in TFS2010 Beta 2 Upgrade

Originally, we had planned to grant the Merge permission to users with the Pend Change permission, and Manage Branch would be granted to users with Admin Project Rights.  The thought here was that converting to branches and creating new branches was targeted more towards project leads than developers, and because the functionality was new, that users branching and merging folders wouldn’t be impacted.

Some time later, we decided we needed to automatically detect and convert folders to branches during the upgrade process.  When we implemented this and performed our upgrade testing, we didn’t realize that after upgrade users without Admin Project Rights couldn’t create new branches. 

The net result here is that for teams that have upgraded from 2008 to Beta 2, only users with Admin Project Rights will be granted the Manage Branch permission.  We have since fixed this bug so that users upgrading from 2008 to RC or RTM will have the permissions applied as described above.  Note that users upgrading from Beta 2 to RC/RTM will not have their permissions changed (we don’t want to overwrite any customizations that may have been made since upgrading to Beta 2).