(TL;DR) Gerrit Code Review offers extensive configuration options that allow organizations to finely control access rights while ensuring auditability through versioned changes in Git. It supports hierarchical project inheritance, enabling structured, scalable permission management. This allows companies to define base rules centrally, which child projects can inherit and customize.

Its key features include granular Access Control Lists (ACLs), where permissions can be set at various levels, even down to individual refs (branches). Submit Requirements provide highly customizable rules for determining whether a change is mergeable, while ref-specific permissions allow precise access policies for different branches. Auditability is a significant advantage, as all permission changes are tracked as Git commits, making compliance easy in regulated environments.

Gerrit’s flexibility makes it a top choice for enterprises in security-sensitive and highly regulated industries.

---

One thing you notice immediately when you start working with/managing Gerrit is the incredible amount of configuration options that allow you to really tailor the installation to your needs.

This theme pervades all of Gerrit, and the Access Control List (ACL) setup is no exception. Gerrit allows organizations to be extremely fine-grained when granting users access to the code base.

Not only you have an unparalleled level of control over your access rights set-up, but it is also as auditable as it gets, as each and every change done to the system is automatically versioned via Git .

This is one of the major reasons why big organizations, or organizations in highly regulated fields, find so much success with Gerrit, other tools simply don’t provide the flexibility and auditability that Gerrit does.

In a world that is becoming increasingly regulated, it is essential to easily comply with auditors’ requirements, and no tool does this quite as well as Gerrit.

So, what’s the fuss all about?

Well, let’s go in order. Firstly, you should know that Gerrit allows you to have a hierarchy of projects. By default, when you create a new setup, there will always be two projects: All-Users and All-Projects. To briefly sum up the former, it will contain all the information related to the users of the system. Each new user creation or modification will be tracked in this Git repository, making it extremely auditable.

However, it’s All-Projectswhere all the fun happens. You can look at All-Projects as the father of all other repositories you’ll create, as, by default, all new repositories inherit their access rights from this one.

ACL Project Inheritance

Yes, you read that right, access rights can be inherited across repositories. This is extremely powerful as it allows you to have “hollow” projects that are nothing more than organizational templates for security or compliance structures that then each project can extend.

For example, say that your organization is split in two, loosly coupled, main divisions. They might want to share very basic rules, i.e. all changes need to be tested before merging, but other than that, they are very much independent and have separate audit requirements or security concerns.

With Gerrit, they can define the basic rules in All-Projects and then have “hollow” child projects that inherit these rules and further customize them.

For example, let’s create two repositories, one per area of the company, they’ll be called SuperSecretProjects and PublicProjects. These projects might never have any code committed to them; they are “just” a shell for different ACLs to reflect how that part of the company works. Each new project can then inherit from them and will have the correct access rights setup without the need to do anything else.

Long gone are the days of one of your teams getting the set-up wrong and wreaking havoc further down the line or auditors having to bother teams individually to get access to their set-up. This can all be managed centrally, while still allowing teams to do the customizations they require.

But how fine-grained are we talking?

Well, let’s examine how to configure new ACLs and the options you have.

This is what a classic Gerrit project access page looks like. You can see that this project, as every project by default, inherits its rights from All-Projects. However, you can then extend its permissions as required. In this case, we’re specifying that Java Developer and Bazel Expertcan express deep dislike towards a change (-2) or a moderate approval (+1) by providing a vote on the Code-Review label, however only the principal engineer will be able to vote with the full range of votes applicable for this label.

Further more, we restrict read access to super-secret-branch to just the principal engineer. This essentially restricts who can view this secret branch, to the point that if any other user will try to git clone this repository, it will not clone this branch(or branches related to this name space). This is an incredibly powerful feature that, as far as I know, is unique to Gerrit.

You’ll notice that I’m keeping a very generic language, others might refer to being able to vote with Code-Review +2 on a change as “being able to approve it”, however, this is not strictly true, it all depends on how we define the submittability(aka whether a change is mergeable or not) of the change for the project in question. To explain this further, I’ll need to take you on a small detour.

Submit Requirements

You’ve guessed it, even the definition of what makes a change good enough to be submitted is extremely configurable thanks to a concept called Submit Requirements. These can be defined in All-Projects or at lower levels in your project hierarchy if you wish to do so. Interestingly, you can also specify which submit requirements can can be altered by each team and which ones need to be enforced company wide.

Submit requirements are a way of decoupling the defintion of submittability of a change from the labels that users can vote on. Labels alone have a purely informational role, but couple them with submit requirements and you get an extremely flexible framework customizable to any requirement.

These Submit Requirements are defined in project.config and read something like so:

[submit-requirement "Code-Review-Required"]
  description = At least one maximum vote for label 'Code-Review' is required
  applicableIf = -branch:refs/meta/config
  submittableIf = label:Code-Review=MAX,user=non_uploader AND -label:Code-Review=MIN
  overridableIf = uploader:MyTrustedUser
  canOverrideInChildProjects = true

This is quite intuitive language, but let’s briefly go over it:

Looking at the submittableIf part of the definition, we can see how this will ensure that changes will only become submittable only if there is at least one vote for the label Code-Review with the highest scored configured for that label that doesn’t come from the user that uploaded the change initially. There should also be no vote with the minimum value by anyone.

However, this requirement can be overriden if, for example, I have a specific user, like an AIBot or a Ci/Cd system, that I’m happy to always trust.

Finally, if there are specific branches that I’d like to exclude, I can do that too by setting the applicableIf clause.

This is just an example. The real strength here is that in either of the applicableIf, submittableIf , and overridableIf clauses, you can use any of the expression operators available for searching changes and more.

Overrall, an incredibly powerful tool if you ask me.

But enough of this now, what about specifying different permission, like push/pull or deletion of branches?

Ref specific permissions

Everything we do in Gerrit applies to a ref namespace.

If you don’t know what a ref is you can think of it somewhat like a branch. Branches, strictly speaking, are refs that are under the namespace refs/heads , so, for example, what you refer too as master really is stored in refs/heads/master .

Hopefully, this helps you understand the image above. When we refer to Reference: refs/* , we’re telling Gerrit to apply the following permission to every ref in the repository.

Let that sink in, Gerrit allows you specify different permissions for each ref in your repository.

Say for example that you want to provide developers with their own sandbox branch where they can go off and test whatever they want. You could provide everyone the create permission in the refs/sandbox namespace and off you go! You could then change your submit requirements so that they aren’t applicable if the target branch starts with refs/sandbox, effectively providing each developer with their own environment to test anything they want.

But what permissions can I set on these refs?

That’s a great question. Really there’s very little limit to the workflows you can achieve with Gerrit. For instance, you can add whatever labels you want, and configure whatever values with whatever description you want.

For instance, say we want to add a Verified label, we’d edit the necessary project.config like so:

[label "Verified"]
 function = NoBlock
 defaultValue = 0
 value = -1 Fails
 value = 0 No score
 value = +1 Verified
 copyCondition = changekind:NO_CHANGE OR changekind:NO_CODE_CHANGE

You can then grant users, or groups, specific permissions on specific branches, like below, where I’m allowing the Administrators group to vote with either -1 and +1 on all refs/heads branched.

Effectively giving you all the flexibility you could possibly want.

Gerrit, out of the box, allows you to assign permissions like

• Delete changes
• Push (force or not)
• Submit
• And many, many more…

You can find a complete list [here](https://gerrit-review.googlesource.com/Documentation/access-control.html)

But what about auditability?

That’s the most beautiful part of it all: Gerrit is not only extremely flexible, any changes you make to its permission model are “just” code changes, which can be reviewed like any other change and are even versioned like any other code change in a Git repository.
If we scroll to the top of the access page, we see the History: browse link

This will bring you to your default code browser where you can see the git log of the All-Projects repo

We can see how the configuration of a new label and providing users with the capability to use it have been recorded with 2 separate commits. Each one of these commits would have been reviewed prior to being merged, that too with configurable ACLs. Which also means that the diff can be easily inspected to easily understand what each changed entailed.

This is unlike any tool I know of and it’s incredibily useful when it comes to analysing what the state of the permissions was when a change was merged if investigating it months if not years after the fact and ensuring that all requirements at the time where met.

To recap

Gerrit gives you best-in-class auditability and workflow customization capabilities that provide unparalleled power to fine-tune approval workflows to your company’s needs.

The hierarchical inheritance model is a game-changer when it comes to enabling teams to move quickly while still ensuring all crucial business rules are always enforced.

It’s these capabilities that make Gerrit the ideal choice for enterprises in highly regulated industries, where security, governance and scalability are crucial for success.

---

Daniele Sassoli
GerritForge Inc. – Engineering Manager
Gerrit Code Review Community Manager
Gerrit Code Review Contributor