Gerrit2 Git Replication
=======================

Gerrit can automatically push any changes it makes to its local Git
repositories to another system.  Usually this would be configured
to provide mirroring of changes, for warm-standby backups or a
load-balanced public mirror farm.

Typically replication should be done over SSH, with a passwordless
public/private key pair.  On a trusted network it is also possible to
use replication over the insecure (but much faster) git:// protocol,
by enabling the `receive-pack` service on the receiving system.

To enable push replication, create `'$site_path'/replication.config`
as a Git-style config file, then restart Gerrit.

Currently the replication runs on a 15 second delay.  This gives
Gerrit a short time window to batch updates going to the same
project, such as when a user uploads multiple changes at once.

An example configuration file to replicate in parallel to four
different hosts follows:

====
  [remote "host-one"]
    url = gerrit2@host-one.example.com:/some/path/${name}.git
    # push defaults to +refs/*:refs/*

  [remote "pubmirror"]
    url = mirror1.us.some.org:/pub/git/${name}.git
    url = mirror2.us.some.org:/pub/git/${name}.git
    url = mirror3.us.some.org:/pub/git/${name}.git
    push = +refs/heads/*
    push = +refs/tags/*
====

Within each url value the magic placeholder `$\{name}` is replaced
with the Gerrit project name.  This is a Gerrit specific extension
to the Git URL syntax.

Multiple URLs may be specified within a single remote block,
listing different destinations which share the same settings.

Most standard Git remote configuration settings can be used within
a remote block.  The `receivepack` option can be used to specify
the remote path to the `git-receive-pack` executable, if it is
not in the remote user's `PATH` by default.

One or more `push` entries may also be specified within a remote
block to select a subset of the refs for replication.  If no push
values are configured, a default of `+refs/\*:refs/*` is used.

As the above configuration uses SSH for both connections it also
relies upon having a `~/.ssh/config` file setup for the user
running Gerrit.  A matching configuration file might be:

====
  Host host-one.example.com:
    IdentityFile ~/.ssh/id_hostone
    PreferredAuthentications publickey
    BatchMode yes

  Host mirror*.us.some.org:
    User mirror-updater
    IdentityFile ~/.ssh/id_pubmirror
    PreferredAuthentications publickey
    BatchMode yes
====

Most (but not all) SSH options are honored:

 * Host
 * Hostname
 * User
 * Port
 * IdentityFile
 * PreferredAuthentications
 * BatchMode
 * StrictHostKeyChecking

SSH authentication must be by passwordless public key, as there is
no facility to read passphases on startup or passwords during the
SSH connection setup, and SSH agents are not supported from Java.

Host keys for any destination SSH servers must appear in the user's
`~/.ssh/known_hosts` file, and must be added in advance, before
Gerrit starts.  If a host key is not listed, Gerrit will be unable to
connect to that destination, and replication to that URL will fail.

Make sure you are replicating to a standard Git daemon or SSH
daemon, and not to another Gerrit's internal SSHD.