In this blog post series we talk about access right mappings between TeamForge and its Gerrit integration. The topics covered by each part are:
- in Part I: What Gitflow is, and how to best use it with TeamForge/Gerrit user defined repository policies.
- in Part II: How to implement your own user-defined repo category with branch based permissions in TeamForge 7.1 and Gerrit 2.6.
- in Part III: Alternative approaches to implement branch based permissions (without user-defined repo categories) and when to use which approach.
Target audience: Project admins, Gerrit administrators using our TeamForge integration.
In the first part of this serie, we have looked into Gitflow’s branching model, configured it in TeamForge via a user-defined repo category called gitflow and verified that it actually works as expected.
In the second part, we have created the gitflow repo category by modifying the mappings file – TeamForgeMappings.xml on the server. So, far so good – this method is recommended, as it allows you to define the new category once and forever. The newly created category can be used across all your Git repositories. However, it does have one drawback: it requires access to the server filesystem to modify the mappings file and restart Gerrit. What if you don’t have such an access? In this case there is no way to add your newly created repo category. That’s true, but… do not panic! Fortunately there are two other options to set up the same access rights:
- Turn off the TeamForge auto-pilot by using our Custom category and by configuring access rights in Gerrit’s UI
- Use an already existing repo category as starting point and modify it so that it fits the required setup
Let’s have a look at both approaches.
The first one has already been described in my blog post about Managing Git branch level permissions with TeamForge and Gerrit but, as we have a new version of Gerrit and a new version of TeamForge, we will look at it again.
So how to implement gitflow model using custom repo category?
It is quite straightforward.
Implementing gitflow with
First we have to go to TeamForge and create a new repository with custom category:
We don’t need to put
[RepoCategory:custom] entry into the description anymore. Instead we choose Custom from
Repository Category options. After the repository gets created we go to the Gerrit project corresponding to this repository (It will be custom_repo project) and click on
Access (to get to the access rights) and then click on
You have probably noticed that this page in our current version of Gerrit is quite different from what it was in version 2.1. Nevertheless, this is the place where you are supposed to add all the necessary rights for the gitflow model.
Now we are ready to start adding the access rights needed by gitflow. But wait – there is one hint: we won’t start from the Custom category, as this one is almost empty initially and adding all the rights would mean a lot of manual work to perform. Life is too short for that so we will use the fact that in the Custom category all rights added on Gerrit side are preserved. That means that if we switch the repo category to any other category (like Default) and then back to Custom we will get all the rights defined in Default category available in Custom.
Let’s do that: We go to
Edit Repository screen in TeamForge, switch the Repository Category to Default and click
Save. Then we go to edit repository again and select Custom Repo Category this time and click
Save again. After going back to our Access page on Gerrit you will see all the default rights, and that’s despite the fact that our repo category is Custom. So, instead of adding everything from scratch, we will actually modify the Default category to fit the gitflow.
Let’s start with
Reference: refs/*. After editing it should look like this:
that means that we have to perform the following steps:
- Remove Developer and Release Manager group from
- Add Developer to
Forge Author Identity.
- Remove Release Manager from
Forge Committer Identity.
- Remove Developer and Release Manager from
- Remove all entries for
- Add Developer and Release Manager to
Push Merge Commit.
After those modifications we are done with
Reference: refs/* section.
In a similar way we have to modify References
refs/tags/*. Here how it should look like just before hitting the
And after saving:
At this point the remaining part is about adding the missing references for gitflow related branches:
release/*. Here it goes:
And the last thing to do is to allow Release Manager to force push directly to
As you can see, it is not the easiest approach to configure gitflow. But, thanks to our category switching trick we were able to perform all the changes in reasonable time. Remember that if you have another repository in gerrit you will have to repeat the work again (unless you play with Project inheritance which will let you do your changes in the parent project and inherit from it).
Now we can look at the second approach.
Implementing gitflow using internal Gerrit groups.
I have to admit that this approach does not allow to implement the gitflow model completely. But, I’ve included it as I feel that our journey through controlling Gerrit access rights from TeamForge wouldn’t be complete without describing this possibility. Plus, this approach is really useful in some cases.
So, what it is about? It is about creating an internal group in Gerrit and adding the TeamForge user groups in
Included Groups of this group.
Why would you need it?
Well, in all pre-defined categories other than Custom if one modify rights on Gerrit side those modification will be lost upon the sync between TeamForge and Gerrit. That’s why we had to use Custom repo category in the previous example. What if we wanted to use Default repo category instead? That’s where internal Gerrit groups come into play.
So let’s start with a repo with Default category, as we aready known that this category is the most similar to the gitflow one. We will configure references
refs/* for the Developer. Note that we cannot modify access rights for
TF: demo: Developer group anymore, because those modification will be wiped out during sync process (as we are using the Default category). What we do instead is to create internal Gerrit group called
gitflow developer which includes
TF: demo: Developer group. As the newly created group is internal the synchronization with TeamForge will not affect it. Here’s how to proceed.
First let’s go to
Gerrit -> People -> Create New Group and create a new
gitflow developer group:
As you see on the screenshot above we can add
TF: demo: Developer to included groups of
gitflow developer group. Of course, to implement gitflow model we would also need to create
gitflow release manager and
gitflow observer roles, each of which will include corresponding TeamForge group in included groups. I’m not going to go through that at the moment but you’ve got the idea.
Now, let’s have a look at Developer rights for references
refs/* in Default category. We know from the previous example (with custom category) that for Developer we will have to:
- Add Developer to
Forge Author Identityand
Push Merge Commit.
- Remove Developer from
Push Merge Commit.
Adding rights is simple – we just go to the project access rights page and add the rights there.
But what about removing permissions? Unfortunately, there is not much we can do. Well, we could try to use the
BLOCK access rule, but we don’t want that as this would have blocked everything below
refs/heads/* including our
feature branches, with no possibility to overcome it. The
Exclusive Flag is also not up to this task because there is no good way of applying it on
refs/heads/*. So the only option we have is to leave
refs/heads/* unchanged and restrict the access to remaining branches. That is we will modify access rights for
Let’s have a look at
refs/heads/hotfix/* as an example, as other branches will be configured in a similar way:
Two things to notice:
- We use our newly created internal user groups instead of TeamForge groups to make sure the rights won’t get wiped out by TeamForge.
- we use
Exclusive flagwhich basically prevents the access from people that do have access to
ref/heads/*but don’t belong to developers nor release managers.
As you can see, this approach is far from optimal. One can add some rights but usually it is not possible to restrict them. Actually, I would recommend this approach only, if the existing repo category is almost there and some small modifications to gerrit access rights are required. Please also note that starting from Gerrit 2.7, you will need a special capability
Create Group to create a new internal Gerrit group.
And… that’s all folks. 🙂 Congratulations, you have just finished the third (and last) part of my blog – alternative approaches to implement branch based permissions. After reading all three parts you should have a quite comprehensive knowledge about setting up Gerrit access rights and controlling them from TeamForge. What is your experience? Do you agree with my suggestions? Do you have other ideas? Which approach would you use and when? Please share your thoughts so others can benefit from it.