릴리스 파이프라인에서 백포트 빌더 실행하기

빌드 도구입니다 — 런타임 의존성이 아닙니다. 이 페이지에서는 백포트를 생성하는 릴리스 파이프라인을 운영하는 방법을 설명합니다. 이 파이프라인은 CI에서 실행되며, 다운스트림 애플리케이션에서는 절대 실행되지 않습니다.

한눈에 보기

프로덕션 경로에서는 두 개의 워크플로를 사용합니다. 0-ci.yml은 두 영구 브랜치 중 어느 쪽에 들어오는 변경이든 모두 게이트합니다. build.yml은 배포본을 생성해 릴리스하며, 소스 릴리스가 이를 트리거합니다. 두 워크플로 모두 .github/workflows/를 기준으로 검증됩니다.

CI 게이트

0-ci.yml은 PHP74 및 PHP81에 대한 push와 pull request에서 실행됩니다. 여기에는 순서대로 실행되는 세 개의 작업이 있습니다:

PHPStan (Build Tools) — composer analyse를 실행하며, rector/rules 및 scripts를 레벨 10으로 분석합니다.
PHPUnit (Rector Rules) — composer test로 세 개의 커스텀 규칙에 대한 픽스처 스위트를 실행합니다.
Build Dry Run — composer build:dry를 실행하며, 앞의 두 작업을 통과해야 실행됩니다.

신뢰된 이벤트는 셀프 호스티드 PHP 러너에서 실행됩니다. 포크 pull request와 Dependabot은 PHP 8.5가 프로비저닝된 GitHub 호스티드 러너에서 실행됩니다. 0-ci.yml(runs-on 표현식과 조건부 setup-php 단계)을 기준으로 검증됩니다. 이중 브랜치 모델에서는 두 대상을 모두 건드리는 변경도 각 브랜치의 pull request에서 독립적으로 게이트됩니다.

릴리스 파이프라인

build.yml은 프로덕션 빌드를 담당합니다. 이는 source-release 유형의 repository_dispatch 이벤트로 트리거되거나, 태그 입력과 함께 workflow_dispatch를 통해 수동으로 트리거됩니다. 버전 태그가 전체 흐름을 좌우합니다. 버전 번호는 선언된 공개 API에 대한 MAJOR.MINOR.PATCH입니다(시맨틱 버저닝 2.0.0 §2).

PHP 8.1 레인

build-php81 — 빌드 도구를 체크아웃하고, PHP 8.5를 프로비저닝하며, 빌드 의존성을 설치하고, 릴리스 태그에서 소스 리포지토리를 클론합니다. 그런 다음 scripts/build.php를 실행하고, 러너를 PHP 8.1로 전환해 PHP 8.1에서 output/src의 구문을 검사한 후, 생성된 패키지를 --no-dev로 설치합니다. 출력물은 아티팩트로 업로드됩니다.
validate-php81 — 아티팩트를 내려받아 PHP 8.1, 8.2, 8.3, 8.4 매트릭스에서 설치 및 테스트를 수행합니다.
release-php81 — 아티팩트를 내려받아 생성된 트리를 커밋하고 태그를 붙인 뒤, vendor/와 .git/를 제외하고 zip으로 압축한 다음, 아카이브가 첨부된 GitHub 릴리스를 게시합니다.

PHP 7.4 레인

build-php74 — PHP74 브랜치에서 빌드 도구를 체크아웃하고, PHP 8.5를 프로비저닝하며, 태그에서 코어 소스 리포지토리만 클론하고, scripts/build.php --target=php74를 실행합니다. 그런 다음 PHP 7.4로 전환해 PHP 7.4에서 출력물의 구문을 검사합니다.
validate-php74 — PHP 7.4 및 8.0 매트릭스에서 설치 및 테스트를 수행합니다.
release-php74 — 코어 전용 출력물을 zip으로 압축하여 동일한 릴리스에 두 번째 아카이브로 첨부합니다.

build.yml 작업 정의 및 매트릭스를 기준으로 검증됩니다.

두 레인은 하나의 GitHub 릴리스를 공유합니다. PHP 8.1 레인이 릴리스를 생성하고, PHP 7.4 레인이 동일한 태그에 자체 아카이브를 첨부합니다. cancel-in-progress: false인 concurrency 그룹 backport-build는 빌드를 직렬화하여 두 소스 릴리스가 서로 경합하지 않게 합니다.

파이프라인 운영하기

빌드 트리거하기

빌드는 보통 소스 조직이 릴리스를 게시할 때 자동으로 트리거됩니다. 특정 태그를 수동으로 다시 빌드하려면 태그 입력과 함께 build.yml을 디스패치합니다(예: v2.0.0). 디스패치 토큰은 secrets.BACKPORT_TRIGGER_TOKEN이며, 소스 리포지토리를 클론할 권한을 부여합니다. build.yml(workflow_dispatch.inputs.tag, GH_TOKEN)을 기준으로 검증됩니다.

실패한 빌드 읽기

빌드 스크립트는 처음으로 실패한 단계에서 멈추고 단계 이름과 오류를 출력합니다. 다섯 단계는 병합, 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 패키지는 일치하는 major.minor 캐럿 제약 조건을 사용해 nextpdf/backport를 고정합니다. scripts/adjust-composer.php(majorMinor(), generateProComposer())를 기준으로 검증됩니다. 소스 릴리스 태그와 백포트 버전이 서로 맞춰진 상태를 유지하도록 해 replace 맵의 일관성을 보장하십시오.

/integrations/backport/security-and-operations/ — 파이프라인의 신뢰 경계와 공급망 태세를 다룹니다.
/integrations/backport/troubleshooting/ — 단계별 실패 레퍼런스입니다.