Gerrit Code Review - Configuration

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.

If NONE, no users other than the current user are visible.

Default is ALL.

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 WebUI, but is ignored when adding reviewers with the set-reviewers command.

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.

Type of user authentication employed by Gerrit. The supported values are:

By default, OpenID.

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 standard Java regular expression (java.util.regex) (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.

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 standard Java regular expression (java.util.regex) (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.

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.

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:

Default is -1, permitting infinite time between authentications.

Time in seconds before an email verification token sent to a user in order to validate their email address expires.

Default is 12 hours.

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.

HTTP header to trust the username from, or unset to select HTTP basic or digest authentication. Only used if auth.type is set to HTTP.

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.

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.

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.

Text displayed in the loginUrl link. Only used if auth.loginUrl is set.

If not set, the "Sign In" text is used.

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.

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.

Target for the "Register" link in the upper right corner. Used only when auth.type is LDAP.

If not set, no "Register" link is displayed.

Text for the "Register" link in the upper right corner. Used only when auth.type is LDAP.

If not set, defaults to "Register".

Target for the "Edit" button when the user is allowed to edit their full name.

Target for the "Obtain Password" link. Used only when auth.type is LDAP, LDAP_BIND or CUSTOM_EXTENSION.

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/ or $canonicalWebUrl/login, allowing users to begin a new web session.

Sets "path" attribute of the authentication cookie.

If not set, HTTP request’s path is used.

Sets "secure" flag of the authentication cookie. If true, cookies will be transmitted only over HTTPS protocol.

By default, false.

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.

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 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: receive.requireContributorAgreement.

Allows Google Account users to automatically update their Gerrit account when/if their Google Account OpenID identity token changes. Identity tokens can change if the server changes hostnames, or for other reasons known only to Google. The upgrade path works by matching users by email address if the identity is not present, and then changing the identity.

This setting also permits old Gerrit 1.x users to seamlessly upgrade from Google Accounts on Google App Engine to OpenID authentication.

Having this enabled incurs an extra database query when Google Account users register with the Gerrit server.

By default, unset/false.

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 DIGEST authentication).

By default this is set to false.

If true then Git over HTTP and HTTP/S traffic is authenticated using standard BasicAuth and credentials validated using the same auth method configured for Gerrit Web UI.

This parameter only affects git over http traffic. If set to false then Gerrit will authenticate through DIGEST authentication and the randomly generated HTTP password in Gerrit DB.

By default this is set to false.

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

This parameter only affects git over http and git over SSH traffic.

By default this is set to false.

If true HTTP REST APIs will accept the X-Gerrit-RunAs HTTP request header from any users granted the 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.

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.

If not absolute, the path is resolved relative to $site_path.

Default is unset, no disk cache.

Maximum age to keep an entry in the cache. Entries are removed from the cache and refreshed from source data every maxAge interval. Values should use common unit suffixes to express their setting:

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:

+

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 "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:

If set to 0 the cache is disabled. Entries are removed immediately after being stored by the cache. This is primarily useful for testing.

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.

If 0, disk storage for the cache is disabled.

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 30 seconds.

How often the database should be rescanned for changes that have been submitted but not merged due to transient errors. Values can be specified using standard time unit abbreviations (ms, sec, min, etc.). Set to 0 to disable periodic rescanning, only scanning once on master node startup.

Default is 300 seconds (5 minutes).

Controls whether or not the mergeability test of changes is enabled. If enabled, when the change page is loaded, the test is triggered. The submit button will be enabled or disabled according to the result.

By default this is false (test is not enabled).

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.

A common pattern to match is bug\\s+(\\d+).

The URL to direct the user to whenever the regular expression is matched. Groups in the match expression may be accessed as $'n'.

The link property is used only when the html property is not present.

HTML to replace the entire matched string with. If present, this property overrides the link property above. Groups in the match expression may be accessed as $'n'.

The configuration file eats double quotes, so escaping them as \" is necessary to protect them from the parser.

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.

Disabling sections in gerrit.config can be used by site administrators to create a library of comment links with html set that are not user-supplied and thus can be verified to be XSS-free, but are only enabled for a subset of projects.

Note that the names and contents of disabled sections are visible even to anonymous users via the REST API.

URL of the web based contact store Gerrit will send any offline contact information to when it collects the data from users as part of a contributor agreement.

See Contact Information.

Shared secret of the web based contact store.

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.

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.

Additional options to pass along to the Java runtime. If multiple values are configured, they are passed in order on the command line, separated by spaces. These options are appended onto JAVA_OPTIONS.

Used on Gerrit slave installations. If set to true the Gerrit JVM is called with the --slave switch, enabling slave mode. If no value is set (or any other value), Gerrit defaults to master mode.

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.

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.

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.

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.

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.

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.

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.

Default is 50 MiB on all platforms. Prior to Gerrit 2.1.6, this value was effectively 2047 MiB.

Common unit suffixes of k, m, or g are supported.

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.

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 loosing log entries in this case.

Default is 64 entries.

Use JGit’s new, experimental recursive merger for three-way merges. This only affects projects configured to automatically resolve conflicts.

Default is false, but in a future release may default to true.

Type of database server to connect to. If set this value will be used to automatically create correct database.driver and database.url values to open the connection.

If not specified, database.driver and database.url are used as-is, and if they are also not specified, defaults to H2.

Hostname of the database server. Defaults to localhost.

Port number of the database server. Defaults to the default port of the server named by database.type.

For POSTGRESQL or MYSQL, the name of the database on the server.

For H2, this is the path to the database, and if not absolute is relative to '$site_path'.

Username to connect to the database server as.

Password to authenticate to the database server with.

Name of the JDBC driver class to connect to the database with. Setting this usually isn’t necessary as it can be derived from database.type or database.url for any supported database.

jdbc: URL for the database. Setting this variable usually isn’t necessary as it can be constructed from the all of the above properties.

If true, use connection pooling for database connections. Otherwise, a new database connection is opened for each request.

Default is false for MySQL, and true for other database backends.

Maximum number of open database connections. If the server needs more than this number, request processing threads will wait up to 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 8.

This setting only applies if database.connectionPool is true.

Minimum number of connections to keep idle in the pool. Default is 4.

This setting only applies if database.connectionPool is true.

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

This setting only applies if database.connectionPool is true.

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:

If a unit suffix is not specified, milliseconds is assumed.

+ Default is 30 seconds.

+ This setting only applies if database.connectionPool is true.

Commands that should be offered to download changes.

Multiple commands are supported:

If download.command is not specified, all download commands are offered.

Schemes that should be used to download changes.

Multiple schemes are supported:

If download.scheme is not specified, SSH, HTTP and Anonymous HTTP downloads are allowed.

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

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.

Defaults to All-Projects if not set.

The default URL for Gerrit to be accessed through.

Typically this would be set to "http://review.example.com/" or "http://example.com/gerrit/" so Gerrit can output links that point back to itself.

Setting this is highly recommended, as its necessary for the upload code invoked by "git push" or "repo upload" to output hyperlinks to the newly uploaded changes.

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.

Optional command to install the commit-msg hook. Typically of the form:

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.

URL to direct users to when they need to report a bug about the Gerrit service. By default this links to the upstream Gerrit Code Review’s own bug tracker but could be directed to the system administrator’s ticket queue.

Default change screen UI to direct users to. Valid values are OLD_UI and CHANGE_SCREEN2. Default is OLD_UI.

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.

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

Optional type of affiliated gitweb service. This allows using alternatives to gitweb, such as cgit. If set to disabled there is no gitweb hyperlinking support.

Valid values are gitweb, cgit, disabled or custom.

Optional pattern to use for constructing the gitweb URL when pointing at a specific commit when custom is used above.

Valid replacements are ${project} for the project name in Gerrit and ${commit} for the SHA1 hash for the commit.

Optional pattern to use for constructing the gitweb URL when pointing at a specific project when custom is used above.

Valid replacements are ${project} for the project name in Gerrit.

Optional pattern to use for constructing the gitweb URL when pointing at a specific branch when custom is used above.

Valid replacements are ${project} for the project name in Gerrit and ${branch} for the name of the branch.

Optional pattern to use for constructing the gitweb URL when pointing at the history of a file in a specific branch when custom is used above.

Valid replacements are ${project} for the project name in Gerrit, ${file} for the file name and ${branch} for the name of the branch.

Optional setting for modifying the link name presented to the user in the Gerrit web-UI.

Default linkname for custom type is "gitweb".

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 Gitblit, allow using an alternative path separator character. In Gitblit, this can be configured through the property web.forwardSlashCharacter. In Gerrit, the alternative path separator can be configured correspondingly using the property gitweb.pathSeparator.

Valid values are the characters *, ( and ).

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," default is "true."

Whether or not Gerrit should provide links to gitweb on draft patch sets.

By default, Gerrit will show links to gitweb on all patch sets. If gitweb only allows publicly viewable references, set this to false to remove the links to draft patch sets from the change review screen.

Valid values are "true" and "false," default is "true".

Controls whether newly created groups should be by default visible to all registered users.

By default, false.

Optional path to hooks, if not specified then '$site_path'/hooks will be used.

Optional filename for the patchset created hook, if not specified then patchset-created will be used.

Optional filename for the draft published hook, if not specified then draft-published will be used.

Optional filename for the comment added hook, if not specified then comment-added will be used.

Optional filename for the change merged hook, if not specified then change-merged will be used.

Optional filename for the merge failed hook, if not specified then merge-failed will be used.

Optional filename for the change abandoned hook, if not specified then change-abandoned will be used.

Optional filename for the change restored hook, if not specified then change-restored will be used.

Optional filename for the ref updated hook, if not specified then ref-updated will be used.

Optional filename for the reviewer added hook, if not specified then reviewer-added will be used.

Optional filename for the topic changed hook, if not specified then topic-changed will be used.

Optional filename for the CLA signed hook, if not specified then cla-signed will be used.

Optional filename for the ref update hook, if not specified then ref-update will be used.

Optional timeout value in seconds for synchronous hooks, if not specified then 30 seconds will be used.

URL of the proxy server when making outgoing HTTP connections for OpenID login transactions. Syntax should be http://hostname:port.

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.

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.

Specifies the URLs the internal HTTP daemon should listen for connections on. The special hostname * may be used to listen on all local addresses. A context path may optionally be included, placing Gerrit Code Review’s web address within a subdirectory of the server.

Multiple protocol schemes are supported:

If multiple values are supplied, the daemon will listen on all of them.

+ By default, http://*:8080.

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.

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.

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:

If not absolute, the path is resolved relative to $site_path.

By default, $site_path/etc/crl.pem.

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:

If not absolute, the path is resolved relative to $site_path.

By default, $site_path/etc/keystore.

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.

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.

By default, true if httpd.listenUrl uses http:// or https://, and false if httpd.listenUrl uses proxy-http:// or proxy-https://.

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.

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.

Maximum number of threads to permit in the worker thread pool.

By default 25, suitable for most lower-volume traffic sites.

Maximum number of client connections which can enter the worker thread pool waiting for a worker thread to become available. 0 disables the queue and permits infinite number of connections.

By default 50.

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:

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.

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.

Example of using a security library secure.jar under $GERRIT_SITE/lib that provides a org.anyorg.MySecureFilter Servlet Filter that enforces a trusted username in the TRUSTED_USER HTTP Header:

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.

Type of secondary indexing employed by Gerrit. The supported values are:

By default, SQL.

Only used when the type is LUCENE.

Determines the amount of RAM that may be used for buffering added documents and deletions before they are flushed to the index. See the Lucene documentation for further details.

Defaults to 16M.

Only used when the type is LUCENE.

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 Lucene documentation for further details.

Defaults to -1, meaning no maximum is set and the writer will flush according to RAM usage.

Only used when the type is LUCENE.

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 or negative, changes are committed after every write. This is very costly but may be useful if offline reindexing is infeasible, or for development servers.

This setting also applies when running the reindex program. If it is configured to commit on every write, this will cause reindex to take an unnecessarily long time to complete on sites that have a lot of changes. It is recommended to temporarily set a higher value while running reindex.

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 false and ldap.server is an ldaps:// style URL, Gerrit will not verify the server certificate when it connects to perform a query.

By default, true, requiring the certificate to be verified.

(Optional) Username to bind to the LDAP server with. If not set, an anonymous connection to the LDAP server is attempted.

(Optional) Password for the user identified by ldap.username. If not set, an anonymous (or passwordless) connection to the LDAP server is attempted.

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

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

Root of the tree containing all user accounts. This is typically of the form ou=people,dc=example,dc=com.

Scope of the search performed for accounts. Must be one of:

Default is subtree as many directories have several levels.

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 RFC 2307 servers, and (&(objectClass=user)(sAMAccountName=${username})) for Active Directory.

(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}.

If set, users will be unable to modify their full name field, as Gerrit will populate it only from the LDAP data.

Default is displayName for RFC 2307 servers, and ${givenName} ${sn} for Active Directory.

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

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

Default is uid for RFC 2307 servers, and ${sAMAccountName.toLowerCase} for Active Directory.

(Optional) Name of an attribute on the user account object which contains the groups the user is part of. Typically used for Active Directory servers.

Default is unset for RFC 2307 servers (disabled) and memberOf for Active Directory.

Root of the tree containing all group objects. This is typically of the form ou=groups,dc=example,dc=com.

Scope of the search performed for group objects. Must be one of:

Default is subtree as many directories have several levels.

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 RFC 2307, and (&(objectClass=group)(cn=${groupname})) for Active Directory.

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.

Default is (|(memberUid=${username})(gidNumber=${gidNumber})) for RFC 2307, and unset (disabled) for Active Directory.

(Optional) Name of the attribute on the group object which contains the value to use as the group name in Gerrit.

Typically the attribute name is cn for RFC 2307 and Active Directory servers. For other servers the attribute name may differ, for example apple-group-realname on Apple MacOS X Server.

It is also possible to specify a literal string containing a pattern of attribute values. For example to create a Gerrit group name consisting of LDAP group name and group ID, use the pattern ${cn} (${gidNumber}).

Default is cn.

Converts the local username, that is used to login into the Gerrit WebUI, to lower case before doing the LDAP authentication. By setting this parameter to true, a case insensitive login to the Gerrit WebUI can be achieved.

If set, it must be ensured that the local usernames for all existing accounts are converted to lower case, otherwise a user that has a local username that contains upper case characters will not be able to login anymore. The local usernames for the existing accounts can be converted to lower case by running the server program LocalUsernamesToLowerCase. Please be aware that the conversion of the local usernames to lower case can’t be undone. For newly created accounts the local username will be directly stored in lower case.

By default, unset/false.

Defines how Gerrit authenticates with the server. When set to GSSAPI Gerrit will use Kerberos. To use kerberos the java.security.auth.login.config system property must point to a login to a JAAS configuration file and, if Java 6 is used, the system property java.security.krb5.conf must point to the appropriate krb5.ini file with references to the KDC.

If set to true, files with the MIME type <name> will be sent as direct downloads to the user’s browser, rather than being wrapped up inside of zipped archives. The type name may be a complete type name, e.g. image/gif, a generic media type, e.g. image/*, or the wildcard */* to match all types.

By default, false for all MIME types.

If true, delta compression between objects is enabled. This may result in a smaller overall transfer for the client, but requires more server memory and CPU time.

False (off) by default, matching Gerrit Code Review 2.1.4.

Maximum number of threads to use for delta compression (if enabled). This is per-client request. If set to 0 then the number of CPUs is auto-detected and one thread per CPU is used, per client request.

By default, 1.

How often plugins should be examined for new plugins to load, removed plugins to be unloaded, or updated plugins to be reloaded. Values can be specified using standard time unit abbreviations (ms, sec, min, etc.).

If set to 0, automatic plugin reloading is disabled. Administrators may force reloading with gerrit plugin reload.

Default is 1 minute.

If true, Gerrit will verify the destination repository has no references under the magic refs/drafts, refs/for, or refs/publish branch namespaces. Names under these locations confuse clients when trying to upload code reviews so Gerrit requires them to be empty.

If false Gerrit skips the sanity check and assumes administrators have ensured the repository does not contain any magic references. Setting to false to skip the check can decrease latency during push.

Default is true.

If set to true, Gerrit will validate that all referenced objects that are not included in the received pack are reachable by the user.

Carrying out this check on gits with many refs and commits can be a very CPU-heavy operation. For non public Gerrit-servers this check may be overkill.

Only disable this check if you trust the clients not to forge SHA1 references to access commits intended to be hidden from the user.

Default is true.

Name of the groups of users that are allowed to execute receive-pack on the server. One or more groups can be set.

If no groups are added, any user will be allowed to execute receive-pack on the server.

Maximum allowed Git object size that receive-pack will accept. If an object is larger than the given size the pack-parsing will abort and the push operation will fail. If set to zero then there is no limit.

Gerrit administrators can use this setting to prevent developers from pushing objects which are too large to Gerrit.

This setting can also be set in the project.config receive.maxObjectSizeLimit in order to further reduce the global setting. The project specific setting is only honored when it further reduces the global limit.

Default is zero.

Common unit suffixes of k, m, or g are supported.

Maximum size of the thread pool in which the change data in received packs is processed.

Defaults to the number of available CPUs according to the Java runtime.

Number of threads to perform change creation or patch set updates concurrently. Each thread uses its own database connection from the database connection pool, and if all threads are busy then main receive thread will also perform a change creation or patch set update.

Defaults to 1, using only the main receive thread. This feature is for databases with very high latency that can benefit from concurrent operations when multiple changes are impacted at once.

Overall timeout on the time taken to process the change data in received packs. Only includes the time processing Gerrit changes and updating references, not the time to index the pack. Values can be specified using standard time unit abbreviations (ms, sec, min, etc.).

Default is 2 minutes. If no unit is specified, milliseconds is assumed.

A name of a group which exists in the database. Zero, one or many groups are allowed. Each on its own line. Groups which don’t exist in the database are ignored.

If true, Gerrit will load and execute rules.pl files in each project’s refs/meta/config branch, if present. When set to false, only the default internal rules will be used.

Default is true, to execute project specific rules.

If false Gerrit will not send email messages, for any reason, and all other properties of section sendemail are ignored.

By default, true, allowing notifications to be sent.

Designates what name and address Gerrit will place in the From field of any generated email messages. The supported values are:

By default, MIXED.

Hostname (or IP address) of a SMTP server that will relay messages generated by Gerrit to end users.

By default, 127.0.0.1 (aka localhost).

Port number of the SMTP server in sendemail.smtpserver.

By default, 25, or 465 if smtpEncryption is ssl.

Specify the encryption to use, either ssl or tls.

By default, none, indicating no encryption is used.

If false and sendemail.smtpEncryption is ssl or tls, Gerrit will not verify the server certificate when it connects to send an email message.

By default, true, requiring the certificate to be verified.

User name to authenticate with, if required for relay.

Password for the account named by sendemail.smtpUser.

If present, each value adds one entry to the whitelist of email addresses that Gerrit can send email to. If set to a complete email address, that one address is added to the white list. If set to a domain name, any address at that domain can receive email from Gerrit.

By default, unset, permitting delivery to any email address.

If true, new change emails and merged change emails from Gerrit will include the complete unified diff of the change. Variable maxmimumDiffSize places an upper limit on how large the email can get when this option is enabled.

By default, false.

Largest size of unified diff output to include in an email. When the diff exceeds this size the file paths will be listed instead. Standard byte unit suffixes are supported.

By default, 256 KiB.

If present, emails sent from Gerrit will have the given level of importance. Valid values include high and low, which email clients will render in different ways.

By default, unset, so no Importance header is generated.

If present, emails sent from Gerrit will expire after the given number of days. This will add the Expiry-Date header and email clients may expire or expunge mails whose Expiry-Date header is in the past. This should be a positive non-zero number indicating how many days in the future the mails should expire.

By default, unset, so no Expiry-Date header is generated.

If true the server checks the User-Agent HTTP header and sends the correct JavaScript to the client as part of the initial page load. This usually reduces a round-trip for the client, allowing the UI to start more quickly. If false, a tiny JavaScript loader is sent to the client instead to determine the correct code to use. Default is true.

If true the server checks the site header, footer and CSS files for updated versions. If false, a server restart is required to change any of these resources. Default is true, allowing automatic reloads.

If true the deprecated /query URL is available to return JSON and text results for changes. If false, the URL is disabled and returns 404 to clients. Default is true, enabling /query.

Specifies the local addresses the internal SSHD should listen for connections on. The following forms may be used to specify an address. In any form, :'port' may be omitted to use the default of 29418.

If multiple values are supplied, the daemon will listen on all of them.

+ To disable the internal SSHD, set listenAddress to off.

+ By default, *:29418.

Specifies the addresses clients should be told to connect to. This may differ from sshd.listenAddress if a firewall based port redirector is being used, making Gerrit appear to answer on port 22. The following forms may be used to specify an address. In any form, :'port' may be omitted to use the default SSH port of 22.

+

If multiple values are supplied, the daemon will advertise all of them.

+ By default, sshd.listenAddress.

If true, enables TCP keepalive messages to the other side, so the daemon can terminate connections if the peer disappears.

Only effective when sshd.backend is set to MINA.

By default, true.

Number of threads to use when executing SSH command requests. If additional requests are received while all threads are busy they are queued and serviced in a first-come-first-served order.

By default, 1.5x the number of CPUs available to the JVM.

Number of threads to allocate for SSH command requests from non-interactive users. If equals to 0, then all non-interactive requests are executed in the same queue as interactive requests.

Any other value will remove the number of threads from the queue allocated to interactive users, and create a separate thread pool of the requested size, which will be used to run commands from non-interactive users.

If the number of threads requested for non-interactive users is larger than the total number of threads allocated in sshd.threads, then the value of sshd.threads is increased to accommodate the requested value.

By default, 0.

Number of threads to use when formatting events to asynchronous streaming clients. Event formatting is multiplexed onto this thread pool by a simple FIFO scheduling system.

By default, 1 plus the number of CPUs available to the JVM.

Number of threads used to parse a command line submitted by a client over SSH for execution, create the internal data structures used by that command, and schedule it for execution on another thread.

By default, 2.

Maximum number of authentication attempts before the server disconnects the client. Each public key that a client has loaded into its local agent counts as one auth request. Users can work around the server’s limit by loading less keys into their agent, or selecting a specific key in their ~/.ssh/config file with the IdentityFile option.

By default, 6.

Time in seconds that a client has to authenticate before the server automatically terminates their connection. Values should use common unit suffixes to express their setting:

By default, 2 minutes.

Time in seconds after which the server automatically terminates idle connections (or 0 to disable closing of idle connections). Values should use common unit suffixes to express their setting:

By default, 0.

Maximum number of concurrent SSH sessions that a user account may open at one time. This is the number of distinct SSH logins that each user may have active at one time, and is not related to the number of commands a user may issue over a single connection. If set to 0, there is no limit.

By default, 64.

Available ciphers. To permit multiple ciphers, specify multiple sshd.cipher keys in the configuration file, one cipher name per key. Cipher names starting with + are enabled in addition to the default ciphers, cipher names starting with - are removed from the default cipher set.

Supported ciphers: aes128-cbc, aes128-cbc, aes256-cbc, blowfish-cbc, 3des-cbc, none.

By default, all supported ciphers except none are available.

Available MAC (message authentication code) algorithms. To permit multiple algorithms, specify multiple sshd.mac keys in the configuration file, one MAC per key. MAC names starting with + are enabled in addition to the default MACs, MAC names starting with - are removed from the default MACs.

Supported MACs: hmac-md5, hmac-md5-96, hmac-sha1, hmac-sha1-96.

By default, all supported MACs are available.

Enable kerberos authentication for SSH connections. To permit kerberos authentication, the server must have a host principal (see sshd.kerberosPrincipal) which is acquired from a keytab. This must be provisioned by the kerberos administrators, and is typically installed into /etc/krb5.keytab on host machines.

The keytab must contain at least one host/ principal, typically using the host’s canonical name. If it does not use the canonical name, the sshd.kerberosPrincipal should be configured with the correct name.

By default, not set and so kerberos authentication is not enabled.

If kerberos authentication is enabled with sshd.kerberosKeytab, instead use the given principal name instead of the default. If the principal does not begin with host/ a warning message is printed and may prevent successful authentication.

This may be useful if the host is behind an IP load balancer or other SSH forwarding systems, since the principal name is constructed by the client and must match for kerberos authentication to work.

By default, host/canonical.host.name

Enable (or disable) the '$site_path'/logs/sshd_log request log. If enabled, a request log file is written out by the SSH daemon.

By default, true.

If true, visible user accounts (according to the value of accounts.visibility) will be offered as completion suggestions when adding a reviewer to a change, or a user to a group.

If false, account suggestion is disabled.

Older configurations may also have one of the accounts.visibility values for this field, including OFF as a synonym for NONE. If accounts.visibility is also set, that value overrides this one; otherwise, this value applies to both suggest.accounts and accounts.visibility.

New configurations should prefer the boolean value for this field and an enum value for accounts.visibility.

The number of characters that a user must have typed before suggestions are provided. If set to 0, suggestions are always provided.

By default 0.

Background color for the page, and major data tables like the all open changes table or the account dashboard. The value must be a valid HTML hex color code, or standard color name.

By default white, FFFFFF.

This is the color of the main menu bar at the top of the page. The value must be a valid HTML hex color code, or standard color name.

By default white, FFFFFF.

Text color for the page, and major data tables like the all open changes table or the account dashboard. The value must be a valid HTML hex color code, or standard color name.

By default dark grey, 353535.

Primary color used as a background color behind text. This is the color of the main menu bar at the top, of table headers, and of major UI areas that we want to offset from other portions of the page. The value must be a valid HTML hex color code, or standard color name.

By default a light grey, EEEEEE.

Background color used within a trimColor area to denote the currently selected tab, or the background color used in a table to denote the currently selected row. The value must be a valid HTML hex color code, or standard color name.

By default a pale blue, D8EDF9.

Background color used for patch outdated messages. The value must be a valid HTML hex color code, or standard color name.

By default a shade of red, F08080.

Background color for tables such as lists of open reviews for odd rows. This is so you can have a different color for odd and even rows of the table. The value must be a valid HTML hex color code, or standard color name.

By default transparent.

Background color for tables such as lists of open reviews for even rows. This is so you can have a different color for odd and even rows of the table. The value must be a valid HTML hex color code, or standard color name.

By default transparent.

A prefix tag that identify the footer line to parse for tracking ids. Several trackingid entries can have the same footer tag. A single trackingid entry can have multiple footer tags. If multiple footer tags are specified, each tag will be parsed separately. (the trailing ":" is optional)

A standard Java regular expression (java.util.regex) used to match the external tracking id part of the footer line. The match can result in several entries in the DB. If grouping is used in the regex the first group will be interpreted as the tracking id. Tracking ids longer than 32 characters will be ignored.

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.

The name of the external tracking system (maximum 10 characters). It is possible to have several trackingid entries for the same tracking system.

Number of seconds to wait for a single network read or write to complete before giving up and declaring the remote side is not responding. If 0, there is no timeout, and this server will wait indefinitely for a transfer to finish.

A timeout should be large enough to mostly transfer the objects to the other side. 1 second may be too small for larger projects, especially over a WAN link, while 10-30 seconds is a much more reasonable timeout value.

Defaults to 0 seconds, wait indefinitely.

Name of the groups of users that are allowed to execute upload-pack on the server. One or more groups can be set.

If no groups are added, any user will be allowed to execute upload-pack on the server.

Name that Gerrit calls itself in Git when it creates a new Git commit, such as a merge during change submission.

By default this is "Gerrit Code Review".

Email address that Gerrit refers to itself as when it creates a new Git commit, such as a merge commit during change submission.

If not set, Gerrit generates this as "gerrit@hostname", where hostname is the hostname of the system Gerrit is running on.

By default, not set, generating the value at startup.

Username that is displayed in the Gerrit WebUI and in e-mail notifications if the full name of the user is not set.

By default "Anonymous Coward" is used.

Local filesystem directory holding the site customization assets. Placing this directory under version control and/or backup is a good idea.

Files in this directory provide additional configuration.

Other files support site customization.