designpaca/docs/DEPLOYMENT_PLAN.md

designpaca 배포 운영 계획

이 문서는 designpaca를 git.chanpaca.net(Forgejo)에서 빌드·배포·릴리스하기 위한 전제와 절차를 적는다. 한 번 읽고 그대로 따라 하면 첫 릴리스까지 갈 수 있어야 한다.

0. 전제 — 러너 환경

CI는 self-hosted linux-builder 러너(host 모드)에서 돈다. host 모드라 러너 머신에 있는 것만 쓸 수 있다.

필요	확인	없을 때
Node 20 이상	node -v	fnm install 22 && fnm default 22 후 러너 재시작
pnpm 10	pnpm -v	corepack enable && corepack prepare pnpm@10.5.2 --activate
git, curl, tar, python3	command -v	배포판 패키지로 설치

build/ci/verify-node.sh가 매 잡 첫 스텝에서 이걸 검사하고, 없으면 명확한 메시지로 즉시 실패시킨다. nvm/fnm/volta의 흔한 설치 경로는 자동으로 PATH에 올려본다.

host 러너에는 Node가 없을 수 있으므로 워크플로에서 uses: 액션을 쓰지 않는다. 체크아웃도 run: 스텝의 git 명령으로 처리한다 (videodownloader 파이프라인과 동일한 패턴).

1. 저장소

git.chanpaca.net/<owner>/designpaca

• 소스 공개 여부는 자유. 단 npm 배포는 npmjs 공개 레지스트리이므로 코드는 어차피 tarball로 공개된다
• 기본 브랜치: main
• 태그 규칙: v<semver> (예: v0.1.0) — 태그 푸시가 릴리스 트리거

2. 시크릿 등록

저장소 → Settings → Actions → Secrets 에 등록한다.

이름	용도	발급처
NPM_TOKEN	npmjs 배포	npmjs.com → Access Tokens → Automation 타입
FORGEJO_NPM_TOKEN	사설 레지스트리 미러	Forgejo → 설정 → 애플리케이션 → 액세스 토큰 (write:package 권한)
RELEASE_TOKEN	릴리스 생성·자산 업로드	Forgejo 액세스 토큰 (write:repository)
CF_API_TOKEN	Cloudflare Pages 배포	Cloudflare → API Tokens → Edit Cloudflare Workers 템플릿
CF_ACCOUNT_ID	Cloudflare 계정 식별	Cloudflare 대시보드 우측 하단 Account ID

변수(Variables)에 선택적으로:

이름	기본값	설명
FORGEJO_NPM_OWNER	yunchan	사설 npm 패키지 소유자

시크릿이 없어도 파이프라인은 죽지 않는다. publish-npm.sh는 FORGEJO_NPM_TOKEN이 없으면 미러를 건너뛰고, 릴리스 스텝은 CF_API_TOKEN이 없으면 페이지 배포를 건너뛴다. 하나씩 붙여가며 굴릴 수 있다.

3. 릴리스 절차

3.1 변경 기록

pnpm changeset            # 무엇이 바뀌었는지, patch/minor/major 중 무엇인지 기록
git add .changeset && git commit -m "changeset: <요약>"

3.2 버전 확정

pnpm version              # changeset version + lockfile 갱신
# packages/*/package.json 과 CHANGELOG.md 가 갱신된다
git add -A && git commit -m "release: v<새 버전>"

designpaca · @designpaca/core · @designpaca/skill은 changesets의 fixed 그룹이라 항상 같은 버전으로 움직인다. 스킬 내용과 CLI 버전이 어긋나면 업그레이드 판정(.designpaca_version 비교)이 깨지기 때문이다.

3.3 태그 푸시 = 릴리스 발동

git tag v0.1.0 && git push origin main --tags

파이프라인이 순서대로 수행한다:

1. verify-node.sh → 의존성 설치
2. 태그와 packages/cli/package.json 버전 일치 확인 (다르면 즉시 실패)
3. 스킬 문서 검사 → 타입 검사 → 테스트 → 빌드 → 배포물 점검
4. npm publish (npmjs) → Forgejo 레지스트리 미러. 이미 배포된 버전이면 조용히 건너뛴다(재실행 안전)
5. Forgejo draft 릴리스 생성 + tarball 첨부
6. Cloudflare Pages 배포

3.4 승격

draft 릴리스를 확인하고 수동으로 Publish한다. draft는 익명에게 보이지 않으므로 QA 시간을 벌 수 있다.

3.5 리허설

태그 없이 돌려볼 수 있다. Actions → release → Run workflow. ci-rehearsal prerelease 릴리스로 전 과정을 검증하되 npm 배포는 건너뛴다(DO_PUBLISH=0).

4. 사용자 설치 경로

npx designpaca                 # 온보딩 TUI
npx designpaca install -t claude-code,codex -s user -y

사설 레지스트리에서 직접 받으려면:

npx --registry=https://git.chanpaca.net/api/packages/<owner>/npm/ designpaca

5. 소개 페이지

• 배포 대상: Cloudflare Pages 프로젝트 designpaca
• 도메인: designpaca.chanpaca.net (Cloudflare DNS에 CNAME → Pages)
• 최초 1회만 수동: Cloudflare 대시보드에서 Pages 프로젝트 생성(빈 프로젝트) → 커스텀 도메인 연결. 이후에는 릴리스 워크플로의 wrangler pages deploy가 알아서 올린다

6. 장애 대응

증상	원인	조치
Node 를 찾을 수 없다	host 러너에 Node 미설치	러너 머신에 fnm으로 Node 22 설치 후 러너 재시작
태그와 package.json 이 다르다	pnpm version 없이 태그를 밀었다	태그 삭제 → 3.2부터 다시
npm publish 403	토큰 만료 / 이름 선점	NPM_TOKEN 재발급, npm view designpaca 로 소유 확인
Forgejo 미러 401	토큰에 write:package 없음	토큰 권한 재발급
릴리스 자산 업로드 실패	RELEASE_TOKEN 권한 부족	write:repository 부여
Pages 배포 스킵	CF_API_TOKEN 미등록	시크릿 등록 (없어도 나머지는 성공한다)

7. 롤백

npm은 배포 취소가 사실상 불가능하다(72시간 이내 unpublish만 가능, 같은 버전 재사용 금지). 따라서 되돌리기가 아니라 앞으로 감는다:

# 문제 버전을 latest 에서 내린다
npm dist-tag add designpaca@<직전 정상 버전> latest
# 수정 후 새 패치 릴리스

사용자 쪽 복구는 npx designpaca@<정상버전> update --force.