====== GitLab ======

Unter https://gitlab.cs.uni-duesseldorf.de/ findet man das [[https://gitlab.com|GitLab]] des Instituts für Informatik.

Unser GitLab hat folgende Erweiterungen freigeschaltet:

  * die offizielle [[https://docs.gitlab.com/ee/ci/|GitLab CI]] und ein [[https://gitlab.cs.uni-duesseldorf.de/cn-tsn/general/templates/gitlab-ci-yml|Repository für Beispielkonfigurationen]]
  * [[https://docs.gitlab.com/ee/user/packages/container_registry/|GitLab Container Registry]] zum Speichern von eigenen Docker Images. Die Registry ist aktuell unter gitlab.cs.uni-duesseldorf.de:5001 zu erreichen. Auch hierfür gibt es Beispielkonfigurationen.
  * Statische Seiten ausliefern mit [[#gitLab-pages|GitLab-Pages]]

Die aktuellen SSH Hostkey-Fingerprints des Systems lauten:
```
2048 SHA256:wqHIGLm6976qsWdfbfNHEa7Qm92CZn7Dhn+LQY/Lq5o gitlab (RSA)
256 SHA256:2LbJS1lyOOs4Fr+LtryPuod66AX/N9uFj6EhmcD609I gitlab (ECDSA)
256 SHA256:U/XIMNPlPBfsW+rT9neQAK7sGyoh1FROEablLy1yBQQ gitlab (ED25519)
```

Im Folgenden werden Not-ToDo's und Best-Practices dafür aufgezeigt.

===== Not-ToDo's =====
Folgende Dinge sind auf keinen Fall zu empfehlen, da im schlimmsten Fall lehrstuhlinterne Daten nach außen gelangen und/oder Dritte Zugriff auf Repositories erhalten.

==== Studenten-Zugriffsrechte höher als Developer ====
[[https://gitlab.com/gitlab-org/gitlab-foss/-/blob/master/doc/user/permissions.md|Hier]] sind die einzelnen Berechtigungen für die jeweiligen GitLab-Rollen aufgelistet. Während Mitarbeiter fast immer in der //Master//-Rolle agieren, haben Studenten als höchsten Status //Developer//. Andernfalls können sie per `git push --force` das komplette Repository manipulieren.

==== Studenten arbeiten in geteilten Projekten auf unprotected branches ====
Auf [[https://docs.gitlab.com/ee/user/project/protected_branches.html|protected branches]] können nur Benutzer mit dem Status //Master// oder höher pushen. Studenten sollten auf ihren eigenen branches arbeiten und Änderungen mittels //Merge Requests// einfließen lassen.

==== Studenten als Gruppen-Mitglieder ====
Als Gruppen-Mitglied hat man die zugehörigen Gruppen-Rechte auf alle Repositories in einer Gruppe. Um unerlaubten Zugriff zu verhindern, werden Studenten nur zu Projekten, **nicht** aber zu Gruppen hinzugefügt.

==== Gists in der intern-Gruppe erstellen ====
Diese Gruppe heißt nicht ohne Grund **intern** – wer also per Gist oder ähnlichem Sachen daraus nach außen teilt, möge bitte die Definition von **intern** im Wörterbuch nachschlagen und sich danach selber an den Kopf fassen.

===== Best Practices =====
[[https://docs.gitlab.com/ee/tutorials/|Hier]] findet man Tutorials für GitLab.

Repositories heißen in GitLab //Projects//.


===== Zugänge =====
Das Instituts-GitLab ist nicht mit dem LDAP der Universität verbunden. Heißt wir können selbst Benutzer anlegen und dann ins GitLab integrieren. Dafür muss der User das [[cs:it:tofu|Zugangsformular]] ausfüllen und bei Studenten muss mir noch der Betreuer eine kurze Nachricht im Mattermost oder per Mail schicken, dass der Student von ihm kommt. Die ggf. nötige Einsortierung in die richtigen Gruppen übernimmt der jeweilige Bereichsadmin. Nach beendigung des Arbeitsverhältnisses (Datum im Formular angegeben bzw. alternativ durch Sabine/Anja/die anderen Admins an mich gemeldet) wird der Account deaktiviert und 6 Monate später gelöscht. Dabei gehen alle Daten in den persönlichen Repos verloren.

===== Import von Repos aus dem SVN =====
[[https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git|Hier]] gibt es die Anleitung dazu. Damit ihr euch die authors.txt-Datei nicht jedes Mal selbst erstellen müsst, ist hier eine Version mit allen Angestellten zu finden. Zusätzlich gibt es hier noch ein Skript um mehrere Repositories zu migrieren und gleichzeitig im Gitlab per API-Zugriff anzulegen. namespace_id und Private-Token müssen entsprechend angepasst werden.

===== Repos für Studierende =====
Für Studierende ist es nicht notwendig, dass diese einer Gruppe zugeordnet werden. Ein normaler Account in unserem GitLab genügt. Dann könnt ihr unter der Gruppe "students" ein Repository erstellen (//New Project// –> //Visibility: private//) und den Studierenden dann unter //Members// hinzufügen. Hierfür muss eine Rolle wie oben beschrieben ausgewählt werden. Diese Rolle gilt nur für das aktuelle Repository und nicht für die ganze Gruppe. Hierbei sollte //Developer// als Rolle ausgewählt werden, denn als Master hätte der Studierende Zugriff auf die CI von GitLab, was nicht notwendig ist.

Kurzüberblick:
  - Student das [[cs:it:tofu|Zugangsformular]] ausfüllen lassen und Thomas bescheid geben (eine Liste mit Studenten, die in der nächsten Zeit kommen, geht auch, ist lediglich zur Kontrolle).
  - Repository in Gruppe "students" erstellen
  - Studierenden im Repository unter Members als Developer hinzufügen
  - Sich selbst im Repository unter Members als Master hinzufügen (ist zwar redundant, lässt aber auf einen Blick erkennen, wer wirklich Teil des Projekts ist)
  - Den master-Branch unprotecten, schließlich soll es das Repository des Studenten sein

==== Repo-Anzahl der Studierenden ====
Studenten können standardmäßig fünf Repositories anlegen. Diese sind nicht direkt für den Betreuer sichtbar und können außerhalb der Lehrstuhl-Struktur im eigenen Namespace liegen.

Dies ist allerdings auch die einzige Möglichkeit für einen Studenten, einen Fork anzulegen (hierzu wird eines seiner verfügbaren Repositories genutzt). Der Betreuer sollte auf jeden Fall zum Fork hinzugefügt werden, damit ein Zusammenhang dokumentiert ist. Sobald das Ablaufdatum im Anmeldeformular überschritten und nicht verlängert worden ist, wird der Account vom Studenten deaktiviert und 6 Monate später gelöscht. Ein etwaiger Merge **muss** vorher stattgefunden haben. Alle privaten Repositories der Studenten gehen hierbei unwiederbringlich verloren!

Sollte ein Student keine eigenen Repos erstellen dürfen, so muss dies bei der **Anmeldung** vermerkt werden.

==== Sichtbarkeit von Repositories ====
**Private Repos** können nur von Personen eingesehen werden, die entweder in der übergeordneten Gruppe eingetragen wurden oder explizit als Member hinzugefügt worden. Das sollte die Standardeinstellung für Abschlussarbeiten o.Ä. sein. Dadurch hat jeder Mitarbeiter und der zugeordnete Studierende Zugriff auf das Repository.

**Interne Repos** können gruppenübergreifend von eingeloggten Benutzern eingesehen werden. Das heißt nicht, dass man automatisch Schreibzugriff auf das Repo hat. Ein Beispiel dafür wäre das paper-build Repo, welches auch Studierende für ihre Abschlussarbeiten verwenden können.

Es gibt auch die Möglichkeit **öffentliche Repositories** anzulegen, welche dann auch von außen einsehbar sind ohne einen Zugang zu unserem GitLab zu haben.

===== Gruppen =====
Auf oberster Ebene beginnen wir typischerweise mit der Lehrstuhlgruppe (bspw. “cn”) und gliedern das entsprechend den Bedürfnissen weiter in Untergruppen. Es gibt die Gruppe “general”, in welchem öffentliche Projekte geteilt werden können. Der Name “public” ist reserviert, weshalb wir uns für “general” entschieden haben. Nur dort ist die höchste Sichtbarkeit einstellbar.

Gruppen / Untergruppen können nur vom Administrator erstellt und verwaltet werden. Wer in eine Gruppe möchte, muss sich daher an den entsprechenden Admin wenden.

Die Standardgruppen von CN/TSN/CCB sind:

  * **intern**: In der Gruppe intern werden Dokumente abgelegt, die **nur** für Mitarbeiter bestimmt sind.
    * **papers**: Diese Gruppe enthält Publikationen an denen gearbeitet wird bzw. die bereits abgeschlossen sind.
    * **teaching**: In dieser Gruppe sind Repos für diverse Vorlesungen/Seminare zu finden, die **nur** für Mitarbeiter bestimmt sind.
  * **project**: Die Gruppe project ist für normale Projekte gedacht, bei denen ihr u.A. mit Studierenden zusammenarbeiten wollt.
  * **students**: Studentische Abschlussarbeiten finden hier Platz.
  * **general**: Enthält templates, allgemeine Dokumente die ggf. GitLabweit geteilt werden.

===== Binärdateien im GitLab (git-lfs) =====
Wenn man pdf-Dateien, große Bilder, Simulationsdaten etc. ablegen möchte, verwenden wir [[https://git-lfs.github.com/|git-lfs]] (large file storage). Diese Dateien werden nicht versioniert, sind aber Teil des Projekts, heißt beim auschecken werden diese Dateien auch heruntergeladen und aktuell gehalten. Nur gibt es keine Versionen der lfs-Dateien, was aber auch sinnvoll ist, denn wenn man an Simulationsdaten denkt bedeuten andere Dateien auch eine andere Simulation.

Dieser Schritt ist notwendig, denn andernfalls schreiben wir die Festplatten unseres GitLab nur unnötig voll, was dann auch zu Backupproblemen führen kann. Die lfs-Dateien werden auf einer anderen Festplatte und ggf. auf einem anderen Server gesichert und sind auch im Backup inbegriffen, nur sparen wir uns die alten Versionen.

Generell sollte aber gelten: generierbare Dateien werden **nicht** eingecheckt, sofern die Rekonstruktion einfach über ein Skript erfolgen kann.

Wir haben beispielhaft eine .gitattributes-Datei angelegt, welche ins Root-Verzeichnis des jeweiligen Projekts angelegt werden sollte, um automatisch neue Dateien direkt ins LFS mit aufzunehmen: https://gitlab.cs.uni-duesseldorf.de/cn-tsn/general/templates/gitattributes-lfs

===== Gitlab-Registry =====
Wichtig/Sicherheitsrelevant: Wenn ihr Images produktiv nutzt und dort Base-Images verwendet (was bei Docker üblich ist, Beispiel: Alpine oder Debian Images von Dockerhub), müsst ihr 2 Dinge beachten, da diese Images sonst die Updates von den Base-Images nicht bekommen:
  * In der .gitlab-ci.yml muss die `docker build` Zeile um `--pull` ergänzt werden.
  * Beispiel: `docker build -t $CI_REGISTRY_IMAGE --pull .`
  * Schedule im Gitlab. Hierzu auf CI / CD → Schedules → New Schedule. Als Titel `Rebuild (Base-Image-Update)`. Dann `Every day (at 4:00am)` (bitte nur diese Zeit verwenden). Dann noch den Branch aussuchen, der verwendet wird. Alles andere so lassen, wie es ist.

===== GitLab-Pages =====

Statische Inhalte können direkt über die GitLab Pages ausgeliefert werden. Das können beispielsweise Projekt-Dokumentationen sein, die aus dem Quellcode von Projekten direkt gebaut und veröffentlicht werden sollen. Dabei kann die Dokumentation innerhalb der CI gebaut werden, muss in einen Top-Level-Ordner `public` kopiert werden und schon wird es ausgeliefert. Wichtig ist, dass der CI Job `pages` heißt. Unter `Settings -> General` kann die Sichtbarkeit der GitLab Pages definiert werden.

Unter `Settings -> Pages` sieht man dann den Link zu der Pages-Seite. 

Weitere Informationen befinden sich in der offiziellen Dokumentation: https://docs.gitlab.com/ee/user/project/pages/