===============================
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*: ``ci@lists.libvirt.org``

* **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`` and ``v*-maint``

    * *Allowed to merge*: Developers + Maintainers

    * *Allowed to push*: None (or Developers + Maintainers if MRs not used)

    * *Require approval from code owners*: disabled

  * **Protected tags**

    * *Tag*: ``v*`` and any project specific tag formats like ``LIBVIRT_*`` or ``CVE*``

    * *Allowed to create*: Developers + Maintainers

* **CI/CD**

  * **Runners**

    * *Shared runners*: Enable shared runners

  * **Variables**

    * *Key*: ``CIRRUS_GITHUB_REPO``

      * *Value*: ``libvirt/$repo``

      * *Protect variable*: enabled

      * *Mask variable*: disabled

    * *Key*: ``CIRRUS_API_TOKEN``

      * No need to set this at the project level: it's already set for the
        libvirt organization and will be inherited from there.


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 the ``@committers`` team with the role "Write", which
      grants the ``libvirtmirror`` user access to sync from GitLab.

  * **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.
