Private Packagist im Team nutzen: privates Composer Registry richtig einrichten

1. Warum ein Team ein privates Composer Registry braucht

Private Packagist ist der von der Composer Firma Tidelift betriebene, kostenpflichtige Dienst zum Hosten privater PHP Pakete, gebaut auf derselben Technologie wie das öffentliche Packagist. Ohne einen solchen Dienst bindet ein Team interne Pakete meist über den vcs Repository Typ direkt an, mit einem Verweis auf das private Git Repository und einem persönlichen Zugangstoken pro Entwickler in der lokalen auth.json. Das funktioniert für ein einzelnes Paket, wird aber bei zehn oder mehr internen Paketen schnell unübersichtlich.

Das eigentliche Problem ist nicht die Technik, sondern die Rechteverwaltung. Verlässt ein Entwickler das Team, müssen sämtliche vergebenen Tokens für jedes einzelne Repository widerrufen werden. Neue Teammitglieder brauchen Zugriff auf potenziell Dutzende Repositories, bevor der erste composer install überhaupt funktioniert. Private Packagist löst das, indem es eine einzige Zugriffsschicht vor alle privaten Pakete legt: ein Team Mitglied bekommt einen einzigen Token für die Organisation, nicht einen pro Repository.

Zusätzlich übernimmt Private Packagist dieselbe Metadaten Auflösung wie das öffentliche Packagist: Versionsinformationen werden aus Git Tags extrahiert, composer.json Änderungen werden automatisch erkannt, und Sicherheitswarnungen aus der Roave Security Advisories Datenbank werden auch für private Pakete eingeblendet, sofern eine bekannte Schwachstelle in einer verwendeten Abhängigkeit auftaucht.

2. Private Packagist einrichten: Organisation und erste Pakete

Die Einrichtung beginnt mit einer Organisation bei packagist.com, dem kommerziellen Gegenstück zu packagist.org. Innerhalb der Organisation legt ein Administrator die erste Paketquelle an, meist durch Verknüpfung mit einem GitHub oder GitLab Account über OAuth. Private Packagist scannt danach automatisch alle Repositories, auf die der verknüpfte Account Zugriff hat, und schlägt vor, welche davon als Composer Pakete importiert werden sollen.

Für jedes importierte Paket erkennt Private Packagist automatisch den Paketnamen aus der composer.json im Repository und beginnt sofort, Tags und Branches als Versionen aufzulösen. Ein wichtiger Unterschied zum öffentlichen Packagist: private Pakete erscheinen nicht in der öffentlichen Suche und sind ausschließlich für Mitglieder der jeweiligen Organisation sichtbar, selbst wenn der Paketname zufällig mit einem öffentlichen Paket kollidiert.

{
  "name": "mironsoft/internal-billing",
  "type": "library",
  "require": {
    "php": "^8.4"
  },
  "repositories": [
    {
      "type": "composer",
      "url": "https://repo.packagist.com/mironsoft-gmbh/"
    }
  ],
  "require-map": {
    "mironsoft/internal-billing": "^4.2"
  }
}

3. Quellen anbinden: GitHub, GitLab und eigene Git Repositories

Private Packagist unterstützt neben GitHub und GitLab auch Bitbucket sowie beliebige SSH erreichbare Git Repositories über eine manuell hinterlegte URL. Für GitHub und GitLab läuft die Anbindung über eine offizielle App Integration, die automatisch Webhooks registriert. Jeder Push auf einen Branch mit gültiger composer.json löst dadurch sofort eine neue Metadaten Aktualisierung im Registry aus, ohne dass jemand manuell einen Sync Button betätigen muss.

Für Repositories außerhalb der unterstützten Plattformen, etwa ein selbst gehostetes GitLab CE oder ein internes Gitea, hinterlegt man einen SSH Deploy Key, den Private Packagist für den Lesezugriff nutzt. In diesem Fall entfällt der automatische Webhook, stattdessen pollt der Dienst das Repository in regelmäßigen Abständen auf neue Tags, was in der Praxis eine Verzögerung von wenigen Minuten bis zur Sichtbarkeit einer neuen Version bedeutet.

# Generate a dedicated deploy key for Private Packagist (read only)
ssh-keygen -t ed25519 -C "private-packagist-readonly" -f ./packagist_deploy_key -N ""

# Add the public key as a read-only deploy key on the self-hosted Git server
cat ./packagist_deploy_key.pub
# Paste the output into: Gitea/GitLab CE -> Repository -> Deploy Keys -> Read only

# Paste the private key into Private Packagist's package source configuration
cat ./packagist_deploy_key

4. Composer Auth: auth.json statt einzelner Tokens

Der entscheidende Vorteil im Entwickleralltag zeigt sich in der auth.json. Statt für jedes private Git Repository einen eigenen Eintrag unter http-basic oder github-oauth zu pflegen, genügt ein einziger Eintrag für die Private Packagist URL der Organisation. Composer authentifiziert sich damit gegen genau eine Quelle und erhält von dort alle Pakete, für die der hinterlegte Token Leserechte besitzt.

Der Token selbst wird nicht mehr pro Repository, sondern pro Organisation in Private Packagist erzeugt und kann granular auf einzelne Teams eingeschränkt werden. Verlässt ein Entwickler das Unternehmen, genügt das Widerrufen dieses einen Tokens, um jeglichen Zugriff auf sämtliche privaten Pakete sofort zu beenden, ganz ohne durch Dutzende Git Repositories navigieren zu müssen.

# Configure Composer to authenticate against Private Packagist
composer config --global --auth http-basic.repo.packagist.com token "$PACKAGIST_TOKEN"

# Verify the auth.json entry was written correctly
cat "$(composer config --global home)/auth.json"

# Install a private package once auth is configured
composer require mironsoft/internal-billing:^4.2

5. Zugriffsrechte pro Team und pro Paket steuern

Private Packagist organisiert Zugriffsrechte über zwei Ebenen: Organisationen und darin verschachtelte Teams. Ein Team Backend kann beispielsweise Lesezugriff auf alle Kernpakete erhalten, während ein Team Mobile ausschließlich auf die für mobile Clients relevanten API Pakete beschränkt bleibt. Diese Trennung verhindert, dass jedes Teammitglied automatisch Zugriff auf sämtliche internen Pakete des Unternehmens bekommt, selbst wenn es diese für die eigene Arbeit gar nicht benötigt.

Zusätzlich unterscheidet Private Packagist zwischen Lese und Schreibrechten auf Paketebene. Ein CI System benötigt in aller Regel nur Lesezugriff, um composer install auszuführen, während nur wenige Personen Schreibrechte zum Anlegen neuer Paketquellen erhalten sollten. Diese feingranulare Trennung reduziert die Angriffsfläche erheblich gegenüber einem einzelnen, für alles gültigen Deploy Key.

Praktisch bildet sich diese Struktur direkt in der Verwaltungsoberfläche ab: eine Organisation enthält mehrere Teams, jedes Team erhält eine Liste zugewiesener Paketgruppen, und jedes Teammitglied wird genau einem oder mehreren Teams zugeordnet. Ein neuer Entwickler im Team Mobile sieht dadurch beim ersten composer install ausschließlich die für ihn freigegebenen Pakete, ganz ohne dass ein Administrator manuell einzelne Repository Berechtigungen durchgehen muss.

{
  "organization": "mironsoft-gmbh",
  "teams": [
    {
      "name": "backend-core",
      "permission": "read",
      "packages": [
        "mironsoft/internal-billing",
        "mironsoft/core",
        "mironsoft/http-client"
      ]
    },
    {
      "name": "mobile-clients",
      "permission": "read",
      "packages": [
        "mironsoft/mobile-api-contracts"
      ]
    },
    {
      "name": "release-managers",
      "permission": "write",
      "packages": ["*"]
    }
  ]
}

6. GitHub Mirroring und Ausfallsicherheit

Eine oft übersehene Funktion von Private Packagist ist das automatische Dist Mirroring. Der Dienst lädt bei jedem erkannten Tag automatisch ein Archiv des jeweiligen Commits herunter und speichert es redundant im eigenen Speicher. Fällt das ursprüngliche GitHub oder GitLab Repository temporär aus, etwa durch eine Störung beim Hosting Anbieter, bleibt composer install trotzdem funktionsfähig, weil Private Packagist das archivierte Dist Paket direkt ausliefert, ganz ohne erneuten Zugriff auf die ursprüngliche Quelle.

Dieses Mirroring ist besonders für CI Pipelines relevant, die während eines Deployments keine Zeit für einen fehlgeschlagenen composer install wegen einer externen Störung haben. Ein GitHub Ausfall betrifft dadurch nur neue Pushes, nicht die Installation bereits getaggter Versionen, was die Ausfallsicherheit der gesamten Build Pipeline spürbar erhöht.

7. Integration in CI Pipelines ohne geleakte Tokens

Für CI Systeme wie GitLab CI, GitHub Actions oder Jenkins hinterlegt man den Private Packagist Token als geschütztes CI Secret, niemals im Klartext im Repository. Der Token wird zur Laufzeit in eine COMPOSER_AUTH Umgebungsvariable im JSON Format geschrieben, die Composer automatisch anstelle der lokalen auth.json auswertet. Dieses Vorgehen vermeidet, dass Zugangsdaten überhaupt als Datei auf der Festplatte des CI Runners landen.

Ein separater, ausschließlich lesender Token pro CI Pipeline, getrennt vom persönlichen Entwickler Token, ist die empfohlene Praxis. Wird ein CI Token kompromittiert, etwa durch einen fehlerhaft konfigurierten Log Output, lässt er sich isoliert widerrufen, ohne dass Entwickler ihre eigenen lokalen Zugangsdaten neu einrichten müssen.

# .gitlab-ci.yml — inject Private Packagist token as JSON auth, never as a file in the repo
install:
  stage: build
  variables:
    COMPOSER_AUTH: '{"http-basic":{"repo.packagist.com":{"username":"token","password":"$PACKAGIST_CI_TOKEN"}}}'
  script:
    - composer install --no-dev --optimize-autoloader --no-progress

8. Alternativen: Satis, Toran Proxy und eigene Lösungen

Wer keinen Drittanbieter Dienst nutzen möchte, kann mit composer/satis ein selbst gehostetes, statisches Composer Repository aufbauen. Satis generiert einmalig oder per Cronjob eine packages.json Datei aus konfigurierten Quell Repositories, die anschließend über einen beliebigen Webserver ausgeliefert wird. Der Vorteil liegt in der vollständigen Kontrolle über die Infrastruktur, der Nachteil in fehlendem automatischem Mirroring, fehlender granularer Rechteverwaltung und der Notwendigkeit, den Cronjob selbst zu betreiben und zu überwachen.

Als Zwischenlösung bietet sich Private Composer Repository Server Software wie Toran Proxy oder ein selbst betriebenes Satis mit einer vorgeschalteten Nginx Basic Auth an. Für kleine Teams mit wenigen internen Paketen ist das oft ausreichend, für wachsende Organisationen mit mehreren Teams und häufigem Personalwechsel wird der Wartungsaufwand einer selbst gehosteten Lösung im Vergleich zu Private Packagist jedoch schnell unverhältnismäßig hoch.

9. Private Packagist im Vergleich zu selbst gehosteten Lösungen

Die Entscheidung zwischen Private Packagist und einer selbst gehosteten Alternative wie Satis hängt stark von Teamgröße, Wartungsbudget und Sicherheitsanforderungen ab. Die folgende Tabelle stellt die wichtigsten Unterschiede gegenüber.

Für Teams unter fünf Entwicklern mit zwei bis drei internen Paketen ist ein selbst gehostetes Satis oft völlig ausreichend und deutlich günstiger. Sobald mehrere Teams mit unterschiedlichen Zugriffsanforderungen, häufiger Personalfluktuation oder strengen Compliance Vorgaben ins Spiel kommen, überwiegt der Verwaltungsvorteil von Private Packagist die zusätzlichen Kosten in den meisten Fällen deutlich.

10. Zusammenfassung

Private Packagist im Team löst das grundlegende Problem verteilter Zugangsdaten für private Composer Pakete: statt persönlicher Tokens pro Git Repository verwaltet ein einziges Registry sämtliche Zugriffsrechte zentral, granular auf Teams und Pakete aufgeteilt. Die Anbindung von GitHub, GitLab und eigenen Git Repositories läuft über automatische Webhooks oder SSH Deploy Keys, während Composer Auth über eine einzige auth.json Konfiguration ohne Dutzende Einzelrepositories auskommt.

Für CI Pipelines sorgt ein separater, ausschließlich lesender Token für eine klare Trennung zwischen persönlichem Entwickler Zugriff und automatisiertem Build Prozess. Automatisches Dist Mirroring erhöht die Ausfallsicherheit gegenüber Störungen beim eigentlichen Git Hoster. Für kleine Teams bleibt ein selbst gehostetes Satis eine valide, kostengünstigere Alternative, doch sobald mehrere Teams und häufiger Personalwechsel ins Spiel kommen, überwiegt der Verwaltungsvorteil von Private Packagist klar.

11. FAQ: Private Packagist im Team nutzen