blob: 295f08db04dc6d91e3c110a3331ef30edbadf050 [file] [view]
---
title: " Gerrit Code Review - Project Configuration File Format"
sidebar: gerritdoc_sidebar
permalink: config-project-config.html
---
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.
## Property inheritance
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.
## 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
[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](#project-section) appears once per project.
The [`access` section](#access-section) appears once per reference
pattern, such as `+refs/*+` or `+refs/heads/*+`. Only one access section
per pattern is allowed.
The [`receive` section](#receive-section) appears once per project.
The [`submit` section](#submit-section) appears once per project.
The [`capability`](#capability-section) section only appears once, and
only in the `All-Projects` repository. It controls core features that
are configured on a global level.
The [`label`](#label-section) 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](config-gerrit.html#commentlink) which is used to define
global comment links.
### 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`. 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](config-gerrit.html#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](config-gerrit.html#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](config-gerrit.html#receive.enableSignedPush) 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](config-gerrit.html#receive.enableSignedPush) 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.
### Change section
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](rest-api-changes.html#change-input) is set to `false`
explicitly when calling the
[CreateChange](rest-api-changes.html#create-change) REST API or the
`remove-private` [PushOption](user-upload.html#private) is used
during the Git push.
Default is `INHERIT`, which means that this property is inherited
from the parent project.
### 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](project-configuration.html#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
### Access section
Each `access` section includes a reference and access rights connected
to groups. Each group listed must exist in the [`groups`
file](#file-groups).
Please refer to the [Access
Categories](access-control.html#access_categories) documentation for a
full list of available access rights.
### MIME Types section
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
### 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](access-control.html#global_capabilities) documentation for
a full list of available capabilities.
### Label section
Please refer to [Custom Labels](config-labels.html#label_custom)
documentation.
### branchOrder section
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.
- branchOrder.branch
A branch name, typically multiple values will be defined. The order
of branch names in this section defines the branch order. The
topmost is considered to be the least stable branch (typically the
master branch) and the last one the most stable (typically the last
maintained release branch).
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.
### reviewer section
Defines config options to adjust a project’s reviewer workflow such as
enabling reviewers and CCs by email.
- reviewer.enableByEmail
A boolean indicating if reviewers and CCs that do not currently have
a Gerrit account can be added to a change by providing their email
address.
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`.
## 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: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](cmd-ls-groups.html).
## 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](prolog-cookbook.html).
## GERRIT
Part of [Gerrit Code Review](index.html)
## SEARCHBOX