The libvirt project has alot of git repositories, and they must all be
configured in the same way, more or less. This page documents the
settings changes that I have made in GitLab and GitHub when configuring
projects, both as a reminder for myself, and to help anyone else doing
the same in future. Also included is info about the repo mirroring on
the libvirt.org server.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
 docs/docs.html.in     |   3 +
 docs/newreposetup.rst | 136 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 139 insertions(+)
 create mode 100644 docs/newreposetup.rst

diff --git a/docs/docs.html.in b/docs/docs.html.in
index 142c79bfa9..6bdf0c32b8 100644
--- a/docs/docs.html.in
+++ b/docs/docs.html.in
@@ -172,6 +172,9 @@
         <dt><a href="testsuites.html">Functional testing</a></dt>
         <dd>Testing libvirt with <a href="testtck.html">TCK test suite</a> and
          <a href="testapi.html">Libvirt-test-API</a></dd>
+
+        <dt><a href="newreposetup.html">New repo setup</a></dt>
+        <dd>Procedure for configuring new git repositories for libvirt</dd>
       </dl>
     </div>
 
diff --git a/docs/newreposetup.rst b/docs/newreposetup.rst
new file mode 100644
index 0000000000..897caaa1ec
--- /dev/null
+++ b/docs/newreposetup.rst
@@ -0,0 +1,136 @@
+===============================
+Repository infrastructure setup
+===============================
+
+GitLab Configuration
+====================
+
+The `GitLab organization <https://gitlab.com/libvirt>`_ hosts the master copy
+of all the libvirt Git repositories.
+
+When creating a new repository the following changes to the defaults are
+required under the ``Settings`` page
+
+* **General**
+
+  * **Naming, topics, avatar**
+
+    * *Project avatar*: upload ``docs/logos/logo-square-256.png``
+
+  * **Visibility, project features, permissions**
+
+    * *Packages*: disabled
+
+    * *Wiki*: disabled
+
+    * *Snippets*: disabled
+
+  * **Merge Requests**
+
+    * *Merge method*: Fast-forward merge
+
+    * *Merge options*: Enable 'delete source branch' option by default
+
+    * *Merge checks*: Pipelines must succeed
+
+  * **Merge request approvals**
+
+    * *Any eligible user*: Num approvals required == 1
+
+* **Integrations**
+
+  * **Pipelines emails**
+
+    * *Recipients*: ``libvirt-ci@redhat.com``
+
+* **Repository**
+
+  * **Push rules**
+
+    * *Do not allow users to remove git tags with git push*: enabled
+
+    * *Commit message*:  ``Signed-off-by:``
+
+    * *Branch name*: ``^(master|v.*-maint)$``
+
+  * **Mirroring repositories**
+
+    * *Git repository URL*: ``https://libvirtmirror@github.com/libvirt/$repo.git``
+
+    * *Mirror direction*: push
+
+    * *Password*:  see ``/root/libvirt-mirror-github-api-token.txt`` on ``libvirt.org``
+
+  * **Protected branches**
+
+    * *Branch*: ``master``
+
+    * *Allowed to merge*: Developers + Maintainers
+
+    * *Allowed to push*: None (or Developers + Maintainers if MRs not used)
+
+    * *Require approval from code owners*: disabled
+
+GitHub configuration
+====================
+
+The `GitHub organization <https://github.com/libvirt>`_ hosts read-only
+mirrors of all the libvirt Git repositories.
+
+When creating a new repository the following changes to the defaults are
+required under the ``Settings`` page
+
+* **Options**
+
+  * **Features**
+
+    * *Wikis*: disabled
+
+    * *Sponsorships*: disabled
+
+    * *Projects*: disabled
+
+  * **Manage access**
+
+    * Add @committers with role "Write"
+
+  * **Integrations**
+
+    * Check for *Repo Lockdown*  (should be set automatically for all projects)
+
+In the master git repository create a file `.github/lockdown.yml` to restrict
+use of issue tracker and pull requests.
+
+
+libvirt.org
+===========
+
+The `Libvirt project server <https://libvirt.org>`_ hosts read-only mirrors of
+all the libvirt Git repositories in the directory ``/data/git``.
+
+When creating a new repository the following steps are required
+
+* Create repo with
+  ::
+
+     $ sudo su -
+     # cd /data/git
+     # mkdir repo.git
+     # cd repo.git
+     # git init --bare
+     # touch export
+     # touch git-daemon-export-ok
+     # cd ..
+     # chown -R gitmirror.gitmirror repo.git
+     # chmod -R g+w repo.git
+     # find -type d repo.git | xargs chmod g+s
+
+* Set the ``description`` and ``config`` files following other repos example
+
+* Setup mirroring
+  ::
+
+    $ sudo su - gitmirror
+    # ./newrepo.sh /data/git/repo.git
+    # cd mirrors
+    # $HOME/sync-one.sh repo.git
-- 
2.24.1

On Wed, 2020-04-08 at 17:41 +0100, Daniel P. Berrangé wrote:
> +GitLab Configuration
> +====================
> +
> +The `GitLab organization <https://gitlab.com/libvirt>`_ hosts the master copy
> +of all the libvirt Git repositories.
> +
> +When creating a new repository the following changes to the defaults are
> +required under the ``Settings`` page

I think *Settings* would be more appropriate than ``Settings`` in
this context.

Missing ":" after "page".

> +GitHub configuration
> +====================
> +
> +The `GitHub organization <https://github.com/libvirt>`_ hosts read-only
> +mirrors of all the libvirt Git repositories.
> +
> +When creating a new repository the following changes to the defaults are
> +required under the ``Settings`` page

Same comments as the GitLab equivalent.

> +  * **Manage access**
> +
> +    * Add @committers with role "Write"

Probably ``@committers``.

I'd also clarify that this is supposed to be a team, and that it
needs to include ``libvirtmirror``, though assuming that teams are
per-org rather than per-repo then the latter might not be strictly
necessary.

> +libvirt.org
> +===========
> +
> +The `Libvirt project server <https://libvirt.org>`_ hosts read-only mirrors of
> +all the libvirt Git repositories in the directory ``/data/git``.

s/Libvirt/libvirt/

> +When creating a new repository the following steps are required

Missing ":" after "required".

> +* Create repo with
> +  ::
> +
> +     $ sudo su -
> +     # cd /data/git
> +     # mkdir repo.git
> +     # cd repo.git

In the other sections you've used ``$repo``, and it would be nice to
be consistent.

> +     # cd ..
> +     # chown -R gitmirror.gitmirror repo.git
> +     # chmod -R g+w repo.git
> +     # find -type d repo.git | xargs chmod g+s

The ``cd ..`` is not necessary if you just call all follow-up
commands on ``.``, but if you think it makes the example clearer then
I have no objection to leaving it in.

> +* Set the ``description`` and ``config`` files following other repos example

s/repos/repos'/

-- 
Andrea Bolognani / Red Hat / Virtualization