Dienste/Gitlab

Gitlab

Der FB3 bietet Gitlab unter folgender URL an:

https://gitlab.informatik.uni-bremen.de/

Anmelden kann sich jede:r FB3-Benutzer:in mit einem Uni-Account (über den LDAP-Tab). Beim ersten Login wird automatisch ein Gitlab-Account angelegt und können erst danach gefunden werden (z.B. für das Einladen in ein Projekt).

Jede Person kann Standardmäßig bis zu 100 Projekte anlegen. Wenn das nicht ausreicht, kann das Limit problemlos angehoben werden. Dazu bitte eine E-Mail an service@informatik.uni-bremen.de schicken oder ein Ticket im Gitlab-Projekt erstellen.

Für den Zugriff auf von Gitlab verwaltete Repositories via SSH wird ein SSH-Schlüsselpaar benötigt. Public-Keys können in Gitlab hinterlegt werden, indem man oben links auf sein Profilbild klick, dann auf "Edit Profile" oder "Preferences" und dann links in der Navigationsleiste auf "SSH Keys".

Der RSA-Fingerprint für den Server lautet MD5:9b:1e:c6:c6:78:69:14:be:e9:5b:e7:24:09:32:78:47 bzw. SHA256:nVTL/k5lSm4Kic3VfN9np76syi2PTVqPsuTmlDuvq5M.

Der ED25519-Fingerprint für den Server lautet MD5:71:a5:06:04:aa:b2:27:96:45:ac:69:52:aa:8c:6b:a4 bzw. SHA256:iJcPCKgka3CYBjml2tDYMasJ/Crqw64Bg9V1WoboC8E.

Um eine konsistente Datensicherung zu gewährleisten ist Gitlab jeden Tag ab ca. 23 Uhr jeweils für ein paar Minuten nicht erreichbar.

Bei Fragen oder Problemen mit Gitlab, bitte eine E-Mail an service@informatik.uni-bremen.de schicken oder ein Ticket im Gitlab-Projekt erstellen.

Gitlab CI/CD

Seit Version 8.0 direkt in Gitlab integriert, bietet der FB3 den zugehörigen Continuous Integration und Delivery Dienst Gitlab-CI/CD an.

Siehe auch die offizielle Dokumentation.

Bei Fragen oder Problemen mit Gitlab-CI, bitte ein Ticket im Gitlab-Projekt aufmachen.

Damit CI/CD in einem Projekt genutzt werden kann, muss in den Projekteinstellungen unter Einstellungen -> Allgemein -> Sichtbarkeit, Funktionen, Berechtigungen die Option CI/CD aktiviert werden.

Runner

Gitlab führt selbst keine Builds aus, sonder delegiert dies an sogenannte Runner. Ein Runner ist ein Prozess, der auf einem beliebigen Rechner laufen kann, und den Gitlab-Server pollt, um anstehende Jobs abzuholen und zu bearbeiten. Dabei ist zwischen "Instance"-, "Group-" und "Project"-Runnern zu unterscheiden. Ein Project-Runner bedient nur bestimmte Projekte, ein Group-Runner alle Projekte in besimmten Gruppen. Instance-Runner bearbeiten alle Jobs, für die kein Project- oder Group-Runner existiert und die für die Nutzung von Instance-Runnern freigeschaltet sind (siehe Einstellungen -> CI/CD -> Runner in den Projekteinstellungen).

Da nicht immer alle Jobs in allen Umgebungen funktionieren, kann mit Tags gesteuert werden, welche Jobs auf welchen Runnern ausgeführt werden können. Wenn einem Job Tags zugeordnet wurden, wird dieser nur auf einem Runner mit den passenden Tags ausgeführt. Wenn einem Job keine Tags zugeordnet sind, dann wird dieser nur von Runnern ausgeführt, die explizit dafür konfiguriert sind ungetaggte Jobs zu bedienen. Wenn mehrere Runner für die Ausführung eines Jobs in Frage kommen wird einer davon per Zufall ausgewählt.

Instance-Runner

Der FB3 stellt eine Reihe von Instance-Runnern zur Verfügung:

Platform	Tags	Hostnamen
Mac OS X	darwin	m{01..06}
Kubernetes	linux, docker, kubernetes	fb3-k8s-{1..4}

Die MacOS-Runner laufen auf den Pool-Rechnern in der E0 im MZH. Vor der Ausführung von Jobs darauf sollte ggf. geprüft werden ob alle dafür nötigen Werkzeuge und Abhängigkeiten installiert sind. Fehlende Abhängigkeiten können auf Anfrage nachinstalliert werden (serviceinformatik.uni-bremen.de).

Der Kubernetes-Runner ist auf einem Kubernetes-Cluster installiert und führt Jobs in OCI-Containern aus. Der Kubernetes-Instance-Runner bedient auch ungetaggte Jobs.

Ein Ausschnitt der Liste der verfügbaren Instance-Runner wird unter Einstellungen -> CI/CD -> Runner in der Projektansicht angezeigt. Man kann nur im Nachhinein über das Build-Log feststellen, auf welchem Instance-Runner ein Job ausgeführt wurde.

Group/Project-Runner

Man kann auch eigene Runner im Kontext einer Gruppe oder eines Projekts erstellen, die dann nur die eigenen Projekte bedienen. Der Vorteil ist, dass man die Entwicklungsumgebung individuell anpassen, oder auch einfach eine bestehende Umgebung direkt weiter benutzen kann. Voraussetzung für den Betrieb eines Runners ist, dass dieser den Gitlab-Server erreichen kann.

Weitere Informationen zum Erstellen eigener Runner sind in der Projektansicht in Gitlab unter Einstellungen -> CI/CD -> Runner zu finden.

Sicherheit

Dieser Abschnitt gilt nur für Runner, die den shell-Exektuor nutzen (also bei den angebotenen Shared-Runnern derzeit die Mac OS X Runner).

Bei der Benutzung und Einrichtung von Runnern sollten einige Punkte in Hinsicht auf Sicherheit und den Schutz vertraulicher Daten beachtet werden:

Jobs sind beliebige Shell-Skripte, die mit den Rechten des Benutzers ausgeführt werden, unter dem der jeweilige Runner-Prozess läuft. Das bedeutet, dass jeder Gitlab-Benutzer, der die entsprechenden Zugriffsrechte auf ein Projekt hat, beliebige Befehle mit den Rechten der Runner ausführen kann, die das jeweilige Projekt bedienen.

Gerade beim Einrichten eigener Runner sollte also darauf geachtet werden, dass keine vertraulichen Informationen zugreifbar sind und dass der Runner nicht mehr Rechte auf dem unterliegenden System hat, als er für die Bearbeitung seiner Jobs benötigt.

Insbesondere bei Shared-Runnern ist zu beachten, dass dadurch z.B. der private Authentisierungs-Token des Runners ausgelesen werden und dadurch der Runner von einer anderen Maschine imitiert werden könnte. Außerdem ist es möglich, direkt auf den Code der bisher vom jeweiligen Runner bearbeiteten Projekte zuzugreifen, solange diese im Arbeitsverzeichnis des Runners verbleiben.

Docker

Wie oben beschrieben führen die mit linux, docker, kubernetes getaggten Runner ihre Jobs in einem Docker-Container aus. Das Default-Image ist debian:latest, was aber gemäß der offiziellen Dokumentation selbst eingestellt werden kann. Abhängigkeiten können im Docker-Image entweder durch die service-Notation oder z.B. durch Aufrufen von apt-get im before_script-Bereich in .gitlab-ci.yml installiert werden.

Alternativ können selbst erstelle Docker-Images über die in Gitlab integrierte Container-Registry genutzt werden.

Tips und Tricks

Container-Images bauen

Es gibt derzeit zwei Wege mit den Kubernetes-Instance-Runnern Container-Images zu bauen: Kaniko und BuildKit. Kaniko sollte wenn möglich bevorzugt werden, da für BuildKit ein separater Dienst mit erhöhten Privilegien benötigt wird, von dem nur wenige Instanzen laufen, was bei hoher Nutzung ggf. zu Engpässen führen kann.

Hier sind minimale Beispiel-Jobs in .gitlab-ci.yml um Container-Images aus einem Dockerfile in der Wurzel des Repositories zu bauen und unter dem Standard-Imagenamen in die Container-Registry des Projektes hochzuladen:

Kaniko

Siehe auch die Kaniko-Dokumentation

Es sollte jeweils das aktuellste Kaniko-Image genutzt werden. (Das Image hat derzeit keinen latest-Tag.)

build:docker:
  stage: build
  image:
    name: ghcr.io/kaniko-build/dist/chainguard-dev-kaniko/executor:v1.25.1-debug
    entrypoint: [""]
  script:
    - /kaniko/executor
      --context "${CI_PROJECT_DIR}"
      --dockerfile "${CI_PROJECT_DIR}/Dockerfile"
      --destination "${CI_REGISTRY_IMAGE}:latest"

BuildKit

Siehe auch die BuildKit-Dokumentation

Die Netzwerkadresse für den BuildKit-Dienst ist in der Umgebungsvariable BUILDKIT_HOST definiert, die von den Kubernetes-Runnern vorgegeben wird. Falls man aus irgendeinem Grund einen selbst betriebenen BuildKit-Dienst verwenden möchte, kann man diese Variable einfach in den Job-Einstellungen überschreiben.

build:docker:
  stage: build
  image: moby/buildkit:latest
  before_script:
    - mkdir -p ~/.docker
    - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > ~/.docker/config.json
  script:
    - buildctl build
        --frontend dockerfile.v0
        --local context="${CI_PROJECT_DIR}"
        --local dockerfile="${CI_PROJECT_DIR}"
        --output type=image,name=${CI_REGISTRY_IMAGE}:latest,push=true

Auf Ressourcen anderer Projekte zugreifen

Siehe auch die Dokumentation zu GitLab CI/CD job token

Man kann einem Job die Berechtigung einräumen, auf die Ressourcen anderer Projekte zuzugreifen, z.B. um ein Container-Image nur einmal bauen zu müssen. Dazu muss in dem Projekt, auf das zugegriffen werden soll, unter Einstellungen -> CI/CD -> Job-Token-Berechtigungen das Projekt in dem der Job läuft in die Liste der berechtigten Projekte aufnehmen.

Cachen von Artefakten und Abhängigkeiten

Siehe auch die Dokumentation zu Caching in GitLab CI/CD

Die Kubernetes-Instance-Runner sind mit einem Cache konfiguriert, der genutzt werden kann um Build-Artefakte oder durch den Job installierte Abhängigkeiten zwischen einzelnen Jobs zu übertragen.

Gitlab-Pages

Siehe auch die Dokumentation zu Gitlab-Pages

Gitlab kann genutzt werden um statische Webseiten zu hosten. Dynamische Inhalte, z.B. mit PHP, sind an dieser Stelle nicht möglich.

Um diese Funktion nutzen zu können muss neben CI/CD in den Projekteinstellungen unter Einstellungen -> Allgemein -> Sichtbarkeit, Funktionen, Berechtigungen der Punkt Seiten aktiviert sein. Danach kann man unter Bereitstellung -> Seiten den Anweisungen folgen um einen CI/CD-Job anzulegen, der die Inhalte generiert und weitere Einstellungen vornehmen.

Siehe die oben verlinkte Gitlab-Dokumentation für weitere Optionen und Beispiele.

Siehe hier für Dokumentation zu der in Gitlab integrierten CI/CD-Funktionalität.

Externe Kooperationspartner

Für externe Kooperationspartner können bei Bedarf Gitlab-Accounts angelegt werden. Dafür bitte eine Mail mit dem Namen, dem gewünschten Benutzernamen und der E-Mailadresse der Person an service@informatik.uni-bremen.de senden. Achtung: der Nutzername muss einen Punkt ('.') enthalten, um Namenskonflikte mit FB3- und Uni-Accounts zu vermeiden (also z.B. otto.mustermann oder o.mustermann verwenden). Bei Angehörigen der Uni-Bremen aus anderen Fachbereichen etc. kann meistens der Uni-Account für die Nutzung von FB3-Diensten freigeschaltet werden. Siehe dazu die Accounts-Seite.

Gitlab-Accounts für Externe, die also nicht an einen Uni-Account gekoppelt sind, können keine eigenen Projekte oder Gruppen erstellen.

Löschung von Gitlab-Accounts

Wenn ein Uni-Account den Zugang zu FB3-Diensten verliert wird der zugehörige Gitlab-Account automatisch gesperrt. Falls der Account zu einem späteren Zeitpunkt wieder Zugang zu FB3-Diensten erhält wird der zugehörige Gitlab-Account automatisch bei der nächsten Anmeldung wieder entsperrt. Gesperrte Gitlab-Accounts die an einen Uni-Account gekoppelt sind werden vorgehalten bis der zugehörige Uni-Account gelöscht wird und dann ebenfalls gelöscht.

Externe Accounts werden nach einem Jahr Inaktivität automatisch deaktiviert und deren Besitzer:in via E-Mail darüber benachrichtigt. Der jeweilige Account kann durch das Anmelden bei Gitlab selbstständig wieder reaktiviert werden. Wenn ein externer Account für mehr als 30 Tage deaktiviert bleibt, wird er automatisch gelöscht.

Alle persönlichen Projekte (also Projekte im Namensraum des Accounts) werden zusammen mit dem Account gelöscht. Alle Beiträge, also Commits, Kommentare, Issues etc., werden nach der Löschung dem "Ghost"-Account übertragen. Siehe auch die Gitlab-Dokumentation zu dem Thema.

Falls der jeweilige Account einziger Besitzer einer Gruppe ist, wird die Gruppe auf einen beliebigen Account mit den nächst höheren Zugriffsrechten übertragen. Falls der jeweilige Account das einzige Mitglied der jeweiligen Gruppe ist wird diese gelöscht. Falls dies nicht gewünscht ist sollte rechtzeitig vorher dafür gesorgt werden, dass ein Nachfolge-Besitzer ernannt wird (oder die Gruppe gelöscht).

Accounts können auch selbstständig gelöscht werden. Das geht indem man oben links auf sein Profilbild klickt, dann "Edit Profile" und dann links unter "User settings" auf "Account".