Custom Module für gitlab und Composer anpassen

By PierreAdmin , 12 October 2026

Was braucht ein eigenes Modul, um in gitlab gepflegt und über composer geladen werden zu können.

Intro

  • Jedes eigene per.net Modul hat ein eigenes, öffentliches GitLab-Projekt in per-net/modules und wird in Projekten wie ein Contrib-Modul per Composer geholt.
  • Lokal liegen die Module in drupal-11-starter/pernet-modules/[modulname]/, jedes mit eigenem Git. Dort werden sie gepflegt.
  • In Projekten landen sie in web/modules/pernet/. Der Ordner wird nicht versioniert (wie contrib). web/modules/custom/ bleibt für Module, die nur ein einzelnes Projekt braucht.
  • Öffentlich heisst: Jeder darf lesen und herunterladen, schreiben darf nur ich. Dafür braucht es keine Keys oder Tokens, weder lokal noch auf den Servern.

A -- Modul nach GitLab bringen (einmalig pro Modul)

A.1 -- Modulordner

  • Fertiges, getestetes Modul im Finder nach pernet-modules/ kopieren.

A.2 -- composer.json im Modul

  • Damit Composer das Modul als Paket erkennt. Beispiel pernet_env_icon:
  • {
    "name": "per-net/pernet_env_icon",
    "description": "per.net: Icon for the current environment in the Navigation sidebar.",
    "type": "drupal-custom-module",
    "license": "GPL-2.0-or-later",
    "require": {
        "drupal/core": "^11"
    }
}
  • Braucht das Modul ein Contrib-Modul, gehört es unter require dazu (z. B. pernet_guide: "drupal/editor_advanced_link": "*").
  • ### WICHTIG: Keine Versionsnummer in die composer.json. Die Version kommt aus dem Git-Tag (siehe C).

A.3 -- .gitignore im Modul

  • # macOS
.DS_Store

A.4 -- GitLab-Projekt anlegen

  • Gruppe per-net > modules > New project > Create blank project
  • Project name: exakt der Modulname, z. B. pernet_env_icon
  • Visibility: Public
  • «Initialize repository with a README» abwählen
  • ### WICHTIG: Ein Projekt kann nur Public sein, wenn auch die Gruppen darüber Public sind. per-net und modules sind seit 12.10.2026 Public, die Untergruppen web, private und tests bleiben privat.
  • ### WICHTIG: Name genau prüfen. Pusht man an eine Adresse, die es nicht gibt, legt GitLab automatisch ein neues, privates Projekt an.

A.5 -- Erster Push und Version

  • Im Terminal im Modulordner (pernet-modules/[modulname]):
  • git init -b main
git add -A
git commit -m "[modulname]: erste Version"
git remote add origin git@gitlab.com:per-net/modules/[modulname].git
git push -u origin main
git tag 1.0.0
git push origin 1.0.0
  • Ein normaler git push überträgt keine Tags, darum der eigene Befehl.
  • Kontrolle auf GitLab: Dateien da, unter Code > Tags steht 1.0.0, Globus-Symbol = Public.

B -- Modul in ein Projekt einbinden

B.1 bis B.3 sind im Starter schon erledigt. Für ein neues Modul braucht es nur einen weiteren Eintrag in B.1.

B.1 -- Quelle in public/composer.json

  • Unter repositories pro Modul ein Eintrag:
  • {
    "type": "vcs",
    "url": "https://gitlab.com/per-net/modules/pernet_env_icon.git"
}
  • vcs = Version Control System: Composer schaut direkt ins Git-Repo und liest die Tags als Versionen. Der bestehende Eintrag type: composer ist dagegen ein Katalog (drupal.org für alle Drupal-Module).

B.2 -- Zielordner in public/composer.json

  • Unter installer-paths als erster Eintrag (Composer nimmt den ersten passenden, sonst landen die Module in custom):
  • "web/modules/pernet/{$name}": [
    "vendor:per-net"
],

B.3 -- .gitignore im Projekt

  • Unter «Drupal Core und Contrib»:
  • /public/web/modules/pernet/

B.4 -- Modul holen

  • ### WICHTIG: Liegt das Modul schon als Kopie in web/modules/custom/, diese zuerst im Finder löschen. Drupal darf nie zwei Kopien desselben Moduls finden. Zwischen Löschen und Composer kein drushh cr und die Site nicht laden.
  • Im Ordner public:
  • composer require per-net/pernet_env_icon:^1.0
  • ^1.0 = alle Versionen ab 1.0.0 bis unter 2.0.0
  • Composer legt web/modules/pernet/ selbst an.
  • Danach drushh cr (Drupal merkt sich, wo die Module liegen) bzw. drushh en [modulname] bei einem neuen Modul.
  • Commit: composer.json und composer.lock

C -- Modul ändern, neue Version

  • Ändern immer in pernet-modules/[modulname], dann wie gewohnt git add -A, git commit, git push.
  • ### WICHTIG: Ein Tag entsteht nie automatisch. Commits ohne neuen Tag liegen zwar auf GitLab, Projekte bekommen sie aber nicht. Der Tag hängt fest an dem Commit, der beim Taggen der aktuellste war.
  • Ist ein Stand fertig, neuen Tag setzen:
  • git tag 1.0.1
git push origin 1.0.1
  • Versionsnummer (Semantic Versioning, MAJOR.MINOR.PATCH):
    • PATCH 1.0.1: Fehler behoben, Tippfehler, nichts Neues
    • MINOR 1.1.0: neue Funktion, alles Bisherige läuft weiter (z. B. neue Editor-Klassen)
    • MAJOR 2.0.0: Projekte müssen angepasst werden (z. B. Feld umbenannt)
  • Im Projekt holen:
  • composer update per-net/[modulname]
drushh updb
drushh cr
  • Installierte Version prüfen: composer show per-net/[modulname]
  • ### HINWEIS: Config in config/optional des Moduls (z. B. Inhaltstypen bei pernet_guide) wird nur bei der Erstinstallation übernommen. Änderungen daran gelten für neue Projekte, in bestehenden Projekten von Hand nachziehen.

✎ Claude – offen: Wie man eine Änderung im Projekt testet, bevor man taggt.

Composer