networkSetup/docs/code-design/05-release-pipeline.md

# 전체 릴리스 생성 파이프라인

2026-10-19 실행 범위 변경: 1차 실행 경로는 MSIX manifest→MakeAppx→서명/검증→불변 결과이며 EXE/CAB/MSP와 Store 프로필은 후속이다. 미서명 개발 결과와 직접 배포 준비 결과를 구분한다. [현재 설계](12-msix-first-builder.md) 참조.

**공통 조정기 + 형식별 빌드**로 구성한다. 아래 단계 표의 WiX·MSI·Burn·CAB·PE 용량 제한은 EXE 경로다. MSIX는 `manifest/자산 생성 → MakeAppx pack → 실제 identity/내용 검사 → 대상별 서명/검증 → 불변 저장`으로 분기한다. MSIX 결과에는 manifest·SDK 정보·패키지·서명/검증 보고서를 보존한다. Store 제출용 결과와 직접 설치 가능한 결과를 구별한다. [범용 출력 계약](11-generic-exe-msix-architecture.md) 참조.

공통 상태는 대상별로 기록한다. 요청한 EXE/MSIX 중 하나라도 실패하면 전체 작업은 `PartialFailed`이며 성공한 결과를 덮어쓰지 않는다. `Finalized`, 직접 배포 준비, `StoreSubmissionReady`, 실제 Store 승인/공개는 다른 판정이다. `DeploymentReady`는 선택한 배포 대상의 설치 증빙을 요구하며 EG-BIM 전환 증빙을 다른 제품에 강제하지 않는다.

## 공통 작업 단계와 상태

```text
Draft → Planned → Running → Built → ArtifactVerified → Finalized
                    └→ Failed / Cancelled / Interrupted
Finalized + 별도 설치 시험 증빙 → DeploymentReady
```

`Finalized`는 아티팩트가 변경 불가능하게 보관됐다는 뜻이다. 설치 시험과 배포 등록까지 성공한 상태는 아니다. `DeploymentReady` 판정은 후속 검증 증빙을 참조하며 기존 릴리스 JSON이나 바이너리를 고치지 않는다. 시험 전 결과는 패치 후보 비교에 사용할 수 있지만 정식 배포 기준으로 승격할 수 없다.

| 단계 | 처리와 실패 조건 |
| --- | --- |
| 사전 검사 | 프로젝트 스키마, 확정 필드, 도구/확장 버전, 서명 접근, 출력 잠금, 디스크 여유 확인 |
| 계획 | 파일 목록과 차이, 설치 기능, GUID, 출력 프로필, 전체 설치·업그레이드 경로 결정 |
| 과정/UI 변환 | 모드별 단계 의존성, 핸들러 계약, UI 백엔드 지원을 검증하고 MSI/Burn/테마 정의로 변환; 미지원 기능은 차단 |
| 스냅샷 | 설정·identity lock·도구 정보 고정, 실제 파일 복사, 크기와 원본 해시 기록 |
| 입력 검증 | 필수 파일, PE 버전/아키텍처, 의존 런타임, 예상한 입력 해시와 복사본 일치 검사 |
| 내부 파일 서명 | 자체 PE 서명과 타임스탬프, 외부 PE 검증, 서명 후 해시 고정 |
| WiX 생성 | 디렉터리·파일·컴포넌트·레지스트리·업그레이드 정의를 결정적 순서로 생성 |
| MSI 생성 | 분할 CAB 포함 출력, 설치 테이블/식별자 검증, 정적 MSI 검증 |
| MSI 서명 | 외부 CAB 서명 및 MSI에 서명 정보 반영이 필요한 순서 처리, 최종 MSI 서명 |
| Burn 생성 | 확정 MSI와 런타임으로 네트워크/오프라인 번들 생성, 엔진·최종 EXE 서명 |
| 산출물 검증 | 도구 결과뿐 아니라 실제 파일의 식별자·서명·크기·의존 관계 검사 |
| 확정 | 모든 최종 해시 계산, 보고서/매니페스트 작성, 동일 볼륨 임시 디렉터리를 불변 경로로 이동 |

입력 원본은 빌드 전에 변경을 멈춘 스테이징 폴더를 사용한다. 복사 중 변경이 감지되면 실패하고 다시 스냅샷을 만든다. 서명 이후 파일 수정이 필요하면 영향받은 단계부터 새 작업으로 실행한다. 진행률은 파일 수·처리 바이트와 단계로 표시하고 외부 도구가 제공하지 않는 정확한 남은 시간을 추정값으로 단정하지 않는다.

디스크 여유는 원본 스테이징, 서명 복사본, 압축 전후 파일, 임시 파일, 기준 버전과 최종 결과를 포함해 계산한다. 정확히 예측할 수 없는 부분은 보수적인 여유량을 적용한다. 수 GB 파일을 메모리에 통째로 적재하지 않고 스트림으로 복사·해시한다.

## EXE 출력 프로필과 대용량 지원

| 프로필 | 산출물과 정책 |
| --- | --- |
| offline-layout | Setup.exe + Product.msi + Data*.cab + prerequisites. 인터넷 없이 설치 가능한 전체 폴더 |
| network | WebSetup.exe + 원격 MSI/CAB/런타임. 모든 payload에 불변 URL·해시·크기 연결 |
| offline-singlefile | 필수 요소를 포함한 단일 오프라인 EXE. 직접 배포에도 사용하며 크기·서명 검증 필수 |

총 설치 용량이 2GB를 넘는 경우 외부 CAB를 분할한다. 기본 압축 전 CAB 예산은 **512MiB 제안값**이며 파일별 크기와 실제 생성 CAB를 검사한다. 이것은 Windows Installer의 고정 제한값이 아니다. WiX MediaTemplate의 미디어 분할 설정과 단일 대형 파일 처리 설정은 서로 다르다. 도구 버전별 지원을 검증하여 매핑한다. [WiX MediaTemplate](https://docs.firegiant.com/wix/schema/wxs/mediatemplate/)

전체 용량 분할이 단일 초대형 파일이나 EXE 형식의 제한까지 해결하지는 않는다. 최초 버전은 개별 파일 2GiB 이상을 보수적으로 차단하고 해당 파일의 별도 패키징 설계를 요구한다. 이 기준은 도구가 지원할 수 있는 최대값에 대한 단정이 아니라 초기 지원 범위다. 큰 파일 분할 기능을 추가할 때는 설치·복구·MSP까지 시험한다.

서명할 PE 파일은 4GB 이상에서 서명 문제가 있으므로 단일 EXE에 모든 내용을 무조건 포함하지 않는다. 4GB 미만도 선택한 Burn 버전·컨테이너·압축 방식에서 성공한다는 보장은 없어 실제 빌드와 서명 검증으로 판정한다. [Microsoft 대형 파일 서명 문제](https://learn.microsoft.com/en-us/windows/msix/package/signing-known-issues)

Store의 MSI/EXE 제출은 독립 실행 가능한 오프라인 설치 패키지를 요구한다. 네트워크 stub이나 별도 CAB URL 목록이 단일 제출 파일을 대신한다고 가정하지 않는다. `format=exe, delivery=offline-singlefile, distribution=store`가 성립하지 않으면 해당 대상의 Store 준비 상태를 실패로 보고한다. MSIX 출력은 별도 필수 백엔드이며 해당 제품의 적합성 없이 자동 전환하지 않는다. [Store 패키지 요건](https://learn.microsoft.com/en-us/windows/apps/publish/publish-your-app/msi/app-package-requirements)

## 서명 정책

Rust/WiX는 서명 인증서를 발급하지 않는다. `Signer` 어댑터가 SignTool과 사전 구성된 인증서 또는 Azure Artifact Signing 프로필을 호출한다. 프로젝트에는 프로필 id만 저장한다. 인증서/서비스 계약은 별도이며 가격과 SmartScreen 설명은 [서명 계획](../plan/06-code-signing-and-smartscreen.md)을 따른다.

자체 EXE/DLL뿐 아니라 IRX 등 확장자가 다른 PE도 헤더로 식별한다. 정책은 `sign-owned`, `verify-vendor`, `not-applicable`로 구분하고 파일 소유권과 허용 서명자를 명시한다. 타사 서명을 지우거나 모든 파일을 자사 서명으로 덮어쓰지 않는다. 서명이 필요한 외부 파일이 미서명인 경우 명시적인 공급자 조치가 없으면 정식 빌드를 차단한다.

내부 PE 서명 → CAB/MSI의 필요한 서명 정보 반영 및 최종 서명 → Burn 엔진 분리·서명·재결합 → 최종 번들 서명 → 최종 해시 순서를 적용한다. 단계별 정확한 명령은 고정된 WiX 버전 어댑터에 캡슐화한다. MSP도 생성 후 서명한다. [WiX 서명 절차](https://docs.firegiant.com/wix/tools/signing/)

인증서 체인·정책·타임스탬프를 검증하고 서명자, 검증 환경, 검증 시각을 기록한다. 일시적인 서명 서비스 오류는 제한적으로 재시도하되 완료된 파일을 재서명하여 해시를 바꾸지 않는다. 토큰·PIN·개인 키·전체 인증 응답은 로그에 남기지 않는다.

## EXE/MSI 전체 설치와 Minor Upgrade

EXE/MSI 대상의 목표 릴리스마다 신규 설치 가능한 전체 MSI를 만든다. 같은 ProductCode를 유지하는 minor upgrade를 기존 설치에 적용하는 것은 단순히 새 MSI를 실행하는 것과 다르므로 별도의 `upgradeRoute`를 제공한다. MVP에서는 해당 기준에 MSP를 적용하는 경로를 우선한다.

MSP가 없는 상태에서 전체 MSI를 대체 업데이트로 사용하려면 해당 버전에 맞는 reinstall/업데이트 동작과 Burn 탐지를 검증한다. 미검증 시 `fallbackArtifactId`만 넣어 실행 가능하다고 표시하지 않고 `FullUpgradeRouteUnavailable`로 차단한다. major upgrade 대상과 minor upgrade 대상의 실행 계획을 분리한다.

## 확정·내보내기

동일 releaseId의 출력 폴더가 있으면 덮어쓰지 않는다. 확정 전 실패한 폴더는 격리하고 명시적인 정리 작업으로 제거한다. EXE 기본 보존 대상은 최종 MSI/CAB/EXE, 서명된 실제 payload, wixpdb, 생성 WXS, 잠금/스냅샷, 로그와 검증 보고서다. 지원 중인 패치가 참조하는 기준은 자동 정리에서 제외한다.

배포 내보내기는 artifacts와 의존 관계, 최종 SHA-256, 설치/업그레이드 경로, 지원 OS·런타임, 패치 기준을 매니페스트로 만든다. offline-layout의 전체 설치 대체 경로는 단일 MSI가 아니라 필요한 CAB·런타임까지 포함한 artifact graph를 가리킨다. 업로드 URL에는 releaseId를 포함한다. payload URL 계획은 Burn 생성 전에 고정하고, 그룹 공개는 별도 배포 시스템에서 수행한다.