howto/git.md

@@ -562,6 +562,56 @@ This procedure is kept for historical purposes only.
     In that example, the `translation.git` repository will push to the
     `tpo/web/translation` mirror.
 
+## Mirroring a private git repository to GitLab's
+
+If a repository is, for some reason (typically security), not hosted
+on GitLab, it can still be mirrored there. A typical example is the
+Puppet repository (see [TPA-RFC-76](https://gitlab.torproject.org/tpo/tpa/team/-/wikis/policy/tpa-rfc-76-puppet-merge-request-workflow)). To mirror the repository, you
+need (make sure to run this as the user which hosts the repository,
+typically `git`):
+
+ 1. create the repository in GitLab, possibly private itself (but
+    sometimes it's fine if it's public as well)
+
+ 1. add the GitLab remote on the private repository:
+
+        git remote add origin ssh://git@gitlab.torproject.org/tpo/tpa/account-keyring.git
+
+ 2. create a deploy key on the server:
+
+        ssh-keygen -t ed25519
+
+ 4. add the deploy key to the repository, in Settings, Repository,
+    Deploy keys, make sure it has write access, and name it after the
+    user on the mirrored host (e.g. `git@alberti.torproject.org` in
+    this case)
+
+ 5. protect the branch, in Settings, Repository, Protected branches:
+
+    - Allowed to merge: no one
+    - Allowed to push and merge: no one, and add the deploy key
+
+ 6. disable merge requests (in Settings, General) or set them to be
+    "fast-forward only" (in Settings, Merge requests)
+
+ 7. on the mirrored repository, add a `post-receive` hook like:
+
+```
+#!/bin/sh
+
+echo "Pushing to GitLab..."
+git push --mirror
+```
+
+    If there's already a `post-receive` hook, add the `git` command to
+    the end of it.
+
+ 8. Test pushing to the mirrored repository, commits should end up on
+    the GitLab mirror.
+
+See also [#41977](https://gitlab.torproject.org/tpo/tpa/team/-/issues/41977) for an example where multiple repos were
+configured as such.
+
 ## Archiving a repository
 
 IMPORTANT: this procedure is DEPRECATED. Repositories archived on