README.md

   1 # git-mirror: Sync your git repositories
   2
   3 ## Introduction
   4
   5 [git-mirror](https://www.ralfj.de/projects/git-mirror) is a tool to keep
   6 multiple git repositories of the same project in sync. Whenever something is
   7 pushed to any repository, the commits will immediately be forwarded to all the
   8 others. The tool assumes to run on a server hosting one of these repositories -
   9 so there has to be at least one you can control. A typical use-case would be
  10 your own [gitolite](http://gitolite.com/gitolite/index.html) installation, that
  11 you want to keep in sync with [GitHub](https://github.com/).
  12
  13 ## Setup (gitolite)
  14
  15 This describes how you set up git-mirror on a server running gitolite. For other
  16 git hosting software, please consult the respective documentation on adding git
  17 hooks. I will assume that gitolite is installed to `/home/git/gitolite`, that
  18 the repositories are sitting in `/home/git/repositories`, and that git-mirror
  19 has been cloned to `/home/git/git-mirror`.
  20
  21 First of all, you need to create a file called `git-mirror.conf` in the
  22 `git-mirror` directory. For now, it only needs to contain a single line:
  23
  24     mail-sender = git@example.com
  25
  26 We will also need to add hooks to the git repositories you want to sync. The
  27 easiest way to manage these hooks is to put them into your `gitolite-admin`
  28 repository, so enable the following line in `/home/git/.gitolite.rc`:
  29
  30     LOCAL_CODE                =>  "$rc{GL_ADMIN_BASE}/local",
  31
  32 Make sure you read the [security note](http://gitolite.com/gitolite/non-core.html#pushcode)
  33 concerning this configuration.
  34
  35 Now add a file called `local/hooks/repo-specific/git-mirror` to your
  36 `gitolite-admin` repository, make it executable, and give it the following
  37 content:
  38
  39     #!/bin/sh
  40     exec ~/git-mirror/githook.py
  41
  42 For every repository you want to be synced, you can enable the hook by adding
  43 the following line to its configuration in `conf/gitolite.conf`:
  44
  45     option hook.post-receive = git-mirror
  46
  47 (If you need multiple hooks here, you can separate them by spaces.)
  48
  49 Finally, you need to tell git-mirror where to sync incoming changes to this
  50 repository to. Add a block like the following to `git-mirror.conf`:
  51
  52     [repo-name]
  53     owner = email@example.com
  54     local = /home/git/repositories/repo-name.git
  55     deploy-key = ssh-key
  56     mirror-a = git@server2.example.com:repo-name.git
  57     mirror-b = git@server2.example.org:the-repo.git
  58
  59 Here, `local` has to be set to the path where the repository is stored
  60 locally. `deploy-key` is the name of the SSH key used for pushing the changes
  61 to other repositories. `owner` is the e-mail-address that errors occurring
  62 during synchronization are sent to. And finally, the URLs to push to are given
  63 by `mirror-<something>`. If these other servers also run gitolite and have a
  64 symmetric setup, then no matter where a change is pushed, git-mirror will
  65 forward it to all the other repositories.
  66
  67 ## Setup (GitHub)
  68
  69 If one of the to-be-synced repositories is on GitHub, you can obviously not use
  70 the procedure above to sync changes that are arriving at GitHub, to the other
  71 repositories. Instead, we will use a webhook, such that GitHub tells your server
  72 that a change happened, and then your server can pull the changes to its local
  73 repository and synchronize all the others. This assumes that the server running
  74 the webhook also hosts one of the copies of the git repository.
  75
  76 First of all, you will have to configure your webserver to run `webhook.py` as
  77 CGI script. Consult the webserver documentation for more details.
  78
  79 Secondly, `webhook.py` needs to be able to find the main git-mirror scripts,
  80 and it needs to be able to execute them as the `git` user. For the first
  81 point, open `webhook.py` and change `webhook_core` to point to the file
  82 `webhook-core.py` in your git-mirror clone. If your installation matches the
  83 paths I used above, that should already be the case. For the second point,
  84 `webhook.py` is using `sudo` to elevate its privileges. You need to tell
  85 `sudo` that this is all right, by creating a file
  86 `/etc/sudoers.d/git-mirror` with content:
  87
  88     www-data        ALL=(git) NOPASSWD: /home/git/git-mirror/webhook-core.py
  89
  90 Now, if you visit `https://example.com/git-mirror/webhook.py` (replace with
  91 your URL), the script should run and tell you `Repository missing or not
  92 found.`.
  93
  94 The next step is to add this as a webhook to the GitHub repository you want to
  95 sync with, to create a fresh SSH key and configure it as deployment key for the
  96 repository, and to configure git-mirror accordingly. For additional security,
  97 one should also configure a shared HMAC secret, such that the webhook can verify
  98 that the data indeed comes from GitHub.
  99
 100 To make your job easier, there is a script `github-add-hooks.py` that can do
 101 all this for you. It assumes that the repository exists on the GitHub side, but
 102 has not yet been configured for git-mirror at all.
 103
 104 To give the script access to your repositories, you need to create an access
 105 token for it. Go to "Personal Access Tokens" in your GitHub configuration, and
 106 create a new token with the permissions `admin:repo_hook` and `public_repo`.
 107 Add the token and the webhook URL to the top part of `git-mirror.conf` (right
 108 below `mail-sender`):
 109
 110     github-token = pastethetokenhere
 111     webhook-url = https://example.com/git-mirror/webhook.py
 112
 113 Now you can call the automatic setup script as follows:
 114
 115     ./github-add-hooks.py -o UserName -e email@example.com \
 116       -l ~/repositories/repo-name.git/ -n github-repo-name
 117
 118 Notice that the username is case-sensitive! This will do all the setup
 119 on the GitHub side, and it will add an appropriate configuration block
 120 to your local `git-mirror.conf`. You still have to manually add the
 121 local git hook to gitolite. Once you are done, any push happening to
 122 either gitolite or GitHub will be visible on the other side
 123 immediately. This applies even to pull requests that you merge in the
 124 GitHub web interface.
 125
 126 ## Source, License
 127
 128 You can find the sources in the [git
 129 repository](https://git.ralfj.de/git-mirror.git) (also available
 130 [on GitHub](https://github.com/RalfJung/git-mirror)).  Guess what, the
 131 two are synced with this tool ;-) . They are provided under a
 132 [2-clause BSD
 133 license](http://opensource.org/licenses/bsd-license.php). See the file
 134 `LICENSE-BSD` for more details.
 135
 136 ## Contact
 137
 138 If you found a bug, or want to leave a comment, please [send me a
 139 mail](mailto:post-AT-ralfj-DOT-de). I'm also happy about pull requests
 140 :)