GitHub Replication Configuration

Initial configuration (required once)

  1. Hiera configuration:

        config_file: '/opt/gerrit/etc/replication.config'
        mode: '0644'
            # ORG == the Org on GitHub
            # ${name} is literal and should exist in that format
            url: '${name}.git'
              - '+refs/heads/*:refs/heads/*'
              - '+refs/heads/*:refs/tags/*'
            timeout: '5'
            threads: '5'
            authGroup: 'GitHub Replication'
            remoteNameStyle: 'dash'
  2. If a $PROJECT-github account does not exist on GitHub, create it, setup 2-factor authentication on the account, and add the recovery tokens to LastPass. The email for the account should be to collab-it+$

  3. Copy the public SSH key for the ‘gerrit’ user into the GitHub account

  4. On the Gerrit Server do the following:

    # create 'root' shell
    sudo -i
    # create 'gerrit' shell
    sudo -iu gerrit
    # Add the server key to gerrit's known_hosts file
    ssh-keyscan -t rsa >> ~/.ssh/known_hosts
    # exit from 'gerrit' shell
    # restart Gerrit so that SSH changes are properly picked up
    systemctl restart gerrit
    # exit from 'root' shell
  5. Add the account to the GitHub Organization as a Member

  6. Configure the Organization with the following options:

    1. Members cannot create repositories

    2. Members cannot delete or transfer repositories

    3. Set the default repository permission to Read

    4. Require 2FA (Two Factor Authentication) for everyone

  7. Create a Replication team in the organization and add the $PROJECT-github account

  8. In Gerrit create a ‘GitHub Replication’ group that is empty

  9. Set the following ACL on the All-Projects repository

        DENY: GitHub Replication

Repository replication setup (repeat for each repository)


After initial setups, descibed above gerrit project creation, github repo creation and gerrit replication are now done with lftools commands.

To create_repo, clone_repo, create_groups_file and add_gitreview:


To create a github repo:

lftools github create-repo --sparse ORGANIZATION REPOSITORY DESCRIPTION

To enable replication:

lftools gerrit create --enable GERRIT_URL LDAP_GROUP REPO USER

Manual Process

Perform the following in each repository mirrored from Gerrit

  1. Create the repository in the GitHub organization replacing any occurrence of ‘/’ with ‘-‘ as ‘/’ is an illegal character for GitHub repositories.

  2. Add the Replication Team to the repository with write privileges

  3. In Gerrit add the following ACL

        ALLOW: GitHub Replication
  4. Perform initial code drop

    The initial code drop must be present before you enable Gerrit replication for a repository.

  5. Enable repo replication

    To enable replication for a single repo:

    ssh -p 29418 ${youruid}@${project_gerrit} replication start --wait --url ${repo_url}

    To enable replication for more than one repo:

    ssh -p 29418 ${youruid}@${project_gerrit} replication start --all --wait
  6. Watch GitHub to see if the repo starts to replicate, if not troubleshoot by looking at ~gerrit/logs/replication*