Den Backport-Builder in einer Release-Pipeline ausführen

Build-Werkzeug – KEINE Laufzeitabhängigkeit. Diese Seite beschreibt den Betrieb der Release-Pipeline, die den Backport erzeugt. Die Pipeline läuft in der CI und niemals in einer nachgelagerten Anwendung.

Auf einen Blick

Der Produktionspfad nutzt zwei Workflows. 0-ci.yml prüft jede Änderung an einem der beiden permanenten Branches. build.yml erzeugt und veröffentlicht die Distribution; ein Source-Release löst diesen Workflow aus. Beide werden gegen .github/workflows/ verifiziert.

Das CI-Gate

0-ci.yml läuft bei Pushes und Pull Requests auf PHP74 und PHP81. Der Workflow hat drei Jobs, die nacheinander ausgeführt werden:

1. PHPStan (Build-Werkzeuge) – composer analyse, Level 10 über rector/rules und scripts.
2. PHPUnit (Rector-Regeln) – composer test, die Fixture-Suiten für die drei benutzerdefinierten Regeln.
3. Build-Trockenlauf – composer build:dry; hängt von den ersten beiden Jobs ab.

Vertrauenswürdige Ereignisse laufen auf selbst gehosteten PHP-Runnern. Fork-Pull-Requests und Dependabot laufen auf GitHub-gehosteten Runnern, auf denen PHP 8.5 bereitgestellt wird. Verifiziert gegen 0-ci.yml (den runs-on-Ausdruck und den bedingten setup-php-Schritt). Das Dual-Branch-Modell prüft eine Änderung, die beide Ziele betrifft, unabhängig im Pull Request des jeweiligen Branches.

Die Release-Pipeline

build.yml ist der Produktions-Build. Er wird durch ein repository_dispatch-Ereignis vom Typ source-release oder manuell über workflow_dispatch mit einer Tag-Eingabe ausgelöst. Der Versions-Tag steuert alles. Eine Versionsnummer folgt dem Schema MAJOR.MINOR.PATCH für eine deklarierte öffentliche API (Semantic Versioning 2.0.0 §2).

PHP-8.1-Lane

1. build-php81 – die Build-Werkzeuge auschecken, PHP 8.5 bereitstellen, Build-Abhängigkeiten installieren, die Source-Repositorys beim Release-Tag klonen, scripts/build.php ausführen, den Runner auf PHP 8.1 umstellen, output/src unter PHP 8.1 per Syntaxprüfung prüfen und anschließend das erzeugte Paket mit --no-dev installieren. Die Ausgabe wird als Artefakt hochgeladen.
2. validate-php81 – das Artefakt herunterladen und auf einer Matrix aus PHP 8.1, 8.2, 8.3 und 8.4 installieren und testen.
3. release-php81 – das Artefakt herunterladen, den generierten Baum committen und taggen, ihn unter Ausschluss von vendor/ und .git/ zippen und ein GitHub-Release mit angehängtem Archiv veröffentlichen.

PHP-7.4-Lane

1. build-php74 – die Build-Werkzeuge auf dem PHP74-Branch auschecken, PHP 8.5 bereitstellen, nur das Core-Source-Repository beim Tag klonen, scripts/build.php --target=php74 ausführen, auf PHP 7.4 umstellen und die Ausgabe unter PHP 7.4 per Syntaxprüfung prüfen.
2. validate-php74 – Installation und Tests auf einer Matrix aus PHP 7.4 und 8.0.
3. release-php74 – die Core-only-Ausgabe zippen und dem gleichen Release als zweites Archiv anhängen.

Verifiziert gegen die Job-Definitionen und Matrizen in build.yml.

Die beiden Lanes teilen sich ein GitHub-Release. Die PHP-8.1-Lane erstellt es, die PHP-7.4-Lane hängt ihr Archiv an denselben Tag an. Die concurrency-Gruppe backport-build mit cancel-in-progress: false serialisiert Builds, sodass zwei Source-Releases nicht miteinander kollidieren können.

Die Pipeline betreiben

Einen Build auslösen

Ein Build wird normalerweise automatisch ausgelöst, wenn die Source-Organisation ein Release veröffentlicht. Um einen bestimmten Tag manuell neu zu bauen, lösen Sie build.yml mit der Tag-Eingabe aus (zum Beispiel v2.0.0). Das Dispatch-Token ist secrets.BACKPORT_TRIGGER_TOKEN und autorisiert das Klonen der Source-Repositorys. Verifiziert gegen build.yml (workflow_dispatch.inputs.tag, GH_TOKEN).

Einen fehlgeschlagenen Build lesen

Das Build-Skript hält bei der ersten fehlgeschlagenen Phase an und gibt den Phasennamen sowie den Fehler aus. Die fünf Phasen sind Merge, Rector, composer.json-Generierung, Asset-Kopie und Validierung. Wenn der Syntaxprüfungsschritt nach dem Build fehlschlägt, hat Rector eine Ausgabe erzeugt, die von der Ziel-Laufzeit abgelehnt wird. Dieser Schritt ist das Gate, das das Release schützt. Ordnen Sie den Fehler der passenden Ursache unter /integrations/backport/troubleshooting/ zu.

Was veröffentlicht wird

Das Release enthält die gezippten Distributionsarchive als Anhänge. Das Paket wird über Versions-Tags ausgeliefert, nicht über Branches. Projekte, die den Backport verwenden, installieren nextpdf/backport (und optional nextpdf/backport-pro) aus dem Release-Kanal. Das Archiv schließt vendor/ und .git/ aus. Verifiziert gegen build.yml (zip -r ... -x '*/vendor/*' '*/.git/*').

Die Ausgabe versionieren

Die erzeugte composer.json enthält die auf der Kommandozeile übergebene Version (--version oder den Dispatch-Tag ohne führendes v). Das Pro-Paket pinnt nextpdf/backport auf die passende major.minor-Caret-Einschränkung. Verifiziert gegen scripts/adjust-composer.php (majorMinor(), generateProComposer()). Halten Sie den Source-Release-Tag und die Backport-Version aufeinander abgestimmt, damit die replace-Map konsistent bleibt.

Weiter

• /integrations/backport/security-and-operations/ – die Vertrauensgrenze und die Haltung der Pipeline zur Lieferkette.
• /integrations/backport/troubleshooting/ – schrittweise Fehlerreferenz pro Phase.