Chạy trình tạo bản backport trong pipeline phát hành

Đây là công cụ build, không phải dependency runtime. Trang này giải thích cách vận hành pipeline phát hành để tạo bản backport. Pipeline chạy trong tích hợp liên tục (CI); nó không bao giờ chạy trong ứng dụng backend.

Tổng quan nhanh

Lộ trình production dùng hai workflow. 0-ci.yml kiểm soát mọi thay đổi trên từng nhánh cố định. Một bản phát hành nguồn sẽ kích hoạt build.yml; workflow này build và phát hành bản phân phối. Cả hai workflow đều được kiểm chứng bằng cách đối chiếu với .github/workflows/.

Cổng kiểm soát CI

0-ci.yml chạy trên các sự kiện push và pull request cho PHP74 và PHP81. Workflow này chạy ba job theo thứ tự:

1. PHPStan (Build Tools) — composer analyse, level 10 cho rector/rules và scripts.
2. PHPUnit (Rector Rules) — composer test, các bộ fixture cho ba quy tắc tùy chỉnh.
3. Build Dry Run — composer build:dry, chỉ chạy sau khi hai job đầu tiên đã vượt qua.

Các sự kiện đáng tin cậy dùng runner PHP tự lưu trữ. Pull request từ fork và Dependabot dùng runner do GitHub lưu trữ với PHP 8.5 đã được cấp. Điều này được kiểm chứng bằng cách đối chiếu với 0-ci.yml (biểu thức runs-on và bước setup-php có điều kiện). Mô hình hai nhánh kiểm soát độc lập các thay đổi chạm tới cả hai target trên pull request của từng nhánh.

Pipeline phát hành

build.yml là bản dựng production. Workflow này chạy khi có sự kiện repository_dispatch loại source-release, hoặc chạy thủ công qua workflow_dispatch với một đầu vào tag. Tag phiên bản điều khiển pipeline. Số phiên bản là MAJOR.MINOR.PATCH trên một public API đã khai báo (Semantic Versioning 2.0.0 §2).

Làn PHP 8.1

1. build-php81 — checkout các công cụ build, cấp PHP 8.5, cài đặt các dependency build, clone các repository nguồn tại tag phát hành, chạy scripts/build.php, chuyển runner sang PHP 8.1, kiểm tra cú pháp output/src trên PHP 8.1, rồi cài đặt gói đã tạo với --no-dev. Job này tải kết quả lên dưới dạng artifact.
2. validate-php81 — tải xuống artifact, sau đó cài đặt và kiểm thử artifact đó trên ma trận gồm PHP 8.1, 8.2, 8.3, và 8.4.
3. release-php81 — tải xuống artifact, commit và gắn thẻ cây thư mục đã tạo, tạo một file lưu trữ zip loại trừ vendor/ và .git/, rồi phát hành một GitHub release có đính kèm file lưu trữ.

Làn PHP 7.4

1. build-php74 — checkout các công cụ build trên nhánh PHP74, cấp PHP 8.5, chỉ clone repository nguồn core tại tag, chạy scripts/build.php --target=php74, chuyển sang PHP 7.4, và kiểm tra cú pháp kết quả trên PHP 7.4.
2. validate-php74 — cài đặt và kiểm thử trên ma trận gồm PHP 7.4 và 8.0.
3. release-php74 — tạo một file lưu trữ zip từ kết quả chỉ-core và đính kèm vào cùng bản phát hành như file lưu trữ thứ hai.

Luồng này được kiểm chứng bằng cách đối chiếu với các định nghĩa job và ma trận trong build.yml.

Hai làn dùng chung một GitHub release. Làn PHP 8.1 tạo bản phát hành, còn làn PHP 7.4 đính kèm file lưu trữ của nó vào cùng tag đó. Nhóm concurrency backport-build với cancel-in-progress: false chạy tuần tự từng bản dựng, nên hai bản phát hành nguồn không thể xung đột với nhau.

Vận hành pipeline

Kích hoạt một bản dựng

Một bản dựng thường tự động khởi chạy khi tổ chức nguồn phát hành một release. Để build lại một tag cụ thể theo cách thủ công, hãy dispatch build.yml với đầu vào tag, chẳng hạn v2.0.0. Token dispatch là secrets.BACKPORT_TRIGGER_TOKEN, và token này cấp quyền clone repository nguồn. Điều này được kiểm chứng bằng cách đối chiếu với build.yml (workflow_dispatch.inputs.tag, GH_TOKEN).

Đọc một bản dựng thất bại

Script build dừng ở giai đoạn thất bại đầu tiên và in ra tên giai đoạn cùng lỗi. Năm giai đoạn là merge, Rector, tạo composer.json, sao chép asset, và kiểm tra. Nếu bước kiểm tra cú pháp sau khi build thất bại, nghĩa là Rector đã tạo ra kết quả mà runtime đích từ chối. Bước này bảo vệ bản phát hành. Hãy đối chiếu lỗi với nguyên nhân tương ứng tại /integrations/backport/troubleshooting/.

Những gì được phát hành

Bản phát hành bao gồm các file lưu trữ phân phối đã nén zip. Gói được phát hành dưới dạng các tag phiên bản, không phải nhánh. Người dùng cài đặt nextpdf/backport (và tùy chọn thêm nextpdf/backport-pro) từ kênh phát hành. File lưu trữ loại trừ vendor/ và .git/. Điều này được kiểm chứng bằng cách đối chiếu với build.yml (zip -r ... -x '*/vendor/*' '*/.git/*').

Gán phiên bản cho kết quả

Tệp composer.json được tạo sẽ mang phiên bản truyền vào trên dòng lệnh (--version, hoặc tag dispatch sau khi đã bỏ ký tự v ở đầu). Gói Pro ghim nextpdf/backport bằng ràng buộc caret major.minor tương ứng. Điều này được kiểm chứng bằng cách đối chiếu với scripts/adjust-composer.php (majorMinor(), generateProComposer()). Hãy giữ cho tag phát hành nguồn và phiên bản backport khớp nhau để bản đồ replace luôn nhất quán.

Tiếp theo

• /integrations/backport/security-and-operations/ — ranh giới tin cậy của pipeline và thế trận chuỗi cung ứng.
• /integrations/backport/troubleshooting/ — tài liệu tham khảo về lỗi cho từng giai đoạn.