Executando o construtor de backport em um pipeline de release

Ferramentas de build, não uma dependência de runtime. Esta página explica como operar o pipeline de release que produz o backport. O pipeline roda na integração contínua (CI); ele nunca é executado em uma aplicação downstream.

Visão geral

O caminho de produção usa dois workflows. 0-ci.yml aplica o gate a cada mudança em cada branch permanente. Uma source release dispara build.yml, que faz o build e o release da distribuição. Ambos os workflows são verificados em relação a .github/workflows/.

O gate de CI

0-ci.yml roda em eventos de push e pull request para PHP74 e PHP81. Ele executa três jobs em ordem:

1. PHPStan (Build Tools) — composer analyse, level 10 para rector/rules e scripts.
2. PHPUnit (Rector Rules) — composer test, as suítes de fixtures para as três regras customizadas.
3. Build Dry Run — composer build:dry, com gate atrás dos dois primeiros jobs.

Eventos confiáveis usam runners de PHP self-hosted. Pull requests de forks e o Dependabot usam runners hospedados no GitHub com PHP 8.5 provisionado. Isso é verificado em relação a 0-ci.yml (a expressão runs-on e o step condicional setup-php). O modelo de dois branches aplica o gate, de forma independente, a mudanças que afetam ambos os targets no pull request de cada branch.

O pipeline de release

build.yml é o build de produção. Ele roda em um evento repository_dispatch do tipo source-release, ou manualmente por meio de workflow_dispatch com uma tag como input. A tag de versão conduz o pipeline. Um número de versão segue MAJOR.MINOR.PATCH para uma API pública declarada (Semantic Versioning 2.0.0 §2).

Lane do PHP 8.1

1. build-php81 — faz o checkout das ferramentas de build, provisiona o PHP 8.5, instala as dependências de build, clona os repositórios de source na tag de release, executa scripts/build.php, troca o runner para PHP 8.1, faz a verificação de sintaxe de output/src no PHP 8.1 e, então, instala o pacote produzido com --no-dev. Ele faz o upload do output como um artifact.
2. validate-php81 — faz o download do artifact e, então, o instala e testa em uma matriz de PHP 8.1, 8.2, 8.3 e 8.4.
3. release-php81 — faz o download do artifact, faz o commit e cria a tag da árvore gerada, cria um arquivo zip que exclui vendor/ e .git/ e publica um GitHub release com o arquivo anexado.

Lane do PHP 7.4

1. build-php74 — faz o checkout das ferramentas de build no branch PHP74, provisiona o PHP 8.5, clona apenas o repositório de source do core na tag, executa scripts/build.php --target=php74, troca para PHP 7.4 e faz a verificação de sintaxe do output no PHP 7.4.
2. validate-php74 — instala e testa em uma matriz de PHP 7.4 e 8.0.
3. release-php74 — cria um arquivo zip a partir do output somente do core e o anexa ao mesmo release como um segundo arquivo.

Esse fluxo é verificado em relação às definições de job e às matrizes de build.yml.

As duas lanes compartilham um único GitHub release. A lane do PHP 8.1 cria o release, e a lane do PHP 7.4 anexa seu arquivo à mesma tag. O grupo de concurrency backport-build com cancel-in-progress: false executa os builds um de cada vez, de modo que dois source releases não podem competir entre si.

Operando o pipeline

Disparando um build

Normalmente, um build inicia automaticamente quando a organização de source publica um release. Para refazer manualmente o build de uma tag específica, faça o dispatch de build.yml com a tag como input, como v2.0.0. O token de dispatch é secrets.BACKPORT_TRIGGER_TOKEN, e ele autoriza clones do repositório de source. Isso é verificado em relação a build.yml (workflow_dispatch.inputs.tag, GH_TOKEN).

Lendo um build que falhou

O script de build para no primeiro estágio que falha e imprime o nome do estágio e o erro. Os cinco estágios são merge, Rector, geração de composer.json, cópia de assets e validação. Se o step de verificação de sintaxe após o build falhar, o Rector produziu um output que o runtime de destino rejeita. Esse step protege o release. Mapeie a falha para a respectiva causa em /integrations/backport/troubleshooting/.

O que é publicado

O release inclui arquivos de distribuição compactados em zip. O pacote é distribuído como tags de versão, não como branches. Os consumidores instalam nextpdf/backport (e, opcionalmente, nextpdf/backport-pro) a partir do canal de release. O arquivo exclui vendor/ e .git/. Isso é verificado em relação a build.yml (zip -r ... -x '*/vendor/*' '*/.git/*').

Versionando o output

O composer.json produzido carrega a versão passada na linha de comando (--version, ou a tag de dispatch sem o v inicial). O pacote Pro fixa nextpdf/backport na restrição de caret major.minor correspondente. Isso é verificado em relação a scripts/adjust-composer.php (majorMinor(), generateProComposer()). Mantenha a tag do source release e a versão do backport alinhadas para que o mapa replace permaneça consistente.

A seguir

• /integrations/backport/security-and-operations/ — o limite de confiança do pipeline e a postura de supply-chain.
• /integrations/backport/troubleshooting/ — a referência de falhas para cada estágio.