Eseguire il builder del backport in una pipeline di release

Strumenti di build — NON una dipendenza di runtime. Questa pagina spiega come gestire la pipeline di release che produce il backport. La pipeline viene eseguita in CI; non viene mai eseguita in un’applicazione a valle.

In sintesi

Il percorso di produzione si basa su due workflow. 0-ci.yml funge da gate per ogni modifica destinata a uno dei due branch permanenti. build.yml produce e rilascia la distribuzione, ed è attivato da una release sorgente. Entrambi sono verificati rispetto a .github/workflows/.

Il gate CI

0-ci.yml viene eseguito su push e pull request destinati a PHP74 e PHP81. Prevede tre job, eseguiti in quest’ordine:

1. PHPStan (Build Tools) — composer analyse, livello 10 su rector/rules e scripts.
2. PHPUnit (Rector Rules) — composer test, le suite di fixture per le tre regole personalizzate.
3. Build Dry Run — composer build:dry, dipendente dai primi due job.

Gli eventi attendibili vengono eseguiti su runner PHP self-hosted. Le pull request da fork e Dependabot vengono eseguite su runner ospitati da GitHub con PHP 8.5 configurato. Verificato rispetto a 0-ci.yml (l’espressione runs-on e lo step condizionale setup-php). Il modello a doppio branch applica il gate in modo indipendente, sulla pull request di ciascun branch, a una modifica che interessa entrambi i target.

La pipeline di release

build.yml è la build di produzione. Viene attivata da un evento repository_dispatch di tipo source-release, oppure manualmente tramite workflow_dispatch con un input tag. Il tag di versione governa l’intero flusso. Un numero di versione è MAJOR.MINOR.PATCH su un’API pubblica dichiarata (Semantic Versioning 2.0.0 §2).

Lane PHP 8.1

1. build-php81 — esegue il checkout degli strumenti di build, configura PHP 8.5, installa le dipendenze di build, clona i repository sorgente al tag della release, esegue scripts/build.php, imposta il runner su PHP 8.1, esegue il controllo sintattico di output/src su PHP 8.1, quindi installa il pacchetto prodotto con --no-dev. L’output viene caricato come artifact.
2. validate-php81 — scarica l’artifact, lo installa e lo testa su una matrice di PHP 8.1, 8.2, 8.3 e 8.4.
3. release-php81 — scarica l’artifact, crea commit e tag per l’albero generato, lo comprime in un archivio zip escludendo vendor/ e .git/, e pubblica una release GitHub con l’archivio allegato.

Lane PHP 7.4

1. build-php74 — esegue il checkout degli strumenti di build sul branch PHP74, configura PHP 8.5, clona solo il repository sorgente core al tag, esegue scripts/build.php --target=php74, passa a PHP 7.4 ed esegue il controllo sintattico dell’output su PHP 7.4.
2. validate-php74 — installa e testa su una matrice di PHP 7.4 e 8.0.
3. release-php74 — comprime l’output solo-core in un archivio zip e lo allega alla stessa release come secondo archivio.

Verificato rispetto alle definizioni dei job e alle matrici di build.yml.

Le due lane condividono un’unica release GitHub. La lane PHP 8.1 la crea e la lane PHP 7.4 allega il proprio archivio allo stesso tag. Il gruppo concurrency backport-build con cancel-in-progress: false serializza le build affinché due release sorgente non possano entrare in conflitto.

Gestire la pipeline

Attivare una build

Di norma una build si attiva automaticamente quando l’organizzazione sorgente pubblica una release. Per ricostruire manualmente un tag specifico, lanciare build.yml con l’input tag (per esempio v2.0.0). Il token di dispatch è secrets.BACKPORT_TRIGGER_TOKEN e autorizza i cloni del repository sorgente. Verificato rispetto a build.yml (workflow_dispatch.inputs.tag, GH_TOKEN).

Interpretare una build fallita

Lo script di build si arresta alla prima fase che fallisce e stampa il nome della fase e l’errore. Le cinque fasi sono merge, Rector, generazione di composer.json, copia degli asset e validazione. Se lo step di controllo sintattico che segue la build fallisce, Rector ha prodotto output che il runtime di destinazione rifiuta. Quello step è il gate che protegge la release. Associare il fallimento alla relativa causa in /integrations/backport/troubleshooting/.

Che cosa viene pubblicato

La release allega gli archivi di distribuzione in formato zip. Il pacchetto viene distribuito come tag di versione, non come branch. I consumer installano nextpdf/backport (e facoltativamente nextpdf/backport-pro) dal canale di release. L’archivio esclude vendor/ e .git/. Verificato rispetto a build.yml (zip -r ... -x '*/vendor/*' '*/.git/*').

Versionare l’output

Il composer.json prodotto riporta la versione passata dalla riga di comando (--version, oppure il tag di dispatch con la v iniziale rimossa). Il pacchetto Pro fissa nextpdf/backport al corrispondente vincolo caret major.minor. Verificato rispetto a scripts/adjust-composer.php (majorMinor(), generateProComposer()). Mantenere allineati il tag della release sorgente e la versione del backport affinché la mappa replace resti coerente.

Prossimi passi

• /integrations/backport/security-and-operations/ — il confine di fiducia e la postura della supply chain della pipeline.
• /integrations/backport/troubleshooting/ — riferimento per i fallimenti fase per fase.