howto/git.md

@@ -342,6 +342,63 @@ It assumes the repository has already been migrated.
          
          repo debian/torproject-keyring
 
+## Destroying a repository
+
+Instead of migrating a repository to GitLab, you might want to simply
+get rid of it. This can be relevant in case the repository is a
+duplicate, or it's a fork and all branches were merged, for example.
+
+We generally prefer to archive repositories that said, so in general
+you should follow the [migration procedure](#migrating-a-repository-to-gitlab) instead.
+
+To destroy a repository:
+
+ 1. [file a ticket with TPA](https://gitlab.torproject.org/tpo/tpa/team/-/issues/new) to request the destruction of the
+    repository or repositories. make sure to explain why you believe
+    the repositories can be destroyed.
+
+ 2. if you're not TPA, you're done, wait for a response or requests
+    for clarification. the rest of this procedure is relevant only
+    for TPA
+
+ 3. if you're TPA, examine the request thoroughly. make sure that:
+
+    1. the GitLab user requesting the destruction has access to the
+       Gitolite repository. normally, usernames should generally
+       match as LDAP users were imported when GitLab was created, but
+       it's good to watch out for [homograph attacks][], for example
+
+    2. there's a reasonable explanation for the destruction, e.g. that
+       no important data will actually be lost when the repository is
+       destroyed
+
+ 3. install a redirection and schedule destruction of the repository,
+    with the command:
+
+        fab -H cupani.torproject.org gitolite.destroy-repo --issue-url=$URL $REPOSITORY
+
+    for example, this is how the `user/nickm/githax` repository was
+    disabled and scheduled for destruction:
+
+        anarcat@angela:tsa-misc$ fab -H cupani.torproject.org gitolite.destroy-repo --issue-url='https://gitlab.torproject.org/tpo/tpa/team/-/issues/41189' user/nickm/githax
+        INFO: preparing destroying of Gitolite repository user/nickm/githax in /srv/git.torproject.org/repositories/user/nickm/githax.git
+        INFO: uploading 468 bytes to /srv/git.torproject.org/repositories/user/nickm/githax.git/hooks/pre-receive
+        INFO: making /srv/git.torproject.org/repositories/user/nickm/githax.git/hooks/pre-receive executable
+        INFO: scheduling destruction of /srv/git.torproject.org/repositories/user/nickm/githax.git in 30 days on cupani.torproject.org
+        INFO: scheduling rm -rf "/srv/git.torproject.org/repositories/user/nickm/githax.git" to run on cupani.torproject.org in 30 days
+        warning: commands will be executed using /bin/sh
+        job 2 at Sat Jul  8 14:57:00 2023
+        INFO: scheduling destruction of /srv/gitweb.torproject.org/repositories/user/nickm/githax.git in 30 days on vineale.torproject.org
+        INFO: scheduling rm -rf "/srv/gitweb.torproject.org/repositories/user/nickm/githax.git" to run on cupani.torproject.org in 30 days
+        warning: commands will be executed using /bin/sh
+        job 3 at Sat Jul  8 14:57:00 2023
+        INFO: now modify gitolite.conf to add "config gitweb.category = Scheduled for destruction"
+
+ 4. as noted in the last line, change the `gitolite.conf` file to move
+    the project to the `Scheduled for destruction` category
+
+[homograph attacks]: https://en.wikipedia.org/wiki/IDN_homograph_attack
+
 ## Mirroring a gitolite repository to GitLab
 
 This procedure is DEPRECATED. Instead, consider [migrating the