Erste Schritte

Du hast ein managed GitLab bei server.camp bestellt – herzlichen Glückwunsch! GitLab ist weit mehr als eine Code-Verwaltung: Es ist die zentrale Plattform für die gesamte Softwareentwicklung – von der Projektplanung über Code-Reviews bis hin zu automatisierten Tests und Deployments. Diese Anleitung richtet sich an Entwicklungsteams in KMU, Freelancer und Vereine, die professionelles Projektmanagement und Versionskontrolle auf eigener Infrastruktur nutzen wollen.

GitLab.com ist eine gute Einstiegsoption – aber für Unternehmen und Teams gibt es überzeugende Gründe, eine eigene GitLab-Instanz bei server.camp zu betreiben:

Für wen lohnt sich ein eigenes GitLab?

Ein eigenes GitLab lohnt sich, sobald eines dieser Kriterien zutrifft: du arbeitest mit Kundendaten oder proprietärem Code, du brauchst mehr als 5 Benutzer, du musst DSGVO-Konformität nachweisen, oder du willst volle Kontrolle über Backups und Konfiguration.

GitLab ist hierarchisch aufgebaut:

• Gruppe – ein Bereich für ein Team, einen Kunden oder einen Themenbereich (z. B. “Interne Projekte”, “Kunde Meier AG”)
• Untergruppe – optionale Verschachtelung innerhalb einer Gruppe (z. B. “Kunde Meier AG / Frontend”, “Kunde Meier AG / Backend”)
• Projekt – eine einzelne Anwendung, Bibliothek oder ein Service innerhalb einer Gruppe

In einem Projekt findest du:

• Repository – der eigentliche Git-Code im Projekt
• Merge Request (MR) – ein Vorschlag, Code-Änderungen zusammenzuführen (Code-Review-Prozess)
• Issue – eine Aufgabe, ein Bug oder eine Feature-Anfrage

📁 Intern
   📁 Infrastructure (Ansible, Terraform, Docker-Configs)
   📁 Libraries (wiederverwendbare Module)
   📁 Tools (interne Skripte, Automatisierung)
📁 Kunde-A
   📁 Frontend
   📁 Backend
   📁 Dokumentation
📁 Kunde-B
   📁 ...
📁 Open Source (öffentliche Projekte, falls gewünscht)

Zugriffsrechte über Gruppen steuern

Lege für jeden Kunden oder internen Bereich eine eigene Gruppe an. Zugriffsrechte werden auf Gruppenebene vergeben und gelten automatisch für alle Projekte innerhalb der Gruppe. So musst du nicht jedes Projekt einzeln konfigurieren – und wenn ein externer Entwickler nur an Kunde A arbeitet, bekommt er nur Zugriff auf die Gruppe “Kunde A”.

In einem Projekt oder einer Gruppe unter Einstellungen → Mitglieder → Einladen. GitLab kennt folgende Rollen:

Externe Freelancer sicher einbinden

Lade externe Entwickler als Developer in die spezifische Kundengruppe ein – nicht auf Instanzebene. So sehen sie nur die Projekte, an denen sie arbeiten, und haben keinen Zugriff auf andere Kunden oder interne Repositories. Beim Projektende entfernst du sie aus der Gruppe.

Für die tägliche Arbeit mit Git empfiehlt sich die Authentifizierung per SSH-Key statt Passwort:

1. SSH-Key generieren (falls noch keiner vorhanden): ssh-keygen -t ed25519
2. Den öffentlichen Schlüssel (~/.ssh/id_ed25519.pub) kopieren
3. In GitLab: Benutzereinstellungen → SSH-Schlüssel → Neuen Schlüssel hinzufügen
4. Ab sofort: git clone git@dein-gitlab.srv.camp:gruppe/projekt.git

GitLab unterstützt die Registrierung nur für bestimmte Domains. Um nur bestimmte Domains zuzulassen, gehe in den Admin-Bereich → Einstellungen → Allgemein → Sign-up restrictions → Domains und füge die gewünschten Domains hinzu. So können sich nur Personen mit einer E-Mail-Adresse aus diesen Domains registrieren.

GitLab unterstützt SSO über SAML und OpenID Connect. Wenn du ein Managed Authentik bei server.camp nutzt, können sich deine Mitarbeitenden mit ihrem zentralen Konto einloggen. SSO ist im Corporate-Paket enthalten. Kontaktiere unseren Support für die Einrichtung.

Auch externe Identity-Provider lassen sich anbinden

Nutzt du bereits Keycloak, Azure AD oder einen anderen Identity-Provider? Kein Problem – GitLab unterstützt die gängigen Protokolle. So kannst du deine bestehende Nutzerverwaltung weiter nutzen und musst keine neuen Accounts anlegen. Voraussetzung ist bei uns die Nutzung des Corporate-Pakets. Wir unterstützen dich gerne bei der Einrichtung.

1. Auf “Neues Projekt” klicken
2. Wähle:
   • Leeres Projekt – für ein neues Vorhaben
   • Aus Vorlage – GitLab bringt Templates für verschiedene Sprachen und Frameworks mit
   • Importieren – von GitHub, Bitbucket oder einem anderen GitLab
3. Projektnamen vergeben und Gruppe auswählen
4. Sichtbarkeit festlegen:
   • Privat – nur eingeladene Mitglieder (empfohlen für fast alle Projekte)
   • Intern – alle angemeldeten Benutzer auf dieser GitLab-Instanz
   • Öffentlich – jeder, auch ohne Account (für Open-Source-Projekte)
5. Optional: README initialisieren (empfohlen – so ist das Repository nicht leer)

Installiere zunächst Git auf deinem Rechner.

# Per SSH (empfohlen)
git clone git@dein-gitlab.srv.camp:gruppe/projekt.git

# Per HTTPS
git clone https://dein-gitlab.srv.camp/gruppe/projekt.git

# Geänderte Dateien für den nächsten Commit vormerken
git add .

# Änderungen als Commit speichern
git commit -m "Kurze Beschreibung, was geändert wurde"

# Änderungen zu GitLab hochladen
git push

Branches erlauben es, an Features oder Bugfixes zu arbeiten, ohne den Hauptentwicklungszweig zu beeinflussen:

# Neuen Branch erstellen und wechseln
git checkout -b feature/neue-funktion

# Änderungen im Branch committen
git add .
git commit -m "Login-Seite implementiert"

# Branch zu GitLab hochladen
git push -u origin feature/neue-funktion

Branch-Namenskonvention

Vereinbare im Team eine einheitliche Benennung für Branches, z. B. feature/beschreibung, fix/beschreibung, hotfix/beschreibung. Das macht die Branch-Liste übersichtlich und signalisiert sofort, worum es geht.

Tipp: kurzlebige Branches sind einfacher in der Handhabung

Je kürzer ein Branch lebt, desto einfacher ist die Handhabung. Arbeite an einem Feature, erstelle einen Merge Request, reviewe und merge – und lösche den Branch anschließend. So vermeidest du lange lebende Branches, die mit dem Hauptbranch auseinanderdriften und schwer zu mergen sind.

Folgenden Workflow empfehlen wir für Teams:

1. Jede Änderung passiert in einem eigenen Branch
2. Wenn die Entwicklung fertig ist, wird ein Merge Request (MR) erstellt
3. Ein Teamkollege reviewt den Code und gibt Feedback oder genehmigt
4. Nach Genehmigung wird der Branch in den Hauptbranch gemergt

1. In GitLab zum Projekt navigieren → Merge Requests → Neu
2. Source Branch (dein Feature-Branch) und Target Branch (z. B. main) auswählen
3. Titel und Beschreibung eintragen – was wurde geändert und warum?
4. Reviewer zuweisen
5. Optional: Labels, Milestone und zugehöriges Issue verknüpfen
6. Auf “Merge Request erstellen” klicken

Als Reviewer:

1. Merge Request öffnen → Tab “Änderungen” zeigt alle Code-Änderungen
2. Zeile anklicken → Kommentar hinterlassen (Fragen, Verbesserungsvorschläge, Lob)
3. Nach der Review: “Genehmigen” klicken
4. Der Autor kann den MR anschließend zusammenführen

main-Branch schützen

Aktiviere unter Einstellungen → Repository → Geschützte Branches den Schutz für main. So kann niemand direkt in den Hauptbranch pushen – alles muss über einen Merge Request mit Review gehen. Das verhindert versehentliche Fehler im Produktivcode und etabliert ein Vier-Augen-Prinzip.

Unter Issues in jedem Projekt kannst du Aufgaben, Bugs und Feature-Anfragen verwalten:

• Titel und Beschreibung – Was ist das Problem oder die Aufgabe? (Markdown wird unterstützt)
• Labels – Kategorisierung (z. B. bug, feature, dringend, backlog)
• Zuweisung – Wer ist zuständig?
• Milestone – Zu welchem Release oder Sprint gehört das Issue?
• Due Date – Fälligkeitsdatum
• Gewicht – Aufwandsschätzung (Story Points)
• Verknüpfung mit MR – Issue automatisch schließen, wenn der MR gemergt wird (mit Closes #42 in der MR-Beschreibung)

Tipp: "Scoped" Labels verwenden

In der Premium- und Ultimate-Version von Gitlab kannst du Scoped Labels nutzen, um strukturierte Informationen zu erfassen. Beispiel: Status::To Do, Status::In Arbeit, Status::Review, Status::Fertig. So kannst du den Status eines Issues direkt am Label ablesen und es in Issue Boards verwenden. Mit kleinen Einschränkungen kannst du das auch in der Community-Version nachahmen, indem du Labels mit einem Präfix versiehst (z. B. Status::To Do). Die Struktur musst du dann manuell pflegen, aber es hilft, den Überblick zu behalten.

Unter Issues → Board kannst du ein Kanban-Board einrichten:

Backlog → To Do → In Arbeit → Review → Fertig

Jedes Issue wird als Karte dargestellt und kann per Drag-and-Drop zwischen den Spalten bewegt werden. Spalten basieren auf Labels – erstelle Labels wie To Do, In Arbeit, Review und füge sie als Board-Spalten hinzu.

Unter Issues → Milestones kannst du Meilensteine mit Start- und Enddatum anlegen. Weise Issues einem Milestone zu und verfolge den Fortschritt über den Fortschrittsbalken. Ideal für Sprint-Planung oder Release-Zyklen.

Jedes Projekt hat ein integriertes Wiki für technische Dokumentation:

• Markdown-basiert
• Eigenständiges Git-Repository (kann geklont und lokal bearbeitet werden)
• Seitenleiste mit Navigation
• Suchfunktion

Typische Wiki-Inhalte:

• Architektur-Übersicht und Systemdesign
• Einrichtungsanleitung für Entwickler (Setup-Guide)
• API-Dokumentation
• Deployment-Prozess und Runbooks
• Entscheidungsprotokolle (ADRs)

Wiki vs. README

Nutze die README.md im Repository für den schnellen Überblick (Was ist das Projekt? Wie starte ich es?). Nutze das Wiki für ausführliche Dokumentation, die über das Repository hinausgeht (Architektur, Prozesse, Entscheidungen).

GitLab CI/CD wird über eine Datei .gitlab-ci.yml im Repository-Root gesteuert. Bei jedem Code-Push wird automatisch eine Pipeline gestartet, die definierte Schritte (Jobs) durchläuft.

stages:
  - test
  - build
  - deploy

test:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm test

build:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/

deploy:
  stage: deploy
  script:
    - echo "Deploy to production"
    # Hier dein Deployment-Skript einfügen
  only:
    - main
  when: manual

Wenn CI/CD konfiguriert ist, zeigt jeder Merge Request den Pipeline-Status an. Du siehst sofort, ob die Tests bestehen, bevor du Code zusammenführst. In Kombination mit geschützten Branches kannst du erzwingen, dass ein MR nur gemergt werden darf, wenn die Pipeline grün ist.

Du kannst deine .gitlab-ci.yml auch lokal testen, bevor du sie pushst. Installiere dazu das Tool gitlab-ci-local auf deinem Rechner und führe die Pipeline lokal aus:

# alle Jobs
gitlab-ci-local

# nur einen bestimmten Job (z. B. "test")
gitlab-ci-local <job-name>

Mehr Infos zur Nutzung von gitlab-ci-local findest du in der offiziellen Dokumentation.

CI/CD-Jobs benötigen einen Runner – ein System, das die Pipeline-Schritte tatsächlich ausführt.

Runner sind nicht im Hosting enthalten

Die GitLab-Pakete bei server.camp enthalten keine GitLab Runner. Einen geteilten Runner für alle Kunden bieten wir aus Sicherheitsgründen nicht an – dein Code und deine Secrets sollen nicht auf einem gemeinsam genutzten System landen.

Du kannst einen GitLab Runner problemlos auf einem eigenen Server, einem Entwickler-Rechner oder in einer VM laufen lassen:

1. GitLab Runner installieren (verfügbar für Linux, macOS, Windows)
2. Runner registrieren: GitLab → Einstellungen → CI/CD → Runner → Neuen Runner registrieren
3. Den angezeigten Token und die URL in den Runner eintragen
4. Executor wählen: Docker (empfohlen), Shell, oder Kubernetes

# Beispiel: Runner unter Linux registrieren
gitlab-runner register \
  --url https://dein-gitlab.srv.camp \
  --token glrt-DEIN_TOKEN

Docker-Executor empfohlen

Der Docker-Executor führt jeden CI/CD-Job in einem frischen Container aus. Das sorgt für reproduzierbare Builds und verhindert, dass sich Reste vorheriger Jobs auf das Ergebnis auswirken. Voraussetzung: Docker muss auf dem Runner-Rechner installiert sein.

Für Teams, die keinen eigenen Server betreiben wollen, bietet server.camp dedizierte Runner an:

Dedizierte Runner laufen isoliert und ausschließlich für deine Instanz. Zur Bestellung kannst du dich einfach an unseren Support wenden.

CI/CD ist optional – du kannst GitLab zunächst vollständig ohne Pipelines nutzen. Versionskontrolle, Issues, Merge Requests und Wikis funktionieren ohne Runner. Wenn du bereit für automatisierte Tests oder Deployments bist, fügst du einen Runner hinzu.

GitLab bringt eine integrierte Container Registry mit. Du kannst Docker-Images direkt in deinem GitLab-Projekt speichern und verwalten – ohne externe Registry wie Docker Hub.

# Docker-Image bauen und in die GitLab Registry pushen
docker login dein-gitlab.srv.camp:1234
docker build -t dein-gitlab.srv.camp:1234/gruppe/projekt:latest .
docker push dein-gitlab.srv.camp:1234/gruppe/projekt:latest

Die Registry ist besonders nützlich in Kombination mit CI/CD: Die Pipeline baut das Image, pusht es in die Registry, und der Deployment-Job zieht es von dort.

GitLab bietet Snippets – kurze Code-Schnipsel, die geteilt werden können, ohne ein vollständiges Repository anzulegen. Ideal für Shell-Skripte, Konfigurationsdateien oder Anleitungen, die im Team geteilt werden sollen.

Snippets können privat, intern oder öffentlich sein und unterstützen Syntax-Highlighting für alle gängigen Sprachen.

GitLab enthält eine integrierte Web IDE basierend auf VS Code – einen vollwertigen Code-Editor direkt im Browser. Ideal für schnelle Änderungen (Typo in der README, Konfigurationsanpassung), ohne das Repository lokal klonen zu müssen.

In jedem Projekt: Code → Open Web IDE (oder . auf der Tastatur drücken).

Tipp für Freelancer: Nutze Issues nicht nur für Code-Aufgaben, sondern auch als Todo-Liste für Kundenprojekte. So hast du Aufgaben, Code und Dokumentation an einem Ort – und kannst dem Kunden bei Bedarf Einblick geben.

Onboarding-Tipp: Erstelle ein Projekt “Onboarding” mit Wiki-Seiten: Setup-Anleitung für Entwickler, Git-Workflow, Branch-Konventionen, CI/CD-Überblick. Neue Entwickler lesen das Wiki und können sofort produktiv starten.

Tipp für Vereine: Auch wenn nur eine Person die Website pflegt – nutze GitLab als Backup und Dokumentationsort. Wenn der Webmaster aufhört, hat der Nachfolger sofort den kompletten Code, die gesamte Änderungshistorie und die Dokumentation im Wiki.

Verbinde GitLab mit Mattermost über Webhooks:

• Neue Merge Requests, Pipeline-Status und Issue-Updates automatisch in einen Entwickler-Channel posten
• Unter Projekt → Einstellungen → Integrationen → Mattermost aktivierbar

Überwache deine deployten Anwendungen mit Uptime Kuma. In Kombination mit Node-RED kannst du bei einem Monitoring-Alert automatisch ein GitLab-Issue erstellen.

Speichere GitLab-Zugangsdaten, Deploy-Tokens und API-Keys sicher in Vaultwarden. Besonders wichtig für CI/CD-Secrets: Nutze GitLab-interne CI/CD-Variablen (maskiert und geschützt) statt Secrets im Code.

Im Corporate-Paket kannst du GitLab mit Authentik per SAML oder OpenID Connect verbinden. Mitarbeitende loggen sich mit einem zentralen Konto ein, Onboarding und Offboarding werden zentral gesteuert.

Jeder Benutzer kann unter Benutzereinstellungen → Konto → Zwei-Faktor-Authentifizierung 2FA aktivieren. Empfohlen für alle Benutzer, Pflicht für Admins und Maintainer.

Für automatisierte Zugriffe (CI/CD, Skripte, Integrationen) nutze Deploy-Tokens oder Personal Access Tokens mit minimal notwendigen Berechtigungen – niemals dein persönliches Passwort in Skripten.

Unter Einstellungen → CI/CD → Variablen kannst du Secrets (API-Keys, Passwörter, Tokens) sicher hinterlegen. Diese stehen in Pipelines zur Verfügung, ohne im Code sichtbar zu sein. Markiere sensible Variablen als “Maskiert” und “Geschützt”.

Falls du Unterstützung beim Einrichten von CI/CD-Pipelines brauchst, Fragen zur Rechteverwaltung hast oder externe Entwickler sicher einbinden möchtest, erreichst du uns jederzeit unter support@server.camp. Wir helfen dir gerne!

Häufig gestellte Fragen zu GitLab findest du auch auf unserer Produktseite.