From 88b334bd977bca4a474ec5a03223c967ad9826be Mon Sep 17 00:00:00 2001
From: Pierre-Yves Chibon <pingou@pingoured.fr>
Date: Apr 21 2022 10:15:29 +0000
Subject: Add documentation on best practices to use the centos namespace on gitlab


Signed-off-by: Pierre-Yves Chibon <pingou@pingoured.fr>

---

diff --git a/docs/gitlab.md b/docs/gitlab.md
new file mode 100644
index 0000000..adf72ff
--- /dev/null
+++ b/docs/gitlab.md
@@ -0,0 +1,81 @@
+# Best practices for the usage of the CentOS namespace on gitlab
+
+This document highlights the best practices SIGs interested in using the CentOS namespace on gitlab.com
+should follow.
+
+## Login in
+
+To login via ACO on gitlab.com, you must use the following link:
+
+## Content
+
+Any and all content hosted on gitlab.com should follow the Requirements the CentOS project has specified
+for SIGs: [https://wiki.centos.org/SpecialInterestGroup#Requirements](https://wiki.centos.org/SpecialInterestGroup#Requirements)
+
+## Access
+
+It is expected that access levels are managed via groups on accounts.centos.org (ACO). There are different
+ways this can be achieved.
+
+### Simple case
+
+For SIGs who are fine with everyone getting the same level of access, a single group can be created on
+https://accounts.centos.org where all the SIG members will be added. This group can then be mapped to that
+SIG’s namespace under gitlab.com/centos and be given `owner` access level.
+
+This means, everyone added to this group on accounts.centos.org will be granted `owner` access to each and
+every project placed under that SIG’s namespace. This also means, that anyone **not** in this group will have
+no access at all.
+
+### More complex case
+
+For SIGs who want or need a more fine tuned model, it is recommended that they create a `groups` namespace under
+the SIG’s namespace. In the group namespace will be placed all the groups needed by the SIG and each of this
+group will be mapped to a corresponding group on ACO. There should be no project under the `groups` namespace.
+The groups can then be given access to any project and the access level of the group can be picked on a
+per-project basis.
+
+Here is an example of the structure recommended for the complex case:
+
+```
+SIG's namespace
+│
+├── groups
+│   ├── group1-developers [grp1]
+│   ├── group2-maintainers [grp2]
+│   └── sig [sg]
+│
+├── rpms
+│   └── pkg [grp1+grp2]
+│
+├── src
+│   └──source_tree [grp1]
+│
+└── sig [sg]
+```
+
+## Group membership refresh
+
+To login via ACO on gitlab.com, you must use the following link:
+
+Group memberships are refreshed upon login into gitlab.com. So if someone is added to a group in ACO, they
+will need to visit that link again: XXX to have their membership refreshed.
+
+## Group names
+
+It is expected that groups on ACO that are created to manage access on gitlab.com should follow the
+corresponding pattern: `<sig>-gitlab-<name>`
+
+Some examples:
+
+- hyperscale-gitlab-maintainers
+- automotive-gitlab-kernel-maintainer
+- automotive-gitlab-sig-owner
+- docs-gitlab-members
+- …
+
+## Requesting a namespace or a group
+
+To request a namespace under gitlab.com/centos or the creation of a group on ACO, simply open a ticket at:
+[https://pagure.io/centos-infra/](https://pagure.io/centos-infra/)
+
diff --git a/docs/index.md b/docs/index.md
index 8c8ddb8..e147ba0 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -13,3 +13,4 @@ You'll find on this (always involving) website best practices for each step in t
   * How to [push to mirror](delivery.md) network
   * How to create a CentOS [spin](spin.md)
   * Rules for [dns entries](dns.md) under sig.centos.org
+  * Using the [CentOS namespace on gitlab.com](gitlab.md)
diff --git a/mkdocs.yml b/mkdocs.yml
index 135e4a8..665c6ee 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -14,6 +14,7 @@ nav:
   - delivery.md
   - dns.md
   - SIG's spin: spin.md
+  - Using GitLab: gitlab.md
 
 theme:
   name: material