update gitea docs and add diagram

Author: rkm

docs/safe-haven-services/code-management-mirroring-service.md

@@ -32,32 +32,84 @@ Access must be requested from your Research Coordinator (RC). On being granted a
 - Gitea URL
 - Username
 - Initial Password
+- Whether egress mirroring is enabled
 
 Gitea can be accessed from your VM desktop by opening a Web Browser and navigating to the provided URL. After logging in for the first time, you will be prompted to change your password.
 
 Once logged-in, you will be presented with a dashboard showing recent activity in your organization. In Gitea, an "organization" is analagous to a project group, and you will be automatically granted access to the organization matching your TRE project identifier.
 
 ## Request a Repository
 
-To request the creation of a repository in your organization, contact your RC and let them know the desired name. Multiple repositories may be created under each organization.
+To request the creation of a repository in your organization, contact your RC and let them know the desired name and external mirror repository, if applicable. The external repository must be empty, as any existing content will be overwritten by the mirroring process.
 
 Once created, your repository will be visible from your Gitea dashboard or under the "Explore" tab.
 
 !!! note "Repository Permissions"
     All members of an organization (TRE project) have full read/write access to each of its repositories, regardless of who requested its creation. This is the intended behaviour and will not be changed e.g., to restrict repository access to a subset of a TRE project's members. This is equivalent to the files in each `/safe_data/<project_id>` directory being accessible to all project members.
 
+Multiple repositories may be created under each organization.
+
 ## Clone a Repository
 
 SSH access is not enabled, so HTTPS must be used to clone repositories.
 
-When running `git clone`, `git fetch`, and `git push`, you will be prompted for your Gitea username and password each time. For convenience, you may wish to generate an access token to avoid re-entering your credentials on each operation. To do this:
+When running `git clone`, `git pull`, and `git push`, you will be prompted for your Gitea username and password each time. For convenience, you may wish to generate an access token to avoid re-entering your credentials after the initial clone. To do this:
 
-1. Click your profile picture in the top right and then on Settings
-1. Click Applications in the sidebar
+1. In Gitea, click your profile picture in the top right and then on "Settings"
+1. Click "Applications" in the sidebar
 1. Create a new token
     1. Enter a descriptive name
     1. Expand "Select permissions" and change "repository" to "Read and Write"
+    1. Copy the generated token
 1. Clone the repo using the token, for example `git clone https://<token>@<url>/<organization>/<repo>.git`
+    1. Note that in the test environment you will have to use "http" instead of "https"
+
+## Request Code Egress
+
+Egress mirroring is achieved through merging of code into a branch named `egress-mirror`. This is pre-created and will contain the same initial commit as the `main` branch.
+
+If enabled, you may submit Pull Requests (PRs) for code to be mirrored to a repository external to the TRE:
+
+1. From the repository page in Gitea, click "Pull Request"
+1. Click "New Pull Request"
+1. Click "merge into" and select the "egress-mirror" branch. This should cause the page to refresh and show the changes that will be requested
+1. Click "New Pull Request"
+1. Create the PR
+    1. Provide a descriptive title
+    1. Describe the changes that are being made, and any notes for reviewers
+    1. Click the cog next to "Reviewers" in the right sidebar and select the RCs group for your project (`<project-id>/RCs`)
+    1. Click "Create Pull Request"
+1. External email notifications are not enabled, so contact your RC via normal channels to make them aware of the PR
+
+By default, PRs require approval from 2 RCs. Once approved and merged, the code changes will be automatically mirrored to the external repository.
+
+!!! note "Squashed Commits"
+    By default, all commits in a PR are "squashed" into a single commit on the mirror branch. This is to help ensure that any intermediate history containing potentially unwanted changes are not accidentally mirrored to the external repository.
+
+### Branching Workflow
+
+It is permitted for other branches and PRs to be created, to support standard software development practices. We suggest the following branching workflow, which uses feature branches and a periodic merge of main into the mirror branch.
+
+```mermaid
+---
+config:
+  gitGraph:
+    mainBranchOrder: 1
+---
+gitGraph title Git Branch Workflow for Egress Mirroring
+  checkout main
+  commit id: "Initial commit"
+  branch egress-mirror order: 2
+  commit id: "-"
+  checkout main
+  commit id: "1"
+  branch my-branch order: 0
+  commit id: "2"
+  checkout main
+  merge my-branch
+  checkout egress-mirror
+  merge main tag: "3"
+```
 
 ## Further Reading and Help