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.


[[refs-meta-config]]
== 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.

[[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.

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.

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`.

Optionally a +commentlink+ section can be added to define project-specific
comment links. The +commentlink+ section has the same format as the
link:config-gerrit.html#commentlink[+commentlink+ section in gerrit.config]
which is used to define global comment links.

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

The project section includes configuration of project settings.

These are the keys:

[[description]]description::
+
A description for the project.

[[state]]state::
+
This setting defines the state of the project. A project can have the
following states:

- `Active`:
+
The project is active and users can see and modify the project according
to their access rights on the project.

- `Read Only`:
+
The project is read only and all modifying operations on it are
disabled. E.g. this means that pushing to this project fails for all
users even if they have push permissions assigned on it.
+
Setting a project to this state is an easy way to temporary close a
project, as you can keep all write access rights in place and they will
become active again as soon as the project state is set back to
`Active`.
+
This state also makes sense if a project was moved to another location.
In this case all new development should happen in the new project and
you want to prevent that somebody accidentally works on the old
project, while keeping the old project around for old references.

- `Hidden`:
+
The project is hidden and only visible to project owners. Other users
are not able to see the project even if they have read permissions
granted on the project.


[[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-Projects` 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::
+
The `Require Change-Id in commit message` option defines whether a
link:user-changeid.html[Change-Id] in the commit message is required
for pushing a commit for review. If this option is set, trying to push
a commit for review that doesn't contain a Change-Id in the commit
message fails with link:error-missing-changeid.html[missing Change-Id
in commit message footer].
+
It is recommended to set this option and use a
link:user-changeid.html#create[commit-msg hook] (or other client side
tooling like EGit) to automatically generate Change-Id's for new
commits. This way the Change-Id is automatically in place when changes
are reworked or rebased and uploading new patch sets gets easy.
+
If this option is not set, commits can be uploaded without a Change-Id,
but then users have to remember to copy the assigned Change-Id from the
change screen and insert it manually into the commit message when they
want to upload a second patch set.
+
Default is `INHERIT`, which means that this property is inherited from
the parent project. The global default for new hosts is `true`
+
This option is deprecated and future releases will behave as if this
is always `true`.

[[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 in
`gerrit.config` globally (link:config-gerrit.html#receive.maxObjectSizeLimit[
receive.maxObjectSizeLimit]).
+
The project specific setting in `project.config` may not set a value higher
than the global limit (if configured). In other words, it is only honored when
it further reduces the global limit.
+
When link:config-gerrit.html#receive.inheritProjectMaxObjectSizeLimit[
`receive.inheritProjectmaxObjectSizeLimit`] is enabled in the global config,
the value is inherited from the parent project. Otherwise, it is not inherited
and must be explicitly set per project.
+
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[`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.

[[receive.rejectImplicitMerges]]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.

[[receive.createNewChangeForAllNotInTarget]]receive.createNewChangeForAllNotInTarget::
+
This option provides a convenience for selecting
link:user-upload.html#base[the merge base] by setting it automatically
to the target branch's tip so you can create new changes for all
commits not in the target branch.
+
This option is disabled if the tip of the push is a merge commit.
+
This option also only works if there are no merge commits in the
commit chain, in such cases it fails warning the user that such
pushes can only be performed by manually specifying
link:user-upload.html#base[bases]
+
This option is useful if you want to push a change to your personal
branch first and for review to another branch for example. Or in cases
where a commit is already merged into a branch and you want to create
a new open change for that commit on another branch.

[[change-section]]
=== Change section

The change section includes configuration for project-specific change settings:

[[change.privateByDefault]]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
link:rest-api-changes.html#change-input[ChangeInput] is set to `false` explicitly
when calling the link:rest-api-changes.html#create-change[CreateChange] REST API
or the `remove-private` link:user-upload.html#private[PushOption] is used during
the Git push.
+
Default is `INHERIT`, which means that this property is inherited from
the parent project.

[[change.workInProgressByDefault]]change.workInProgressByDefault::
+
Controls whether all new changes in the project are set as WIP by default.
+
Note that a new change will be ready if the `workInProgress` field in
link:rest-api-changes.html#change-input[ChangeInput] is set to `false` explicitly
when calling the link:rest-api-changes.html#create-change[CreateChange] REST API
or the `ready` link:user-upload.html#wip[PushOption] is used during
the Git push.
+
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:

[[content_merge]]submit.mergeContent::
+
Defines whether Gerrit will try to
do a content merge when a path conflict occurs. Valid values are
'true', 'false', or 'INHERIT'.  Default is 'INHERIT'. This option can
be modified by any project owner through the project console, `Browse`
> `Repositories` > my/project > `Allow content merges`.

[[submit.action]]submit.action::
+
Defines the submit action aka submit type aka submit strategy that Gerrit
should use to integrate changes into the target branch when they are submitted.
+
In general, submitting a change only merges the change if all its dependencies
are also submitted. The only exception is the `cherry pick` submit action which
ignores dependencies and hence is not recommended to be used (see
link:#cherry_pick[below]).
+
[[submit-type]]
--
The following submit actions are supported:

[[merge_if_necessary]]
* 'merge if necessary':
+
If the change being submitted is a strict superset of the destination branch,
then the branch is fast-forwarded to the change. If not, then a merge commit is
automatically created. This is identical to the classical `git merge` behavior,
 or `git merge --ff`.

[[always_merge]]
[[merge_always]]
* 'merge always':
+
Always produce a merge commit, even if the change is a strict superset of the
destination branch. This is identical to the behavior of `git merge --no-ff`,
and may be useful if the project needs to follow submits with
`git log --first-parent`.

[[rebase_if_necessary]]
* 'rebase if necessary':
+
If the change being submitted is a strict superset of the destination branch,
then the branch is fast-forwarded to the change. If not, then the change is
automatically rebased and then the branch is fast-forwarded to the change.
+
When Gerrit tries to do a merge, by default the merge will only succeed if
there is no path conflict. A path conflict occurs when the same file has also
been changed on the other side of the merge.

[[rebase_always]]
* 'rebase always':
+
Basically, the same as `rebase if necessary`, but it creates a new patchset
even if fast forward is possible and like `cherry pick` it ensures footers such
as `Change-Id`, `Reviewed-On`, and others are present in resulting commit that
is merged.
+
Thus, `rebase always` can be considered similar to `cherry pick`, but with the
important distinction that `rebase always` does not ignore dependencies.

[[fast_forward_only]]
* 'fast forward only':
+
With this action Gerrit does not create merge commits on submitting a change.
Merge commits may still be submitted, but they must be created on the client
prior to uploading to Gerrit for review.
+
To submit a change, the change must be a strict superset of the destination
branch. That is, the change must already contain the tip of the destination
branch at submit time.

[[cherry_pick]]
* 'cherry pick' (usage not recommended, user link:#rebase_always[rebase always]
instead):
+
With this submit action Gerrit always performs a cherry pick of the current
patch set when a change is submitted. This ignores the parent lineage and
instead creates a brand new commit on top of the current head of the target
branch. The submitter becomes the committer of the new commit and the original
commit author is retained.
+
Ignoring change dependencies on submit is often confusing for users. For users
that stack changes on top of each other, it's unexpected that these
dependencies are ignored on submit. Ignoring dependencies also means that
submitters need to submit the changes individually in the correct order.
Otherwise it's likely that submissions fail due to conflicts or that the
target branch gets broken (because it contains the submitted change, but not
its predecessors which may be required for the submitted change to work
correctly).
+
If link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`]
is enabled changes that have the same topic are submitted together, the same as
with all other submit actions. This means by setting the same topic on all
dependent changes it's possible to submit a stack of changes together and
overcome the limitation that change dependencies are ignored.
+
When cherry picking the patchset, Gerrit automatically appends onto the end of
the commit message a short summary of the change's approvals, and a URL link
back to the change on the web.
+
Using this submit action is not recommended because it ignores change
dependencies, instead link:#rebase_always[rebase always] should be used which
behaves the same way except that it respects change dependencies (in particular
`rebase always` adds the same kind of footers to the merged commit as
`cherry pick`).

--
+
[[submit_type_inherit]]
In addition the submit action can be set to `Inherit`, which means that the
value that is configured in the parent project applies. For new projects
`Inherit` is the default, unless the default is overridden by the global
link:config-gerrit.html#repository.name.defaultSubmitType[defaultSubmitType]
configuration. Configuring `Inherit` for the `All-Projects` root project is
equivalent to configuring link:#merge_if_necessary[merge if necessary].
+
If `submit.action` is not set, the default is 'merge if necessary'.
+
NOTE: For the value of `submit.action` in `project.config` use the exact
spelling as given above, e.g. 'merge if necessary' (without the single quotes,
but with the spaces).
+
NOTE: Project owners can also set the submit action in the Gerrit UI:
`Browse` > `Repositories` > my/repository > `Submit type`

[[submit.matchAuthorToCommitterDate]]submit.matchAuthorToCommitterDate::
+
Defines whether 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
(when rebase is necessary) Rebase If Necessary.

[[submit.rejectEmptyCommit]]submit.rejectEmptyCommit::
+
Defines whether empty commits should be rejected when a change is merged. When using
link:#submit.action[submit action] Cherry Pick, Rebase If Necessary or Rebase Always changes may
become empty upon submit, since the rebase|cherry-pick can lead to an empty commit. If this option
is set to 'true' the merge would fail in such a case. An empty commit is still allowed as the
initial commit on a branch.


[[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.

[[submit-requirement-section]]
=== Submit Requirement section

Please refer to link:config-submit-requirements.html[Configuring Submit
Requirements] 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.

[[reviewer-section]]
=== reviewer section

Defines config options to adjust a project's reviewer workflow such as enabling
reviewers and CCs by email.

[[reviewer.enableByEmail]]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 effect 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`.

[[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
---------