リリースパイプラインでバックポートビルダーを実行する

ビルドツール群であり、ランタイム依存関係ではありません。このページでは、バックポートを生成するリリースパイプラインの運用方法を説明します。このパイプラインは CI 上で実行され、ダウンストリームアプリケーション内では決して実行されません。

概要

本番経路では 2 つのワークフローを使用します。0-ci.yml は、いずれかの恒久ブランチへのすべての変更をゲートします。build.yml はディストリビューションを生成してリリースし、ソースリリースがこれをトリガーします。どちらも .github/workflows/ を基に検証済みです。

CI ゲート

0-ci.yml は、PHP74 および PHP81 へのプッシュとプルリクエストで実行されます。順番に実行される 3 つのジョブがあります。

1. PHPStan (Build Tools) — composer analyse。rector/rules と scripts を対象とするレベル 10 の解析。
2. PHPUnit (Rector Rules) — composer test。3 つのカスタムルールのフィクスチャスイート。
3. Build Dry Run — composer build:dry。最初の 2 つのジョブの後段でゲートされます。

信頼されたイベントは、セルフホストの PHP ランナーで実行されます。フォークからのプルリクエストと Dependabot は、PHP 8.5 がプロビジョニングされた GitHub ホステッドランナーで実行されます。0-ci.yml（runs-on 式と条件付きの setup-php ステップ）を基に検証済みです。デュアルブランチモデルでは、両方のターゲットに影響する変更を、各ブランチのプルリクエストで個別にゲートします。

リリースパイプライン

build.yml は本番ビルドです。これは source-release タイプの repository_dispatch イベントによって、またはタグ入力付きの workflow_dispatch を介して手動でトリガーされます。バージョンタグがすべてを駆動します。バージョン番号は、宣言された公開 API に対する MAJOR.MINOR.PATCH です（Semantic Versioning 2.0.0 §2）。

PHP 8.1 レーン

1. build-php81 — ビルドツールをチェックアウトし、PHP 8.5 をプロビジョニングし、ビルド依存関係をインストールし、リリースタグでソースリポジトリをクローンし、scripts/build.php を実行し、ランナーを PHP 8.1 に切り替え、PHP 8.1 上で output/src の構文チェックを行い、その後 --no-dev で生成されたパッケージをインストールします。出力はアーティファクトとしてアップロードされます。
2. validate-php81 — アーティファクトをダウンロードし、PHP 8.1、8.2、8.3、8.4 のマトリクスでインストールとテストを行います。
3. release-php81 — アーティファクトをダウンロードし、生成されたツリーをコミットしてタグ付けし、vendor/ と .git/ を除外して ZIP 化し、アーカイブを添付した GitHub リリースを公開します。

PHP 7.4 レーン

1. build-php74 — PHP74 ブランチでビルドツールをチェックアウトし、PHP 8.5 をプロビジョニングし、タグを指定してコアソースリポジトリのみをクローンし、scripts/build.php --target=php74 を実行し、PHP 7.4 に切り替え、PHP 7.4 上で出力の構文チェックを行います。
2. validate-php74 — PHP 7.4 と 8.0 のマトリクスでインストールとテストを行います。
3. release-php74 — コアのみの出力を ZIP 化し、2 つ目のアーカイブとして同じリリースに添付します。

build.yml のジョブ定義とマトリクスを基に検証済みです。

2 つのレーンは 1 つの GitHub リリースを共有します。PHP 8.1 レーンがこれを作成し、PHP 7.4 レーンが同じタグに自身のアーカイブを添付します。cancel-in-progress: false を伴う concurrency グループ backport-build はビルドを直列化するため、2 つのソースリリースが競合することはありません。

パイプラインの運用

ビルドのトリガー

通常、ソース組織がリリースを公開すると、ビルドは自動的にトリガーされます。特定のタグを手動で再ビルドするには、タグ入力付きの build.yml をディスパッチします（例: v2.0.0）。ディスパッチトークンは secrets.BACKPORT_TRIGGER_TOKEN であり、ソースリポジトリのクローンを認可します。build.yml（workflow_dispatch.inputs.tag、GH_TOKEN）を基に検証済みです。

失敗したビルドの読み解き

ビルドスクリプトは最初に失敗したステージで停止し、ステージ名とエラーを出力します。5 つのステージは、マージ、Rector、composer.json の生成、アセットのコピー、検証です。ビルド後の構文チェックステップが失敗した場合、Rector はターゲットランタイムが拒否する出力を生成したことになります。そのステップが、リリースを保護するゲートです。失敗を原因に対応付けるには、/integrations/backport/troubleshooting/. を参照してください。

公開される内容

リリースには、ZIP 化されたディストリビューションアーカイブが添付されます。パッケージはブランチではなく、バージョンタグとして提供されます。利用者は、リリースチャネルから nextpdf/backport（および任意で nextpdf/backport-pro）をインストールします。アーカイブは vendor/ と .git/ を除外します。build.yml（zip -r ... -x '*/vendor/*' '*/.git/*'）を基に検証済みです。

出力のバージョニング

生成された composer.json には、コマンドラインで渡されたバージョン（--version、または先頭の v を取り除いたディスパッチタグ）が記録されます。Pro パッケージは、nextpdf/backport を、対応する major.minor のキャレット制約で固定します。scripts/adjust-composer.php（majorMinor()、generateProComposer()）を基に検証済みです。replace マップが一貫した状態を保つよう、ソースリリースタグとバックポートバージョンを揃えておいてください。

次のステップ

• /integrations/backport/security-and-operations/ — パイプラインの信頼境界とサプライチェーンの体制。
• /integrations/backport/troubleshooting/ — ステージごとの失敗リファレンス。