Subversion Path-Based Permissions in CollabNet TeamForge

August 24, 2009 CollabNet VersionOne

CollabNet TeamForge (CTF) 5.2 has been out for a while now but I thought I would help introduce the most significant feature added as a result of its release: Subversion path-based permissions.  Prior
to CTF 5.2, when you wanted to manage access control for your Subversion repositories, you were able to provide only “blanket level”
permissioning.  This means that you either had no access, read access
or read/write access and that access applied for the whole repository.
There was no way to open up or lock down subsets of the repository
tree.  For many, this was fine but often resulted in some process of
maintaining multiple repositories to suit their needs.  The problem was
even bigger for those that came from other solutions where they were use to full control.

Well, with the release of CTF 5.2, you now have the ability
to use path-based permissions to take full control of the repository
access for your project’s repositories.  Once you create a Subversion repository, path-based permissions are available just like the rest of the CTF tools.  For those of you that do not want or need path-based permissions, CTF still works with blanket-level access.

(Note: The purpose of
this article is not to teach you how to create a CTF integration,
project or repository and assumes that you’ve got a Subversion
repository already created and ready to work with.)

As with previous releases of CTF, to start we need to get to the project Permissions by performing the following steps:

  1. Click the “Project Admin” tab
  2. Click the “Permissions” menu item to the left

Now we can create a new role or modify an existing role so that we
can create some new path-based permissions for our repository.  To
provide a full example, we’ll create a few roles:

  • Developer: Has complete access to the repository except the /tags directory where he can only read.
  • Manager: Has complete access to the repository
  • Contractor: Has no access anywhere except /trunk/contractor and /branches/b1/contractor

(As with any CTF role, you can add individual users or you can create groups of users and then add those groups to the role.)  To get started, let’s click the “Create” button on the Permissions page.  Fill out the form with the following values:

  • Role Name: Developer
  • Description: This role is for developers.

Once you’ve done this, click the “Create” button once more.  At this point, the role is created but it has no real permissions set.  Since we’re here for path-based permissions, click the “Source Code” menu item to the left.  This is where the magic happens for path-based permissions.  To set/manipulate path-based permissions, look down in the “Permissions for Specific Repositories” section of this page to see a list of repositories.  (Only Subversion repositories have the ability to have path-based permissions set for them.)  To get started, click the “Path-based Permissions” radio button and you should see that a sub-form is displayed.  This is where you will add these path-based permissions.

Let’s go ahead and setup the Developer role.  To do this, follow these steps:

  1. Change the default permission for the “/” path to be “View and Commit” by selecting the “View and Commit” radio button
  2. Click the “Add” button
  3. In the newly displayed text box, type in “/tags”
  4. Beside the “/tags” row, select the “View” radio button.
  5. Click the “Save” button

At this point, we have fulfilled the requirements for the Developer role.  Based on our permissions model, any user with the Developer role will have full read/write access to the repository except for the “/tags” directory and everything below it, where the user will have read access only.  Below is a screenshot of what you might expect to see:

Now that we know how to create a role in CTF and modify its “Source Code” permissions to use path-based permissions for Subversion, let’s quickly go through configuring the other two roles, starting with the Manager role.

To configure the “Source Code” permissions for the Manager role, follow these steps:

  1. Create the role using the same steps above (The “Role Name” should be “Manager” and the description should be “This role is for managers.”)
  2. Get to the “Source Code” permissions for this role using the same steps above
  3. Enable path-based permissions using the same steps above
  4. Click the “View and Commit” radio button for the default repository path
  5. Click “Save”

As with the Developer role, here is an example screenshot:

The last role we have to configure is the Contractor role.  To configure it, follow these steps:

  1. Create the role using the same steps above (The “Role Name” should
    be “Contractor” and the description should be “This role is for contractors.”)
  2. Get to the “Source Code” permissions for this role using the same steps above
  3. Enable path-based permissions using the same steps above (Since we’ll not be giving access to any parts of the repository by default, we will not be updating the default path permissions.)
  4. Click the “Add” button
  5. In the newly displayed text box, type “/branches/b1/contractor”
  6. Beside the “/branches/b1/contractor” row, click the “View and Commit” radio button
  7. Click the “Add” button
  8. In the newly displayed text box, type “/trunk/contractor”
  9. Beside the “/trunk/contractor” row, click the “View and Commit” radio button
  10. Click the “Save” button

Here is an example of the configuration:

At this point you have all of your roles created and you could start adding project members with their respective roles, which is outside the scope of this article.  One more thing before we move on is to explain how these permissions are used to give you access.

When it comes to generating the internal “model” of what you have access to, CTF plays by the same rules as Subversion’s authorization model.  The idea here is that you can give/restrict access at any path and the permission for that path applies for said path and all paths below that path.  Sounds simple enough.  Now…to “override” a higher-level permission, all you have to do is create a path-based permission for the path you want to enable/restrict access for.  You saw an example of this in the Contractor role.  While we initially said that the Contractor role would have no access at “/”, we then enabled access at “/branches/b1/contractor” and “/trunk/contractor” by creating a more specific rule and that rule applies at that path and everything below that path unless overridden by a lower-level rule.  So to summarize: Permissions for a path are inherited from their parent unless you create a new path-based permission for the path in question overriding its parent’s permission.

So what else is there to learn about path-based permissions in CTF?  Well, you should know the CTF tools that path-based permissions are enforced on.  Sure Subversion access is a given but here is the full list of CTF tooling that path-based permissions impact the access of:

  • Subversion access
  • Source code browsing (This includes the enablement/display of the “Source Code” toolbar button, the listing of the repositories when the “Source Code” button is clicked and the actual content rendered when you click a repository and start browsing its content.)
  • Commit viewer (Much like the source code browsing, when you view commit objects in the Commit Viewer, the content rendered depends on your access permissions.)
  • Repository monitoring

Well, that pretty much sums up path-based permissions in CTF.  As you can tell by the information above, path-based permissions are a very simple yet very powerful way to restrict access to your source code and the CTF tooling related to source code.  If you have any question about path-based permissions or anything in CollabNet TeamForge, please visit our community site for mailing lists, forums, articles and help documentation.

Previous Article
How complex is "complex"?
How complex is "complex"?

Commenting on the differences between the business models of Red Hat and Acquia, Matt Asay really nails a p...

Next Article
Adopting Agile… the Video Podcast
Adopting Agile… the Video Podcast

A month or so ago I put together a video podcast for VersionOne on adopting agile in the enterprise. Given ...