🌐 Gitlab pages

gitlab 🌐 Gitlab pages
Tags:
Categories:

  2 minute read  

Celem niniejszego dokumentu jest przedstawienie kompletnego procesu uruchomienia strony internetowej opartej na MkDocs za pomocą GitLab Pages oraz podłączenia jej do własnej domeny, np. docs.rachuna-net.pl lub rachuna-net.pl.

Wymagania

  • GitLab repository z plikami markdown zgodnymi z framweork gohugo i template docsy
  • Dostęp do panelu zarządzania DNS

1. Przygotowanie repozytorium z dokumentacją

  1. Zainicjalizuj projekt MkDocs (jeśli jeszcze nie istnieje):

    hugo new my-project
cd my-project

  2. Dodaj plik .gitlab-ci.yml do repozytorium:

    image: $CONTAINER_IMAGE_GOHUGO

🚀 build gohugo project:
stage: build
script:
   - npm install
   - hugo
artifacts:
   paths:
      - public
rules:
   - when: on_success

pages:
   stage: deploy
   dependencies:
      - 🚀 build gohugo project
   script:
      - echo "publish pages"
   pages: true
   rules: !reference [.rule:deploy:gohugo, rules]
   environment:
      name: Production
      url: https://$CI_PROJECT_NAMESPACE.gitlab.io/
only:
   - main

  3. Wypchnij zmiany do GitLaba:

    git add .
git commit -m "Init hugo site"
git push origin main

  4. Po chwili strona powinna być dostępna pod adresem domyślnym:

    https://<nazwa-użytkownika>.gitlab.io/<nazwa-repozytorium>

2. Podłączenie subdomeny docs.rachuna-net.pl

  1. Repozytorium → Settings → Pages → kliknij New Domain

  2. Ustawienie domeny np. docs.rachuna-net.pl

  3. GitLab wygeneruje dwa rekordy DNS:

    • ALIAS:

      docs.rachuna-net.pl.  ALIAS  pl.rachuna-net.gitlab.io.

    • TXT:

      _gitlab-pages-verification-code.docs.rachuna-net.pl.  TXT  gitlab-pages-verification-code=<wygenerowany_kod>

  4. ustawienie rekordów do strefy DNS domeny.

  5. GitLab automatycznie zweryfikuje rekordy i wygeneruje certyfikat SSL (Let’s Encrypt)

  1. Wystaw swoją aplikacje na gitlab-pages ✅ https://docs-7c5e90.gitlab.io
  2. W ustawieniach pages należy wybrać Deploy → page → new domain:

Po wypełnieniu formularza otrzymasz wpisy do rekordów DNS

   docs.rachuna-net.pl ALIAS pl.rachuna-net.gitlab.io.
   _gitlab-pages-verification-code.docs.rachuna-net.pl TXT gitlab-pages-verification-code=XYZ
  1. Po chwili następuje aktualizacja domeny
  2. Utworzenie Certyfikatu SSL z Let’s Encrypt

3. Podłączenie domeny głównej

Dla domen głównych nie można użyć ALIAS/CNAME, należy użyć rekordu A.

  1. W ustawieniach Pages → New Domain → dodaj rachuna-net.pl

  2. Skonfiguruj DNS:

    rachuna-net.pl.                                  A     35.185.44.232
_gitlab-pages-verification-code.rachuna-net.pl.  TXT   gitlab-pages-verification-code=<kod>

  3. Po propagacji DNS i weryfikacji – certyfikat SSL zostanie wystawiony automatycznie.

4. Efekt końcowy

Po wykonaniu powyższych kroków, strona MkDocs będzie dostępna pod Twoją własną domeną z certyfikatem SSL, np.:

https://docs.rachuna-net.pl

Przydatne linki

Last modified August 14, 2025: feat!: DEVOPS-123 Zmiana mkdocs na hugo (660375f)