blob: 0c218c896effed0a8beca7e1f1c92bee42b4cf96 [file] [log] [blame]
:linkattrs:
= Gerrit Code Review - Configuration
== File `etc/gerrit.config`
The optional file `'$site_path'/etc/gerrit.config` is a Git-style
config file that controls many host specific settings for Gerrit.
[NOTE]
The contents of the `etc/gerrit.config` file are cached at startup
by Gerrit. For most properties, if they are modified in this file, Gerrit
needs to be restarted before it will use the new values. Some properties
support being link:#reloadConfig[`reloaded`] without restart.
Sample `etc/gerrit.config`:
----
[core]
packedGitLimit = 200 m
[cache]
directory = /var/cache/gerrit
----
[[reloadConfig]]
=== Reload `etc/gerrit.config`
Some properties support being reloaded without restart when a `reload config`
command is issued through link:cmd-reload-config.html[`SSH`] or the
link:rest-api-config.html#reload-config[`REST API`]. If a property supports
this it is specified in the documentation for the property below.
[[accountPatchReviewDb]]
=== Section accountPatchReviewDb
The AccountPatchReviewDb is a database used to store the user file reviewed
flags.
[[accountPatchReviewDb.url]]accountPatchReviewDb.url::
+
The url of accountPatchReviewDb. Supported types are `CLOUDSPANNER`, `H2`,
`POSTGRESQL`, `MARIADB`, and `MYSQL`. Drop the driver jar in the lib folder of
the site path if the Jdbc driver of the corresponding Database is not yet in
the class path.
+
Default is to create H2 database in the db folder of the site path.
+
Changing this parameter requires to migrate database using the
link:pgm-MigrateAccountPatchReviewDb.html[MigrateAccountPatchReviewDb] program.
Migration cannot be done while the server is running.
+
Also note that the db_name has to be a new db and not reusing an old ReviewDb
database from a former 2.x site, otherwise gerrit's init will remove the table.
----
[accountPatchReviewDb]
url = jdbc:postgresql://<host>:<port>/<db_name>?user=<user>&password=<password>
----
[[accountPatchReviewDb.poolLimit]]accountPatchReviewDb.poolLimit::
+
Maximum number of open database connections. If the server needs
more than this number, request processing threads will wait up
to <<accountPatchReviewDb.poolMaxWait, poolMaxWait>> seconds for a
connection to be released before they abort with an exception.
This limit must be several units higher than the total number of
httpd and sshd threads as some request processing code paths may
need multiple connections.
+
Default is <<sshd.threads, sshd.threads>>
+ <<httpd.maxThreads, httpd.maxThreads>> + 2.
+
[[accountPatchReviewDb.poolMinIdle]]database.poolMinIdle::
+
Minimum number of connections to keep idle in the pool.
Default is 4.
+
[[accountPatchReviewDb.poolMaxIdle]]accountPatchReviewDb.poolMaxIdle::
+
Maximum number of connections to keep idle in the pool. If there
are more idle connections, connections will be closed instead of
being returned back to the pool.
Default is min(<<accountPatchReviewDb.poolLimit, accountPatchReviewDb.poolLimit>>, 16).
+
[[accountPatchReviewDb.poolMaxWait]]accountPatchReviewDb.poolMaxWait::
+
Maximum amount of time a request processing thread will wait to
acquire a database connection from the pool. If no connection is
released within this time period, the processing thread will abort
its current operations and return an error to the client.
Values should use common unit suffixes to express their setting:
+
* ms, milliseconds
* s, sec, second, seconds
* m, min, minute, minutes
* h, hr, hour, hours
+
If a unit suffix is not specified, `milliseconds` is assumed.
Default is `30 seconds`.
[[accounts]]
=== Section accounts
[[accounts.visibility]]accounts.visibility::
+
Controls visibility of other users' dashboard pages and
completion suggestions to web users.
+
If `ALL`, all users are visible to all other users, even
anonymous users.
+
If `SAME_GROUP`, only users who are also members of a group the
current user is a member of are visible.
+
If `VISIBLE_GROUP`, only users who are members of at least one group
that is visible to the current user are visible. To make an account
visible to all users (e.g. because it is a service account) when
`VISIBLE_GROUP` is used, create a `Public Users` group that has the
`Make group visible to all registered users` option enabled and add the
account as a group member.
+
If `NONE`, no users other than the current user are visible.
+
Default is `ALL`.
[[accounts.defaultDisplayName]]accounts.defaultDisplayName::
+
If a user account does not have a display name set, which is the normal
case, then this configuration value chooses the strategy how to choose
the display name. Note that this strategy is not applied by the backend.
If the AccountInfo has the display name unset, then the client has to
apply this strategy.
+
If `FULL_NAME`, then the (full) name of the user is chosen from
link:rest-api-accounts.html#account-info[AccountInfo].
+
If `FIRST_NAME`, then the first word (i.e. everything until first
whitespace character) of the (full) name of the user is chosen from
link:rest-api-accounts.html#account-info[AccountInfo].
+
If `USERNAME`, then the username of the user is chosen from
link:rest-api-accounts.html#account-info[AccountInfo]. If that is not
set, then the (full) name will be used.
+
Default is `FULL_NAME`.
[[addreviewer]]
=== Section addreviewer
[[addreviewer.maxWithoutConfirmation]]addreviewer.maxWithoutConfirmation::
+
The maximum number of reviewers a user can add at once by adding a
group as reviewer without being asked to confirm the operation.
+
If set to 0, the user will never be asked to confirm adding a group
as reviewer.
+
Default is 10.
+
This setting only applies for adding reviewers in the Gerrit Web UI,
but is ignored when adding reviewers with the
link:cmd-set-reviewers.html[set-reviewers] command.
+
This value supports link:#reloadConfig[configuration reloads].
[[addreviewer.maxAllowed]]addreviewer.maxAllowed::
+
The maximum number of reviewers a user can add at once by adding a
group as reviewer.
+
If set to 0, there is no limit for the number of reviewers that can
be added at once by adding a group as reviewer.
+
Default is 20.
+
This value supports link:#reloadConfig[configuration reloads].
[[addReviewer.baseWeight]]addReviewer.baseWeight::
+
The weight that will be applied in the default reviewer ranking algorithm.
This can be increased or decreased to give more or less influence to plugins.
If set to zero, the base ranking will not have any effect. Reviewers will then
be ordered as ranked by the plugins (if there are any).
+
By default 1.
[[auth]]
=== Section auth
See also link:config-sso.html[SSO configuration].
[[auth.type]]auth.type::
+
Type of user authentication employed by Gerrit. The supported
values are:
+
* `OpenID`
+
The default setting. Gerrit uses any valid OpenID
provider chosen by the end-user. For more information see
http://openid.net/[openid.net,role=external,window=_blank].
+
* `OpenID_SSO`
+
Supports OpenID from a single provider. There is no registration
link, and the "Sign In" link sends the user directly to the provider's
SSO entry point.
+
* `HTTP`
+
Gerrit relies upon data presented in the HTTP request. This includes
HTTP basic authentication, or some types of commercial single-sign-on
solutions. With this setting enabled the authentication must
take place in the web server or servlet container, and not from
within Gerrit.
+
* `HTTP_LDAP`
+
Exactly like `HTTP` (above), but additionally Gerrit pre-populates
a user's full name and email address based on information obtained
from the user's account object in LDAP. The user's group membership
is also pulled from LDAP, making any LDAP groups that a user is a
member of available as groups in Gerrit. Hence the `_LDAP` suffix in
the name of this authentication type. Gerrit does NOT authenticate
the user via LDAP.
+
* `CLIENT_SSL_CERT_LDAP`
+
This authentication type is actually kind of SSO. Gerrit will configure
Jetty's SSL channel to request the client's SSL certificate. For this
authentication to work a Gerrit administrator has to import the root
certificate of the trust chain used to issue the client's certificate
into the <review-site>/etc/keystore.
After the authentication is done Gerrit will obtain basic user
registration (name and email) from LDAP, and some group memberships.
Hence the `_LDAP` suffix in the name of this authentication type.
Gerrit does NOT authenticate the user via LDAP.
This authentication type can only be used under hosted daemon mode, and
the httpd.listenUrl must use https:// as the protocol.
Optionally, certificate revocation list file can be used
at <review-site>/etc/crl.pem. For details, see httpd.sslCrl.
+
* `LDAP`
+
Gerrit prompts the user to enter a username and a password, which
it then verifies by performing a simple bind against the configured
<<ldap.server,ldap.server>>. In this configuration the web server
is not involved in the user authentication process.
+
The actual username used in the LDAP simple bind request is the
account's full DN, which is discovered by first querying the
directory using either an anonymous request, or the configured
<<ldap.username,ldap.username>> identity. Gerrit can also use kerberos if
<<ldap.authentication,ldap.authentication>> is set to `GSSAPI`.
+
If link:#auth.gitBasicAuthPolicy[`auth.gitBasicAuthPolicy`] is set to `HTTP`,
the randomly generated HTTP password is used for authentication. On the other hand,
if link:#auth.gitBasicAuthPolicy[`auth.gitBasicAuthPolicy`] is set to `HTTP_LDAP`,
the password in the request is first checked against the HTTP password and, if
it does not match, it is then validated against the LDAP password.
Service users that are link:cmd-create-account.html[internal-only] are
authenticated by their HTTP passwords.
* `LDAP_BIND`
+
Gerrit prompts the user to enter a username and a password, which
it then verifies by performing a simple bind against the configured
<<ldap.server,ldap.server>>. In this configuration the web server
is not involved in the user authentication process.
+
Unlike `LDAP` above, the username used to perform the LDAP simple bind
request is the exact string supplied in the dialog by the user.
The configured <<ldap.username,ldap.username>> identity is not used to obtain
account information.
+
* `OAUTH`
+
OAuth is a protocol that lets external apps request authorization to private
details in a user's account without getting their password. This is
preferred over Basic Authentication because tokens can be limited to specific
types of data, and can be revoked by users at any time.
+
Site owners have to register their application before getting started. Note
that provider specific plugins must be used with this authentication scheme.
+
Git clients may send OAuth 2 access tokens instead of passwords in the Basic
authentication header. Note that provider specific plugins must be installed to
facilitate this authentication scheme. If multiple OAuth 2 provider plugins are
installed one of them must be selected as default with the
`auth.gitOAuthProvider` option.
+
* `DEVELOPMENT_BECOME_ANY_ACCOUNT`
+
*DO NOT USE*. Only for use in a development environment.
+
When this is the configured authentication method a hyperlink titled
`Become` appears in the top right corner of the page, taking the
user to a form where they can enter the username of any existing
user account, and immediately login as that account, without any
authentication taking place.
+
By default, OpenID.
[[auth.allowedOpenID]]auth.allowedOpenID::
+
List of permitted OpenID providers. A user may only authenticate
with an OpenID that matches this list. Only used if `auth.type`
is set to `OpenID` (the default).
+
Patterns may be either a
link:http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[standard
Java regular expression (java.util.regex),role=external,window=_blank] (start with `^` and
end with `$`) or be a simple prefix (any other string).
+
By default, the list contains two values, `http://` and `https://`,
allowing users to authenticate with any OpenID provider.
[[auth.trustedOpenID]]auth.trustedOpenID::
+
List of trusted OpenID providers. Only used if `auth.type` is
set to `OpenID` (the default).
+
In order for a user to take advantage of permissions beyond those
granted to the `Anonymous Users` and `Registered Users` groups,
the user account must only have OpenIDs which match at least one
pattern from this list.
+
Patterns may be either a
link:http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[standard
Java regular expression (java.util.regex),role=external,window=_blank] (start with `^` and
end with `$`) or be a simple prefix (any other string).
+
By default, the list contains two values, `http://` and `https://`,
allowing Gerrit to trust any OpenID it receives.
[[auth.openIdDomain]]auth.openIdDomain::
+
List of allowed OpenID email address domains. Only used if
`auth.type` is set to `OPENID` or `OPENID_SSO`.
+
Domain is case insensitive and must be in the same form as it
appears in the email address, for example, "example.com".
+
By default, any domain is accepted.
[[auth.maxOpenIdSessionAge]]auth.maxOpenIdSessionAge::
+
Time in seconds before an OpenID provider must force the user
to authenticate themselves again before authentication to this
Gerrit server. Currently this is only a polite request, and users
coming from providers that don't support the PAPE extension will
be accepted anyway. In the future it may be enforced, rejecting
users coming from providers that don't honor the max session age.
+
If set to 0, the provider will always force the user to authenticate
(e.g. supply their password). Values should use common unit suffixes
to express their setting:
+
* s, sec, second, seconds
* m, min, minute, minutes
* h, hr, hour, hours
* d, day, days
* w, week, weeks (`1 week` is treated as `7 days`)
* mon, month, months (`1 month` is treated as `30 days`)
* y, year, years (`1 year` is treated as `365 days`)
+
Default is -1, permitting infinite time between authentications.
[[auth.registerEmailPrivateKey]]auth.registerEmailPrivateKey::
+
Private key to use when generating an email verification token.
+
If not set, a random key is generated when running the
link:pgm-init.html[site initialization].
[[auth.maxRegisterEmailTokenAge]]auth.maxRegisterEmailTokenAge::
+
Time in seconds before an email verification token sent to a user in
order to validate their email address expires.
+
* s, sec, second, seconds
* m, min, minute, minutes
* h, hr, hour, hours
* d, day, days
* w, week, weeks (`1 week` is treated as `7 days`)
* mon, month, months (`1 month` is treated as `30 days`)
* y, year, years (`1 year` is treated as `365 days`)
+
Default is 12 hours.
[[auth.openIdSsoUrl]]auth.openIdSsoUrl::
+
The SSO entry point URL. Only used if `auth.type` is set to
`OpenID_SSO`.
+
The "Sign In" link will send users directly to this URL.
[[auth.httpHeader]]auth.httpHeader::
+
HTTP header to trust the username from, or unset to select HTTP basic
authentication. Only used if `auth.type` is set to `HTTP`.
[[auth.httpDisplaynameHeader]]auth.httpDisplaynameHeader::
+
HTTP header to retrieve the user's display name from. Only used if `auth.type`
is set to `HTTP`.
+
If set, Gerrit trusts and enforces the user's full name using the HTTP header
and disables the ability to manually modify the user's full name
from the contact information page.
[[auth.httpEmailHeader]]auth.httpEmailHeader::
+
HTTP header to retrieve the user's e-mail from. Only used if `auth.type`
is set to `HTTP`.
+
If set, Gerrit trusts and enforces the user's e-mail using the HTTP header
and disables the ability to manually modify or register other e-mails
from the contact information page.
[[auth.httpExternalIdHeader]]auth.httpExternalIdHeader::
+
HTTP header to retrieve the user's external identification token.
Only used if `auth.type` is set to `HTTP`.
+
If set, Gerrit adds the value contained in the HTTP header to the
user's identity. Typical use is with a federated identity token from
an external system (e.g. GitHub OAuth 2.0 authentication) where
the user's auth token exchanged during authentication handshake
needs to be used for authenticated communication to the external
system later on.
+
Example: `auth.httpExternalIdHeader: X-GitHub-OTP`
[[auth.loginUrl]]auth.loginUrl::
+
URL to redirect a browser to after the end-user has clicked on the
login link in the upper right corner. Only used if `auth.type` is set
to `HTTP` or `HTTP_LDAP`.
Organizations using an enterprise single-sign-on solution may want to
redirect the browser to the SSO product's sign-in page for completing the
login process and validate their credentials.
+
If set, Gerrit allows anonymous access until the end-user performs the login
and provides a trusted identity through the HTTP header.
If not set, Gerrit requires the HTTP header with a trusted identity
and returns the error page 'LoginRedirect.html' if such a header is not
present.
[[auth.loginText]]auth.loginText::
+
Text displayed in the loginUrl link. Only used if `auth.loginUrl` is set.
+
If not set, the "Sign In" text is used.
[[auth.registerPageUrl]]auth.registerPageUrl::
+
URL of the registration page to use when a new user logs in to Gerrit for
the first time. Used only when `auth.type` is set to `HTTP`.
+
If not set, the standard Gerrit registration page `/#/register/` is displayed.
[[auth.logoutUrl]]auth.logoutUrl::
+
URL to redirect a browser to after the end-user has clicked on the
"Sign Out" link in the upper right corner. Organizations using an
enterprise single-sign-on solution may want to redirect the browser
to the SSO product's sign-out page.
+
If not set, the redirect returns to the list of all open changes.
[[auth.registerUrl]]auth.registerUrl::
+
Target for the "Register" link in the upper right corner. Used only
when `auth.type` is `LDAP`, `LDAP_BIND` or `CUSTOM_EXTENSION`.
+
If not set, no "Register" link is displayed.
[[auth.registerText]]auth.registerText::
+
Text for the "Register" link in the upper right corner. Used only
when `auth.type` is `LDAP`, `LDAP_BIND` or `CUSTOM_EXTENSION`.
+
If not set, defaults to "Register".
[[auth.editFullNameUrl]]auth.editFullNameUrl::
+
Target for the "Edit" button when the user is allowed to edit their
full name. Used only when `auth.type` is `LDAP`, `LDAP_BIND` or
`CUSTOM_EXTENSION`.
[[auth.httpPasswordUrl]]auth.httpPasswordUrl::
+
Target for the "Obtain Password" link. Used only when `auth.type` is
`CUSTOM_EXTENSION`.
[[auth.switchAccountUrl]]auth.switchAccountUrl::
+
URL to switch user identities and login as a different account than
the currently active account. This is disabled by default except when
`auth.type` is `OPENID` and `DEVELOPMENT_BECOME_ANY_ACCOUNT`. If set
the "Switch Account" link is displayed next to "Sign Out".
+
When `auth.type` does not normally enable this URL administrators may
set this to `login/`, allowing users to begin a new web session. This value
is used as an href in the Gerrit web app, so absolute URLs like
`https://someotherhost/login` work as well.
+
If a ${path} parameter is included, then the Gerrit web app will substitute the
currently viewed path in the link. Be aware that this path will include
a leading slash, so a value like this might be appropriate: `/login${path}`.
[[auth.cookiePath]]auth.cookiePath::
+
Sets "path" attribute of the authentication cookie.
+
If not set, HTTP request's path is used.
[[auth.cookieDomain]]auth.cookieDomain::
+
Sets "domain" attribute of the authentication cookie.
+
If not set, HTTP request's domain is used.
[[auth.cookieSecure]]auth.cookieSecure::
+
Sets "secure" flag of the authentication cookie. If `true`, cookies
will be transmitted only over HTTPS protocol.
+
By default, `false`.
[[auth.emailFormat]]auth.emailFormat::
+
Optional format string to construct user email addresses out of
user login names. Only used if `auth.type` is `HTTP`, `HTTP_LDAP`
or `LDAP`.
+
This value can be set to a format string, where `{0}` is replaced
with the login name. E.g. "\{0\}+gerrit@example.com" with a user
login name of "foo" will produce "foo+gerrit@example.com" during
the first time user "foo" registers.
+
If the site is using `HTTP_LDAP` or `LDAP`, using this option is
discouraged. Setting `ldap.accountEmailAddress` and importing the
email address from the LDAP directory is generally preferred.
[[auth.contributorAgreements]]auth.contributorAgreements::
+
Controls whether or not the contributor agreement features are
enabled for the Gerrit site. If enabled a user must complete a
contributor agreement before they can upload changes.
+
If enabled, the admin must also add one or more
link:config-cla.html[contributor-agreement sections]
in project.config and create agreement files under
`'$site_path'/static`, so users can actually complete one or
more agreements.
+
By default this is `false` (no agreements are used).
+
To enable the actual usage of contributor agreement the project
specific config option in the `project.config` must be set:
link:config-project-config.html#receive.requireContributorAgreement[
receive.requireContributorAgreement].
[[auth.trustContainerAuth]]auth.trustContainerAuth::
+
If `true` then it is the responsibility of the container hosting
Gerrit to authenticate users. In this case Gerrit will blindly trust
the container.
+
This parameter only affects git over http traffic. If set to false
then Gerrit will do the authentication (using Basic authentication).
+
By default this is set to `false`.
[[auth.gitBasicAuthPolicy]]auth.gitBasicAuthPolicy::
+
When `auth.type` is `LDAP`, `LDAP_BIND` or `OAUTH`, it allows using either the generated
HTTP password, the LDAP or OAUTH password, or a combination of HTTP and LDAP
authentication, to authenticate Git over HTTP and REST API requests.
The supported values are:
+
*`HTTP`
+
Only the HTTP password is accepted when doing Git over HTTP and REST API requests.
+
*`LDAP`
+
Only the `LDAP` password is allowed when doing Git over HTTP and REST API
requests.
+
*`OAUTH`
+
Only the `OAUTH` authentication is allowed when doing Git over HTTP and REST API
requests.
+
*`HTTP_LDAP`
+
The password in the request is first checked against the HTTP password and, if
it does not match, it is then validated against the `LDAP` password.
+
By default this is set to `LDAP` when link:#auth.type[`auth.type`] is `LDAP`
and `OAUTH` when link:#auth.type[`auth.type`] is `OAUTH`.
Otherwise, the default value is `HTTP`.
+
When gitBasicAuthPolicy is set to `LDAP` or `HTTP_LDAP` and the user
is authenticating with the LDAP username/password, the Git client config
needs to have `http.cookieFile` set to a local file, otherwise every
single call would trigger a full LDAP authentication and groups resolution
which could introduce a noticeable latency on the overall execution
and produce unwanted load to the LDAP server.
[[auth.gitOAuthProvider]]auth.gitOAuthProvider::
+
Selects the OAuth 2 provider to authenticate git over HTTP traffic with.
+
In general there is no way to determine from an access token alone, which
OAuth 2 provider to address to verify that token, and the BasicAuth
scheme does not support amending such details. If multiple OAuth provider
plugins in a system offer support for git over HTTP authentication site
administrators must configure, which one to use as default provider.
In case the provider cannot be determined from a request the access token
will be sent to the default provider for verification.
+
The value of this parameter must be the identifier of an OAuth 2 provider
in the form `plugin-name:provider-name`. Consult the respective plugin
documentation for details.
[[auth.userNameToLowerCase]]auth.userNameToLowerCase::
+
If set the username that is received to authenticate a git operation
is converted to lower case for looking up the user account in Gerrit.
+
By setting this parameter a case insensitive authentication for the
git operations can be achieved, if it is ensured that the usernames in
Gerrit (scheme `username`) are stored in lower case (e.g. if the
parameter link:#ldap.accountSshUserName[ldap.accountSshUserName] is
set to `${sAMAccountName.toLowerCase}`). It is important that for all
existing accounts this username is already in lower case. It is not
possible to convert the usernames of the existing accounts to lower
case because this would break the access to existing per-user
branches and Gerrit provides no tool to do such a conversion. Accounts
created using the REST API or the `create-account` SSH command will
be created with all lowercase characters, when this option is set.
+
Setting this parameter to `true` will prevent all users from login that
have a non-lower-case username.
+
This parameter only affects git over http and git over SSH traffic.
+
By default this is set to `false`.
[[auth.userNameCaseInsensitive]]auth.userNameCaseInsensitive::
+
If set the username will be handled case insensitively but case preserving,
i.e. a user can login with `johndoe` or `JohnDoe` for the same account
created for `JohnDoe`. The form of the username used during account creation
will be used wherever the username is displayed. Sandbox branches created
for a user can also only be created for this original form.
+
Note, that this does not work for all existing accounts, if they were
not originally created with all lowercase, since the note keys of the
external IDs will not match the new scheme. For more details refer to
the link:config-accounts.html#external-ids[External ID documentation].
+
Gerrit provides the
link:pgm-ChangeExternalIdCaseSensitivity.html[offline]
and the online link:externalid-case-insensitivity.html#online-migration[online]
tools to migrate existing accounts to match the new scheme.
+
Naturally, if there were two accounts only different in capitalization,
e.g. `johndoe` and `JohnDoe`, the account `JohnDoe` will not be able
to authenticate anymore after setting this option. If such duplicate
accounts exist the migration tool will fail, since the newly computed
note name would be identical and thus conflict. These duplicates thus
have to be deleted manually by deleting the respective external ID.
+
For newly initialized sites this option defaults to `true`.
+
Default is `false`.
[[auth.userNameCaseInsensitiveMigrationMode]]auth.userNameCaseInsensitiveMigrationMode::
+
Setting migration mode to `true` allows to fallback to case sensitive
behaviour if the migrated external ID cannot be found. This allows to
trigger the migration while Gerrit process is running.
+
Default is `false`.
[[auth.enableRunAs]]auth.enableRunAs::
+
If `true` HTTP REST APIs will accept the `X-Gerrit-RunAs` HTTP request
header from any users granted the link:access-control.html#capability_runAs[Run As]
capability. The header and capability permit the authenticated user
to impersonate another account.
+
If `false` the feature is disabled and cannot be re-enabled without
editing gerrit.config and restarting the server.
+
Default is `true`.
[[auth.allowRegisterNewEmail]]auth.allowRegisterNewEmail::
+
Whether users are allowed to register new email addresses.
+
In addition for the HTTP authentication type
link:#auth.httpemailheader[auth.httpemailheader] must *not* be set to
enable registration of new email addresses.
+
By default, `true`.
[[auth.autoUpdateAccountActiveStatus]]auth.autoUpdateAccountActiveStatus::
+
Whether to allow automatic synchronization of an account's inactive flag upon login.
+
If set to `true`, upon login, if the authentication back-end reports the account as active,
the account's inactive flag in NoteDb will be updated to be active.
+
If the authentication back-end reports the account as inactive, the account's flag will be
updated to be inactive and the login attempt will be blocked. Users enabling this feature
should ensure that their authentication back-end is supported. Currently, only
strict 'LDAP' authentication is supported.
+
In addition, if this parameter is not set, or `false`, the corresponding scheduled
task to deactivate inactive Gerrit accounts will also be disabled. If this
parameter is set to `true`, users should also consider configuring the
link:#accountDeactivation[accountDeactivation] section appropriately.
+
By default, `false`.
[[auth.skipFullRefEvaluationIfAllRefsAreVisible]]auth.skipFullRefEvaluationIfAllRefsAreVisible::
+
Whether to skip the full ref visibility checks as a performance shortcut when a
user has READ permission for all refs.
+
The full ref filtering would filter out refs for pending edits, private changes
and auto merge commits.
+
By default, `true`.
[[cache]]
=== Section cache
[[cache.threads]]cache.threads::
+
Number of threads to use when running asynchronous cache tasks.
The threads executor is delegated to when sending removal notifications to listeners,
when asynchronous computations like refresh, refreshAfterWrite are performed, or when
performing periodic maintenance.
+
**NOTE**: Setting it to 0 disables the dedicated thread pool and indexing will be done in the
same thread as the operation. This may result in evictions taking longer because the
listeners are executed in the caller's thread.
+
By default, the JVM common ForkJoinPool is used.
[[cache.directory]]cache.directory::
+
Path to a local directory where Gerrit can write cached entities for
future lookup. This local disk cache is used to retain potentially
expensive to compute information across restarts. If the location
does not exist, Gerrit will try to create it.
+
Technically, cached entities are persisted as a set of H2 databases
inside this directory.
+
If not absolute, the path is resolved relative to `$site_path`.
+
Default is unset, no disk cache.
[[cache.enableDiskStatMetrics]]cache.enableDiskStatMetrics::
+
Whether to enable the computation of disk statistics of persistent caches.
This computation is expensive and requires a long time on larger installations.
+
By default, `false`.
[[cache.h2CacheSize]]cache.h2CacheSize::
+
The size of the in-memory cache for each opened H2 cache database, in bytes.
+
Some caches of Gerrit are persistent and are backed by an H2 database.
H2 uses memory to cache its database content. The parameter `h2CacheSize`
allows to limit the memory used by H2 and thus prevent out-of-memory
caused by the H2 database using too much memory.
+
Technically the H2 cache size is configured using the CACHE_SIZE parameter in
the H2 JDBC connection URL, as described
link:http://www.h2database.com/html/features.html#cache_settings[here,role=external,window=_blank]
+
Default is unset, using up to half of the available memory.
+
H2 will persist this value in the database, so to unset explicitly specify 0.
+
Common unit suffixes of 'k', 'm', or 'g' are supported.
[[cache.h2AutoServer]]cache.h2AutoServer::
+
If set to `true`, enable H2 autoserver mode for the H2-backed persistent cache
databases.
+
See link:http://www.h2database.com/html/features.html#auto_mixed_mode[here,role=external,window=_blank]
for detail.
+
Default is `false`.
[[cache.openFiles]]cache.openFiles::
+
The number of file descriptors to add to the limit set by the Gerrit daemon.
+
Persistent caches are stored on the file system and as such participate in the
file descriptors utilization. The number of file descriptors can vary depending
on the cache configuration and the specific backend used.
+
The additional file descriptors required by the cache should be accounted for
via this setting, so that the Gerrit daemon can adjust the ulimit accordingly.
+
If you increase this to a larger setting you may need to also adjust
the ulimit on file descriptors for the host JVM, as Gerrit needs
additional file descriptors available for network sockets and other
repository data manipulation.
+
Default is 0.
[[cache.name.maxAge]]cache.<name>.maxAge::
+
Maximum age to keep an entry in the cache.
Values should use common unit suffixes to express their setting:
+
* s, sec, second, seconds
* m, min, minute, minutes
* h, hr, hour, hours
* d, day, days
* w, week, weeks (`1 week` is treated as `7 days`)
* mon, month, months (`1 month` is treated as `30 days`)
* y, year, years (`1 year` is treated as `365 days`)
+
--
If a unit suffix is not specified, `seconds` is assumed. If 0 is
supplied, the maximum age is infinite and items are never purged
except when the cache is full.
Default is `0`, meaning store forever with no expire, except:
* `"adv_bases"`: default is `10 minutes`
* `"ldap_groups"`: default is `1 hour`
* `"web_sessions"`: default is `12 hours`
--
[[cache.name.memoryLimit]]cache.<name>.memoryLimit::
+
The total cost of entries to retain in memory. The cost computation
varies by the cache. For most caches where the in-memory size of each
entry is relatively the same, memoryLimit is currently defined to be
the number of entries held by the cache (each entry costs 1).
+
For caches where the size of an entry can vary significantly between individual
entries (notably `"git_modified_files"`, `"modified_files"`, `"git_file_diff"`,
`"gerrit_file_diff"`, `"diff_intraline"`), memoryLimit is an approximation of
the total number of bytes stored by the cache. Larger entries that represent
bigger patch sets or longer source files will consume a bigger portion of the
memoryLimit. For these caches the memoryLimit should be set to roughly the
amount of RAM (in bytes) the administrator can dedicate to the cache.
+
Default is 1024 for most caches, except:
+
* `"adv_bases"`: default is `4096`
* `"git_modified_files"`: default is `10m` (10 MiB of memory)
* `"modified_files"`: default is `10m` (10 MiB of memory)
* `"git_file_diff"`: default is `10m` (10 MiB of memory)
* `"gerrit_file_diff"`: default is `10m` (10 MiB of memory)
* `"diff_intraline"`: default is `10m` (10 MiB of memory)
* `"diff_summary"`: default is `10m` (10 MiB of memory)
* `"external_ids_map"`: default is `2` and should not be changed
* `"groups"`: default is unlimited
* `"groups_byname"`: default is unlimited
* `"groups_byuuid"`: default is unlimited
* `"groups_byuuid_persisted"`: default is `1g` (1 GiB of disk space)
* `"plugin_resources"`: default is 2m (2 MiB of memory)
+
If set to 0 the cache is disabled; entries are loaded but not stored
in-memory.
+
**NOTE**: When the cache is disabled, there is no locking when accessing
the same key/value, and therefore multiple threads may
load the same value concurrently with a higher memory footprint.
To keep a minimum caching and avoid concurrent loading of the same
key/value, set `memoryLimit` to `1` and `maxAge` to `1`.
[[cache.name.expireFromMemoryAfterAccess]]cache.<name>.expireFromMemoryAfterAccess::
+
Time after last access to automatically expire entries from an in-memory
cache. If 0 or not specified, entries are never expired in this manner.
Values may use unit suffixes as in link:#cache.name.maxAge[maxAge].
+
This option only applies to in-memory caches; persistent cache values are
not expired in this manner, and are only pruned via
link:#cache.name.diskLimit[diskLimit].
[[cache.name.diskLimit]]cache.<name>.diskLimit::
+
Total size in bytes of the keys and values stored on disk. Caches that
have grown bigger than this size are scanned daily at 1 AM local
server time to trim the cache. Entries are removed in least recently
accessed order until the cache fits within this limit. Caches may
grow larger than this during the day, as the size check is only
performed once every 24 hours.
+
Default is 128 MiB per cache, except:
+
* `"change_notes"`: disk storage is disabled by default
* `"diff_summary"`: default is `1g` (1 GiB of disk space)
* `"external_ids_map"`: disk storage is disabled by default
* `"persisted_projects"`: default is `1g` (1 GiB of disk space)
+
If 0 or negative, disk storage for the cache is disabled.
[[cache.name.refreshAfterWrite]]cache.<name>.refreshAfterWrite::
+
Duration after which we asynchronously refresh the cached value.
+
Values should use common unit suffixes to express their setting:
+
* ms, milliseconds
* s, sec, second, seconds
* m, min, minute, minutes
* h, hr, hour, hours
+
This applies only to these caches that support refreshing:
+
* `"projects"`: Caching project information in-memory. Defaults to 15 minutes.
[[cache.refreshThreadPoolSize]]cache.refreshThreadPoolSize::
+
Number of threads that are available to refresh cached values that became
out of date. This applies only to these caches that support refreshing:
+
* `"projects"`: Caching project information in-memory
+
Refreshes will only be scheduled on this executor if the values are
out of sync.
The check if they are is cheap and always happens on the thread that
inquires for a cached value.
+
Defaults to 2.
==== [[cache_names]]Standard Caches
cache `"accounts"`::
+
Cache entries contain important details of an active user, including
their display name, preferences, and known email addresses. Entry
information is obtained from NoteDb data in the `All-Users` repo.
+
If direct updates are made to `All-Users`, this cache should be flushed.
cache `"adv_bases"`::
+
Used only for push over smart HTTP when branch level access controls
are enabled. The cache entry contains all commits that are available
for the client to use as potential delta bases. Push over smart HTTP
requires two HTTP requests, and this cache tries to carry state from
the first request into the second to ensure it can complete.
cache `"default_preferences"`::
+
Caches the server's default general, edit and diff preferences.
+
Default value is 1 to hold only the most current version in-memory.
cache `"changes"`::
+
The size of `memoryLimit` determines the number of projects for which
all changes will be cached. If the cache is set to 1024, this means all
changes for up to 1024 projects can be held in the cache.
+
Default value is 0 (disabled). It is disabled by default due to the fact
that change updates are not communicated between Gerrit servers. Hence
this cache should be disabled in a cluster setup using multiple primary
or multiple replica nodes.
+
The cache should be flushed whenever NoteDb change metadata in a repository is
modified outside of Gerrit.
cache `"changes_by_project"`::
+
Ideally, the memorylimit of this cache is large enough to cover all projects.
This should significantly speed up change ref advertisements and git pushes,
especially for projects with lots of changes, and particularly on replicas
where there is no index.
cache `"git_modified_files"`::
+
Each item caches the list of git modified files between two git trees
corresponding to two different commits. This cache does not read the actual
file contents nor does it include the edits (modified regions) of the files.
cache `"modified_files"`::
+
Each item caches the list of modified files between two commits. This cache
is similar to the `git_modified_files` cache but performs extra logic including
filtering out files that are untouched by both commits because they were purely
modified between the parent commits.
cache `"git_file_diff"`::
+
Each item caches the pure git diff between two git trees for a specific file
path. The diff includes all the file attributes (old/new paths, change/patch
types) as well as the list of edits corresponding to the modified regions in
the file.
cache `"gerrit_file_diff"`::
+
Each item caches the diff between two git commits for a specific file path.
This cache is similar to the `git_file_diff` cache but performs extra logic
including identifying the edits that are due to rebase. The diff for the
"commit message" and "merge list" can also be requested from this cache.
+
Entries in this cache are relatively large, so memoryLimit is an
estimate in bytes of memory used. Administrators should try to target
cache.diff.memoryLimit to fit all changes users will view in a 1 or 2
day span. The same applies for other diff caches: `"git_modified_files"`,
`"modified_files"` and `"git_file_diff"`.
cache `"diff_intraline"`::
+
Each item caches the intraline difference of one file, when compared
between two commits. Gerrit uses this cache to accelerate display of
intraline differences when viewing a file.
+
Entries in this cache are relatively large, so memoryLimit is an
estimate in bytes of memory used. Administrators should try to target
cache.diff.memoryLimit to fit all files users will view in a 1 or 2
day span.
cache `"diff_summary"`::
+
Each item caches list of file paths which are different between two
commits. Gerrit uses this cache to accelerate computing of the list
of paths of changed files.
+
Ideally, disk limit of this cache is large enough to cover all changes.
This should significantly speed up change reindexing, especially
full offline reindexing.
cache `"external_ids_map"`::
+
A singleton cache whose sole entry is a map of the parsed representation
of link:config-accounts.html#external-ids[all current external IDs]. The
cache may temporarily contain 2 entries, but the second one is promptly
expired.
+
It is not recommended to change the in-memory attributes of this cache
away from the defaults. The cache may be persisted by setting
`diskLimit`, which is only recommended if cold start performance is
problematic.
cache `"git_tags"`::
+
If branch or reference level READ access controls are used, this
cache tracks which tags are reachable from the branch tips of a
repository. Gerrit uses this information to determine the set
of tags that a client may access, derived from which tags are
part of the history of a visible branch.
+
The cache is persisted to disk across server restarts as it can
be expensive to compute (60 or more seconds for a large history
like the Linux kernel repository).
cache `"comment_context"`::
+
Caches the context lines of comments, which are the lines of the source file
highlighted by the user when the comment was written.
cache `"groups"`::
+
Caches the basic group information of internal groups by group ID,
including the group owner, name, and description.
+
For this cache it is important to configure a size that is larger than
the number of internal Gerrit groups, otherwise general Gerrit
performance may be poor. This is why by default this cache is
unlimited.
+
External group membership obtained from LDAP is cached under
`"ldap_groups"`.
cache `"groups_byname"`::
+
Caches the basic group information of internal groups by group name,
including the group owner, name, and description.
+
For this cache it is important to configure a size that is larger than
the number of internal Gerrit groups, otherwise general Gerrit
performance may be poor. This is why by default this cache is
unlimited.
+
External group membership obtained from LDAP is cached under
`"ldap_groups"`.
cache `"groups_byuuid"`::
+
Caches the basic group information of internal groups by group UUID,
including the group owner, name, and description.
+
For this cache it is important to configure a size that is larger than
the number of internal Gerrit groups, otherwise general Gerrit
performance may be poor. This is why by default this cache is
unlimited.
+
External group membership obtained from LDAP is cached under
`"ldap_groups"`.
cache `"groups_byuuid_persisted"`::
+
Caches the basic group information of internal groups by group UUID,
including the group owner, name, and description.
+
This is the persisted version of `groups_byuuid` cache. The intention of this
cache is to have an in-memory size of 0.
+
External group membership obtained from LDAP is cached under
`"ldap_groups"`.
cache `"groups_bymember"`::
+
Caches the groups which contain a specific member (account). If direct
updates are made to the `account_group_members` table, this cache should
be flushed.
cache `"groups_bysubgroups"`::
+
Caches the parent groups of a subgroup. If direct updates are made
to the `account_group_includes` table, this cache should be flushed.
cache `"groups_external"`::
+
Caches all the external groups available to Gerrit. The cache holds a
single entry which maps to the latest available of all external groups'
UUIDs. This cache uses "groups_external_persisted" to load its value.
cache `"groups_external_persisted"`::
+
Caches all external groups available to Gerrit at some point in history.
The cache key is representation of a specific groups state in NoteDb and
the value is the list of all external groups.
The cache is persisted to enhance performance.
cache `"ldap_groups"`::
+
Caches the LDAP groups that a user belongs to, if LDAP has been
configured on this server. This cache should be configured with a
low maxAge setting, to ensure LDAP modifications are picked up in
a timely fashion.
cache `"ldap_groups_byinclude"`::
+
Caches the hierarchical structure of LDAP groups.
cache `"ldap_usernames"`::
+
Caches a mapping of LDAP username to Gerrit account identity. The
cache automatically updates when a user first creates their account
within Gerrit, so the cache expire time is largely irrelevant.
cache `"permission_sort"`::
+
Caches the order in which access control sections must be applied to a
reference. Sorting the sections can be expensive when regular
expressions are used, so this cache remembers the ordering for
each branch.
cache `"plugin_resources"`::
+
Caches formatted plugin resources, such as plugin documentation that
has been converted from Markdown to HTML. The memoryLimit refers to
the bytes of memory dedicated to storing the documentation.
cache `"persisted_projects"`::
+
Caches the project description records, from the `refs/meta/config`
branch of each project. This is the persisted variant of the
`projects` cache. The intention is for this cache to have an in-memory
size of 0.
cache `"projects"`::
+
Caches the project description records, from the `refs/meta/config`
branch of each project. If a project record is updated or deleted, this
cache should be flushed. Newly inserted projects do not require
a cache flush, as they will be read upon first reference.
NOTE: This cache should be disabled or set with a low refreshAfterWrite
in a cluster setup using multiple primary or multiple replica nodes.
cache `"prolog_rules"`::
+
Caches parsed `rules.pl` contents for each project. This cache uses the same
size as the `projects` cache when `cache.prolog_rules.memoryLimit` is not set.
cache `"pure_revert"`::
+
Result of checking if one change or commit is a pure/clean revert of
another.
cache `"soy_sauce_compiled_templates"`::
+
Caches compiled soy templates. Stores at most only one key-value pair with
a constant key value and the value is a compiled SoySauce templates. The value
is reloaded automatically every few seconds if there are reads from the cache.
If cache is not used for 1 minute, the item is removed (i.e. emails can be send
with templates which are max 1 minute old).
cache `"sshkeys"`::
+
Caches unpacked versions of user SSH keys, so the internal SSH daemon
can match against them during authentication. The unit of storage
is per-user, so 1024 items translates to 1024 unique user accounts.
As each individual user account may configure multiple SSH keys,
the total number of keys may be larger than the item count.
NOTE: This cache should be disabled or set with a low refreshAfterWrite
in a cluster setup using multiple primary or multiple replica nodes.
cache `"web_sessions"`::
+
Tracks the live user sessions coming in over HTTP. Flushing this
cache would cause all users to be signed out immediately, forcing
them to sign-in again. To avoid breaking active users, this cache
is not flushed automatically by `gerrit flush-caches --all`, but
instead must be explicitly requested.
+
If no disk cache is configured (or `cache.web_sessions.diskLimit`
is set to 0) a server restart will force all users to sign-out,
and need to sign-in again after the restart, as the cache was
unable to persist the session information. Enabling a disk cache
is strongly recommended.
+
Session storage is relatively inexpensive. The average entry in
this cache is approximately 346 bytes.
+
The `maxAge` configuration is also used for as maximum lifetime
of the HTTP servlet container session.
See also link:cmd-flush-caches.html[gerrit flush-caches].
==== [[cache_options]]Cache Options
[[cache.git_file_diff.timeout]]cache.git_file_diff.timeout::
+
Maximum number of milliseconds to wait for git diff data before giving up and
falling back on a simpler diff algorithm that will not be able to break down
modified regions into smaller ones. This is a work around for an infinite loop
bug in the default difference algorithm implementation.
+
Values should use common unit suffixes to express their setting:
+
* ms, milliseconds
* s, sec, second, seconds
* m, min, minute, minutes
* h, hr, hour, hours
+
--
If a unit suffix is not specified, `milliseconds` is assumed.
Default is 5 seconds.
--
[[cache.diff_intraline.timeout]]cache.diff_intraline.timeout::
+
Maximum number of milliseconds to wait for intraline difference data
before giving up and disabling it for a particular file pair. This is
a work around for an infinite loop bug in the intraline difference
implementation.
+
If computation takes longer than the timeout, the worker thread is
terminated, an error message is shown, and no intraline difference is
displayed for the file pair.
+
Values should use common unit suffixes to express their setting:
+
* ms, milliseconds
* s, sec, second, seconds
* m, min, minute, minutes
* h, hr, hour, hours
+
--
If a unit suffix is not specified, `milliseconds` is assumed.
Default is 5 seconds.
--
[[cache.diff_intraline.enabled]]cache.diff_intraline.enabled::
+
Boolean to enable or disable the computation of intraline differences
when populating a diff cache entry. This flag is provided primarily
as a backdoor to disable the intraline difference feature if
necessary. To maintain backwards compatibility with prior versions,
this setting will fallback to `cache.diff.intraline` if not set in the
configuration.
+
Default is `true`, enabled.
[[cache.projects.loadOnStartup]]cache.projects.loadOnStartup::
+
If the project cache should be loaded during server startup.
+
The cache is loaded concurrently. Admins should ensure that the cache
size set under <<cache.name.memoryLimit,cache.projects.memoryLimit>>
is not smaller than the number of repos.
+
Default is `false`, disabled.
[[cache.projects.loadThreads]]cache.projects.loadThreads::
+
Only relevant if <<cache.projects.loadOnStartup,cache.projects.loadOnStartup>>
is `true`.
+
The number of threads to allocate for loading the cache at startup. These
threads will die out after the cache is loaded.
+
Default is the number of CPUs.
[[cache.project_list.interval]]cache.project_list.interval::
+
The link:#schedule-configuration-interval[interval] for running
the project_list cache warmer.
By default, if `cache.project_list.maxAge` is set, `interval` will be set to
half its value. If `cache.project_list.maxAge` is not set or `interval` is set
to `-1`, it is disabled.
[[cache.project_list.startTime]]cache.project_list.startTime::
+
The link:#schedule-configuration-startTime[start time] for running
the project_list cache warmer.
Default is 00:00 if the project_list cache warmer is enabled.
[[cachePruning]]
=== Section cachePruning
[[cachePruning.pruneOnStartup]]cachePruning.pruneOnStartup::
+
Whether to asynchronously prune all cache when starting Gerrit.
+
Defaults to `true`.
[[cachePruning.startTime]]cachePruning.startTime::
+
The link:#schedule-configuration-startTime[start time] for running
cache pruning.
+
Defaults to `01:00`.
[[cachePruning.interval]]cachePruning.interval::
+
The link:#schedule-configuration-interval[interval] for running
cache pruning.
+
Defaults to `1d`.
link:#schedule-configuration-examples[Schedule examples] can be found
in the link:#schedule-configuration[Schedule Configuration] section.
[[capability]]
=== Section capability
[[capability.administrateServer]]capability.administrateServer::
+
Names of groups of users that are allowed to exercise the
`administrateServer` capability, in addition to those listed in
All-Projects. Configuring this option can be a useful fail-safe
to recover a server in the event an administrator removed all
groups from the `administrateServer` capability, or to ensure that
specific groups always have administration capabilities.
+
----
[capability]
administrateServer = group Fail Safe Admins
----
+
The configuration file uses group names, not UUIDs. If a group is
renamed the gerrit.config file must be updated to reflect the new
name. If a group cannot be found for the configured name a warning
is logged and the server will continue normal startup.
+
If not specified (default), only the groups listed by All-Projects
may use the `administrateServer` capability.
[[capability.makeFirstUserAdmin]]capability.makeFirstUserAdmin::
+
Whether the first user that logs in to the Gerrit server should
automatically be added to the administrator group and hence get the
`administrateServer` capability assigned. This is useful to bootstrap
the link:config-accounts.html[account data].
+
Default is `true`.
[[change]]
=== Section change
[[change.allowBlame]]change.allowBlame::
+
Allow blame on side by side diff. If set to `false`, blame cannot be used.
+
Default is `true`.
[[change.cacheAutomerge]]change.cacheAutomerge::
+
When reviewing merge commits, the left-hand side shows the output of the result
of JGit's automatic merge algorithm. This option controls whether this output is
cached in the change repository, or if only the diff is cached in the persistent
diff caches (`"git_modified_files"`, `modified_files`, `"git_file_diff"`,
`"file_diff"`).
+
If `true`, automerge results are stored in the repository under
`refs/cache-automerge/*`; the results of diffing the change against its
automerge base are stored in the diff caches. If `false`, no extra data is
stored in the repository, only the diff caches. This can result in slight
performance improvements by reducing the number of refs in the repo.
+
Default is `true`.
[[change.commentSizeLimit]]change.commentSizeLimit::
+
Maximum allowed size in characters of a regular (non-robot) comment. Comments
which exceed this size will be rejected. Size computation is approximate and may
be off by roughly 1%. Common unit suffixes of 'k', 'm', or 'g' are supported.
The value must be positive.
+
The default limit is 16kiB.
[[change.topicLimit]]change.topicLimit::
+
Maximum allowed number of changes with the same topic. 0 or negative values
mean "unlimited".
+
By default 5,000.
[[change.cumulativeCommentSizeLimit]]change.cumulativeCommentSizeLimit::
+
Maximum allowed size in characters of all comments (including robot comments)
and change messages. Size computation is approximate and may be off by roughly
1%. Common unit suffixes of 'k', 'm', or 'g' are supported.
+
The default limit is 3MiB.
[[change.disablePrivateChanges]]change.disablePrivateChanges::
+
If set to `true`, users are not allowed to create private changes.
+
The default is `false`.
[[change.maxComments]]change.maxComments::
+
Maximum number of comments (regular plus robot) allowed per change. Additional
comments are rejected.
+
By default 5,000.
[[change.maxFiles]]change.maxFiles::
+
Maximum number of files allowed per change. Larger changes are rejected and must
be split up. For merge changes we are comparing against the auto-merge commit,
so we allow large merges, if they merge cleanly.
+
By default 100,000.
[[change.maxFileSizeDownload]]change.maxFileSizeDownload::
+
The link:rest-api-changes.html#get-content[GetContent] and
link:rest-api-changes.html#get-safe-content[DownloadContent] REST APIs will
refuse to load files larger than this limit (in bytes). 0 or negative values
mean "unlimited".
+
By default 0 (unlimited).
[[change.maxPatchSets]]change.maxPatchSets::
+
Maximum number of patch sets allowed per change. If this is insufficient,
recreate the change with a new Change-Id, then abandon the old change.
+
By default 1000.
[[change.maxUpdates]]change.maxUpdates::
+
Maximum number of updates to a change. Counts only updates to the main NoteDb
meta ref; draft comments, robot comments, stars, etc. do not count towards the
total.
+
Many NoteDb operations require walking the entire change meta ref and loading
its contents into memory, so changes with arbitrarily many updates may cause
high CPU usage, memory pressure, persistent cache bloat, and other problems.
+
The following operations are allowed even when a change is at the limit:
* Abandon
* Submit
* Submit by push with `%submit`
* Auto-close by pushing directly to the branch
* Fix with link:rest-api-changes.html#fix-input[`expect_merged_as`]
By default 1000.
[[change.mergeabilityComputationBehavior]]change.mergeabilityComputationBehavior::
+
This setting determines when Gerrit computes if a change is mergeable or not.
This computation is expensive, especially when the repository is large or when
there are many open changes.
+
This config can have the following states:
+
* `API_REF_UPDATED_AND_CHANGE_REINDEX`: Gerrit indexes `mergeability` enabling
the `is:mergeable` predicate in change search and allowing fast retrieval of
this bit in query responses. Gerrit will always serve `mergeable` in
link:rest-api-changes.html#change-info[ChangeInfo] objects.
Gerrit will reindex all open changes when the target ref advances (expensive).
* `REF_UPDATED_AND_CHANGE_REINDEX`: Gerrit indexes `mergeability` enabling the
`is:mergeable` predicate in change search and allowing fast retrieval of this
bit in query responses. Gerrit will never serve `mergeable` in
link:rest-api-changes.html#change-info[ChangeInfo]
objects. This state can be a final state for instances that only want to
optimize the read path, but not the write path for speed or serve as an
intermediary step for instances that want to optimize both and need to migrate
callers of their API.
Gerrit will reindex all open changes when the target ref advances (expensive).
* `NEVER`: Gerrit does not index `mergeable`, so `is:mergeable` is disabled as
query operator. Gerrit does not serve `mergeable` in
link:rest-api-changes.html#change-info[ChangeInfo].
NOTE: Gerrit would only render conflict changes section on change
screen if `API_REF_UPDATED_AND_CHANGE_REINDEX` value is set.
Default is `NEVER`.
[[change.conflictsPredicateEnabled]]change.conflictsPredicateEnabled::
+
This setting determines when Gerrit renders conflict changes section on change
screen and also supports `conflicts` predicate. This computation is expensive,
computing ConflictsPredicate has a runtime complexity of O(nˆ2) with n number
of open changes on a branch. When set to `false` GUI will silently ignore the
error message and leave the conflict changes section on change screen empty.
See also implications on rendering of conflict changes section in configuration
section:link:#change.mergeabilityComputationBehavior[change.mergeabilityComputationBehavior].
Default is `true`.
[[change.maxSubmittableAtOnce]]change.maxSubmittableAtOnce::
+
Maximum number of changes that can be chained together in the same repository
to be submitted at once.
+
Default is 32767.
[[change.move]]change.move::
+
Whether the link:rest-api-changes.html#move-change[Move Change] REST
endpoint is enabled.
+
The move change functionality has some corner cases with undesired side
effects. Hence administrators may decide to disable this functionality.
In particular, if a change that has dependencies on other changes is
moved to a new branch, and the moved change gets submitted to the new
branch, the changes on which the change depends are silently merged
into the new branch, although these changes have not been moved to that
branch (see details in
link:https://issues.gerritcodereview.com/issues/40009784[issue 40009784]).
+
By default `true`.
[[change.enableRobotComments]]change.enableRobotComments::
+
Are robot comments enabled in the Gerrit UI? This setting allows phasing out
robot comments.
+
By default `true`.
[[change.propagateSubmitRequirementErrors]]change.propagateSubmitRequirementErrors::
+
If set, requests that access the submit requirements of a change fail with an
HTTP 500 error if the change has a submit requirement with a non-parseable
expression that would otherwise result in an
link:config-submit-requirements#status-error[ERROR] status for the submit
requirement.
+
Submit requirement expressions can become non-parseable due to bypassing the
validation that normally happens when updating the project configuration in
the `refs/meta/config` branch, or due to bugs in Gerrit.
+
A special case are expressions that use plugin-provided predicates. If any
plugin that provides a predicate fails to load (e.g. due to an error in the
plugin) the predicate can no longer be resolved and expressions that are using
it can no longer be parsed. This is an error that requires the attention of the
team that operates Gerrit, but in order to get notified when this happens the
operation team would need to setup custom monitoring that observes whether
link:config-submit-requirements#status-error[ERROR] statuses are returned for
submit requirements. Instead this config option can be used to make
non-parseable submit requirement expressions cause HTTP 500 errors which
triggers the automatic alerting for errors that Gerrit operation teams usually
have in place. This allows the operation team to react quickly when this
happens.
+
The drawback of enabling this option is that it causes requests to fail rather
than handling parsing errors gracefully, which can make Gerrit for impacted
users unusable.
[[change.robotCommentSizeLimit]]change.robotCommentSizeLimit::
+
Maximum allowed size in characters of a robot comment. Robot comments which
exceed this size will be rejected on addition. Size computation is approximate
and may be off by roughly 1%. Common unit suffixes of 'k', 'm', or 'g' are
supported. Zero or negative values allow robot comments of unlimited size.
+
The default limit is 1MiB.
[[change.sendNewPatchsetEmails]]change.sendNewPatchsetEmails::
+
When `false`, emails will not be sent to owners, reviewers, and cc for
creating a new patchset unless they are project watchers or have starred
the change.
+
Default is `true`.
[[change.strictLabels]]change.strictLabels::
+
Reject invalid label votes: invalid labels or invalid values. This
configuration option is provided for backwards compatibility and may
be removed in future gerrit versions.
+
Default is `false`.
[[change.submitLabel]]change.submitLabel::
+
Label name for the submit button.
+
Default is "Submit".
[[change.submitLabelWithParents]]change.submitLabelWithParents::
+
Label name for the submit button if the change has parents which will
be submitted together with this change.
+
Default is "Submit including parents".
[[change.submitTooltip]]change.submitTooltip::
+
Tooltip for the submit button. Variables available for replacement
include `${patchSet}` for the current patch set number (1, 2, 3),
`${branch}` for the branch name ("master") and `${commit}` for the
abbreviated commit SHA-1 (`c9c0edb`).
+
Default is "Submit patch set ${patchSet} into ${branch}".
[[change.submitTooltipAncestors]]change.submitTooltipAncestors::
+
Tooltip for the submit button if there are ancestors which would
also be submitted by submitting the change. Additionally to the variables
as in link:#change.submitTooltip[change.submitTooltip], there is the
variable `${submitSize}` indicating the number of changes which are
submitted.
+
Default is "Submit all ${topicSize} changes of the same topic (${submitSize}
changes including ancestors and other changes related by topic)".
[[change.submitTopicLabel]]change.submitTopicLabel::
+
If `change.submitWholeTopic` is set and a change has a topic,
the label name for the submit button is given here instead of
the configuration `change.submitLabel`.
+
Defaults to "Submit whole topic"
[[change.submitTopicTooltip]]change.submitTopicTooltip::
+
If `change.submitWholeTopic` is configured to `true` and a change has a
topic, this configuration determines the tooltip for the submit button
instead of `change.submitTooltip`. The variable `${topicSize}` is available
for the number of changes in the same topic to be submitted. The number of
all changes to be submitted is in the variable `${submitSize}`.
+
Defaults to "Submit all ${topicSize} changes of the same topic
(${submitSize} changes including ancestors and other
changes related by topic)".
[[change.submitWholeTopic]]change.submitWholeTopic::
+
Determines if the submit button submits the whole topic instead of
just the current change.
+
Default is `false`.
[[change.updateDelay]]change.updateDelay::
+
How often in seconds the web interface should poll for updates to the
currently open change. The poller relies on the client's browser
cache to use If-Modified-Since and respect `304 Not Modified` HTTP
responses. This allows for fast polls, often under 8 milliseconds.
+
With a configured 30 second delay a server with 4900 active users will
typically need to dedicate 1 CPU to the update check. 4900 users
divided by an average delay of 30 seconds is 163 requests arriving per
second. If requests are served at ~6 ms response time, 1 CPU is
necessary to keep up with the update request traffic. On a smaller
user base of 500 active users, the default 30 second delay is only 17
requests per second and requires ~10% CPU.
+
If 0 the update polling is disabled.
+
Default is 5 minutes.
[[change.diff3ConflictView]]change.diff3ConflictView::
+
Use the diff3 formatter for merge, rebase and cherry-picking commits with conflicts.
+
For merge commits with diff3 when the conflicts are shown in the "Auto Merge" view,
the base section from the common parents will be shown as well.
This setting takes effect when generating the automerge, which happens on upload.
Also the setting takes effect when using rebase or cherry-picking in Gerrit Web UI.
Changing the setting leaves existing changes unaffected.
+
Default is `false`.
[[change.maxFileSizeDiff]]change.maxFileSizeDiff::
+
The threshold of file sizes in megabytes beyond which a
link:rest-api-changes.html#get-diff[file diff] request will fail.
+
If not set or set to zero, no limits are applied on file sizes.
[[change.skipCurrentRulesEvaluationOnClosedChanges]]change.skipCurrentRulesEvaluationOnClosedChanges::
+
If `false`, Gerrit will always take latest project configuration to
compute submit labels. This means that, closed changes (either merged
or abandoned) will be evaluated against the latest configuration which
may produce different results. Especially for merged changes, they may
look like they didn't meet the submit requirements.
+
When `true`, evaluation will be skipped and Gerrit will show the
exact status of submit labels when change was submitted. Post-review
votes will only be allowed on labels that were configured when change
was closed.
+
Default is `false`.
[[changeCleanup]]
=== Section changeCleanup
This section allows to configure change cleanups and schedules them to
run periodically.
[[changeCleanup.abandonAfter]]changeCleanup.abandonAfter::
+
Period of inactivity after which open changes should be abandoned
automatically.
+
By default `0`, never abandon open changes.
+
[WARNING] Auto-Abandoning changes may confuse/annoy users. When
enabling this, make sure to choose a reasonably large grace period and
inform users in advance.
+
The following suffixes are supported to define the time unit:
+
* `d, day, days`
* `w, week, weeks` (`1 week` is treated as `7 days`)
* `mon, month, months` (`1 month` is treated as `30 days`)
* `y, year, years` (`1 year` is treated as `365 days`)
[[changeCleanup.abandonIfMergeable]]changeCleanup.abandonIfMergeable::
+
Whether changes which are mergeable should be auto-abandoned. When set
to `false`, `-is:mergeable` is appended to the query used to find
the changes to auto-abandon.
+
By default `true`, meaning mergeable changes are auto-abandoned.
+
If
link:#change.mergeabilityComputationBehavior[`change.mergeabilityComputationBehavior`]
is set to `NEVER`, setting this option to `false` has no effect and it behaves
as though it were set to `true`.
[[changeCleanup.cleanupAccountPatchReview]]changeCleanup.cleanupAccountPatchReview::
+
Whether accountPatchReview data should be also removed when change
gets auto-abandoned.
+
By default `false`.
[[changeCleanup.abandonMessage]]changeCleanup.abandonMessage::
+
Change message that should be posted when a change is abandoned.
+
'${URL}' can be used as a placeholder for the Gerrit web URL.
+
By default "Auto-Abandoned due to inactivity, see
${URL}Documentation/user-change-cleanup.html#auto-abandon\n\n
If this change is still wanted it should be restored.".
[[changeCleanup.startTime]]changeCleanup.startTime::
+
The link:#schedule-configuration-startTime[start time] for running
change cleanups.
[[changeCleanup.interval]]changeCleanup.interval::
+
The link:#schedule-configuration-interval[interval] for running
change cleanups.
link:#schedule-configuration-examples[Schedule examples] can be found
in the link:#schedule-configuration[Schedule Configuration] section.
[[attentionSet]]
=== Section attentionSet
This section allows to configure readding of change owners and schedules them to
run periodically.
[[attentionSet.readdAfter]]attentionSet.readdAfter::
+
Period of inactivity after which open no-WIP/private changes should have change owner
added to attention-set automatically (if they are not already).
+
By default `0`, never readd change owner.
+
[WARNING] Auto-readding change owners may confuse/annoy users. When
enabling this, make sure to choose a reasonably large grace period and
inform users in advance.
+
The following suffixes are supported to define the time unit:
+
* `d, day, days`
* `w, week, weeks` (`1 week` is treated as `7 days`)
* `mon, month, months` (`1 month` is treated as `30 days`)
* `y, year, years` (`1 year` is treated as `365 days`)
[[attentionSet.readdMessage]]attentionSet.readdMessage::
+
Attention-set message that should be shown as reason when an change owner is readded.
+
'${URL}' can be used as a placeholder for the Gerrit web URL.
+
By default "Owner readded to attention-set due to inactivity, see
${URL}Documentation/user-attention-set.html#auto-readd-owner\n\n
If you do not want to be readded to the attention-set when the timer has counted down.
Set this change as WIP or private.".
[[attentionSet.startTime]]attentionSet.startTime::
+
The link:#schedule-configuration-startTime[start time] for running
readd owner to attention-set.
[[attentionSet.interval]]attentionSet.interval::
+
The link:#schedule-configuration-interval[interval] for running
readd owner to attention-set.
link:#schedule-configuration-examples[Schedule examples] can be found
in the link:#schedule-configuration[Schedule Configuration] section.
[[commentlink]]
=== Section commentlink
Comment links are find/replace strings applied to change descriptions,
patch comments, in-line code comments and approval category value descriptions
to turn set strings into hyperlinks. One common use is for linking to
bug-tracking systems.
In the following example configuration the 'changeid' comment link
will match typical Gerrit Change-Id values and create a hyperlink
to changes which reference it. The second configuration 'bugzilla'
will hyperlink terms such as 'bug 42' to an external bug tracker,
supplying the argument record number '42' for display.
Before matching is done the relevant contents are html-escaped. If 'match' needs
to contain `&`, `<`, `>`, `"` or `'`, replace them with `&amp;`, `&gt;`,
`&lt;`, `&quot;` and `&apos;` respectively.
commentlinks supports link:#reloadConfig[configuration reloads]. Though a
link:cmd-flush-caches.html[flush-caches] of "projects" is needed for the
commentlinks to be immediately available in the UI.
----
[commentlink "changeid"]
match = (I[0-9a-f]{8,40})
link = "/q/$1"
[commentlink "bugzilla"]
match = "(^|\\s)(bug\\s+#?)(\\d+)($|\\s)"
link = http://bugs.example.com/show_bug.cgi?id=$3
prefix = $1
suffix = $4
text = $2$3
----
Comment links can also be specified in `project.config` and sections in
children override those in parents.
[[commentlink.name.match]]commentlink.<name>.match::
+
A JavaScript regular expression to match positions to be replaced
with a hyperlink. Subexpressions of the matched string can be
stored using groups and accessed with `$'n'` syntax, where 'n'
is the group number, starting from 1.
+
The configuration file parser eats one level of backslashes, so the
character class `\s` requires `\\s` in the configuration file. The
parser also terminates the line at the first `#`, so a match
expression containing # must be wrapped in double quotes.
+
To match case insensitive strings, a character class with both the
upper and lower case character for each position must be used. For
example, to match the string `bug` in a case insensitive way the match
pattern `[bB][uU][gG]` needs to be used.
+
The commentlink.name.match regular expressions are applied to the raw,
unformatted and unescaped text form. Regex matching against HTML is not
supported. Comment link patterns that are written in this style should
be updated to match text formats.
+
A common pattern to match is `bug\\s+(\\d+)`.
+
In order to better control the visual presentation of the link `prefix`,
`suffix` and `text` is used. With the generated link html looking like:
`prefix<a ...>text</a>suffix`.
[[commentlink.name.link]]commentlink.<name>.link::
+
The URL to direct the user to whenever the regular expression is
matched. Groups in the match expression may be accessed as `$'n'`.
[[commentlink.name.prefix]]commentlink.<name>.prefix::
+
The text inserted before the link. Groups in the match expression may be
accessed as `$'n'`.
[[commentlink.name.suffix]]commentlink.<name>.suffix::
+
The text inserted after the link. Groups in the match expression may be
accessed as `$'n'`.
[[commentlink.name.text]]commentlink.<name>.text::
+
The text content of the link. Groups in the match expression may be
accessed as `$'n'`.
+
If not specified defaults to `$&` (the matched text).
[[commentlink.name.enabled]]commentlink.<name>.enabled::
+
Whether the comment link is enabled. A child project may override a
section in a parent or the site-wide config that is disabled by
specifying `enabled = true`.
+
By default, `true`.
+
Note that the names and contents of disabled sections are visible even
to anonymous users via the
link:rest-api-projects.html#get-config[REST API].
[[container]]
=== Section container
These settings are applied only if Gerrit is started as the container
process through Gerrit's 'gerrit.sh' rc.d compatible wrapper script.
[[container.heapLimit]]container.heapLimit::
+
Maximum heap size of the Java process running Gerrit, in bytes.
This property is translated into the '-Xmx' flag for the JVM.
+
Default is platform and JVM specific.
+
Common unit suffixes of 'k', 'm', or 'g' are supported.
[[container.javaHome]]container.javaHome::
+
Path of the JRE/JDK installation to run Gerrit with. If not set, the
Gerrit startup script will attempt to search your system and guess
a suitable JRE. Overrides the environment variable 'JAVA_HOME'.
[[container.javaOptions]]container.javaOptions::
+
Additional options to pass along to the Java runtime. May be specified
multiple times to configure multiple values. If multiple values are
configured, they are passed in order on the command line, separated by
spaces. These options are appended onto 'JAVA_OPTIONS'.
+
For example, it is possible to overwrite Gerrit's default log4j
configuration:
+
----
javaOptions = -Dlog4j.configuration=file:///home/gerrit/site/etc/log4j.properties
----
+
Gerrit built-in loggers are then ignored: error logger (`error_log` file),
link:#httpd.requestLog[httpd.requestLog] and
link:#sshd.requestLog[sshd.requestLog]. The
link:#log.jsonLogging[log.jsonLogging] and
link:#log.textLogging[log.textLogging] options are also ignored.
[[container.daemonOpt]]container.daemonOpt::
+
Additional options to pass to the daemon (e.g. '--enable-httpd'). If
multiple values are configured, they are passed in that order to the command
line, separated by spaces.
+
Execute `java -jar gerrit.war daemon --help` to see all possible
options.
[[container.replica]]container.replica::
+
Used on Gerrit replica installations. If set to `true` the Gerrit JVM is
called with the '--replica' switch, enabling replica mode. If no value is
set (or any other value), Gerrit defaults to primary mode enabling write
operations.
[[container.slave]]container.slave::
+
Backward compatibility for link:#container.replica[`container.replica`]
config setting.
[[container.startupTimeout]]container.startupTimeout::
+
The maximum time (in seconds) to wait for a gerrit.sh start command
to run a new Gerrit daemon successfully. If not set, defaults to
90 seconds.
[[container.shutdownTimeout]]container.shutdownTimeout::
+
The maximum time (in seconds) to wait for a gerrit.sh stop command.
This is added to the highest value between either 'sshd.gracefulStopTimeout'
or 'httpd.gracefulStopTimeout'. If not set, defaults to
30 seconds
[[container.user]]container.user::
+
Login name (or UID) of the operating system user the Gerrit JVM
will execute as. If not set, defaults to the user who launched
the 'gerrit.sh' wrapper script.
[[container.war]]container.war::
+
Path of the JAR file to start daemon execution with. This should
be the path of the local 'gerrit.war' archive. Overrides the
environment variable 'GERRIT_WAR'.
+
If not set, defaults to '$site_path/bin/gerrit.war', or to
'$HOME/gerrit.war'.
[[core]]
=== Section core
[NOTE]
The link:#jgitConfig[etc/jgit.config] file supports configuration of all JGit
options.
[[core.packedGitWindowSize]]core.packedGitWindowSize::
+
Number of bytes of a pack file to load into memory in a single
read operation. This is the "page size" of the JGit buffer cache,
used for all pack access operations. All disk IO occurs as single
window reads. Setting this too large may cause the process to load
more data than is required; setting this too small may increase
the frequency of `read()` system calls.
+
Default on JGit is 8 KiB on all platforms.
+
Common unit suffixes of 'k', 'm', or 'g' are supported.
[[core.packedGitLimit]]core.packedGitLimit::
+
Maximum number of bytes to load and cache in memory from pack files.
If JGit needs to access more than this many bytes it will unload less
frequently used windows to reclaim memory space within the process.
As this buffer must be shared with the rest of the JVM heap, it
should be a fraction of the total memory available.
+
Default on JGit is 10 MiB on all platforms.
+
Common unit suffixes of 'k', 'm', or 'g' are supported.
[[core.packedGitUseStrongRefs]]core.packedGitUseStrongRefs::
+
Set to `true` in order to use strong references to reference packfile
pages cached in the WindowCache. Otherwise SoftReferences are used.
If this option is set to `false`, the Java garbage collector will
flush the WindowCache to free memory if the used heap comes close to
the maximum heap size. This has the advantage that it can quickly
reclaim memory which was used by the WindowCache but comes at the
price that the previously cached pack file content needs to be again
copied from the file system cache to the Gerrit process.
Setting this option to `true` prevents flushing the WindowCache
which provides more predictable performance.
+
Default is `false`.
[[core.deltaBaseCaseLimit]]core.deltaBaseCacheLimit::
+
Maximum number of bytes to reserve for caching base objects
that multiple deltafied objects reference. By storing the entire
decompressed base object in a cache Git is able to avoid unpacking
and decompressing frequently used base objects multiple times.
+
Default on JGit is 10 MiB on all platforms. You probably do not
need to adjust this value.
+
Common unit suffixes of 'k', 'm', or 'g' are supported.
[[core.packedGitOpenFiles]]core.packedGitOpenFiles::
+
Maximum number of pack files to have open at once. A pack file
must be opened in order for any of its data to be available in
a cached window.
+
If you increase this to a larger setting you may need to also adjust
the ulimit on file descriptors for the host JVM, as Gerrit needs
additional file descriptors available for network sockets and other
repository data manipulation.
+
Default on JGit is 128 file descriptors on all platforms.
[[core.streamFileThreshold]]core.streamFileThreshold::
+
Largest object size, in bytes, that JGit will allocate as a
contiguous byte array. Any file revision larger than this threshold
will have to be streamed, typically requiring the use of temporary
files under '$GIT_DIR/objects' to implement pseudo-random access
during delta decompression.
+
Servers with very high traffic should set this to be larger than
the size of their common big files. For example a server managing
the Android platform typically has to deal with ~10-12 MiB XML
files, so `15 m` would be a reasonable setting in that environment.
Setting this too high may cause the JVM to run out of heap space
when handling very big binary files, such as device firmware or
CD-ROM ISO images.
+
Defaults to 25% of the available JVM heap, limited to 2g.
+
Common unit suffixes of 'k', 'm', or 'g' are supported.
[[core.packedGitMmap]]core.packedGitMmap::
+
When `true`, JGit will use `mmap()` rather than `malloc()+read()`
to load data from pack files. The use of mmap can be problematic
on some JVMs as the garbage collector must deduce that a memory
mapped segment is no longer in use before a call to `munmap()`
can be made by the JVM native code.
+
In server applications (such as Gerrit) that need to access many
pack files, setting this to `true` risks artificially running out
of virtual address space, as the garbage collector cannot reclaim
unused mapped spaces fast enough.
+
Default on JGit is `false`. Although potentially slower, it yields
much more predictable behavior.
[[core.asyncLoggingBufferSize]]core.asyncLoggingBufferSize::
+
Size of the buffer to store logging events for asynchronous logging.
Putting a larger value can protect threads from stalling when the
AsyncAppender threads are not fast enough to consume the logging events
from the buffer. It also protects from losing log entries in this case.
+
Default is 64 entries.
[[core.useRecursiveMerge]]core.useRecursiveMerge::
+
Use JGit's recursive merger for three-way merges. This only affects
projects that allow content merges.
+
As explained in this
link:http://codicesoftware.blogspot.com/2011/09/merge-recursive-strategy.html[
blog,role=external,window=_blank], the recursive merge produces better results if the two commits
that are merged have more than one common predecessor.
+
Default is `true`.
[[core.repositoryCacheCleanupDelay]]core.repositoryCacheCleanupDelay::
+
Delay between each periodic cleanup of expired repositories.
+
Values can be specified using standard time unit abbreviations (`ms`, `sec`,
`min`, etc.).
+
Set it to 0 in order to switch off cache expiration. If cache expiration is
switched off, the JVM can still evict cache entries when it is running low
on available heap memory.
+
Set it to -1 to automatically derive cleanup delay from
`core.repositoryCacheExpireAfter` (lowest value between 1/10 of
`core.repositoryCacheExpireAfter` and 10 minutes).
+
Default is -1.
[[core.repositoryCacheExpireAfter]]core.repositoryCacheExpireAfter::
+
Time an unused repository should expire and be evicted from the repository
cache.
+
Values can be specified using standard time unit abbreviations (`ms`, `sec`,
`min`, etc.).
+
Default is 1 hour.
[[core.usePerRequestRefCache]]core.usePerRequestRefCache::
+
Use a per request (currently per request thread) ref cache. The ref
cache uses JGit's SnapshottingRefDirectory to ensure that packed
refs are checked and potentially read at least once per request
(lazily) if needed. This helps reduce the overhead of checking if
the packed-refs file is outdated.
+
Default is `true`.
[[dashboard]]
=== Section dashboard
[[dashboard.submitRequirementColumns]]dashboard.submitRequirementColumns::
+
The list of submit requirement names that should be displayed as separate
columns in the dashboard.
[[download]]
=== Section download
----
[download]
command = checkout
command = cherry_pick
command = pull
command = format_patch
scheme = ssh
scheme = http
scheme = anon_http
scheme = anon_git
scheme = repo
hide = ssh
----
The download section configures the allowed download methods.
[[download.command]]download.command::
+
Commands that should be offered to download changes.
+
Multiple commands are supported:
+
* `checkout`
+
Command to fetch and checkout the patch set.
+
* `cherry_pick`
+
Command to fetch the patch set and to cherry-pick it onto the current
commit.
+
* `pull`
+
Command to pull the patch set.
+
* `format_patch`
+
Command to fetch the patch set and to feed it into the `format-patch`
command.
+
If `download.command` is not specified, all download commands are
offered.
[[download.scheme]]download.scheme::
+
Schemes that should be used to download changes.
+
Multiple schemes are supported:
+
* `http`
+
Authenticated HTTP download is allowed.
+
* `ssh`
+
Authenticated SSH download is allowed.
+
* `anon_http`
+
Anonymous HTTP download is allowed.
+
* `anon_git`
+
Anonymous Git download is allowed. This is not default, it is also
necessary to set <<gerrit.canonicalGitUrl,gerrit.canonicalGitUrl>>
variable.
+
* `repo`
+
Gerrit advertises patch set downloads with the `repo download`
command, assuming that all projects managed by this instance are
generally worked on with the
https://gerrit.googlesource.com/git-repo[repo multi-repository tool].
This is not default, as not all instances will deploy repo.
+
If `download.scheme` is not specified, SSH, HTTP and Anonymous HTTP
downloads are allowed.
[[download.hide]]download.hide::
+
Schemes that can be used to download changes, but will not be advertised
in the UI. This can be any scheme that can be configured in <<download.scheme>>.
+
This is mostly useful in a deprecation scenario during a time where using
a scheme is discouraged, but has to be supported until all clients have
migrated to use a different scheme.
+
By default, no scheme will be hidden in the UI.
[[download.checkForHiddenChangeRefs]]download.checkForHiddenChangeRefs::
+
Whether the download commands should be adapted when the change refs
are hidden.
+
Git has a configuration option to hide refs from the initial
advertisement (`uploadpack.hideRefs`). This option can be used to hide
the change refs from the client. As consequence fetching changes by
change ref does not work anymore. However by setting
`uploadpack.allowTipSha1InWant` to `true` fetching changes by commit ID
is possible. If `download.checkForHiddenChangeRefs` is set to `true`
the git download commands use the commit ID instead of the change ref
when a project is configured like this.
+
Example git configuration on a project:
+
----
[uploadpack]
hideRefs = refs/changes/
hideRefs = refs/cache-automerge/
allowTipSha1InWant = true
----
+
By default `false`.
[[download.archive]]download.archive::
+
Specifies which archive formats, if any, should be offered on the change
screen and supported for `git-upload-archive` operation:
+
----
[download]
archive = tar
archive = tbz2
archive = tgz
archive = txz
archive = zip
----
If `download.archive` is not specified defaults to all archive
commands. Set to `off` or empty string to disable.
Zip is not supported because it may be interpreted by a Java plugin as a
valid JAR file, whose code would have access to cookies on the domain.
For this reason `zip` format is always excluded from formats offered
through the `Download` drop down or accessible in the REST API.
[[gc]]
=== Section gc
This section allows to configure the git garbage collection and schedules it
to run periodically. It will be triggered and executed sequentially for all
projects.
[[gc.aggressive]]gc.aggressive::
+
Determines if scheduled garbage collections and garbage collections triggered
through Web-UI should run in aggressive mode or not. Aggressive garbage
collections are more expensive but may lead to significantly smaller
repositories.
+
Valid values are "`true`" and "`false`," default is "`false`".
[[gc.startTime]]gc.startTime::
+
The link:#schedule-configuration-startTime[start time] for running the
git garbage collection.
[[gc.interval]]gc.interval::
+
The link:#schedule-configuration-interval[interval] for running the
git garbage collection.
link:#schedule-configuration-examples[Schedule examples] can be found
in the link:#schedule-configuration[Schedule Configuration] section.
[[gerrit]]
=== Section gerrit
[[gerrit.basePath]]gerrit.basePath::
+
Local filesystem directory holding all Git repositories that
Gerrit knows about and can process changes for. A project
entity in Gerrit maps to a local Git repository by creating
the path string `"${basePath}/${project_name}.git"`.
+
If relative, the path is resolved relative to `'$site_path'`.
[[gerrit.allProjects]]gerrit.allProjects::
+
Name of the permissions-only project defining global server
access controls and settings. These are inherited into every
other project managed by the running server. The name is
relative to `gerrit.basePath`.
+
The link:#cache_names[persisted_projects cache] must be
flushed after this setting is changed.
+
Defaults to `All-Projects` if not set.
[[gerrit.defaultBranch]]gerrit.defaultBranch::
+
Name of the link:project-configuration.html#default-branch[default branch]
to use on the project creation, if no other branches were specified in the input.
+
Defaults to `refs/heads/master` if not set.
[[gerrit.allUsers]]gerrit.allUsers::
+
Name of the project in which meta data of all users is stored.
The name is relative to `gerrit.basePath`.
+
Defaults to `All-Users` if not set.
[[gerrit.canonicalWebUrl]]gerrit.canonicalWebUrl::
+
The default URL for Gerrit to be accessed through.
+
Typically this would be set to something like "http://review.example.com/"
or "http://example.com:8080/gerrit/" so Gerrit can output links that point
back to itself.
+
Setting this is highly recommended, as it is necessary for the upload
code invoked by "git push" or "repo upload" to output hyperlinks
to the newly uploaded changes.
[[gerrit.canonicalGitUrl]]gerrit.canonicalGitUrl::
+
Optional base URL for repositories available over the anonymous git
protocol. For example, set this to `git://mirror.example.com/base/`
to have Gerrit display patch set download URLs in the UI. Gerrit
automatically appends the project name onto the end of the URL.
+
By default unset, as the git daemon must be configured externally
by the system administrator, and might not even be running on the
same host as Gerrit.
[[gerrit.docUrl]]gerrit.docUrl::
+
Optional base URL for documentation, under which one can find
"index.html", "rest-api.html", etc. Used as the base for the fixed set
of links in the "Documentation" tab. A slash is implicitly appended.
(For finer control over the top menu, consider writing a
link:dev-plugins.html#top-menu-extensions[plugin].)
+
If unset or empty, the documentation tab will only be shown if
`/Documentation/index.html` can be reached by the browser at app load
time.
[[gerrit.editGpgKeys]]gerrit.editGpgKeys::
+
If enabled and server-side signed push validation is also
link:#receive.enableSignedPush[enabled], enable the
link:rest-api-accounts.html#list-gpg-keys[REST API endpoints] and web UI
for editing GPG keys. If disabled, GPG keys can only be added by
administrators with direct git access to All-Users.
+
Defaults to `true`.
[[gerrit.installCommitMsgHookCommand]]gerrit.installCommitMsgHookCommand::
+
Optional command to install the `commit-msg` hook. Typically of the
form:
+
----
fetch-cmd some://url/to/commit-msg .git/hooks/commit-msg ; chmod +x .git/hooks/commit-msg
----
+
By default unset; falls back to using scp from the canonical SSH host,
or curl from the canonical HTTP URL for the server. Only necessary if a
proxy or other server/network configuration prevents clients from
fetching from the default location.
[[gerrit.gitHttpUrl]]gerrit.gitHttpUrl::
+
Optional base URL for repositories available over the HTTP
protocol. For example, set this to `http://mirror.example.com/base/`
to have Gerrit display URLs from this server, rather than itself.
+
By default unset, as the HTTP daemon must be configured externally
by the system administrator, and might not even be running on the
same host as Gerrit.
[[gerrit.installBatchModule]]gerrit.installBatchModule::
+
Repeatable list of class name of additional Guice modules to load as
override to the batchInjector's modules during the init phases.
Classes are resolved using the primary Gerrit class loader, hence the
class needs to be either declared in Gerrit or an additional JAR
located under the `/lib` directory.
+
By default unset.
[[gerrit.installDbModule]]gerrit.installDbModule::
+
Repeatable list of class name of additional Guice modules to load at
Gerrit startup as part of the dbInjector.
Classes are resolved using the primary Gerrit class loader, hence the
class needs to be either declared in Gerrit or an additional JAR
located under the `/lib` directory.
+
By default unset.
[[gerrit.installIndexModule]]gerrit.installIndexModule::
+
Class name of the Guice modules to load as alternate implementation
for the Gerrit indexes backend.
Classes are resolved using the primary Gerrit class loader, hence the
class needs to be either declared in Gerrit or an additional JAR
located under the `/lib` directory.
+
NOTE: The `gerrit.installIndexModule` has precedence over the
`index.type`.
+
By default unset.
+
Example:
----
[gerrit]
installIndexModule = com.google.gerrit.elasticsearch.ElasticIndexModule
----
[[gerrit.installModule]]gerrit.installModule::
+
Repeatable list of class name of additional Guice modules to load at
Gerrit startup as part of the sysInjector.
Classes are resolved using the primary Gerrit class loader, hence the
class needs to be either declared in Gerrit or an additional JAR
located under the `/lib` directory.
+
By default unset.
+
Example:
----
[gerrit]
installModule = com.googlesource.gerrit.libmodule.MyModule
installModule = com.example.abc.OurSpecialSauceModule
installDbModule = com.example.def.OurCustomProvider
installBatchModule = com.example.ghi.CustomBatchInitModule
----
[[gerrit.listProjectsFromIndex]]gerrit.listProjectsFromIndex::
+
Enable rendering of project list from the secondary index instead
of purely relying on the in-memory cache.
+
By default `false`.
+
[NOTE]
The in-memory cache (set to `false`) rendering provides an **unlimited list** as a result
of the list project API, causing the full list of projects to be
returned as a result of the link:rest-api-projects.html[/projects/] REST API
or the link:cmd-ls-projects.html[gerrit ls-projects] SSH command.
When the rendering from the secondary index (set to `true`),
the **list is limited** by the global capability
link:access-control.html#capability_queryLimit[queryLimit]
which is defaulted to 500 entries.
[[gerrit.projectStatePredicateEnabled]]
+
Indicates whether the link:rest-api-projects.html[/projects/] REST API endpoint
supports filtering projects by state. The value is exposed in
link:rest-api-config.html[/config/server/info] REST API endpoint.
+
Instances having a custom implementation of ProjectQueryBuilder might have
disabled the `state` predicate in which case the setting should be set to
`false`.
+
Default: `true`.
[[gerrit.primaryWeblinkName]]gerrit.primaryWeblinkName::
+
Name of the link:dev-plugins.html#links-to-external-tools[Weblink] that should
be chosen in cases where only one Weblink can be used in the UI, for example in
inline links.
+
By default unset, meaning that the UI is responsible for trying to identify
a weblink to be used in these cases, most likely weblinks that links to code
browsers with known integrations with Gerrit (like Gitiles and Gitweb).
+
Example:
----
[gerrit]
primaryWeblinkName = gitiles
----
[[gerrit.reportBugUrl]]gerrit.reportBugUrl::
+
URL to direct users to when they need to report a bug.
+
By default unset, meaning no bug report URL will be displayed. Administrators
should set this to the URL of their issue tracker, if necessary.
[[gerrit.enablePeerIPInReflogRecord]]gerrit.enablePeerIPInReflogRecord::
Record actual peer IP address in ref log entry for identified user.
Defaults to `false`.
[[gerrit.secureStoreClass]]gerrit.secureStoreClass::
+
Use the secure store implementation from a specified class.
+
If specified, must be the fully qualified class name of a class that implements
the `com.google.gerrit.server.securestore.SecureStore` interface, and the jar
file containing the class must be placed in the `$site_path/lib` folder.
+
If not specified, the default no-op implementation is used.
[[gerrit.canLoadInIFrame]]gerrit.canLoadInIFrame::
+
For security reasons Gerrit will always jump out of iframe.
Setting this option to `true` will prevent this behavior.
+
By default `false`.
[[gerrit.xframeOption]]gerrit.xframeOption::
+
Add link:https://tools.ietf.org/html/rfc7034[`X-Frame-Options`] header to all HTTP
responses. The `X-Frame-Options` HTTP response header can be used to indicate
whether or not a browser should be allowed to render a page in a
`<frame>`, `<iframe>`, `<embed>` or `<object>`.
+
Available values:
+
1. ALLOW - The page can be displayed in a frame.
2. SAMEORIGIN - The page can only be displayed in a frame on the same origin as the page itself.
+
If link:#gerrit.canLoadInIFrame is set to `false` this option is ignored and the
`X-Frame-Options` header is always set to `DENY`.
Setting this option to `ALLOW` will cause the `X-Frame-Options` header to be omitted
the the page can be displayed in a frame.
+
By default SAMEORIGIN.
[[gerrit.cdnPath]]gerrit.cdnPath::
+
Path prefix for Gerrit's static resources if using a CDN.
[[gerrit.faviconPath]]gerrit.faviconPath::
+
Path for Gerrit's favicon after link:#gerrit.canonicalWebUrl[default URL],
including icon name and extension (.ico should be used).
[[gerrit.instanceId]]gerrit.instanceId::
+
Optional identifier for this Gerrit instance.
Used to identify a specific instance within a group of Gerrit instances with the
same `serverId` (i.e.: a Gerrit cluster).
Unlike `instanceName` this value is not available in the email templates.
The instance ID can also be configured by setting the Java system property
`gerrit.instanceId` on startup. This will override the configuration in the
gerrit.config.
[[gerrit.instanceName]]gerrit.instanceName::
+
Short identifier for this Gerrit instance.
A good name should be short but precise enough so that users can identify the instance among others.
+
Defaults to the full hostname of the Gerrit server.
[[gerrit.experimentalRollingUpgrade]]gerrit.experimentalRollingUpgrade::
+
Enable Gerrit rolling upgrade to the next version.
For example if Gerrit v3.2 is version N (All-Projects:refs/meta/version=183)
then its next version N+1 is v3.3 (All-Projects:refs/meta/version=184).
Allow Gerrit to start even if the underlying schema version has been bumped to
the next Gerrit version.
+
Set to `true` if Gerrit is installed in
[high-availability configuration](https://gerrit.googlesource.com/plugins/high-availability/+/refs/heads/master/README.md)
during the rolling upgrade to the next version.
+
By default `false`.
+
The rolling upgrade process, at high level, assumes that Gerrit is installed
on two or more nodes sharing the repositories over NFS. The upgrade is composed
of the following steps:
+
1. Set gerrit.experimentalRollingUpgrade to `true` on all Gerrit masters
2. Set the first master unhealthy
3. Shutdown the first master and [upgrade](install.html#init) to the next version
4. Startup the first master, wait for the online reindex to complete (where applicable)
5. Verify the the first master upgrade is successful and online reindex is complete
6. Set the first master healthy
7. Repeat steps 2. to 6. for all the other Gerrit nodes
+
[WARNING]
Rolling upgrade may or may not be possible depending on the changes introduced
by the target version of the upgrade. Refer to the release notes and check whether
the rolling upgrade is possible or not and the associated constraints.
[[gerrit.importedServerId]]gerrit.importedServerId::
+
ServerId of the repositories imported from other Gerrit servers. Changes coming
associated with the imported serverIds are indexed and displayed in the UI
but they are not searchable by `changeNumber` therefore the
`index.cacheQueryResultsByChangeNum` must also be set to `false`.
Imported changes are still discoverable in any other ways, for example:
project:someproject branch:main changeId:I78a7add1fe2597cad788c833d8f771f09b54cf33
+
Specify multiple `gerrit.importedServerId` for allowing the import from multiple
Gerrit servers with different serverIds.
+
[NOTE]
The account-ids referenced in the imported changes are used for looking up the
associated account-id locally, using the `imported:` external-id.
Example: the account-id 1000 from the imported server-id 59a4964e-6376-4ed9-beef
will be looked up in the local accounts using the `imported:1000@59a4964e-6376-4ed9-beef`
external-id.
+
If this value is not set, all changes imported from other Gerrit servers will be
ignored.
+
By default empty.
[[gerrit.requireChangeForConfigUpdate]]gerrit.requireChangeForConfigUpdate::
+
If true, all attempts to update a project config directly using any REST API are rejected.
Instead, users should always use APIs which create a config change (for review).
+
By default `false`.
[[gerrit.serverId]]gerrit.serverId::
+
Used by NoteDb to, amongst other things, identify author identities from
per-server specific account IDs.
+
If this value is not set on startup it is automatically set to a random UUID.
+
[NOTE]
If this value doesn't match the serverId used when creating an already existing
NoteDb, Gerrit will not be able to use that instance of NoteDb. The serverId
used to create the NoteDb will show in the resulting exception message in case
the value differs.
[[gitweb]]
=== Section gitweb
Gerrit can forward requests to either an internally managed gitweb
(which allows Gerrit to enforce some access controls), or to an
externally managed gitweb (where the web server manages access).
See also link:config-gitweb.html[Gitweb Integration].
[[gitweb.cgi]]gitweb.cgi::
+
Path to the locally installed `gitweb.cgi` executable. This CGI will
be called by Gerrit Code Review when the URL `/gitweb` is accessed.
Project level access controls are enforced prior to calling the CGI.
+
Defaults to `/usr/lib/cgi-bin/gitweb.cgi` if `gitweb.url` is not set.
[[gitweb.url]]gitweb.url::
+
Optional URL of an affiliated gitweb service. Defines the
web location where a `gitweb.cgi` is installed to browse
`gerrit.basePath` and the repositories it contains.
+
Gerrit appends any necessary query arguments onto the end of this URL.
For example, `?p=$project.git;h=$commit`.
[[gitweb.type]]gitweb.type::
+
Optional type of affiliated gitweb service. This allows using
alternatives to gitweb, such as cgit.
+
Valid values are `gitweb`, `cgit`, `disabled` or `custom`.
+
If not set, or set to `disabled`, there is no gitweb hyperlinking
support.
[[gitweb.revision]]gitweb.revision::
+
Optional pattern to use for constructing the gitweb URL when pointing
at a specific commit when `gitweb.type` is set to `custom`.
+
Valid replacements are `${project}` for the project name in Gerrit
and `${commit}` for the SHA-1 hash for the commit.
[[gitweb.project]]gitweb.project::
+
Optional pattern to use for constructing the gitweb URL when pointing
at a specific project when `gitweb.type` is set to `custom`.
+
Valid replacements are `${project}` for the project name in Gerrit.
[[gitweb.branch]]gitweb.branch::
+
Optional pattern to use for constructing the gitweb URL when pointing
at a specific branch when `gitweb.type` is set to `custom`.
+
Valid replacements are `${project}` for the project name in Gerrit
and `${branch}` for the name of the branch.
[[gitweb.tag]]gitweb.tag::
+
Optional pattern to use for constructing the gitweb URL when pointing
at a specific tag when `gitweb.type` is set to `custom`.
+
Valid replacements are `${project}` for the project name in Gerrit
and `${tag}` for the name of the tag.
[[gitweb.roottree]]gitweb.roottree::
+
Optional pattern to use for constructing the gitweb URL when pointing
at the contents of the root tree in a specific commit when `gitweb.type`
is set to `custom`.
+
Valid replacements are `${project}` for the project name in Gerrit
and `${commit}` for the SHA-1 hash for the commit.
[[gitweb.file]]gitweb.file::
+
Optional pattern to use for constructing the gitweb URL when pointing
at the contents of a file in a specific commit when `gitweb.type` is
set to `custom`.
+
Valid replacements are `${project}` for the project name in Gerrit,
`${file}` for the file name, `${hash}` for the SHA-1 hash for the commit,
and `${commit}` for the change ref or SHA-1 of the commit if no base
patch set.
[[gitweb.filehistory]]gitweb.filehistory::
+
Optional pattern to use for constructing the gitweb URL when pointing
at the history of a file in a specific branch when when `gitweb.type`
is set to `custom`.
+
Valid replacements are `${project}` for the project name in Gerrit,
`${file}` for the file name and `${branch}` for the name of the
branch.
[[gitweb.linkname]]gitweb.linkname::
+
Optional setting for modifying the link name presented to the user
in the Gerrit web-UI.
+
The default linkname for custom type is `gitweb`.
[[gitweb.pathSeparator]]gitweb.pathSeparator::
+
Optional character to substitute the standard path separator (slash) in
project names and branch names.
+
By default, Gerrit will use hexadecimal encoding for slashes in project and
branch names. Some web servers, such as Tomcat, reject this hexadecimal
encoding in the URL.
+
Some alternative gitweb services, such as link:http://gitblit.com[Gitblit,role=external,window=_blank],
allow using an alternative path separator character. In Gitblit, this can be
configured through the property link:http://gitblit.com/properties.html[web.forwardSlashCharacter,role=external,window=_blank].
In Gerrit, the alternative path separator can be configured correspondingly
using the property `gitweb.pathSeparator`.
+
Valid values are the characters `*`, `(` and `)`.
[[gitweb.urlEncode]]gitweb.urlEncode::
+
Whether or not Gerrit should encode the generated viewer URL.
+
Gerrit composes the viewer URL using information about the project, branch, file
or commit of the target object to be displayed. Typically viewers such as CGit
and gitweb do need those parts to be encoded, including the `/` in project's name,
for being correctly parsed.
However other viewers could instead require an unencoded URL (e.g. GitHub web
based viewer).
+
Valid values are `true` and `false`. The default is `true`.
[[groups]]
=== Section groups
[[groups.auditLog.ignoreRecordsFromUnidentifiedUsers]]groups.auditLog.ignoreRecordsFromUnidentifiedUsers::
+
Controls whether AuditLogReader should ignore commits created by unidentified users.
If `true`, then AuditLogReader ignores commits in the refs/groups/* made by unidentified users (i.e.
when the author of a commit can't be parsed as account id).
+
The current version of Gerrit writes identified users as authors for new refs/groups/* commits.
However, some old versions used a server identity as the author (e.g. "Gerrit Code Review
<server@googlesource.com>") for such commits. Such string can't be converted to account id but
usually the commit shouldn't be ignored.
+
By default, `false`.
+
Setting it to `true` may lead to some unexpected results in audit log and must be set carefully.
[[groups.includeExternalUsersInRegisteredUsersGroup]]groups.includeExternalUsersInRegisteredUsersGroup::
+
Controls whether external users (these are users we have sufficient
knowledge about but who don't yet have a Gerrit account) are considered
to be members of the `REGISTERED_USERS` group.
+
This setting only makes sense if you run custom code (e.g. from a plugin
or a custom authentication backend). By default, Gerrit core always requires
users to register and doesn't use external users.
+
By default, `true`.
[[groups.newGroupsVisibleToAll]]groups.newGroupsVisibleToAll::
+
Controls whether newly created groups should be by default visible to
all registered users.
+
By default, `false`.
[[groups.uuid.name]]groups.<uuid>.name::
+
Display name for group with the given UUID.
+
This option is only supported for system groups (scheme 'global').
+
E.g. this parameter can be used to configure another name for the
`Anonymous Users` group:
+
----
[groups "global:Anonymous-Users"]
name = All Users
----
+
When setting this parameter it should be verified that there is no
existing group with the same name (case-insensitive). Configuring an
ambiguous name makes Gerrit fail on startup. Once set Gerrit ensures
that it is not possible to create a group with this name. Gerrit also
keeps the default name reserved so that it cannot be used for new
groups either. This means there is no danger of ambiguous group names
when this parameter is removed and the system group uses the default
name again.
[[groups.relevantGroup]]groups.relevantGroup::
+
UUID of an external group that should always be considered as relevant
when checking whether an account is visible.
+
This setting is only relevant for external group backends and only if
the link:#accounts.visibility[account visibility] is set to
`SAME_GROUP` or `VISIBLE_GROUP`.
+
If the link:#accounts.visibility[account visibility] is set to
`SAME_GROUP` or `VISIBLE_GROUP` users should see all accounts that are
a member of a group that contains themselves or that is visible to
them. Checking this would require getting all groups of the current
user and all groups of the accounts for which the visibility is being
checked, but since getting all groups that a user is a member of is
expensive for external group backends Gerrit doesn't query these groups
but instead guesses the relevant groups. Guessing relevant groups
limits the inspected groups to all groups that are mentioned in the
ACLs of the projects that are currently cached (i.e. all groups that
are listed in the link:config-project-config.html#file-groups[groups]
files of the cached projects). This is not very reliable since it
depends on which groups are mentioned in the ACLs and which projects
are currently cached. To make this more reliable this configuration
parameter allows to configure external groups that should always be
considered as relevant.
+
As said this setting is only relevant for external group backends. In
Gerrit core this is only the LDAP backend, but it may apply to further
group backends that are added by plugins.
+
This parameter may be added multiple times to specify multiple relevant
groups.
[[has-operand-alias]]
=== Section has operand alias
'has' operand aliasing allows global aliases to be defined for query
'has' operands. Currently only change queries are supported. The alias
name is the git config key name, and the 'has' operand being aliased
is the git config value.
For example:
----
[has-operand-alias "change"]
oldtopic = topic
----
This section is particularly useful to alias 'has' operands (which may
be long and clunky as they include a plugin name in them) to shorter
operands without the plugin name. Admins should take care to choose
shorter operands that are unique and unlikely to conflict in the future.
Aliases are resolved dynamically at invocation time to the currently
loaded version of plugins. If a referenced plugin is not loaded, or
does not define the command, "unsupported operand" is returned to the
user.
Aliases will override existing 'has' operands. In case of multiple
aliases with same name, the last one defined will be used.
When the target of an alias does not exist, the 'has' operand with the
name of the alias will be used (if present). This enables an admin to
configure the system to override a core 'has' operand with an operand
provided by a plugin when present and otherwise fall back to the 'has'
operand provided by core.
[[http]]
=== Section http
[[http.proxy]]http.proxy::
+
URL of the proxy server when making outgoing HTTP
connections for OpenID login transactions. Syntax
should be `http://`'hostname'`:`'port'.
[[http.proxyUsername]]http.proxyUsername::
+
Optional username to authenticate to the HTTP proxy with.
This property is honored only if the username does not
appear in the http.proxy property above.
[[http.proxyPassword]]http.proxyPassword::
+
Optional password to authenticate to the HTTP proxy with.
This property is honored only if the password does not
appear in the http.proxy property above.
[[http.addUserAsRequestAttribute]]http.addUserAsRequestAttribute::
+
If `true`, 'User' attribute will be added to the request attributes so it
can be accessed outside the request scope (will be set to username or id
if username not configured).
+
This attribute can be used by the servlet container to log user in the
http access log.
+
When running the embedded servlet container, this attribute is used to
print user in the httpd_log.
+
* `%{User}r`
+
Pattern to print user in Tomcat AccessLog.
+
Default value is `true`.
[[http.addUserAsResponseHeader]]http.addUserAsResponseHeader::
+
If `true`, the header 'User' will be added to the list of response headers so it
can be accessed from a reverse proxy for logging purposes.
+
Default value is `false`.
[[httpd]]
=== Section httpd
The httpd section configures the embedded servlet container.
[[httpd.listenUrl]]httpd.listenUrl::
+
Configuration for the listening sockets of the internal HTTP daemon.
Each entry of `listenUrl` combines the following options for a
listening socket: protocol, network address, port and context path.
+
_Protocol_ can be either `http://`, `https://`, `proxy-http://` or
`proxy-https://`. The latter two are special forms of `http://` with
awareness of a reverse proxy (see below). _Network address_ selects
the interface and/or scope of the listening socket. For notes
examples, see below. _Port_ is the TCP port number and is optional
(default value depends on the protocol). _Context path_ is the
optional "base URI" for the Gerrit Code Review as application to
serve on.
+
**Protocol** schemes:
+
* `http://`
+
Plain-text HTTP protocol. If port is not supplied, defaults to 80,
the standard HTTP port.
+
* `https://`
+
SSL encrypted HTTP protocol. If port is not supplied, defaults to
443, the standard HTTPS port.
+
For configuration of the certificate and private key, see
<<httpd.sslKeyStore,httpd.sslKeyStore>>.
+
[NOTE]
SSL/TLS configuration capabilities of Gerrit internal HTTP daemon
are very limited. Externally facing production sites are strongly
encouraged to use a reverse proxy configuration to handle SSL/TLS
and use a `proxy-https://` scheme here (below) for security and
performance reasons.
+
* `proxy-http://`
+
Plain-text HTTP relayed from a reverse proxy. If port is not
supplied, defaults to 8080.
+
Like `http://`, but additional header parsing features are
enabled to honor `X-Forwarded-For`, `X-Forwarded-Host` and
`X-Forwarded-Server`. These headers are typically set by Apache's
link:https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers[mod_proxy,role=external,window=_blank].
+
[NOTE]
--
For secruity reasons, make sure to only allow connections from a
trusted reverse proxy in your network, as clients could otherwise
easily spoof these headers and thus spoof their originating IP
address effectively. If the reverse proxy is running on the same
machine as Gerrit daemon, the use of a _loopback_ network address
to bind to (see below) is strongly recommended to mitigate this.
If not using Apache's mod_proxy, validate that your reverse proxy
sets these headers on all requests. If not, either configure it to
sanitize them from the origin, or use the `http://` scheme instead.
--
+
* `proxy-https://`
+
Plain-text HTTP relayed from a reverse proxy that has already
handled the SSL encryption/decryption. If port is not supplied,
defaults to 8080.
+
Behaves exactly like `proxy-http://`, but also sets the scheme to
assume `https://` is the proper URL back to the server.
+
--
**Network address** forms:
* Loopback (localhost): `127.0.0.1` (IPv4) or `[::1]` (IPv6).
* All (unspecified): `0.0.0.0` (IPv4), `[::]` (IPv6) or `*`
(IPv4 and IPv6)
* Interface IP address, e.g. `1.2.3.4` (IPv4) or
`[2001:db8::a00:20ff:fea7:ccea]` (IPv6)
* Hostname, resolved at startup time to an address.
**Context path** is the local part of the URL to be used to access
Gerrit on ('base URL'). E.g. `/gerrit/` to serve Gerrit on that URI
as base. If set, consider to align this with the
<<gerrit.canonicalWebUrl,gerrit.canonicalWebUrl>> setting. Correct
settings may depend on the reverse proxy configuration as well. By
default, this is `/` so that Gerrit serves requests on the root.
If multiple values are supplied, the daemon will listen on all
of them.
Examples:
----
[httpd]
listenUrl = proxy-https://127.0.0.1:9999/gerrit/
[gerrit]
# Reverse proxy is configured to serve with SSL/TLS on
# example.com and to relay requests on /gerrit/ onto
# http://127.0.0.1:9999/gerrit/
canonicalWebUrl = https://example.com/gerrit/
----
----
[httpd]
# Listen on specific external interface with plaintext
# HTTP on IPv6.
listenUrl = http://[2001:db8::a00:20ff:fea7:ccea]
# Also listen on specific internal interface for use with
# reverse proxy run on another host.
listenUrl = proxy-https://192.168.100.123
----
See also the page on link:config-reverseproxy.html[reverse proxy]
configuration.
By default, `\http://*:8080`.
--
[[httpd.reuseAddress]]httpd.reuseAddress::
+
If `true`, permits the daemon to bind to the port even if the port
is already in use. If `false`, the daemon ensures the port is not
in use before starting. Busy sites may need to set this to true
to permit fast restarts.
+
By default, `true`.
[[httpd.gracefulStopTimeout]]httpd.gracefulStopTimeout::
+
Set a graceful stop time. If set, the daemon ensures that all incoming
calls are preserved for a maximum period of time, before starting
the graceful shutdown process. Sites behind a workload balancer such as
HAProxy would need this to be set for avoiding serving errors during
rolling restarts.
+
Values should use common unit suffixes to express their setting:
+
* s, sec, second, seconds
* m, min, minute, minutes
+
By default, 0 seconds (immediate shutdown).
[[httpd.inheritChannel]]httpd.inheritChannel::
+
If `true`, permits the daemon to inherit its server socket channel
from fd0/1(stdin/stdout). When set to `true`, the server can be socket
activated via systemd or xinetd.
+
By default, `false`.
[[httpd.requestHeaderSize]]httpd.requestHeaderSize::
+
Size, in bytes, of the buffer used to parse the HTTP headers of an
incoming HTTP request. The entire request headers, including any
cookies sent by the browser, must fit within this buffer, otherwise
the server aborts with the response '413 Request Entity Too Large'.
+
One buffer of this size is allocated per active connection.
Allocating a buffer that is too large wastes memory that cannot be
reclaimed, allocating a buffer that is too small may cause unexpected
errors caused by very long Referer URLs or large cookie values.
+
By default, 16384 (16 K), which is sufficient for most OpenID and
other web-based single-sign-on integrations.
[[httpd.sslCrl]]httpd.sslCrl::
+
Path of the certificate revocation list file in PEM format. This
crl file is optional, and available for CLIENT_SSL_CERT_LDAP
authentication.
+
To create and view a crl using openssl:
+
----
openssl ca -gencrl -out crl.pem
openssl crl -in crl.pem -text
----
+
If not absolute, the path is resolved relative to `$site_path`.
+
By default, `$site_path/etc/crl.pem`.
[[httpd.sslKeyStore]]httpd.sslKeyStore::
+
Path of the Java keystore containing the server's SSL certificate
and private key. This keystore is required for `https://` in URL.
+
To create a self-signed certificate for simple internal usage:
+
----
keytool -keystore keystore -alias jetty -genkey -keyalg RSA
chmod 600 keystore
----
+
If not absolute, the path is resolved relative to `$site_path`.
+
By default, `$site_path/etc/keystore`.
[[httpd.sslKeyPassword]]httpd.sslKeyPassword::
+
Password used to decrypt the private portion of the sslKeyStore.
Java keystores require a password, even if the administrator
doesn't want to enable one.
+
If set to the empty string the embedded server will prompt for the
password during startup.
+
By default, `gerrit`.
[[httpd.requestLog]]httpd.requestLog::
+
Enable (or disable) the `'$site_path'/logs/httpd_log` request log.
If enabled, an NCSA combined log format request log file is written
out by the internal HTTP daemon. The httpd log format is documented
link:logs.html#_httpd_log[here].
+
`log4j.appender` with the name `httpd_log` can be configured to overwrite
programmatic configuration.
+
By default, `true` if httpd.listenUrl uses http:// or https://,
and `false` if httpd.listenUrl uses proxy-http:// or proxy-https://.
[[httpd.acceptorThreads]]httpd.acceptorThreads::
+
Number of worker threads dedicated to accepting new incoming TCP
connections and allocating them connection-specific resources.
+
By default, 2, which should be suitable for most high-traffic sites.
[[httpd.minThreads]]httpd.minThreads::
+
Minimum number of spare threads to keep in the worker thread pool.
This number must be at least 1 larger than httpd.acceptorThreads
multiplied by the number of httpd.listenUrls configured.
+
By default, 5, suitable for most lower-volume traffic sites.
[[httpd.maxThreads]]httpd.maxThreads::
+
Maximum number of threads to permit in the worker thread pool.
+
By default 25, suitable for most lower-volume traffic sites.
+
[NOTE]
Unless SSH daemon is disabled, see <<sshd.listenAddress, sshd.listenAddress>>,
the max number of concurrent Git requests over HTTP and SSH together is
defined by the <<sshd.threads, sshd.threads>> and
<<sshd.batchThreads, sshd.batchThreads>>.
[[httpd.maxQueued]]httpd.maxQueued::
+
Maximum number of client connections which can enter the worker
thread pool waiting for a worker thread to become available.
0 sets the queue size to the Integer.MAX_VALUE.
+
By default 200.
[[httpd.maxWait]]httpd.maxWait::
+
Maximum amount of time a client will wait for an available
thread to handle a project clone, fetch or push request over the
smart HTTP transport.
+
Values should use common unit suffixes to express their setting:
+
* s, sec, second, seconds
* m, min, minute, minutes
* h, hr, hour, hours
* d, day, days
* w, week, weeks (`1 week` is treated as `7 days`)
* mon, month, months (`1 month` is treated as `30 days`)
* y, year, years (`1 year` is treated as `365 days`)
+
--
If a unit suffix is not specified, `minutes` is assumed. If 0
is supplied, the maximum age is infinite and connections will not
abort until the client disconnects.
By default, 5 minutes.
--
[[httpd.filterClass]]httpd.filterClass::
+
Class that implements the javax.servlet.Filter interface
for filtering any HTTP related traffic going through the Gerrit
HTTP protocol.
Class is loaded and configured in the Gerrit Jetty container
and run in front of all Gerrit URL handlers, allowing the filter
to inspect, modify, allow or reject each request.
It needs to be provided as JAR library
under $GERRIT_SITE/lib as it is resolved using the default Gerrit class
loader and cannot be dynamically loaded by a plugin.
+
Failing to load the Filter class would result in a Gerrit start-up
failure, as this class is supposed to provide mandatory filtering
in front of Gerrit HTTP protocol.
+
Typical usage is in conjunction with the `auth.type=HTTP` as replacement
of an Apache HTTP proxy layer as security enforcement on top of Gerrit
by returning a trusted username as HTTP Header.
+
Allow multiple values to install multiple servlet filters.
+
Example of using a security library secure.jar under $GERRIT_SITE/lib
that provides a org.anyorg.MySecureHeaderFilter Servlet Filter that enforces
a trusted username in the `TRUSTED_USER` HTTP Header and
org.anyorg.MySecureIPFilter that performs source IP security filtering:
+
----
[auth]
type = HTTP
httpHeader = TRUSTED_USER
[httpd]
filterClass = org.anyorg.MySecureHeaderFilter
filterClass = org.anyorg.MySecureIPFilter
----
[[filterClass.className.initParam]]filterClass.<className>.initParam::
+
Gerrit supports customized pluggable HTTP filters as `filterClass`. This
option allows to pass extra initialization parameters to the filter. It
allows for multiple key/value pairs to be passed in this pattern:
+
----
initParam = <key>=<value>
----
For a comprehensive example:
+
----
[httpd]
filterClass = org.anyorg.AFilter
filterClass = org.anyorg.BFilter
[filterClass "org.anyorg.AFilter"]
key1 = value1
key2 = value2
[filterClass "org.anyorg.BFilter"]
key3 = value3
----
[[httpd.idleTimeout]]httpd.idleTimeout::
+
Maximum idle time for a connection, which roughly translates to the
TCP socket `SO_TIMEOUT`.
+
This value is interpreted as the maximum time between some progress
being made on the connection. So if a single byte is read or written,
then the timeout is reset.
+
The max idle time is applied:
+
* When waiting for a new message to be received on a connection
* When waiting for a new message to be sent on a connection
+
By default, 30 seconds.
[[httpd.robotsFile]]httpd.robotsFile::
+
Location of an external robots.txt file to be used instead of the one
bundled with the .war of the application.
+
If not absolute, the path is resolved relative to `$site_path`.
+
If the file doesn't exist or can't be read the default robots.txt file
bundled with the .war will be used instead.
[[httpd.registerMBeans]]httpd.registerMBeans::
+
Enable (or disable) registration of Jetty MBeans for Java JMX.
+
By default, `false`.
[[index]]
=== Section index
The index section configures the secondary index.
Note that after enabling the secondary index, the index must be built
using the link:pgm-reindex.html[reindex program] before restarting the
Gerrit server.
[[index.type]]index.type::
+
*(DEPRECATED)* The only supported value is `LUCENE`, which is the default,
that means a link:http://lucene.apache.org/[Lucene]
index is used.
+
For using other indexing backends (e.g. ElasticSearch), refer to
`gerrit.installIndexModule` setting.
+
[[index.threads]]index.threads::
+
Number of threads to use for indexing in normal interactive operations. Setting
it to 0 disables the dedicated thread pool and indexing will be done in the same
thread as the operation.
+
If not set or set to a zero, defaults to the number of logical CPUs as returned
by the JVM. If set to a negative value, defaults to a direct executor.
[[index.batchThreads]]index.batchThreads::
+
Number of threads to use for indexing in background operations, such as
online schema upgrades, and also the default for offline reindexing.
+
If not set or set to a zero, defaults to the number of logical CPUs as returned
by the JVM. If set to a negative value, defaults to a direct executor.
[[index.cacheQueryResultsByChangeNum]]index.cacheQueryResultsByChangeNum::
+
Allow to cache and reuse the change JSON elements by their Change number.
This improves the performance of queries that are returning Changes duplicates.
It needs to be turned off when having Changes imported from other servers
because of the potential conflicts of change numbers.
+
Defaults to `true`.
[[index.onlineUpgrade]]index.onlineUpgrade::
+
Whether to upgrade to new index schema versions while the server is
running. This is recommended as it prevents additional downtime during
Gerrit version upgrades (avoiding the need for an offline reindex step
using Reindex), but can add additional server load during the upgrade.
+
If set to `false`, there is no way to upgrade the index schema to take
advantage of new search features without restarting the server.
+
Defaults to `true`.
[[index.excludeProjectFromChangeReindex]]index.excludeProjectFromChangeReindex::
+
A list of projects that will be excluded from reindexing. This can be used
to exclude projects which are expensive to reindex to prioritize the other
projects.
+
Excluded projects can later be reindexed by for example using the
link:cmd-index-changes-in-project.html[index changes in project command].
[[index.reuseExistingDocuments]]index.reuseExistingDocuments::
+
Whether to reuse index documents that already exist during reindexing.
+
Currently, only supported by the changes index.
+
This feature is useful, if the Gerrit server has to be restarted
during an ongoing index online upgrade, since this would cause
a complete reindexing otherwise that might take an extensive time.
+
Each existing document in the index will be checked for staleness
and reindexed if found to be stale.
+
Defaults to false.
[[index.paginationType]]index.paginationType::
+
The pagination type to use when index queries are repeated to
obtain the next set of results. Supported values are:
+
* `OFFSET`
+
Index queries are repeated with a non-zero offset to obtain the
next set of results.
_Note: Results may be inaccurate if the data-set is changing during the query
execution._
+
* `SEARCH_AFTER`
+
Index queries are repeated using a search-after object. Index
backends can provide their custom implementations for search-after.
Note that, `SEARCH_AFTER` does not impact using offsets in Gerrit
query APIs.
_Note: Depending on the index backend and its settings, results may be
inaccurate if the data-set is changing during the query execution._
+
* `NONE`
+
Index queries are executed returning all results, without internal
pagination.
_Note: Since the entire set of indexing results is kept in memory
during the API execution, this option may lead to higher memory utilisation
and overall reduced performance.
Bear in mind that some indexing backends may not support unbounded queries;
therefore, the NONE option is unavailable._
+
Defaults to `OFFSET`.
[[index.defaultLimit]]index.defaultLimit::
+
Default limit, if the user does not provide a limit. If this is not set or set
to 0, then index queries are executed with the maximum permitted limit for the
user, which may be really high and cause too much load on the index. Thus
setting this default limit to something smaller like 100 allows you to control
the load, while not taking away any permission from the user. If the user
provides a limit themselves, then `defaultLimit` is ignored.
[[index.maxLimit]]index.maxLimit::
+
Maximum limit to allow for search queries. Requesting results above this
limit will truncate the list (but will still set `_more_changes` on
result lists). Set to 0 for no limit.
+
When `index.type` is set to `LUCENE`, defaults to no limit.
[[index.maxPages]]index.maxPages::
+
Maximum number of pages of search results to allow, as index
implementations may have to scan through large numbers of skipped
results when searching with an offset. Requesting results starting past
this threshold times the requested limit will result in an error. Set to
0 for no limit.
+
Defaults to no limit.
[[index.pageSizeMultiplier]]index.pageSizeMultiplier::
+
When index queries are repeated to obtain more results, this multiplier
will be used to determine the limit for the next query. Using a page
multiplier allows queries to start off small and thus provide good
latency for queries which may end up only having very few results, and
then scaling up to have better throughput to handle queries with larger
result sets without incurring the overhead of making as many queries as
would be required with a smaller limit. This strategy of using a multiplier
attempts to create a balance between latency and throughput by dynamically
adjusting the query size to the number of results being returned by each
query in the pagination.
+
The larger the multiplier, the better the throughput on large queries, and
it also improves latency on large queries by scaling up quickly. However, a
larger multiplier can hurt latencies a bit by making the "last" query in a
series longer than needed. The impact of this depends on how much the backend
latency goes up when specifying a large limit and few results are returned.
Setting link:#index.maxPageSize[index.maxPageSize] that isn't too large, can
likely help reduce the impacts of this.
+
For example, if the limit of the previous query was 500 and pageSizeMultiplier
is configured to 5, the next query will have a limit of 2500.
+
_Note: ignored when paginationType is `NONE`_
+
Defaults to 1 which effectively turns this feature off.
[[index.maxPageSize]]index.maxPageSize::
+
Maximum size to allow when index queries are repeated to obtain more results. Note
that, link:#index.maxLimit[index.maxLimit] will be used to limit page size if it
is configured to a value lower than maxPageSize.
+
For example, if the limit of previous query was 500, pageSizeMultiplier is
configured to 5 and maxPageSize to 2000, the next query will have a limit of
2000 (instead of 2500).
+
_Note: ignored when paginationType is `NONE`_
+
Defaults to no limit.
[[index.maxTerms]]index.maxTerms::
+
Maximum number of leaf terms to allow in a query. Too-large queries may
perform poorly, so setting this option causes query parsing to fail fast
before attempting to send them to the secondary index.
+
When the index type is `LUCENE`, also sets the maximum number of clauses
permitted per BooleanQuery. This is so that all enforced query limits
are the same.
+
Defaults to 1024.
[[index.autoReindexIfStale]]index.autoReindexIfStale::
+
Whether to automatically check if a document became stale in the index
immediately after indexing it. If `false`, there is a race condition during two
simultaneous writes that may cause one of the writes to not be reflected in the
index. The check to avoid this does consume some resources.
+
Defaults to `false`.
[[index.indexChangesAsync]]index.indexChangesAsync::
+
On BatchUpdate, do not await indexing completion before returning the request
to the user (WEB_BROWSER requests only).
This has an advantage of faster UI (because indexing latency does not contribute
to the write request latency) and disadvantage that the indexing result might not be
immediately available after the write request.
+
Defaults to `false`.
[[index.scheduledIndexer]]
==== Subsection index.scheduledIndexer
This section configures periodic indexing. Periodic indexing is
intended to run only on replicas and only updates the group index.
Replication to replicas happens on Git level so that Gerrit is not aware
of incoming replication events. But replicas need an updated group index
to resolve memberships of users for ACL validation. To keep the group
index in replicas up-to-date the Gerrit replica periodically scans the
group refs in the All-Users repository to reindex groups if they are
stale.
The scheduled reindexer is not able to detect group deletions that
happened while the replica was offline, but since group deletions are not
supported this should never happen. If nevertheless groups refs were
deleted while a replica was offline a full offline link:pgm-reindex.html[
reindex] must be performed.
This section is only used if Gerrit runs in replica mode, otherwise it is
ignored.
[[index.scheduledIndexer.runOnStartup]]index.scheduledIndexer.runOnStartup::
+
Whether the scheduled indexer should run once immediately on startup.
If set to `true` the replica startup is blocked until all stale groups
were reindexed. Enabling this allows to prevent that replicas that were
offline for a longer period of time run with outdated group information
until the first scheduled indexing is done.
+
Defaults to `true`.
[[index.scheduledIndexer.enabled]]index.scheduledIndexer.enabled::
+
Whether the scheduled indexer is enabled. If the scheduled indexer is
disabled you must implement other means to keep the group index for the
replica up-to-date.
+
Defaults to `true`.
[[index.scheduledIndexer.startTime]]index.scheduledIndexer.startTime::
+
The link:#schedule-configuration-startTime[start time] for running
the scheduled indexer.
+
Defaults to `00:00`.
[[index.scheduledIndexer.interval]]index.scheduledIndexer.interval::
+
The link:#schedule-configuration-interval[interval] for running
the scheduled indexer.
+
Defaults to `5m`.
link:#schedule-configuration-examples[Schedule examples] can be found
in the link:#schedule-configuration[Schedule Configuration] section.
==== Lucene configuration
Open and closed changes are indexed in separate indexes named
'open' and 'closed' respectively.
The following settings are only used when the index type is `LUCENE`.
[[index.name.ramBufferSize]]index.name.ramBufferSize::
+
Determines the amount of RAM that may be used for buffering added documents
and deletions before they are flushed to the index. See the
link:http://lucene.apache.org/core/4_6_0/core/org/apache/lucene/index/LiveIndexWriterConfig.html#setRAMBufferSizeMB(double)[
Lucene documentation,role=external,window=_blank] for further details.
+
Defaults to 16M.
[[index.name.maxBufferedDocs]]index.name.maxBufferedDocs::
+
Determines the minimal number of documents required before the buffered
in-memory documents are flushed to the index. Large values generally
give faster indexing. See the
link:http://lucene.apache.org/core/4_6_0/core/org/apache/lucene/index/LiveIndexWriterConfig.html#setMaxBufferedDocs(int)[
Lucene documentation,role=external,window=_blank] for further details.
+
Defaults to -1, meaning no maximum is set and the writer will flush
according to RAM usage.
[[index.name.commitWithin]]index.name.commitWithin::
+
Determines the period at which changes are automatically committed to
stable store on disk. This is a costly operation and may block
additional index writes, so lower with caution.
+
If zero, changes are committed after every write. This is very costly
but may be useful if offline reindexing is infeasible, or for development
servers.
+
Values can be specified using standard time unit abbreviations (`ms`, `sec`,
`min`, etc.).
+
If negative, `commitWithin` is disabled. Changes are flushed to disk when
the in-memory buffer fills, but only committed and guaranteed to be synced
to disk when the process finishes.
+
Defaults to 300000 ms (5 minutes).
[[index.name.maxMergeCount]]index.name.maxMergeCount::
+
Determines the max number of simultaneous merges that are allowed. If a merge
is necessary yet we already have this many threads running, the incoming thread
(that is calling add/updateDocument) will block until a merge thread has
completed. Note that Lucene will only run the smallest maxThreadCount merges
at a time. See the
link:https://lucene.apache.org/core/5_5_0/core/org/apache/lucene/index/ConcurrentMergeScheduler.html#setDefaultMaxMergesAndThreads(boolean)[
Lucene documentation,role=external,window=_blank] for further details.
+
Defaults to -1 for (auto detection).
[[index.name.maxThreadCount]]index.name.maxThreadCount::
+
Determines the max number of simultaneous Lucene merge threads that should be running at
once. This must be less than or equal to maxMergeCount. See the
link:https://lucene.apache.org/core/5_5_0/core/org/apache/lucene/index/ConcurrentMergeScheduler.html#setDefaultMaxMergesAndThreads(boolean)[
Lucene documentation,role=external,window=_blank] for further details.
+
For further details on Lucene index configuration (auto detection) which
affects maxThreadCount and maxMergeCount settings.
See the
link:https://lucene.apache.org/core/5_5_0/core/org/apache/lucene/index/ConcurrentMergeScheduler.html#AUTO_DETECT_MERGES_AND_THREADS[
Lucene documentation,role=external,window=_blank]
+
Defaults to -1 for (auto detection).
[[index.name.enableAutoIOThrottle]]index.name.enableAutoIOThrottle::
+
Allows the control of whether automatic IO throttling is enabled and used by
default in the lucene merge queue. Automatic dynamic IO throttling, which when
on is used to adaptively rate limit writes bytes/sec to the minimal rate necessary
so merges do not fall behind. See the
link:https://lucene.apache.org/core/5_5_0/core/org/apache/lucene/index/ConcurrentMergeScheduler.html#enableAutoIOThrottle()[
Lucene documentation,role=external,window=_blank] for further details.
+
Defaults to `true` (throttling enabled).
During offline reindexing, setting ramBufferSize greater than the size
of index (size of specific index folder under <site_dir>/index) and
maxBufferedDocs as -1 avoids unnecessary flushes and triggers only a
single flush at the end of the process.
Sample Lucene index configuration:
----
[index]
type = LUCENE
[index "changes_open"]
ramBufferSize = 60 m
maxBufferedDocs = 3000
maxThreadCount = 5
maxMergeCount = 50
[index "changes_closed"]
ramBufferSize = 20 m
maxBufferedDocs = 500
maxThreadCount = 10
maxMergeCount = 100
enableIOThrottle = false
----
[[event]]
=== Section event
[[event.payload.listChangeOptions]]events.payload.listChangeOptions::
+
List of options that Gerrit applies when rendering the payload of an
internal event. This is the same set of options that are documented
link:rest-api-changes.html#query-options[here].
+
Depending on the setup, these events might get serialized using stream
events.
+
This can be set to the set of minimal options that consumers of Gerrit's
events need. A minimal set would be (`SKIP_DIFFSTAT`).
+
Every option that gets added here will have a performance impact. The
general recommendation is therefore to set this to a minimal set of
required options.
+
Defaults to all available options minus `CHANGE_ACTIONS`,
`CURRENT_ACTIONS` and `CHECK`. This is a rich default to make sure the
config is backwards compatible with what the default was before the config
was added.
[[event.comment-added.publishPatchSetLevelComment]]event.comment-added.publishPatchSetLevelComment::
+
Add patch set level comment as event comment. Without this option, patch set
level comment will not be included in the event comment attribute. Given that
currently patch set level, file and robot comments are not exposed in the
`comment-added` event type, those comments will be lost. One particular use
case is to re-trigger CI build from the change screen by adding a comment with
specific content, e.g.: `recheck`. Jenkins Gerrit Trigger plugin and Zuul CI
depend on this feature to trigger change verification.
+
By default, `true`.
[[event.stream-events.enableRefUpdatedEvents]]event.stream-events.enableRefUpdatedEvents::
+
Enable streaming of `ref-updated` event which represents a single ref update operation.
Batch ref updates are represented as a series of `ref-updated` events.
This allows event listeners to react on a ref update.
Please consider switching to `batch-ref-updated` event which provides better control on grouping and
preserving order of the ref updates.
+
By default, `true`.
[[event.stream-events.enableBatchRefUpdatedEvents]]event.stream-events.enableBatchRefUpdatedEvents::
+
Enable streaming of `batch-ref-updated` event which represents group of
refs updated during a single batch ref update operation.
Single ref updates are also streamed as a `batch-ref-updated` events with a single ref specified.
This allows event listeners to react on all ref updated events and disable individual `ref-updated`
events by setting <<event.stream-events.enableRefUpdatedEvents, event.stream-events.enableRefUpdatedEvents>> to `false`.
+
By default, `false`.
[[event.stream-events.enableDraftCommentEvents]]event.stream-events.enableDraftCommentEvents::
+
Enable streaming of `ref-updated` events for `refs/draft-comments` refs.
Enable this flag in case listeners in your system are supposed to react on draft operations.
+
NOTE: Due to the nature of drafts, the amount of `ref-updated` events created on draft operations could be high.
The extra amount of events depends on the usage pattern of the installation. It is worth evaluating
the amount of extra events produced before enabling this flag by counting the calls to the draft APIs.
+
By default, `false`.
[[experiments]]
=== Section experiments
This section covers experimental new features. Gerrit uses experiments
to research new behavior in frontend and core backend. Once the research is done, the experimental
feature either stays and the experimentation flag gets removed, or the feature as a whole
gets removed
[[experiments.enabled]]experiments.enabled::
+
List of experiments that are currently enabled. The release notes contain currently
available experiments.
+
We will not remove experiments in stable patch releases. They are likely to be
removed in the next stable version.
----
[experiments]
enabled = ExperimentKey
----
[[experiments.disabled]]experiments.disabled::
+
List of experiments that are currently disabled. The release notes contain currently
available experiments. This list disables experiments with the given key that are
either enabled by default or explicitly in the config.
----
[experiments]
disabled = ExperimentKey
----
[[ldap]]
=== Section ldap
LDAP integration is only enabled if `auth.type` is set to
`HTTP_LDAP`, `LDAP` or `CLIENT_SSL_CERT_LDAP`. See above for a
detailed description of the `auth.type` settings and their
implications.
An example LDAP configuration follows, and then discussion of
the parameters introduced here. Suitable defaults for most
parameters are automatically guessed based on the type of server
detected during startup. The guessed defaults support
link:http://www.ietf.org/rfc/rfc2307.txt[RFC 2307,role=external,window=_blank], Active
Directory and link:https://www.freeipa.org[FreeIPA,role=external,window=_blank].
----
[ldap]
server = ldap://ldap.example.com
accountBase = ou=people,dc=example,dc=com
accountPattern = (&(objectClass=person)(uid=${username}))
accountFullName = displayName
accountEmailAddress = mail
groupBase = ou=groups,dc=example,dc=com
groupMemberPattern = (&(objectClass=group)(member=${dn}))
----
[[ldap.guessRelevantGroups]]ldap.guessRelevantGroups::
+
Filter the groups found in LDAP by guessing the ones relevant to
Gerrit and removing the others from list completions and ACL evaluations.
The guess is based on two elements: the projects most recently
accessed in the cache and the list of LDAP groups included in their ACLs.
+
Please note that projects rarely used and thus not cached may be
temporarily inaccessible by users even with LDAP membership and grants
referenced in the ACLs.
+
By default, `true`.
[[ldap.server]]ldap.server::
+
URL of the organization's LDAP server to query for user information
and group membership from. Must be of the form `ldap://host` or
`ldaps://host` to bind with either a plaintext or SSL connection.
+
If `auth.type` is `LDAP` this setting should use `ldaps://` to
ensure the end user's plaintext password is transmitted only over
an encrypted connection.
+
If you want to configure multiple ldap servers you can try to put
multiple ldap urls separated by a space:
`server = ldaps://ldap1 ldaps://ldap2`
See https://issues.gerritcodereview.com/issues/40010644[issue 40010644].
[[ldap.startTls]]ldap.startTls::
+
If `true`, Gerrit will perform StartTLS extended operation.
+
By default, `false`, StartTLS will not be enabled.
[[ldap.supportAnonymous]]ldap.supportAnonymous::
+
If `false`, Gerrit will provide credentials only at connection open, this is
required for some `LDAP` implementations that do not allow anonymous bind
for StartTLS or for reauthentication.
+
By default, `true`.
[[ldap.sslVerify]]ldap.sslVerify::
+
If `false` and ldap.server is an `ldaps://` style URL or `ldap.startTls`
is `true`, Gerrit will not verify the server certificate when it connects
to perform a query.
+
By default, `true`, requiring the certificate to be verified.
[[ldap.groupsVisibleToAll]]ldap.groupsVisibleToAll::
+
If `true`, LDAP groups are visible to all registered users.
+
By default, `false`, LDAP groups are visible only to administrators and
group members.
[[ldap.username]]ldap.username::
+
_(Optional)_ Username to bind to the LDAP server with. If not set,
an anonymous connection to the LDAP server is attempted.
[[ldap.password]]ldap.password::
+
_(Optional)_ Password for the user identified by `ldap.username`.
If not set, an anonymous (or passwordless) connection to the LDAP
server is attempted.
[[ldap.referral]]ldap.referral::
+
_(Optional)_ How an LDAP referral should be handled if it is
encountered during directory traversal. Set to `follow` to
automatically follow any referrals, or `ignore` to ignore the
referrals.
+
By default, `ignore`.
[[ldap.readTimeout]]ldap.readTimeout::
+
_(Optional)_ The read timeout for an LDAP operation. The value is
in the usual time-unit format like "1 s", "100 ms", etc...
A timeout can be used to avoid blocking all of the SSH command start
threads in case the LDAP server becomes slow.
+
By default there is no timeout and Gerrit will wait for the LDAP
server to respond until the TCP connection times out.
[[ldap.accountBase]]ldap.accountBase::
+
Root of the tree containing all user accounts. This is typically
of the form `ou=people,dc=example,dc=com`.
+
This setting may be added multiple times to specify more than
one root.
[[ldap.accountScope]]ldap.accountScope::
+
Scope of the search performed for accounts. Must be one of:
+
* `one`: Search only one level below accountBase, but not recursive
* `sub` or `subtree`: Search recursively below accountBase
* `base` or `object`: Search exactly accountBase; probably not desired
+
Default is `subtree` as many directories have several levels.
[[ldap.accountPattern]]ldap.accountPattern::
+
Query pattern to use when searching for a user account. This may be
any valid LDAP query expression, including the standard `(&...)` and
`(|...)` operators. If `auth.type` is `HTTP_LDAP` then the variable
`${username}` is replaced with a parameter set to the username
that was supplied by the HTTP server. If `auth.type` is `LDAP` then
the variable `${username}` is replaced by the string entered by
the end user.
+
This pattern is used to search the objects contained directly under
the `ldap.accountBase` tree. A typical setting for this parameter
is `(uid=${username})` or `(cn=${username})`, but the proper
setting depends on the LDAP schema used by the directory server.
+
Default is `(uid=${username})` for FreeIPA and RFC 2307 servers,
and `(&(objectClass=user)(sAMAccountName=${username}))`
for Active Directory.
[[ldap.accountFullName]]ldap.accountFullName::
+
_(Optional)_ Name of an attribute on the user account object which
contains the initial value for the user's full name field in Gerrit.
Typically this is the `displayName` property in LDAP, but could
also be `legalName` or `cn`.
+
Attribute values may be concatenated with literal strings. For
example to join given name and surname together, use the pattern
`${givenName} ${SN}`.
+
Default is `displayName` for FreeIPA and RFC 2307 servers,
and `${givenName} ${sn}` for Active Directory.
+
A non-empty or default value prevents users from modifying their full
name field. To allow edits to the full name field, set to the empty
string.
[[ldap.accountEmailAddress]]ldap.accountEmailAddress::
+
_(Optional)_ Name of an attribute on the user account object which
contains the user's Internet email address, as defined by this
LDAP server.
+
Attribute values may be concatenated with literal strings,
for example to set the email address to the lowercase form
of sAMAccountName followed by a constant domain name, use
`${sAMAccountName.toLowerCase}@example.com`.
+
If set, the preferred email address will be prefilled from LDAP,
but users may still be able to register additional email addresses,
and select a different preferred email address.
+
Default is `mail`.
[[ldap.accountSshUserName]]ldap.accountSshUserName::
+
_(Optional)_ Name of an attribute on the user account object which
contains the initial value for the user's SSH username field in
Gerrit. Typically this is the `uid` property in LDAP, but could
also be `cn`. Administrators should prefer to match the attribute
corresponding to the user's workstation username, as this is what
SSH clients will default to.
+
Attribute values may also be forced to lowercase, or to uppercase in
an expression. For example, `${sAMAccountName.toLowerCase}` will
force the value of sAMAccountName, if defined, to be all lowercase.
The suffix `.toUpperCase` can be used for the other direction.
The suffix `.localPart` can be used to split attribute values of
the form 'user@example.com' and return only the left hand side, for
example `${userPrincipalName.localPart}` would provide only 'user'.
+
If set, users will be unable to modify their SSH username field, as
Gerrit will populate it only from the LDAP data. Note that once the
username has been set it cannot be changed, therefore it is
recommended not to make changes to this setting that would cause the
value to differ, as this will prevent users from logging in.
+
Default is `uid` for FreeIPA and RFC 2307 servers,
and `${sAMAccountName.toLowerCase}` for Active Directory.
[[ldap.accountMemberField]]ldap.accountMemberField::
+
_(Optional)_ Name of an attribute on the user account object which
contains the groups the user is part of. Typically used for Active
Directory and FreeIPA servers.
+
Default is unset for RFC 2307 servers (disabled)
and `memberOf` for Active Directory and FreeIPA.
[[ldap.accountMemberExpandGroups]]ldap.accountMemberExpandGroups::
+
_(Optional)_ Whether to expand nested groups recursively. This
setting is used only if `ldap.accountMemberField` is set.
+
Default is unset for FreeIPA and `true` for RFC 2307 servers
and Active Directory.
[[ldap.fetchMemberOfEagerly]]ldap.fetchMemberOfEagerly::
+
_(Optional)_ Whether to fetch the `memberOf` account attribute on
login. Setups which use LDAP for user authentication but don't make
use of the LDAP groups may benefit from setting this option to `false`
as this will result in a much faster LDAP login.
+
Default is unset for RFC 2307 servers (disabled) and `true` for
Active Directory and FreeIPA.
[[ldap.groupBase]]ldap.groupBase::
+
Root of the tree containing all group objects. This is typically
of the form `ou=groups,dc=example,dc=com`.
+
This setting may be added multiple times to specify more than
one root.
[[ldap.groupScope]]ldap.groupScope::
+
Scope of the search performed for group objects. Must be one of:
+
* `one`: Search only one level below groupBase, but not recursive
* `sub` or `subtree`: Search recursively below groupBase
* `base` or `object`: Search exactly groupBase; probably not desired
+
Default is `subtree` as many directories have several levels.
[[ldap.groupPattern]]ldap.groupPattern::
+
Query pattern used when searching for an LDAP group to connect
to a Gerrit group. This may be any valid LDAP query expression,
including the standard `(&...)` and `(|...)` operators. The variable
`${groupname}` is replaced with the search term supplied by the
group owner.
+
Default is `(cn=${groupname})` for FreeIPA and RFC 2307 servers,
and `(&(objectClass=group)(cn=${groupname}))` for Active Directory.
[[ldap.groupMemberPattern]]ldap.groupMemberPattern::
+
Query pattern to use when searching for the groups that a user
account is currently a member of. This may be any valid LDAP query
expression, including the standard `(&...)` and `(|...)` operators.
+
If `auth.type` is `HTTP_LDAP` then the variable `${username}` is
replaced with a parameter set to the username that was supplied
by the HTTP server. Other variables appearing in the pattern,
such as `${fooBarAttribute}`, are replaced with the value of the
corresponding attribute (in this case, `fooBarAttribute`) as read
from the user's account object matched under `ldap.accountBase`.
Attributes such as `${dn}` or `${uidNumber}` may be useful.
+