GitBucket Mirror Plugin

This plugin adds repository mirroring to Gitbucket.

This plugin allows repository owners to configures mirrors for their repositories. The mirrors are copies of the repositories that are kept updated automatically thanks to a post-receive hook executing the equivalent of a git push --mirror command. Therefore, every reference (commits, tags and branches) pushed to a repository will be propagated to its mirrors.

A typical use case occurs when a user or an organization wants to use a GitBucket instance as the main Git repository hosting service, while keeping read-only updated copies of the repositories on Github, for example to improve the visibility of the repositories among the open source community.

Installation

Download the jar file from the release page and copy it under the plugins directory of your GitBucket instance ($GITBUCKET_HOME/plugins).

Usage

The plugin adds a section entitled Mirrors to the side menu of every repository hosted on a GitBucket instance. Once authenticated, repository owners and administrators can use this section to add new mirrors and modify or delete existing ones. It is also possible to update a mirror manually and to disable automatic updates.

The plugin will report the status of the last update. If the mirror has diverged from the original repository, it is likely that the update will fail. In this case, you should first deal with the divergence before expecting a successful update. In principle, you should keep the mirror repository read-only in order to avoid this kind of issues.

Creating a new mirror

As an example, let's consider the creation of a mirror on Github for a repository hosted on GitBucket.

First, you must create the mirror repository on Github as a new empty repository. Let's assume that the new mirror is located at a URL alike https://github.com/username/repos.git.

Then, you can go to the Mirrors view of your repository on GitBucket and click on the New Mirror button. Choose a name for the new mirror and enter its URL in the dedicated input field. If you need credentials, you should provide the username in the URL, as in https://username@github.com/username/repos.git and the password in the dedicated form input located below the URL.

Submit the new mirror and every push received by your repository on GitBucket will now be propagated to the mirror on Github.

SSH support

It is also possible to use the SSH protocol instead of HTTP. Again, you need to provide the credentials in the URL to perform authentication (the password can also be provided in the password input field).

If you are rather using a public/private key system, you can use the environment variable MIRROR_SSH_PRIVATE_KEYS to specify a semicolon separated list of locations where GitBucket will be able to find your private key (e.g. ~/private_key1;~/private_key2). you should not need to set this environment variable if your private key is located at a standard location such as ~/.ssh/id_rsa. Note that passphrase protected private keys are not supported.

You will also need to setup host keys for the SSH connexion to succeed. If needed, you can use the environment variable MIRROR_SSH_HOST_KEYS to specify a custom location for your host keys. One way to setup host keys is to use the ssh-keyscan tool provided by the OpenSSH client:

ssh-keyscan -t ssh-rsa github.com >> ~/.ssh/known_hosts

Compatibility

Release Notes

1.4.1

• Fix NullPointerException during plugin initialization.

1.4.0

• Support GitBucket 4.37.x.

1.3.0

• Support GitBucket 4.35.0.

1.2.0

• Bump to GitBucket 4.34.0.
• Pull request hook support.
• Enable GitHub Actions.

1.1.1

• Add a form input field for password.

1.1.0

• Bump to GitBucket 4.32.0.

1.0.2

• Add SSH protocol support.
• Improve documentation in README file.

1.0.1

• Fix bug about deleted references not being propagated.
• Choose a more appropriate menu icon.
• Improve README file.

1.0.0

• Initial release.