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.
refs/meta/config
namespaceThe 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.
If a property is set to INHERIT, then the value from the parent project is used. If the property is not set in any parent project, the default value is FALSE.
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 [access "refs/heads/*"] label-Your-Label-Here = -1..+1 group Administrators [capability] administrateServer = group Administrators [receive] requireContributorAgreement = false [label "Your-Label-Here"] function = MaxWithBlock value = -1 Your -1 Description value = 0 Your No score Description value = +1 Your +1 Description
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.
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.
The label
section can appear multiple times. You can also redefine the text and behavior of the built in label types Code-Review
and Verified
.
Optionally a commentlink
section can be added to define project-specific comment links. The commentlink
section has the same format as the commentlink
section in gerrit.config which is used to define global comment links.
The project section includes configuration of project settings.
These are the keys:
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
. If All-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 in gerrit.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.
receive.checkReceivedObjects
Controls whether or not the JGit functionality for checking received objects is enabled.
By default Gerrit checks the validity of git objects. Setting this variable to false should not be used unless a project with history containing invalid objects needs to be pushed into a Gerrit repository.
This functionality is provided as some other git implementations have allowed bad history to be written into git repositories. If these repositories need pushing up to Gerrit then the JGit checks need to be disabled.
The default value for this is true, false disables the checks.
receive.enableSignedPush
Controls whether server-side signed push validation is enabled on the project. Only has an effect if signed push validation is enabled on the server; see the global configuration for details.
Default is INHERIT
, which means that this property is inherited from the parent project.
receive.requireSignedPush
Controls whether server-side signed push validation is required on the project. Only has an effect if signed push validation is enabled on the server, and link:#receive.enableSignedPush is set on the project. See the global configuration for details.
Default is INHERIT
, which means that this property is inherited from the parent project.
receive.rejectImplicitMerges
Controls whether a check for implicit merges will be performed when changes are pushed for review. An implicit merge is a case where merging an open change would implicitly merge another branch into the target branch. Typically, this happens when a change is done on master and, by mistake, pushed to a stable branch for review. When submitting such change, master would be implicitly merged into stable without anyone noticing that. When this option is set to true Gerrit will reject the push if an implicit merge is detected.
This check is only done for non-merge commits, merge commits are not subject of the implicit merge check.
Default is INHERIT
, which means that this property is inherited from the parent project.
The change section includes configuration for project-specific change settings:
change.privateByDefault
Controls whether all new changes in the project are set as private by default.
Note that a new change will be public if the is_private
field in ChangeInput is set to false
explicitly when calling the CreateChange REST API or the remove-private
PushOption is used during the Git push.
Default is INHERIT
, which means that this property is inherited from the parent project.
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.
matchAuthorToCommitterDate: Defines whether to the author date will be changed to match the submitter date upon submit, so that git log shows when the change was submitted instead of when the author last committed. Valid values are true, false, or INHERIT. The default is INHERIT. This option only takes effect in submit strategies which already modify the commit, i.e. Cherry Pick, Rebase Always, and (perhaps) Rebase If Necessary.
Merge strategy
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.
The mimetype
section may be configured to force the web code reviewer to return certain MIME types by file path. MIME types may be used to activate syntax highlighting.
[mimetype "text/x-c"] path = *.pkt [mimetype "text/x-java"] path = api/current.txt
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.
Please refer to Custom Labels documentation.
Defines a branch ordering which is used for backporting of changes. Backporting will be offered for a change (in the Gerrit UI) for all more stable branches where the change can merge cleanly.
Example:
[branchOrder] branch = master branch = stable-2.9 branch = stable-2.8 branch = stable-2.7
The branchOrder
section is inheritable. This is useful when multiple or all projects follow the same branch rules. A branchOrder
section in a child project completely overrides any branchOrder
section from a parent i.e. there is no merging of branchOrder
sections. A present but empty branchOrder
section removes all inherited branch order.
Branches not listed in this section will not be included in the mergeability check. If the branchOrder
section is not defined then the mergeability of a change into other branches will not be done.
Defines config options to adjust a project’s reviewer workflow such as enabling reviewers and CCs by email.
This setting only takes affect for changes that are readable by anonymous users.
Default is INHERIT
, which means that this property is inherited from the parent project. If the property is not set in any parent project, the default value is FALSE
.
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:Change-Owner Change Owner 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.
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