Receiving Repositories: How To Unpack

Ensure that the destination system has git-teleport installed. You can do without it if necessary, but it will make things much easier.

Creating New Receive Mirrors

While the bundle files are useful for transit, they are not a permanent home for your data. Each repository you mirror needs a corresponding repository on the receiving system. These repositories, which are called Receive Mirrors, are read-only mirrors. They are intended to represent the remote repositories just as if you had cloned them.

The Receive Mirrors are intended to be exact duplicates of the repositories on the sending side. Crucially, you MUST NOT let your users push novel commits to the Receive Mirrors. Receive Mirrors must be modified only with git-teleport. Failure to adhere to this requirement will cause problems.

You can keep your Receive Mirrors anywhere that Git can access, including your local disk, a shared filesystem, or behind a git remote accessible via SSH or HTTP(S). Wherever you keep them, you will need to set aside space in your hierarchy for these mirrors. If you usually store your repositories on NFS in /net/git, and the mirrored repositories originated from your corporate intranet, then a path of

/net/git/mirrors/intranet

might be appropriate.

Here, the mirrors directory is dedicated to Receive Mirrors only. This helps keep them separate from your normal, writable repositories that include original commits and content. The intranet subdirectory further segregates these mirrors from repositories that originate from other places, such as your corporate partners.

Once you have selected a storage location, you will need to create the Receive Mirror repositories.

Examine the directory of bundle files you created during the previous step. (If you compressed them, extract them.) In the root directory of the bundles, you will find a Beamupfile. This text file is automatically generated by git-teleport. Continuing with our example from above, you will find the following entries:

# GIT-TELEPORT BEAMUPFILE
# …
# This file was automatically generated by git-teleport.

ProjectAlpha.git
ProjectBravo.git
mysubfolder/ProjectCharlie.git

This file lists the repository names you must create. The names for these repositories on your system must match these strings exactly, including case. Continuing with the above example, you will need to create:

  • /net/git/mirrors/intranet/ProjectAlpha.git
  • /net/git/mirrors/intranet/ProjectBravo.git
  • /net/git/mirrors/intranet/mysubfolder/ProjectCharlie.git

Your repositories may or may not have the ".git" extension—this extension is optional. Use the same convention as the sender.

The creation instructions are different for repositories stored on your local filesystem versus on SSH/HTTP(S) network remotes. Follow the instructions in the applicable sub-section.

Receive Mirrors on Local Filesystem

This includes shared filesystems, like NFS or SMB.

git teleport skeleton \
  /net/git/mirrors/intranet/ProjectAlpha.git \
  /net/git/mirrors/intranet/ProjectBravo.git \
  /net/git/mirrors/intranet/mysubfolder/ProjectCharlie.git

The skeleton command will create the above repositories, if they don't already exist, and configure them for use with git-teleport. This script takes the following actions:

  1. Creates the repository in --bare mode
  2. git config core.sharedRepository true, which helps with linux permission issues on shared folders
  3. Adds a pre-receive hook which denies pushes from clients other than git teleport. This helps prevent accidental pushes.
  4. Adds a teleport-mirror file to the root of the repository directory. This file tells git-teleport that the repository is safe to use for mirroring.

If this command succeeds, you are ready to go.

Receive Mirrors on Remote Server

You can store your repositories on a "smart" server, like Gitlab, or on a "dumb" directory over SSH. The important difference from "local filesystem" mode is:

THE NAMING CONVENTION IS MANDATORY, and git-teleport will enforce it.

  • ✔ git@mygitlab:mirrors/intranet/ProjectAlpha.git
  • ✔ https://mygitlab/git/mirror/intranet/ProjectAlpha.git
  • ✖ git@mygitlab:mystuff/ProjectAlpha.git (invalid)

Your Receive Mirrors must be stored in a subdirectory named either "mirror" or "mirrors" (plural), exactly. It does not matter which path component is named "mirrors." Regardless of which variation you choose, it is vital that you keep only Receive Mirrors in the mirrors/ directory.

We also recommend that you use a subdirectory like mirrors/intranet, in case other sites also start sending you teleport bundles.

  • If you have access to the remote filesystem, you can use git teleport skeleton as above.

  • If you are using a smart host, like Gitlab, you must create the repositories yourself via your smart host's UI. Create an empty repository, without a README file or other templates. Everyone who updates bundles must have write permission.

Smart repository hosts might restrict push access to certain branches, like master or develop. This will prevent you from receiving updates. To avoid these restrictions on Gitlab, ensure that there are no protected branches or other push rules. Gitlab will usually auto-protect these branches after the first git-teleport update. Be sure to check the settings page after your first update and unprotect all branches.

git-teleport will set the CONFIRM_MIRROR_UPDATE push option when pushing to its mirrors. If your repo hosting software permits it, you may want to require this push option to prevent accidental updates to the mirrors.

Unpacking the Bundles

Now that your Receive Mirrors exist, it's time to put them to use. Change directory to the location of your bundle files and run:

cd path/to/bundle/files    # must contain a Beamupfile
git teleport unpack /net/git/mirrors/intranet

The argument to unpack is the URL or path prefix where your Receive Mirrors are stored.

Alternatively, you may run

git teleport unpack path/to/bundle/files /net/git/mirrors/intranet

without changing directory.

When this command completes successfully, the repositories in mirrors/intranet will be exact duplicates of the sending side. They will have all branches, tags, and notes—just as they are in the upstream repository.

If git-teleport reports an error, your repositories haven't been completely mirrored. See "Troubleshooting."