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