Inhalt

LRZ GitLab vs. LRZ GitLab CE

Im folgenden Tabelle sind die wichtigsten Unterschiede zwischen den zwei Instanzen aufgeführt. 

Visuelle Unterscheidbarkeit der beiden Instanzen

Die beiden Instanzen sind neben den unterschiedlichen URLs durch unterschiedliche Favicons sowie eine farbliche Titelzeile in der Community Edition voneinander zu unterscheiden.
Für alle die häufig sowohl LRZ GitLab als auch LRZ GitLab CE verwenden, empfehlen wir zur besseren Unterscheidbarkeit zusätzlich die Nutzung verschiedener Farbschemas (Color theme). Das Farbschema kann durch Klick aufs Profilbild -> Preferences -> Color theme -> Save changes gewechselt werden.

Migration der Projekte und Gruppen zwischen LRZ GitLab und LRZ GitLab CE

Es gibt zwei alternative Verfahren um Projekte und Gruppen von einer GitLab-Instanz auf einer anderen Instanz zu verschieben:

1. Das klassische Verfahren mit Projekt Export -Dateien
2. Das neue Verfahren Migrate groups by direct transfer

Das klassische Verfahren wird empfohlen, wenn nur wenige Projekte verschoben werden sollen. Die nötige Schritte sind:

1. Auf der Quellinstanz eine Projekt Export -Datei erstellen: Settings → General → Advanced → Export project
2. Die erstellte Export-Datei runterladen
3. Auf der Zielinstanz die Export-Datei importieren: New project → Import project → GitLab export

Das neue Verfahren ist nach GitLab noch in Beta, wird jedoch empfohlen wenn eine oder mehrere Gruppen mit vielen Projekten verschoben werden sollen. Die nötige Schritte sind:

1. Ein Personal Access Token mit der Berechtigung api auf der Quellinstanz erstellen: Edit profile → Access tokens → Add new token
2. Auf der Zielinstanz zur Quellinstanz verbinden: New group → Import group → Import groups by direct transfer → Die URL und die erstellte Personal Access Token angeben → Connect instance
3. In der Liste die gewünschte Quellgruppe(n) (Source Group) und derer Zielgruppe (New group) wählen. Bitte beachten, dass als Zielgruppe eine bereits vorhandene Gruppe automatisch vorgewählt sein kann und die Quellgruppe unter diese Gruppe als Subgruppe importiert wird. Um die Gruppe als neue eigenständige Gruppe zu importieren bitte No parent wählen.
4. Das Importieren mit Import with projects starten. Bitte beachten dass die Bearbeitung einige Zeit in anspruch nehmen kann. 

Anmerkungen:

• Die Information welche Person welchen Commit in den Projekten gemacht hat wird erhalten. Falls das Konto auf dem Zielinstanz nicht vorhanden ist, wird anstatt des Links zum Profil neben dem Commit die E-Mail-Adresse gezeigt.
• Berechtigungen in den Gruppen und Projekten werden nur erhalten, wenn das Konto auf der Zielinstanz bereits vorhanden ist und die E-Mail-Adresse auf der Quellinstanz als Public email freigegeben ist. Die E-Mail-Adresse ist für die Verknüpfung maßgebend, die Usernamen dürfen zwischen den Instanzen abweichend sein.

Falls Probleme bei der Migration auftreten, kontaktieren Sie uns bitte über den LRZ Servicedesk.

Was passiert mit Projekten von gelöschten Kennungen?

Wird eine Kennung gelöscht oder ihr die GitLab-Berechtigung entzogen, wird das zugehörige Konto in GitLab gesperrt. Projekte und Gruppen, die diesem Konto gehören, werden in GitLab noch für drei Monate und in Backups für weitere drei Monate (insgesamt 6 Monate) erhalten. Danach werden sie endgültig gelöscht.

Wenn eine oder mehrere Gruppen oder Projekte der Kennung weiterhin aktiv bleiben sollen, müssen sie vor der Löschung der Kennung einem anderen aktiven GitLab-Konto übertragen werden. 

Um eine Gruppe weiterhin aktiv zu halten, wird einfach ein weiteres Konto in der Mitgliedsliste der Gruppe mit dem höchsten Berechtigungsstufe (Owner) eingetragen. Solange mindestens ein aktives Konto als Owner in der Gruppe eingetragen ist bleiben auch alle Projekte innerhalb der Gruppe automatisch aktiv.

Wenn ein persönliches Projekt des Kontos weiterhin aktiv bleiben soll, empfehlen wir das Projekt in eine Gruppe zu verschieben, die auch speziell zu diesem Zweck erstellt werden kann. Die Übertragung erfolgt in den erweiterten Einstellungen des Projekts (Project Settings → General → Advanced → Transfer project). Danach das weiterhin aktive GitLab-Konto als Owner in der Gruppe oder im Projekt eintragen. Alternativ kann das Projekt exportiert werden (Project Settings → General → Advanced → Export project) und an eine Person mit weiterhin gültiger GitLab-Berechtigung weitergeben werden, um das Projekt zu importieren (New project/repository → Import project → Import project from GitLab export).

Bitte beachten: Das Eintragen eines zusätzlichen Kontos als Owner in einem persönlichen Projekt schützt nicht von der automatischen Löschung.

Vor allem für öffentliche Projekte empfehlen wir die Projekte in Gruppen einzuordnen.

Werden Projekte gesichert? Wie kann ich ein gelöschtes Projekt wiederherstellen?

Das LRZ erzeugt tägliche Backups der kompletten GitLab-Instanz. Diese Backups werden dediziert gelagert und regelmäßig auf Integrität überprüft. Die Backups dienen allerdings nur dazu, GitLab nach einem kritischen Fehler wiederherzustellen. Dabei wird die komplette GitLab-Instanz auf den Zeitpunkt des Backups zurückgesetzt. Eine Wiederherstellung einzelner Projekte im laufenden Betrieb ist derzeit nicht möglich.

Eine Wiederherstellung von Repositories, die selbst gelöscht wurden, ist innerhalb von sieben Tagen möglich, sofern das Projekt bereits einmal im Backup vorhanden ist. Dabei kann allerdings nur das Git-Repository wiederhergestellt werden – alle Issues, Merge Requests und Snippets können nach dem Löschen des Projekts nicht wiederhergestellt werden.

Kann ich Zwei-Faktor-Authentifizierung (2FA) nutzen?

Ja, LRZ GitLab unterstützt Zwei-Faktor-Authentifizierung (2FA). Beim Einloggen wird nach der Eingabe Ihrer gewöhnlichen Kennung und dem Passwort ein zusätzliches Passwort gefragt. Dieses kann entweder mit einer auf dem Smartphone installierten App wie "privacyIDEA Authenticator" oder mit einem U2F-Gerät wie z.B. einem Yubikey erzeugt werden. Die Nutzung der 2FA ist eine freiwillige Möglichkeit die Sicherheit Ihres GitLab-Kontos zu erhöhen.

Um 2FA zu aktivieren, wählen Sie in Ihren Einstellungen "Account → Enable two-factor authentication". Dann scannen Sie den gezeigten QR-Code mit Ihrer App und geben das neu generierte Einmalpasswort ein. GitLab registriert die App automatisch und zeigt noch eine Liste von Recovery-Codes an. Diese Codes sollten in einem sicheren Ort aufbewahrt werden. Sie ermöglichen es den Zugang zum Konto wiederherzustellen falls Sie z.B. Ihr Smartphone und damit die App verlieren.

Ein U2F-Gerät kann auf der gleichen Seite zusätzlich zur App als zweite 2FA-Methode registriert werden. Danach können Sie Ihr Gerät anstatt der App benutzen. Die Registrierung eines 2FA-Geräts ohne erst eine App zu registrieren ist in GitLab leider nicht möglich. 

Hinweis: Nach dem zweiten Passwort der 2FA wird nur beim Einloggen auf der LRZ GitLab Webseite gefragt. Falls Sie auf Ihrem Konto einen SSH-Key hintergelegt haben, ist Zugriff mit dem Key weiterhin ohne zusätzliche Passwörter möglich. Die Authentifizierung auf der Kommandozeile (z.B. für das Klonen der Projekte) durch HTTPS ist dagegen nach der Aktivierung der 2FA nicht mehr möglich. Bitte benutzen Sie auf der Kommandozeile den Zugang mit dem SSH-Key.

Auf der GitLab-Seite finden Sie eine detaillierte Anleitung in Englisch. 

Sollten Sie 2FA-App oder Gerät und auch die Recovery Codes verloren haben, kontaktieren Sie uns bitte über den LRZ Servicedesk.

Wie lautet der SSH-Key-Fingerprint von GitLab?

Wenn Sie das erste Mal über ein Terminal/eine Eingabeaufforderung auf Ihrem PC Kontakt mit GitLab aufnehmen (z.B. wenn Sie ein Projekt klonen oder Änderungen ins Repository schreiben möchten), werden Sie wahrscheinlich nach der Authentizität des Hosts gefragt, mit dem Sie sich verbinden möchten. Die Fingerprints des LRZ GitLab finden Sie auf dessen Instanzkonfigurationsseite.

Wie greife ich auf die Container Registry meines Projekts zu?

Aktivieren Sie zunächst die Container Registry in den Projekt-Einstellungen unter "Settings" -> "General" → "Visibility, project features, permissions" -> "Container registry". Anschließend sollte in der Menüspalte auf der linken Seite unter "Deploy" ein neuer Menüpunkt "Container Registry" angezeigt werden. Im Menüpunkt "Container Registry" finden Sie die vorhandenen Images mit deren URLs oder, falls keine Images vorhanden sind, die URL der Registry Ihres Projekts.

Wir empfehlen die Nutzung von Access Tokens für den Zugriff auf die Container Registry. Hier ein beispielhafter Aufruf für die Kommandozeile:

$ docker login gitlab-int.srv.lrz.de:5005 -u USERNAME -p TOKEN

Mehr Informationen finden Sie in der offiziellen GitLab-Dokumentation: GitLab Docs: Authenticate with the container registry (externer Link)

Kann ich mit Personen auf GitLab zusammenarbeiten, die über keine entsprechende Kennung verfügen?

Ja, dies ist möglich mit GitInvited.

GitInvited wurde entwickelt, um in Kollaborationsprojekten externen Personen ebenfalls einen GitLab-Zugang geben zu können. Dabei haben alle, die sich mithilfe eines LDAP-Accounts (z.B. LRZ-, TUM- oder LMU-Kennung) in GitLab eingeloggt haben, jeweils ein Kontingent von 20 Einladungen. Diese Einladungen können über GitInvited an beliebige E-Mail-Adressen versendet werden. Die E-Mail-Adresse darf dabei noch nicht in GitLab registriert sein.

Kontos die durch diese Methode erstellt sind, haben den Status extern in LRZ GitLab. Das bedeutet unter anderem, dass sie keine Gruppen oder eigene Projekte erstellen können. Siehe GitLab Permissions Dokumentation für Details.

Personen, die die Einladung versendet haben (im weiteren Verlauf "Parent User" genannt), werden in der GitInvited-Datenbank mit den eingeladenen Personen ("Child User") verknüpft. So hat das LRZ auch für diese externen Personen immer einen Ansprechpartner.

Falls ein Parent User in GitLab geblockt wird (z.B. weil seine Kennung abgelaufen ist), werden alle Child User, für die er verantwortlich ist, ebenfalls geblockt. Um dies zu verhindern, müssen diese Personen zu einem neuen Parent User migriert werden. Dies kann nur von den Administratoren durchgeführt werden. Bitten Sie den neuen Parent User sich an den LRZ Servicedesk zu wenden.

Obwohl GitInvited und GitLab unter verschiedenen URLs erreichbar sind, findet eine Kommunikation beider Dienste untereinander statt. Beim erstmaligen Login kommt es daher vor, dass man im Zuge des OAuth-Login-Verfahrens zwischen den Anwendungen weitergeleitet wird.

Wie kann ich mein Repository verkleinern?

Vor allem mit großen oder sehr dynamischen Dateien können Git-Repositories groß werden. Das hat nicht nur Auswirkung auf dem Speicherplatz und Download-Zeiten, sondern verursacht zusätzliche Last auf unseren Servern. Insbesondere wenn man mit binären Dateien arbeitet und vergessen hat, sie mit Git Large File Storage (LFS) zu verwalten, ist die Verkleinerung des Repositorys oft nötig. Die Größe des Projekts inklusive Repository und LFS-Dateien wird auf der Projekt-Seite gezeigt. Grundregel: Wenn das Repository ohne Git LFS größer als 1 GB ist, soll es verkleinert werden.

Es reicht leider nicht, unnötige Dateien im Projekt-Verzeichnis einfach zu löschen. Dadurch wird das Repository nicht kleiner, weil die alten Versionen der Dateien weiterhin im Git verwaltet sind.

Methode 1: Das Projekt neu erstellen

Die einfachste und in den meisten Fällen empfohlene Methode ist eine Neuerstellung des Projektes, mit LFS-Verwaltung für binäre Dateien:

1. Neues leeres Projekt erstellen (New Project → Blank project → <Projektname angeben und "Initialize repository with a README" ankreuzen>)
2. Das neue Projekt klonen:
   git clone https://gitlab.lrz.de/username/new-project-with-lfs.git
   (oder durch SSH: git clone git@gitlab.lrz.de:username/new-project-with-lfs.git)
3. Dateien aus dem alten Projekt ins neue Projekt kopieren (ohne das Verzeichis .git/)

4. Git LFS initialisieren und LFS Tracking für binäre Dateien aktivieren:
   git lfs install
git lfs track '*.jpg'
git lfs track '*.zip'
git lfs track 'my_binary_data_file'
   ... weitere lfs track Kommandos für mehr Dateien und Dateitypen falls nötig ...

5. Dateien ins GitLab hochladen:
   git add .
git commit -m "Initial commit"
git push

6. Das alte Projekt löschen (Settings → General → Advanced → Remove project) 

Mit dieser Methode bleiben die alten Versionen der Dateien und dazugehörende Commit-Nachrichten, Branches, Issues usw. nicht erhalten. 

Methode 2: Die Versionsdateien umschreiben (history rewrite)

Falls die Verfügbarkeit der alten Versionen der Dateien, Commit-Nachrichten und/oder Branches des Projektes wichtig sind, kann diese etwas aufwändigere Methode verwendet werden. Es handelt sich um ein teilweises Umschreiben der Versionsdateien (history rewrite) mit Tools wie git-filter-repo oder BFG Repo Cleaner. So können beispielsweise Quellcode-Dateien mit ihrer gesamten Versionierung erhalten bleiben und nur alte Versionen der großen binären Dateien gelöscht werden. Die Einzelheiten in der Nutzung dieser Tools sind davon abhängig, wie die Dateien im Projekt organisiert sind. Unten ist ein Beispiel wie die Schritte bei dieser Methode ausschauen können:

1. Das bestehende Projekt mit Option "mirror" klonen
   git clone --mirror https://gitlab.lrz.de/username/the-big-project.git
(oder durch SSH: git clone --mirror git@gitlab.lrz.de:username/the-big-project.git)
   Hinweis: Falls Ihr Projekt bereits LFS-Dateien beinhaltet, werden sie durch diese Kommando nicht geklont und müssen im Schritt 5 manuell in das neue Projekt kopiert werden.
2. Mit git-filter-repo ausgewählte Dateien und Verzeichnisse löschen. In unserem Beispiel wird der Inhalt der Verzeichnis data sowie jpg- und zip-Dateien aus dem Projekt und dessen History entfernt. Für Einzelheiten bitte die Dokumentation der Tools konsultieren.
   cd the-big-project.git
git-filter-repo --use-base-name --path-glob '*.jpg' --path-glob '*.zip' --invert-paths
git-filter-repo --path data/ --invert-paths
3. Das verkleinerte Repository in ein neues Projekt hochladen
   git push --mirror https://gitlab.lrz.de/username/new-project-with-lfs.git
   Das neue Projekt klonen (ohne Option "mirror"):
4. cd ..
git clone https://gitlab.lrz.de/username/new-project-with-lfs.git
cd new-project-with-lfs

5. Ausgewählte binäre Dateien und Verzeichnisse aus dem alten Projekt in das neue Projekt kopieren (ohne das Verzeichis .git/ und die Dateien die im neuen Projekt bereits vorhanden sind).
6. Git LFS initialisieren und LFS Tracking für binäre Dateien aktivieren:
   git lfs install
git lfs track '*.jpg'
git lfs track '*.zip'
git lfs track 'my_binary_data_file'
   ... weitere lfs track Kommandos für mehr Dateien und Dateitypen falls nötig ...
   Hinweis: Falls Sie mehrere Branches im Ihrem Repository haben, bitte sicherstellen dass Git LFS in allen Branches ordnungsgemäß initialisiert wird.
7. Dateien ins GitLab hochladen:
   git add .
git commit -m "Adds some data files"
git push
8. Das alte Projekt löschen (Settings → General → Advanced → Remove project)

Mit dieser Methode bleiben die Versionierung der Dateien, Branches und Tags erhalten. Branch Requests auf der GitLab Web-Oberfläche gehen verloren, aber weil Branches weiterhin vorhanden sind können neue Branch Requests leicht erstellt werden. Issues, Kommentare, Snippets und andere Inhalte die nicht ein Teil der Git-Repository selber sondern im GitLab-Datenbank gespeichert sind bleiben nicht erhalten.

Issues können separat als CSV-Datei exportiert und wieder im neuen Projekt importiert werden. Kommentare in den Issues bleiben allerdings nicht erhalten.

Wichtig: Auch mit dieser Methode bitte ein neues Projekt mit einem neuen Pfad erstellen und das verkleinerte Repository dort pushen. Sonst bleiben die alten Versionen der Dateien noch als interne Referenzen auf dem Server erhalten.

(Für Fortgeschrittene gibt es eine auf der GitLab-Seite beschriebene Methode, innerhalb des Projektes nur die Repository umzuschreiben und damit alle weiteren Daten wie Issues, Kommentare usw. und der ursprüngliche Pfad zu erhalten. Sie ist relativ kompliziert und wir empfehlen sie nur, wenn Sie mit Git und GitLab gut vertraut sind. Falls Sie diese Methode probieren möchten, bitte sicherstellen dass alle Schritte, inklusive das Repository Cleanup mit der commit.map-Datei, durchgeführt werden. Außerdem ist es wichtig, dass alle Mitglieder des Projekts nach dem Verkleinern ihre lokale Kopien löschen und das Projekt neu klonen. Sonst wird beim nächsten git push das alte unveränderte History ins Projekt hochgeladen was zu einem Chaos führt.)