From 40000df3559e7a1d0cba7f867f775b617613c0b0 Mon Sep 17 00:00:00 2001
From: Kristal Dale <kristal.dale@intel.com>
Date: Fri, 7 Feb 2020 14:25:29 -0800
Subject: [PATCH] Add new page to Developer Resources section

Add a new page with instruction on how to mirror an OpenDev
repo to GitHub.

Patchset 5: Apply reST formatting and basic editorial for consistency.

Change-Id: Ib0d7784937da36557d4c365a758dde27534074e7
Signed-off-by: Kristal Dale <kristal.dale@intel.com>
---
 doc/source/developer_resources/index.rst      |   1 +
 .../developer_resources/mirror_repo.rst       | 102 ++++++++++++++++++
 2 files changed, 103 insertions(+)
 create mode 100644 doc/source/developer_resources/mirror_repo.rst

diff --git a/doc/source/developer_resources/index.rst b/doc/source/developer_resources/index.rst
index 1c72d3c7d..88c343eb6 100644
--- a/doc/source/developer_resources/index.rst
+++ b/doc/source/developer_resources/index.rst
@@ -12,5 +12,6 @@ Developer Resources
    architecture_docs
    starlingx_patching
    move_to_new_openstack_version_in_starlingx
+   mirror_repo
    Project Specifications <https://docs.starlingx.io/specs/>
 
diff --git a/doc/source/developer_resources/mirror_repo.rst b/doc/source/developer_resources/mirror_repo.rst
new file mode 100644
index 000000000..32b271a48
--- /dev/null
+++ b/doc/source/developer_resources/mirror_repo.rst
@@ -0,0 +1,102 @@
+=============================
+Mirror OpenDev Repo to GitHub
+=============================
+
+This section describes the steps to create a Zuul job to sync an OpenDev
+repository to a GitHub repository.
+
+.. contents::
+   :local:
+   :depth: 1
+
+----------------------------------------------------
+Create Zuul job to sync OpenDev repository to GitHub
+----------------------------------------------------
+
+#. Prepare GitHub repository.
+
+   #. Create a new repository under github.com/starlingx. If possible, use the
+      same repository name as original OpenDev repository.
+
+   #. Grant 'write' permission to the starlingx-github user. Zuul will use the
+      starlingx-github user to sync the repository.
+
+#. Generate an SSH key.
+
+   Zuul is needed to generate an SSH key. Refer to the
+   `Zuul Quick-Start <https://zuul-ci.org/docs/zuul/tutorials/quick-start.html>`_
+   for Zuul installation instructions.
+
+   From a server that has the Zuul tool installed, run the following command,
+   where <repo> is the name of the repository. The SSH key is at the end of the
+   output after <fieldname>: tag.
+
+   .. code-block:: yaml
+
+      zuul/tools/encrypt_secret.py --infile ./starlingx.github@gmail.com --strip --tenant \
+      openstack https://zuul.opendev.org starlingx/<repo>
+
+      writing RSA key
+      Public key length: 4096 bits (512 bytes)
+      Max plaintext length per chunk: 470 bytes
+      Input plaintext length: 3246 bytes
+      Number of chunks: 7
+
+      - secret:
+          name: <name>
+          data:
+            <fieldname>: <ssh_key>
+
+#. Add a new job to Zuul.
+
+   Create a new job in .zuul.yaml in the root directory of the repository. The
+   new job should look like the example below. Make sure to replace <repo> with
+   the actual repository name. Replace <ssh_key> with the actual SSH key
+   generated in the previous step.
+
+   .. code-block:: yaml
+
+      - job:
+         name: stx-<repo>-upload-git-mirror
+         parent: upload-git-mirror
+         description: Mirrors opendev.org/starlingx/<repo> to github.com/starlingx/<repo>
+         vars:
+           git_mirror_repository: starlingx/<repo>
+         secrets:
+           - name: git_mirror_credentials
+             secret: stx-<repo>-github-secret
+             pass-to-parent: true
+
+       - secret:
+         name: stx-<repo>-github-secret
+         data:
+           user: git
+           host: github.com
+           # yamllint disable-line rule:line-length
+           host_key: github.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==
+           ssh_key: <ssh_key>
+
+#. Set the new job as a Zuul post job.
+
+   Add the job (named stx-<repo>-upload-git-mirror) to the post job section of
+   the .zuul.yaml file. If there isn't an existing post job, create a new post
+   job section. The .zuul.yaml post job section should look like the example
+   below. Make sure <repo> is replaced with the actual repository name.
+
+   Example .zuul.yaml post job section:
+
+   .. code-block:: yaml
+
+       - project:
+         post:
+           jobs:
+             stx-<repo>-upload-git-mirror
+
+----------------
+Example Zuul job
+----------------
+
+An example of adding a Zuul job to sync a repository from opendev.org/starlingx
+to github.com/starlingx can be found at:
+
+https://opendev.org/starlingx/config/commit/5df1f3a89a6e1ef699fc6030a18902faf45daf88