Exécuter le générateur de rétroportage dans un pipeline de publication

Outillage de build — PAS une dépendance d’exécution. Cette page explique comment exploiter le pipeline de publication qui produit le rétroportage. Le pipeline s’exécute en CI ; il ne s’exécute jamais dans une application en aval.

En bref

Le parcours de production repose sur deux workflows. 0-ci.yml vérifie chaque modification apportée à l’une ou l’autre des branches permanentes. Une publication source déclenche build.yml, qui produit puis publie la distribution. Les deux workflows sont vérifiés par rapport à .github/workflows/.

Le verrou CI

0-ci.yml s’exécute sur les push et les pull requests vers PHP74 et PHP81. Il comporte trois jobs, exécutés dans l’ordre :

1. PHPStan (Build Tools) — composer analyse, niveau 10 appliqué à rector/rules et scripts.
2. PHPUnit (Rector Rules) — composer test, avec les suites de fixtures des trois règles personnalisées.
3. Build Dry Run — composer build:dry, dépendant des deux premiers jobs.

Les événements de confiance s’exécutent sur des runners PHP auto-hébergés. Les pull requests issues de forks et Dependabot s’exécutent sur des runners hébergés par GitHub, où PHP 8.5 est provisionné. Vérifié par rapport à 0-ci.yml (l’expression runs-on et l’étape conditionnelle setup-php). Le modèle à deux branches vérifie séparément toute modification qui touche les deux cibles, via la pull request de chaque branche.

Le pipeline de publication

build.yml est la build de production. Elle se déclenche sur un événement repository_dispatch de type source-release, ou manuellement via workflow_dispatch avec un tag en entrée. Le tag de version pilote tout le processus. Le numéro de version suit MAJOR.MINOR.PATCH pour une API publique déclarée (Semantic Versioning 2.0.0 §2).

Voie PHP 8.1

1. build-php81 — récupère l’outillage de build, provisionne PHP 8.5, installe les dépendances de build, clone les dépôts source au tag de publication, exécute scripts/build.php, bascule le runner sur PHP 8.1, vérifie la syntaxe d’output/src sur PHP 8.1, puis installe le paquet produit avec --no-dev. La sortie est envoyée en tant qu’artefact.
2. validate-php81 — récupère l’artefact, puis l’installe et le teste sur une matrice de PHP 8.1, 8.2, 8.3 et 8.4.
3. release-php81 — récupère l’artefact, valide et tague l’arbre généré, le compresse en excluant vendor/ et .git/, et publie une release GitHub avec l’archive jointe.

Voie PHP 7.4

1. build-php74 — récupère l’outillage de build sur la branche PHP74, provisionne PHP 8.5, clone uniquement le dépôt source du cœur au tag, exécute scripts/build.php --target=php74, bascule sur PHP 7.4, puis vérifie la syntaxe de la sortie sur PHP 7.4.
2. validate-php74 — installe et teste sur une matrice de PHP 7.4 et 8.0.
3. release-php74 — compresse uniquement la sortie du cœur et la joint à la même release en tant que seconde archive.

Vérifié par rapport aux définitions de jobs et aux matrices de build.yml.

Les deux voies partagent une seule et même release GitHub. La voie PHP 8.1 la crée, et la voie PHP 7.4 joint son archive au même tag. Le groupe concurrency backport-build avec cancel-in-progress: false sérialise les builds afin que deux publications source ne puissent pas entrer en concurrence.

Exploiter le pipeline

Déclencher une build

Une build se déclenche normalement de façon automatique lorsque l’organisation source publie une release. Pour reconstruire un tag spécifique manuellement, déclenche build.yml avec le tag en entrée (par exemple v2.0.0). Le jeton de déclenchement est secrets.BACKPORT_TRIGGER_TOKEN, et il autorise le clonage des dépôts source. Vérifié par rapport à build.yml (workflow_dispatch.inputs.tag, GH_TOKEN).

Lire une build en échec

Le script de build s’arrête à la première étape en échec et affiche le nom de l’étape ainsi que l’erreur. Les cinq étapes sont la fusion, Rector, la génération de composer.json, la copie des ressources et la validation. Si l’étape de vérification de syntaxe qui suit la build échoue, Rector a produit une sortie que l’environnement d’exécution cible rejette. Cette étape est le garde-fou qui protège la release. Rattache l’échec à sa cause dans /integrations/backport/troubleshooting/.

Ce qui est publié

La release joint les archives de distribution compressées. Le paquet est livré sous forme de tags de version, et non de branches. Les consommateurs installent nextpdf/backport (et éventuellement nextpdf/backport-pro) depuis le canal de release. L’archive exclut vendor/ et .git/. Vérifié par rapport à build.yml (zip -r ... -x '*/vendor/*' '*/.git/*').

Versionner la sortie

Le composer.json produit porte la version transmise sur la ligne de commande (--version, ou le tag de déclenchement avec le v initial retiré). Le paquet Pro épingle nextpdf/backport à la contrainte caret major.minor correspondante. Vérifié par rapport à scripts/adjust-composer.php (majorMinor(), generateProComposer()). Garde le tag de publication source et la version du rétroportage alignés afin que la table replace reste cohérente.

Suite

• /integrations/backport/security-and-operations/ — la frontière de confiance et la posture de chaîne d’approvisionnement du pipeline.
• /integrations/backport/troubleshooting/ — référence des échecs étape par étape.