Documentation/config-project-config.txt

= Gerrit Code Review - Project Configuration File Format

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.


[[file-project_config]]
== 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 link:#project-section[+project+ section] appears once per project.

The link:#access-section[+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
<<access_category,below>>.

The link:#receive-section[+receive+ section] appears once per project.

The link:#submit-section[+submit+ section] appears once per project.

The link:#capability-section[+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
<<capability_category,below>>.

The link:#label-section[+label+] section can appear multiple times. You can
also redefine the text and behavior of the built in label types `Code-Review`
and `Verified`.

[[project-section]]
=== Project section

The project section includes configuration of project settings.

These are the keys:

- Description


[[receive-section]]
=== Receive section

The receive section includes configuration of project-specific
receive settings:

[[receive.requireContributorAgreement]]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:
link:config-gerrit.html#auth.contributorAgreements[auth.contributorAgreements].

[[receive.requireSignedOffBy]]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]]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]]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 link:config-gerrit.html#receive.maxObjectSizeLimit[
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]]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]]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 link:config-gerrit.html#receive.enableSignedPush[global
configuration] for details.
+
Default is `INHERIT`, which means that this property is inherited from
the parent project.

[[receive.requireSignedPush]]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 link:config-gerrit.html#receive.enableSignedPush[global
configuration] for details.
+
Default is `INHERIT`, which means that this property is inherited from
the parent project.

[[submit-section]]
=== 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 link:project-configuration.html#submit_type[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]]
=== Access section

Each +access+ section includes a reference and access rights connected
to groups.  Each group listed must exist in the link:#file-groups[+groups+ file].

Please refer to the
link:access-control.html#access_categories[Access Categories]
documentation for a full list of available access rights.


[[mimetype-section]]
=== 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]]
=== 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
link:access-control.html#global_capabilities[Global Capabilities]
documentation for a full list of available capabilities.

[[label-section]]
=== Label section

Please refer to link:config-labels.html#label_custom[Custom Labels] documentation.

[[branchOrder-section]]
=== 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]]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.


[[file-groups]]
== 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
link:cmd-ls-groups.html[the +ls-groups+ SSH command].


[[file-rules_pl]]
== 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
link:prolog-cookbook.html[the Prolog cookbook page].

GERRIT
------
Part of link:index.html[Gerrit Code Review]

SEARCHBOX
---------