GitLab CI fuer generische PHP-Microservices: Pipeline ohne Magento-Bezug

1. Warum eine Microservice-Pipeline anders aussieht als eine Magento-Pipeline

Eine Magento-Pipeline muss mit Besonderheiten wie Reindexierung, statischem Content-Deployment, Zero-Downtime-Wechseln zwischen Release-Verzeichnissen und einer komplexen Modul-Struktur umgehen. Ein eigenstaendiger PHP-Microservice, etwa ein Symfony-basierter Rechnungsdienst oder eine Laravel-API fuer Bestellstatus-Abfragen, hat davon nichts: Er besteht aus einem einzigen Composer-Projekt, einer ueberschaubaren Zahl an Abhaengigkeiten und meist einem klaren, containerisierten Deployment-Ziel.

Diese Reduktion ist ein Vorteil, kein Mangel. Eine generische Pipeline fuer einen Microservice kann sich auf vier klare Schritte konzentrieren: Abhaengigkeiten installieren, automatisierte Tests ausfuehren, statische Code-Analyse durchfuehren und ein deploybares Artefakt, meist ein Docker-Image, bauen und ausrollen. Wer versucht, Magento-Pipeline-Patterns eins zu eins auf ein solches Projekt zu uebertragen, baut unnoetige Komplexitaet ein, die weder gebraucht noch gewartet werden will.

2. Grundgeruest: Stage-Aufbau fuer eine generische PHP-Pipeline

Der Grundaufbau folgt einem einfachen linearen Muster: build installiert Abhaengigkeiten und stellt sie als Artefakt fuer nachfolgende Stages bereit, test fuehrt PHPUnit und statische Analyse parallel aus, und deploy baut und verteilt das finale Artefakt. Anders als bei Magento entfaellt eine eigene Stage fuer Static-Content-Deployment oder Reindexierung vollstaendig, weil es diese Konzepte in einem generischen PHP-Service schlicht nicht gibt.

Wichtig ist der stages:-Block am Anfang der Datei, der die Reihenfolge global festlegt. Jobs innerhalb derselben Stage laufen parallel, Stages selbst nacheinander, es sei denn, needs: definiert explizite Abhaengigkeiten quer durch die Stages, was bei kleineren Microservices oft gar nicht noetig ist, weil die Gesamtlaufzeit ohnehin gering bleibt.

stages:
  - build
  - test
  - deploy

variables:
  COMPOSER_CACHE_DIR: "$CI_PROJECT_DIR/.composer-cache"

default:
  image: php:8.3-cli
  before_script:
    - apt-get update -qq && apt-get install -y -qq unzip git
    - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

3. Composer install und Caching als Basis fuer alle Folge-Jobs

Der build-Job installiert die Abhaengigkeiten einmal und stellt vendor/ als Artefakt fuer alle nachfolgenden Jobs bereit. Das vermeidet, dass jeder Test- und Analyse-Job composer install einzeln ausfuehrt, was bei mehreren parallelen Jobs unnoetig Zeit kostet und die Runner unnoetig belastet. Kombiniert mit einem CI-Cache fuer den Composer-Download-Cache beschleunigt sich auch der erste composer install spuerbar, da Paket-Zips nicht bei jedem Lauf erneut aus dem Netz geladen werden muessen.

Fuer produktionsnahe Builds ist composer install --no-dev --optimize-autoloader die richtige Wahl im finalen Deployment-Artefakt, waehrend Test- und Analyse-Jobs die Dev-Abhaengigkeiten wie PHPUnit oder PHPStan benoetigen. Ein sauberer Ansatz ist deshalb, im build-Job einmal mit Dev-Abhaengigkeiten zu installieren und Test-Jobs dieses Artefakt weiterzuverwenden, waehrend ein separater, spaeterer Schritt im Deploy-Kontext die schlanke Produktionsvariante erzeugt.

build:
  stage: build
  script:
    - composer install --no-interaction --prefer-dist
  cache:
    key: composer-cache
    paths:
      - $COMPOSER_CACHE_DIR
  artifacts:
    paths:
      - vendor/
    expire_in: 1 hour

4. PHPUnit mit Coverage-Auswertung im MR-Widget

GitLab liest Testabdeckung direkt aus der Job-Ausgabe aus, wenn eine coverage:-Regex im Job hinterlegt ist, und zeigt das Ergebnis als Prozentzahl im Pipeline-Widget an. Fuer detailliertere Auswertung, etwa Zeilen-genaue Markierung im Diff eines Merge Requests, wird zusaetzlich ein Cobertura-XML-Report als artifacts: reports: coverage_report benoetigt, den PHPUnit ueber --coverage-cobertura erzeugt.

Wichtig ist, dass Xdebug oder PCOV im verwendeten PHP-Image aktiv ist, da PHPUnit ohne Coverage-Treiber keine Abdeckungsdaten erzeugen kann und den Report-Schritt stillschweigend uebersprint. Fuer schnellere Testlaeufe empfiehlt sich PCOV gegenueber Xdebug, da es ausschliesslich fuer die Coverage-Erfassung entwickelt wurde und dadurch deutlich weniger Overhead im Vergleich zum vollen Xdebug-Debugger verursacht.

phpunit:
  stage: test
  needs: ["build"]
  script:
    - vendor/bin/phpunit --coverage-text --coverage-cobertura=coverage.xml
  coverage: '/^\s*Lines:\s*\d+.\d+\%/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml

5. Statische Code-Analyse mit PHPStan und PHP-CS-Fixer

Statische Analyse laeuft in einer eigenstaendigen Stage parallel zu PHPUnit, da beide Werkzeuge unabhaengig voneinander arbeiten und sich nicht gegenseitig blockieren muessen. PHPStan prueft Typkorrektheit und potenzielle Laufzeitfehler bereits vor der Ausfuehrung, waehrend PHP-CS-Fixer im --dry-run-Modus sicherstellt, dass der Code-Stil dem Projektstandard entspricht, ohne die Dateien tatsaechlich zu veraendern.

Beide Tools sollten die Pipeline bei Verstoessen aktiv fehlschlagen lassen, anders als etwa optionale Security-Scans, weil Stilverstoesse und Typfehler in einem gut gepflegten Microservice-Projekt kein akzeptabler Zustand fuer den main-Branch sind. Ein exit code ungleich null von PHPStan oder PHP-CS-Fixer --dry-run reicht dafuer bereits aus, ohne dass zusaetzliche allow_failure:-Konfiguration noetig waere.

phpstan:
  stage: test
  needs: ["build"]
  script:
    - vendor/bin/phpstan analyse src --level=8 --no-progress

php-cs-fixer:
  stage: test
  needs: ["build"]
  script:
    - vendor/bin/php-cs-fixer fix --dry-run --diff

6. Symfony-spezifische Schritte: Doctrine-Migrationen und Environment

Bei einem Symfony-Service kommen zwei zusaetzliche Pruefungen hinzu, die es bei einem generischen PHP-Projekt ohne Framework nicht gibt: doctrine:schema:validate stellt sicher, dass die Entity-Mappings zum tatsaechlichen Datenbankschema passen, und doctrine:migrations:migrate --dry-run in der test-Stage prueft, dass ausstehende Migrationen fehlerfrei anwendbar sind, ohne sie tatsaechlich auf einer echten Datenbank auszufuehren.

Da Symfony strikt zwischen APP_ENV=test, dev und prod unterscheidet, muss die CI-Umgebungsvariable APP_ENV explizit auf test gesetzt werden, sonst greift die Pipeline versehentlich auf eine Produktionskonfiguration zu, die in CI gar nicht existiert. Eine eigene .env.test.local, die nur in der Pipeline verwendet wird, haelt echte Zugangsdaten sauber von der CI-Konfiguration getrennt.

symfony-doctrine-check:
  stage: test
  needs: ["build"]
  variables:
    APP_ENV: test
  services:
    - postgres:16
  script:
    - php bin/console doctrine:schema:validate --skip-sync
    - php bin/console doctrine:migrations:migrate --dry-run --no-interaction

7. Laravel-spezifische Schritte: artisan test und Config-Cache

Bei Laravel uebernimmt artisan test die Rolle von PHPUnit als komfortabler Wrapper mit lesbarer Ausgabe und zusaetzlichen Laravel-spezifischen Assertions. Vor dem Testlauf muss die .env-Datei aus .env.testing kopiert und ein APP_KEY generiert werden, da Laravel ohne gueltigen Verschluesselungsschluessel bereits beim Bootstrapping mit einer Exception abbricht.

Zusaetzlich lohnt sich ein artisan config:cache und artisan route:cache Testlauf innerhalb der Pipeline, selbst wenn dieser Cache im Testkontext nicht dauerhaft genutzt wird. Er deckt fruehzeitig Fehler auf, die erst beim Cachen der Konfiguration sichtbar werden, etwa nicht aufloesbare Umgebungsvariablen in Config-Dateien, die im normalen unkgecachten Betrieb stillschweigend als null durchgereicht wuerden.

laravel-test:
  stage: test
  needs: ["build"]
  script:
    - cp .env.testing .env
    - php artisan key:generate
    - php artisan config:cache
    - php artisan test --parallel

8. Deployment als Docker-Image-Build und -Push

Der uebliche Deployment-Weg fuer einen containerisierten Microservice ist der Build eines Docker-Images innerhalb der Pipeline mit anschliessendem Push in die GitLab Container Registry, gefolgt von einem Rollout auf der Zielplattform, etwa via kubectl oder einem einfachen SSH-Restart auf einem Docker-Compose-Host. Das produktionsreife Image sollte dabei ein Multi-Stage-Dockerfile nutzen, das Composer-Dev-Abhaengigkeiten und Test-Tools gar nicht erst in das finale Image uebernimmt.

Anders als bei einer Magento-Instanz mit geteiltem Dateisystem und mehreren parallel laufenden PHP-FPM-Prozessen ist das Deployment eines Microservices meist ein einzelner, austauschbarer Container. Ein fehlgeschlagenes Deployment laesst sich deshalb haeufig einfach durch Zuruecksetzen auf das vorherige Image-Tag beheben, ohne die komplexeren Zero-Downtime-Mechanismen, die bei monolithischen Magento-Deployments noetig sind.

build-image:
  stage: deploy
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

9. Fazit: schlank bleiben statt Magento-Muster zu kopieren

Ein generischer PHP-Microservice profitiert am meisten von einer Pipeline, die genau die Schritte enthaelt, die das Projekt tatsaechlich braucht, und nicht von einer verkleinerten Kopie einer Magento-Pipeline mit uebernommenen, aber ungenutzten Konzepten. Build, Test, statische Analyse und ein einfacher Image-Build reichen fuer die meisten Symfony- oder Laravel-Services vollstaendig aus.

Framework-spezifische Ergaenzungen wie Doctrine-Migrationspruefungen bei Symfony oder artisan test bei Laravel sollten gezielt und minimal eingebaut werden, statt vorsorglich jede denkbare Pruefung zu integrieren. Eine kurze, gut lesbare .gitlab-ci.yml ist bei einem kleinen Microservice fast immer wertvoller als eine vollstaendige, aber unuebersichtliche Pipeline mit ungenutzten Stages.

10. Zusammenfassung

11. FAQ: GitLab CI fuer PHP-Microservices: Das Wichtigste auf einen Blick