This page explains the storage format of Gerrit’s project configuration and access control models.
The web UI access control panel is a front end for human-readable
configuration files under the refs/meta/config
namespace in the
affected project. Direct manipulation of these files is mainly
relevant in an automation scenario of the access controls.
The refs/meta/config
namespace
The namespace contains three different files that play different
roles in the permission model. With read permission to that reference,
it is possible to fetch the refs/meta/config
reference to a local
repository. A nice side effect is that you can also upload changes
to project permissions and review them just like with regular code
changes. The preview changes option is also provided on the UI. Please note
that you will have to configure push rights for the refs/meta/config
name
space if you’d like to use the possibility to automate permission updates.
The file project.config
The project.config
file contains the link between groups and their
permitted actions on reference patterns in this project and any projects
that inherit its permissions.
The format in this file corresponds to the Git config file format, so
if you want to automate your permissions it is a good idea to use the
git config
command when writing to the file. This way you know you
don’t accidentally break the format of the file.
Here follows a git config
command example:
$ git config -f project.config project.description "Rights inherited by all other projects"
Below you will find an example of the project.config
file format:
[project] description = Rights inherited by all other projects [access "refs/*"] read = group Administrators [capability] administrateServer = group Administrators [receive] requireContributorAgreement = false
As you can see, there are several sections.
The project
section appears once per project.
The access
section appears once per reference pattern,
such as refs/*
or refs/heads/*
. Only one access section per pattern is
allowed. You will find examples of keys and values in each category section
below.
The receive
section appears once per project.
The submit
section appears once per project.
The capability
section only appears once, and only
in the All-Projects
repository. It controls core features that are configured
on a global level. You can find examples of these
below.
Project section
The project section includes configuration of project settings.
These are the keys:
-
Description
Receive section
The receive section includes configuration of project-specific receive settings:
- receive.requireContributorAgreement
-
Controls whether or not a user must complete a contributor agreement before they can upload changes. Default is
INHERIT
. IfAll-Project
enables this option then the dependent project must set it to false if users are not required to sign a contributor agreement prior to submitting changes for that specific project. To use that feature the global option ingerrit.config
must be enabled: auth.contributorAgreements. - receive.requireSignedOffBy
-
Sign-off can be a requirement for some projects (for example Linux kernel uses it). Sign-off is a line at the end of the commit message which certifies who is the author of the commit. Its main purpose is to improve tracking of who did what, especially with patches. Default is
INHERIT
, which means that this property is inherited from the parent project. - receive.requireChangeId
-
Controls whether or not the Change-Id must be included in the commit message in the last paragraph. Default is
INHERIT
, which means that this property is inherited from the parent project. - receive.maxObjectSizeLimit
-
Maximum allowed Git object size that receive-pack will accept. If an object is larger than the given size the pack-parsing will abort and the push operation will fail. If set to zero then there is no limit.
Project owners can use this setting to prevent developers from pushing objects which are too large to Gerrit. This setting can also be set it
gerrit.config
globally receive.maxObjectSizeLimit.The project specific setting in
project.config
is only honored when it further reduces the global limit.Default is zero.
Common unit suffixes of k, m, or g are supported.
Submit section
The submit section includes configuration of project-specific submit settings:
-
mergeContent: Defines whether to automatically merge changes. Valid values are true, false, or INHERIT. Default is INHERIT.
-
action: defines the submit type. Valid values are fast forward only, merge if necessary, rebase if necessary, merge always and cherry pick. The default is merge if necessary.
Merge strategy
Access section
Each access
section includes a reference and access rights connected
to groups. Each group listed must exist in the groups
file.
Please refer to the Access Categories documentation for a full list of available access rights.
Capability section
The capability
section only appears once, and only in the All-Projects
repository. It controls Gerrit administration capabilities that are configured
on a global level.
Please refer to the Global Capabilities documentation for a full list of available capabilities.
The file groups
Each group in this list is linked with its UUID so that renaming of
groups is possible without having to rewrite every groups
file
in every repository where it’s used.
This is what the default groups file for All-Projects.git
looks like:
# UUID Group Name # 3d6da7dc4e99e6f6e5b5196e21b6f504fc530bba Administrators global:Anonymous-Users Anonymous Users global:Project-Owners Project Owners global:Registered-Users Registered Users
This file can’t be written to by the git config
command.
In order to reference a group in project.config
, it must be listed in
the groups
file. When editing permissions through the web UI this
file is maintained automatically, but when pushing updates to
refs/meta/config
this must be dealt with by hand. Gerrit will refuse
project.config
files that refer to groups not listed in groups
.
The UUID of a group can be found on the General tab of the group’s page
in the web UI or via the -v
option to
the ls-groups
SSH command.
The file rules.pl
The rules.pl
files allows you to replace or amend the default Prolog
rules that control e.g. what conditions need to be fulfilled for a
change to be submittable. This file content should be
interpretable by the Prolog Cafe interpreter.
You can read more about the rules.pl
file and the prolog rules on
the Prolog cookbook page.
Part of Gerrit Code Review