Git Connector configuration for failover to another Git host

Git Connector can mirror from a Git server, such as GitLab, GitHub, Gerrit, or Helix TeamHub. If that Git server becomes unavailable, the Git Connector supports the manual configuration of mirroring from the failover server.

Note
  • The two Git servers should be replicas of each other.
  • The Git Connector can run on a machine separate from the Git server and the Helix Core Server (recommended), the same machine as a Git server (also recommended), or the machine with Helix Core Server (not recommended).
  • Perforce has tested failover with GitLab and Gerrit.

Procedure

To perform a failover of the third-party Git server that the Git Connector fetches from, use the Helix Git Connector setremote command.

We recommend you first use this command with the -n option:

gconn --mirrorhooks -n setremote oldUrl newUrl

where

  • oldUrl is a pattern that matches the primary Git server URL for a set of one or more repos
  • newUrl is replacement pattern containing the failover or secondary server URL, such that all mirrored repos with MirroredFrom URLs matching the oldUrl pattern will be modified by substitution
  • -n displays in preview mode the names of the repos that would be affected, but does not perform the operation

To perform the operation, omit the -n option:

gconn --mirrorhooks setremote oldUrl newUrl

Example

  1. Set the environment variable GCONN_CONFIG to the absolute path to the gconn.conf file:

    export GCONN_CONFIG=/opt/perforce/git-connector/gconn.conf

  2. Run the list command to see the names of repos that are associated with webhooks:

    gconn --mirrorhooks list

    The output might be:

    gconn --mirrorhooks list
    //graphDepot/project1 <<< http://primaryGitHost/hth/projects/support/repositories/git/project1.git
//graphDepot/project2 <<< http://primaryGitHost/hth/projects/support/repositories/git/project2.git  ... Not mirrored by this Gconn instance ( no mirror config )
//graphDepot/project3 <<< http://primaryGitHost/hth/projects/support/repositories/git/project3.git ... Not mirrored by this Gconn instance ( no mirror config )

  3. Include the -n option to see what the effect would be:

    gconn -n --mirrorhooks setremote https://primaryGitHost https://secondaryGitHost 

    This is a report of a trial run. No MirroredFrom urls are changed.
Execute without the '-n' option to update the urls.
//graphDepot/project1: updating remote url from http://primaryGitHost/hth/projects/support/repositories/git/project1.git
to git@http://secondaryGitHost/hth/projects/support/repositories/git/project1.git

    The screen output indicates this is merely a test:

  4. To run the command that switches to the secondary server, omit the -n option:

    gconn --mirrorhooks setremote https://primaryGitHost https://secondaryGitHost

  5. Run the list command again to list the repos that now need to be associated with webhooks:

    gconn --mirrorhooks list

    The output is:

    gconn --mirrorhooks list
    //graphDepot/project1 <<< http://secondaryGitHost/hth/projects/support/repositories/git/project1.git
//graphDepot/project2 <<< http://primaryGitHost/hth/projects/support/repositories/git/project2.git  ... Not mirrored by this Gconn instance ( no mirror config )
//graphDepot/project3 <<< http://primaryGitHost/hth/projects/support/repositories/git/project3.git ... Not mirrored by this Gconn instance ( no mirror config )

Effect

The setremote command affects both the Git Connector server and the Graph Depot server:

  • On the Git Connector server, it reconfigures the .mirror.config file to point to the failover URL as the "upstream_url".
  • On the Git Connector server, it reconfigures the upstream fetch URL of repo's cached git repository.

  • On the Helix Server, it reconfigures the repo spec so that the MirroredFrom: field points to the failover URL.

Command-line Help

To get command-line Help on the setremote command, at your Git Connector command line, type

gconn --help

You will see, in addition to the explanations of the commands for add, remove, and list, an explanation of the setremote command.

Next Steps

First, configure the failover third-party Git server with a web hook for each repo that you want to mirror.

Note

You can reuse the same secret token that is in the repository's .mirror.config file.

For detailed steps on how to set up the web hook, see the instructions that match your situation:

Finally, push to the currently active Git server and verify that the webhook causes the Git Connector to fetch the change so that Git Connector mirrors the change into a repo.