Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 Server Administration Documentation | 2025.2

# Git Connector configuration for failover to another Git host

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

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 P4 Server (recommended), the same machine as a Git server (also recommended), or the machine with P4 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 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 P4 Server, it reconfigures repo spec 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 P4 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.

The secret token is also included in the repo spec on the P4 Server. To write the repo spec to standard output, run:

p4 repo -o {//graphDepotName/repoName}

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

- GitHub or GitLab HTTP
- GitHub or GitLab SSH
- Configure Gerrit for HTTP
- Configure Gerrit for SSH
- Perforce TeamHub HTTP
- Perforce TeamHub SSH

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.

Your search for returned results