Mit GitLab Pages veröffentlichst du statische Websites direkt aus einem GitLab-Repository – kostenlos auf GitLab.com. Das funktioniert für reines HTML genauso wie für Websites, die ein Static Site Generator (SSG) wie Hugo, Jekyll, Astro oder Eleventy erzeugt.
In diesem Tutorial richtest du Schritt für Schritt ein neues Projekt ein: von der CI/CD-Konfiguration über den ersten Deploy bis zur eigenen Domain mit HTTPS. Grundkenntnisse in Git und Webentwicklung setzen wir voraus.
So funktioniert GitLab Pages
GitLab Pages baut deine Website mit GitLab CI/CD. Die Konfiguration steht in der Datei .gitlab-ci.yml im Stammverzeichnis deines Projekts. Sie legt fest, wie ein Runner deine Website erzeugt.
Entscheidend ist ein Job mit dem Namen pages. Er legt die fertigen Dateien im Ordner public ab und gibt diesen Ordner als Artefakt weiter. Läuft der Job erfolgreich durch, veröffentlicht GitLab den Inhalt von public als Website.
Weil der Build in einer normalen Pipeline läuft, hast du die volle Kontrolle: Du kannst beliebige Befehle ausführen, Abhängigkeiten installieren, Plugins nutzen und jeden Build live im Job-Log verfolgen. Kein Black-Box-Hosting.
Welche Arten von Websites gibt es?
Mit GitLab Pages kannst du zwei Arten von Websites anlegen:
- Benutzer- oder Gruppen-Website: eine Website pro Benutzer oder Gruppe, erreichbar unter
https://benutzername.gitlab.iooderhttps://gruppenname.gitlab.io. Dafür muss das Projekt genau so heißen, zum Beispielbenutzername.gitlab.io. - Projekt-Websites: beliebig viele, eine pro Projekt, zum Beispiel unter
https://benutzername.gitlab.io/projektname.
Tipp: Wenn du Websites für ein Unternehmen oder ein Team veröffentlichst, lege dafür eine Gruppe an, statt deinen persönlichen Account zu nutzen. So bleiben private und berufliche Projekte getrennt, und die Website liegt unter dem Namen der Gruppe.
Hinweis: Neue Projekte veröffentlichen standardmäßig unter einer eindeutigen Domain (zum Beispiel projektname-abc123.gitlab.io). Wenn du die Adresse im Format benutzername.gitlab.io/projektname möchtest, deaktiviere unter Deploy > Pages die Option Eindeutige Domain verwenden (englische Oberfläche: Use unique domain).
Schritt 1: Projekt anlegen
Es gibt zwei Wege:
- Mit Vorlage starten: Wähle Neues Projekt > Aus Vorlage erstellen und dann eine Pages-Vorlage, zum Beispiel Pages/Plain HTML, Pages/Hugo oder Pages/Jekyll. Die Vorlage bringt eine funktionierende
.gitlab-ci.ymlbereits mit. Weitere Beispiele findest du in der Gruppe GitLab Pages examples. - Leeres Projekt: Wähle Neues Projekt > Leeres Projekt erstellen, vergib einen Namen und lege die Sichtbarkeit fest.
Die Sichtbarkeit des Repositorys und die der Website sind zwei verschiedene Dinge: Auch aus einem privaten Repository kann eine öffentliche Website entstehen. Wer die Website besucht, sieht nur die erzeugten HTML-, CSS- und JavaScript-Dateien, nicht deinen Quellcode. Unter Einstellungen > Allgemein > Sichtbarkeit legst du fest, wer die Pages-Website sehen darf.
Schritt 2: Die .gitlab-ci.yml anlegen
Lege im Stammverzeichnis deines Projekts eine Datei .gitlab-ci.yml an. Hier drei Beispiele.
Option A: Reines HTML
Liegen deine HTML-Dateien direkt im Repository, reicht diese Konfiguration:
pages:
stage: deploy
script:
- mkdir .public
- cp -r * .public
- mv .public public
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
Der Job pages kopiert alle Dateien in den Ordner public und gibt ihn als Artefakt weiter. Die Regel unter rules sorgt dafür, dass nur Commits auf dem Standard-Branch (meist main) die Website aktualisieren.
Option B: Hugo
Hugo erzeugt die Website standardmäßig direkt im Ordner public:
image: registry.gitlab.com/pages/hugo/hugo_extended:latest
variables:
GIT_SUBMODULE_STRATEGY: recursive
pages:
script:
- hugo --minify
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
GIT_SUBMODULE_STRATEGY: recursive brauchst du, wenn dein Theme als Git-Submodul eingebunden ist.
Option C: Jekyll
Jekyll läuft auf Ruby. Mit Bundler und einem Gemfile im Projekt sieht die Konfiguration so aus:
image: ruby:3.3
pages:
before_script:
- bundle install
script:
- bundle exec jekyll build -d public
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
Für andere Generatoren wie Astro, Eleventy oder Docusaurus funktioniert es nach demselben Prinzip: im script bauen, das Ergebnis in public ablegen, public als Artefakt weitergeben.
Syntax vorab prüfen: Unter Build > Pipeline-Editor kannst du deine .gitlab-ci.yml im Tab Validieren prüfen, bevor du sie committest.
Von der ersten Website zum ganzen Workflow
Dieselbe Pipeline, die deine Website baut, testet und deployt auch deine Anwendungen. Mit GitLab verwaltest du Code, Reviews und CI/CD auf einer Plattform.
Schritt 3: Inhalte pushen und Deploy prüfen
Committe die .gitlab-ci.yml zusammen mit deinen Inhalten und pushe auf den Standard-Branch. GitLab startet daraufhin automatisch eine Pipeline. Unter Build > Pipelines verfolgst du den Fortschritt. Ist der Job pages erfolgreich, findest du die Adresse deiner Website unter Deploy > Pages.
Wichtig: Committe keine lokal erzeugten Build-Ordner, also zum Beispiel nicht _site (Jekyll) oder public (Hugo). Sonst landen doppelte Inhalte im Repository, und der Build kann fehlschlagen. Trage diese Ordner in die .gitignore im Stammverzeichnis ein, für Jekyll etwa so:
_site
Läuft der Build nicht durch, findest du die Ursache im Job-Log unter Build > Jobs. Dort kannst du auch die Artefakte durchsuchen oder herunterladen und so prüfen, was genau im Ordner public gelandet ist.
Schritt 4: Eigene Domain verbinden (optional)
Die Standardadresse unter gitlab.io funktioniert ohne weitere Einrichtung. Wenn du eine eigene Domain nutzen möchtest, gehst du so vor:
- Öffne in deinem Projekt Deploy > Pages und wähle Neue Domain.
- Trage deine Domain ein, zum Beispiel
example.comoderwww.example.com. - Lege beim DNS-Anbieter deiner Domain die Einträge an, die GitLab anzeigt:
- Für eine Root-Domain (
example.com) einenA-Eintrag auf die IP-Adresse des GitLab-Pages-Servers. Die aktuelle Adresse steht in der Dokumentation zu eigenen Domains. - Für eine Subdomain (
www.example.com) einenCNAME-Eintrag aufbenutzername.gitlab.io. - Einen
TXT-Eintrag zur Verifizierung. GitLab zeigt dir den genauen Wert an. Ohne Verifizierung wird die Domain nicht aktiviert.
- Für eine Root-Domain (
- Klicke auf Verifizieren, sobald die DNS-Einträge gesetzt sind.
DNS-Änderungen brauchen oft etwas Zeit, bis sie überall ankommen. Ist die Domain nicht sofort erreichbar, warte ein paar Minuten und versuche es erneut.
HTTPS: GitLab kann für deine Domain automatisch ein kostenloses Zertifikat von Let's Encrypt ausstellen und erneuern. Alternativ lädst du ein eigenes Zertifikat hoch.
Du kannst mehrere Domains und Subdomains mit demselben Projekt verbinden. Wiederhole dafür einfach die Schritte oben.
FAQ
Ist GitLab Pages kostenlos?
Ja. GitLab Pages ist in allen Tarifen auf GitLab.com enthalten, auch im kostenlosen.
Welche Websites kann ich mit GitLab Pages hosten?
Nur statische Websites: HTML, CSS und JavaScript, auch wenn sie ein Static Site Generator erzeugt. Serverseitige Sprachen wie PHP und Datenbankverbindungen werden nicht unterstützt.
Warum heißt der Job pages, und warum der Ordner public?
GitLab erkennt am Job-Namen pages, dass das Ergebnis als Website veröffentlicht werden soll. Standardmäßig wird der Inhalt des Ordners public veröffentlicht.
Kann ich aus einem privaten Repository eine öffentliche Website veröffentlichen?
Ja. Die Sichtbarkeit des Repositorys und die der Pages-Website stellst du getrennt ein.
Kann ich eine eigene Domain mit HTTPS nutzen?
Ja. Du verbindest die Domain unter Deploy > Pages, verifizierst sie per TXT-Eintrag und lässt das Zertifikat automatisch über Let's Encrypt ausstellen oder lädst ein eigenes hoch.
Wo finde ich die erzeugten Dateien nach dem Build?
Unter Build > Jobs im Job pages. Dort kannst du die Artefakte durchsuchen oder herunterladen.




