Yun Chan c8fb3abbaf docs(release): Linux(deb/AppImage) 별도 Phase 백로그 명시

- release-guide 알려진 제약 표에 Linux 행 추가 (사이드카/TTS 백엔드 장벽 + Phase 범위)
- project_status v0.2.0 후속에 Linux 별도 Phase 합의 기록 (7대 장벽)

2026-07-22 03:50:34 +09:00

6.6 KiB

Raw Blame History

D3RO Voice 릴리스 가이드

agent-switchboard-client의 릴리스 체계를 이식한 멀티플랫폼 배포 파이프라인.

파이프라인 개요

git tag vX.Y.Z → push
  ├─ package-windows  (runner: build-win-x64, TW-VIVEN-BUILD)      → NSIS exe + latest.yml
  ├─ package-macos    (runner: build-mac-arm64, TW-BUILD-MAC-ARM64) → dmg + zip + latest-mac.yml   [D3RO_MAC_RUNNER="true"일 때만]
  └─ release-create   (runner: build-linux-x64 Docker, TW-BUILD01)
       ├─ Generic Package Registry 업로드
       │    ├─ d3ro-voice/<version>/  (버전별 보관)
       │    └─ d3ro-voice/latest/     (electron-updater feed — 매 릴리스 갱신)
       └─ GitLab Release 생성 + asset 링크

버전은 태그에서 자동 동기화된다 (scripts/ci/sync-version.mjs — v0.2.0 → package.json 0.2.0).
macOS artifacts가 없으면 Windows 단독으로 릴리스가 생성된다 (경고 로그만).

릴리스 절차

git tag v0.2.0
git push origin v0.2.0

끝. 파이프라인이 패키징 → 레지스트리 업로드 → Release 생성까지 자동 수행한다.

사용자가 1회 설정해야 하는 것

1. macOS runner (2026-07-21 기준 완료됨)

사내 공용 runner TW-BUILD-MAC-ARM64(tags: build-mac-arm64)가 온라인이며, CI 변수 D3RO_MAC_RUNNER="true"도 설정 완료. 별도 등록 불필요.

Mac runner 환경 전제조건 (미충족 시 package-macos 잡 실패 — allow_failure라 릴리스는 진행):

Xcode Command Line Tools, Node 22+(또는 volta), Python 3.11+
brew install sox — install-sox.sh가 이 바이너리를 번들함

2. 자동 업데이트 활성화 (Windows) — 2026-07-21 기준 완료됨

프로젝트 ID = 1172 (기입 완료)
두 곳에 같은 feed URL 기입 (어긋나면 안 됨):
- apps/desktop/src/main/update-feed.ts의 UPDATE_FEED_URL ✅
- apps/desktop/electron-builder.yml의 publish.url ✅
```
https://gitlab.twentyoz.kr:8443/api/v4/projects/1172/packages/generic/d3ro-voice/latest
```
publish 섹션은 latest.yml/latest-mac.yml 생성을 트리거하는 필수 설정이다 (없으면 electron-builder가 update info 파일을 아예 만들지 않음).
package_registry_access_level=public 설정 완료 ✅ (2026-07-21, API로 적용) — 앱의 무인증 다운로드/랜딩 페이지 다운로드 링크의 전제. 비공개로 되돌리면 자동 업데이트가 401로 조용히 중단됨.
v0.1.1-alpha부터 배포된 앱이 4시간 주기로 업데이트를 체크한다

산출물 파일명 규칙

파일명에 공백 금지 — GitLab Generic Package Registry가 공백을 불허해 latest.yml의 url과 레지스트리 파일명이 어긋나면 업데이트 다운로드가 404 난다.

Windows: D3RO-Voice-Setup-<version>-x64.exe
macOS: D3RO-Voice-<version>-arm64.dmg / .zip

알려진 제약 / 후속 단계

항목	현재 상태	후속
macOS 서명/공증	❌ ad-hoc 서명 (`identity=-`, switchboard 검증 조합) — Gatekeeper가 차단하면 우클릭→열기 또는 `xattr -dr com.apple.quarantine "/Applications/D3RO Voice.app"`	Apple Developer 계정($99/년) 확보 시 switchboard의 prepare/cleanup-macos-keychain.mjs + 공증 패턴 이식. 주의: D3RO는 asarUnpack native 모듈 + ollama/sox 바이너리 다중 서명 필요
macOS 자동 업데이트	❌ 미지원 (Squirrel.Mac이 서명 요구)	서명 도입 후 latest-mac.yml feed 연결
업데이트 무결성 서명	latest.yml SHA-512 (electron-builder 기본)	switchboard의 Ed25519 update-policy 매니페스트 체계 이식 검토
CHANGELOG	✅ v0.2.0-alpha부터 운영	`publish-gitlab-release.mjs`가 `## [버전]` 섹션을 Release 노트로 자동 추출. CHANGELOG를 풍부하게 = Release 페이지 품질 직결

Release 페이지 운영 (v0.2.0-alpha부터)

GitLab Release 페이지는 CHANGELOG가 단일 진실 원천이다. 릴리스 품질을 올기려면 CHANGELOG를 잘 쓴다.

Release 노트 = CHANGELOG 섹션 (자동)

publish-gitlab-release.mjs의 extractChangelogSection(changelog, version)가 태그 버전(0.2.0-alpha)과 매칭되는 ## [0.2.0-alpha] 섹션을 Release 노트로 추출. CHANGELOG를 고치면 Release 노트에 자동 반영 — 릴리스 후수정해도 다음 릴리스에 반영되지 않으니 릴리스 "전"에 CHANGELOG를 확정.

권장 섹션 구조 (Keep a Changelog)

## [버전] - YYYY-MM-DD
> 다운로드 안내 (Windows exe / macOS dmg 파일명 + 자동업데이트/서명 메모)
### Added / Changed / Fixed / Removed / Internal

상단 인용 블록(>)에 다운로드 파일명·자동업데이트·macOS 서명 안내를 적으면 사용자가 Release 페이지에서 바로 확인.
내부 작업(refactor-wave 등)은 ### Internal로 분리 — 사용자 관심사(Added/Fixed)가 위에 오도록.

릴리스 체크리스트

CHANGELOG [버전] 섹션 작성 (위 구조)
memory/project_status.md 최신화 (규칙 13)
git tag vX.Y.Z && git push origin vX.Y.Z
GitLab 파이프라인 모니터링 (package-windows / package-macos / release-create)
Release 페이지에서 노트·asset 링크·latest.yml 확인
(검증) 기존 앱에서 자동 업데이트 수신 확인

버전 정책

0.x.y-alpha: 개발 프리릴리스 (현재 단계). 자동업데이트 feed는 alpha 체널.
minor 범프: 대규모 재설계/정리(Midnight Glass v2, refactor-wave). patch: 버그 수정 중심.
alpha→정식 전환은 기능·안정성 기준 충족 시 (별도 합의). | mac x64 (Intel) | 빌드 안 함 (사이드카가 arm64 전용) | 수요 발생 시 Intel Mac runner 추가 | | Linux (deb/AppImage) | ❌ 미지원 — 사이드카 Linux 빌드·TTS 백엔드 부재 | 별도 Phase(2026-07-22 합의). 사이드카 Linux PyInstaller(ctranslate2) + TTS 백엔드 신규(espeak-ng/Piper — 현재 Windows SAPI 전용) + electron-builder linux(deb+AppImage, afterInstall로 sox/의존 안내) + CI package-linux 잡(TW-BUILD01 Docker 툴체인 확장) + QA(Ubuntu/Debian/Fedora). switchboard 원본도 Windows-only라 참조 패턴 없음 |

참고 파일

.gitlab-ci.yml — 파이프라인 정의
scripts/ci/sync-version.mjs — 태그 → package.json 버전 동기화
scripts/ci/publish-gitlab-release.mjs — 레지스트리 업로드 + Release 생성
apps/desktop/src/main/services/UpdateService.ts — 자동 업데이트 (electron-updater)
apps/desktop/src/main/update-feed.ts — feed URL SSOT
원본 패턴: D:\workspace\agent-switchboard-client (.gitlab-ci.yml, scripts/publish-gitlab-release.mjs)

6.6 KiB Raw Blame History