From a8140794de464083f03a66e009a3f987e3332416 Mon Sep 17 00:00:00 2001
From: Thomas Rushby <twr1m15@soton.ac.uk>
Date: Mon, 7 Feb 2022 11:25:32 +0000
Subject: [PATCH] New file: mirroring repositories

---
 howTo/mirroringRepositories.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 howTo/mirroringRepositories.md

diff --git a/howTo/mirroringRepositories.md b/howTo/mirroringRepositories.md
new file mode 100644
index 0000000..2e24d07
--- /dev/null
+++ b/howTo/mirroringRepositories.md
@@ -0,0 +1,24 @@
+# Mirroring repositories in Gitlab
+
+Author: Tom Rushby (@tom_rushby)
+
+Gitlab has a useful page on mirroring: https://docs.gitlab.com/ee/user/project/repository/mirror/
+
+## Gitlab to GitHub mirror
+
+i.e. you want to create a copy of a repository in the University Git service on GitLab.
+
+In this case we create a *push mirror*: a downstream repository (on GitHub) that mirrors the commits made to the upstream repository (on Gitlab).
+
+Creating a mirror allows a repository with restricted access to be publically availble (and backed-up on another platform), as well as taking advantage of functionality on GitHub such as pages (currently not available on the Univeristy implementation of GitLab).
+
+It's not terribly clear on the page linked above, but you will need to generate an Access Token within your GutHub account. This will be use as the password in the mirroring section of the repo on GitLab (git.soton.ac.uk). https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
+
+## Step-by-step
+
+1. Create a clean (target, or 'downstream') repository in your GitHub account. I use the identical name as the repo in GitLab and add (mirror) in the description to indicate that it is a mirrored copy.
+2. Copy the https URL to the repo e.g. `https://github.com/mygitaccount/myrepo`
+3. In the **Gitlab** (source, or 'upstream') repository to be mirrored, goto > `Settings` > `Repository` and expand the `Mirrroring repositories` section. Enter the GitHub repo URL but in the format `https://gitusername@github.com/gitusername/reponame`.
+4. Go back to **GitHub** and and [create a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). In the top right corner. click your profile photo, and click **Settings**. On the Settings page, click **Developer settings** (at the bottom of the left-hand sidebar). Click **Personal access tokens** in the left sidebar and then **Generate new token**. When generating the access token you will need to tick the boxes to allow "repo" and "workflow" permissions. Once complete, copy the access token to the clipboard.
+5. Now in **Gitlab**, paste the access token into the **Password** field and click the **Mirror repository** button. The repository should now appear in the Mirrored repositories list with 'Push' as the direction. Each time a commit is made to your Gitlab repository  it will be automatically pushed to the mirrored repository downstream. Clicking the 'Update now' button in the right-hand column of the list will force the push and is useful to test the process when setting up. If the process fails, errors will be shown in the list under 'Last successful update'.
+6. Commit to your Gitlab repo and watch your GitHub copy update automatically. Magic!
-- 
GitLab