CI/CD

pubm은 로컬 터미널과 CI 러너 모두에서 잘 동작하도록 설계되었습니다. 핵심은 일반 pubm 파이프라인이 이미 버전 단계에서 보류 중인 changeset을 소비하는 방법을 안다는 점이므로, CI를 준비하기 위해 별도의 pubm changesets version 단계를 둘 필요가 없다는 것입니다.

pubm init은 설정 중에 CI 워크플로를 자동으로 생성할 수 있습니다. 마법사는 태그 기반 publish를 위한 .github/workflows/release.yml과 PR changeset 강제를 위한 .github/workflows/changeset-check.yml 생성을 제안하므로, 직접 작성할 필요가 없습니다.

권장 릴리스 모델

두 단계로 나누어 사용합니다.

1. 로컬 또는 통제된 릴리스 작업에서 pubm --mode ci --phase prepare를 실행합니다.
2. CI에서는 pubm --mode ci --phase publish로 publish합니다.

pubm --mode ci --phase prepare

pubm --mode ci --phase publish

CI 준비가 하는 일

pubm --mode ci --phase prepare는 단순한 토큰 점검이 아닙니다. 실제 publish 직전까지 릴리스 파이프라인을 실행합니다.

• 레지스트리 토큰과 플러그인 자격 증명을 수집합니다.
• 필요하면 GitHub Secrets로 동기화합니다.
• 사전 조건과 필수 조건 검사를 실행합니다.
• 생략되지 않았다면 테스트와 빌드를 실행합니다.
• 보류 중인 changeset이 있으면 버전 단계에서 소비합니다.
• 릴리스 커밋을 생성하고 태그와 브랜치 변경을 push합니다.
• 실제 publish 대신 publish 작업을 dry-run합니다.

따라서 CI 준비 후에 pubm patch --dry-run을 다시 실행할 필요가 없습니다.

필수 환경 변수

CI에서는 환경 변수를 통해 레지스트리 토큰을 제공합니다.

변수	레지스트리
NODE_AUTH_TOKEN	npm
JSR_TOKEN	jsr
CARGO_REGISTRY_TOKEN	crates.io

플러그인은 자신이 요구하는 자격 증명을 별도로 선언할 수도 있습니다. pubm은 이를 자동으로 수집하고 해석합니다. --ci-prepare 동안에는 누락된 값을 프롬프트하고 GitHub Secrets로 동기화하며, --phase publish 동안에는 환경 변수에서만 해석된 값을 읽고 필수 자격 증명이 하나라도 없으면 오류를 냅니다.

예를 들어 @pubm/plugin-brew는 다음을 요구합니다.

변수	용도
PUBM_BREW_GITHUB_TOKEN	Homebrew용 formula 업데이트를 push하고 pull request를 열 때 사용하는 GitHub PAT입니다.

GitHub Secrets 동기화

이미 CI 준비 실행을 통해 토큰을 로컬에 저장했다면, 다음으로 GitHub Secrets에 반영할 수 있습니다.

pubm secrets sync
pubm secrets sync --registry npm,jsr

GitHub Actions 예시 구조

name: Release

on:
  push:
    tags:
      - "v*"
      - "@*"

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 24

      - run: pnpm install --frozen-lockfile
      - run: pubm --mode ci --phase publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
          JSR_TOKEN: ${{ secrets.JSR_TOKEN }}
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

CI에서 snapshot 릴리스

실제 릴리스를 만들지 않고 CI에서 미리보기 버전을 publish하려면 pubm snapshot을 사용합니다. 전체 릴리스 전에 패키지 변경 사항을 테스트하는 데 유용합니다.

- name: Publish snapshot
  run: npx pubm snapshot
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

모노레포에서는 snapshot할 패키지를 필터링할 수 있습니다.

- name: Publish snapshot
  run: npx pubm snapshot --filter @acme/core --filter @acme/react
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

Snapshot 버전은 기본 버전, 태그, 타임스탬프, 커밋 해시로 구성된 임시 버전 번호로 publish됩니다. 일반 릴리스 버전에는 영향을 주지 않습니다.

자주 겪는 CI 문제

얕은 checkout

태그 기반 및 히스토리 인식 작업에는 전체 Git 정보가 필요합니다. 릴리스 작업에는 fetch-depth: 0을 사용합니다.

누락된 레지스트리 토큰

pubm은 CI에서 프롬프트를 띄울 수 없습니다. 토큰이 없으면 실행은 실패합니다.

npm 2FA 토큰 불일치

CI publish에는 자동화 호환 토큰을 사용합니다.

빌드 결과물이 contents에 없음

dist/에서 publish한다면, 워크플로가 pubm --mode ci --phase publish 이전에 실제로 dist/를 생성하는지 확인합니다.

GitHub Release 자산

프로젝트가 pubm.config.ts에서 releaseAssets를 사용한다면, pubm --mode ci --phase publish는 자산 파이프라인을 실행하고 결과물을 GitHub Release에 자동 업로드합니다.

GITHUB_TOKEN 요구사항

GitHub Release 생성과 자산 업로드는 GitHub API를 사용합니다. GITHUB_TOKEN 또는 contents: write 권한이 있는 fine-grained token을 제공합니다. 이 토큰은 자산 업로드뿐 아니라 모든 GitHub Release 생성에 필요합니다.

- run: pubm --mode ci --phase publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitHub Actions는 모든 workflow run에 GITHUB_TOKEN을 내장된 secret으로 주입합니다. 직접 생성할 필요는 없고, 환경 변수로만 넘기면 됩니다.

업로드 전에 빌드 결과물이 존재해야 함

자산 파이프라인은 빌드 단계 이후에 실행됩니다. 워크플로가 pubm --mode ci --phase publish 실행 전에 바이너리 산출물(예: platforms/*/bin/의 컴파일된 바이너리)을 생성하는지 확인합니다. 설정된 glob 패턴이 업로드 시점에 파일을 하나도 찾지 못하면 pubm은 이를 오류로 처리합니다.

Release asset 예시

name: Release

on:
  push:
    tags:
      - "v*"

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 24

      - run: npm ci
      - run: npm run build       # platforms/*/bin/mytool을 생성해야 합니다.
      - run: pubm --mode ci --phase publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

PR 기반 version bump 워크플로

직접 push하는 대신, pubm이 pull request를 생성하게 할 수도 있습니다. 베이스 브랜치가 보호되어 있거나 publish 전에 리뷰 단계를 원할 때 유용합니다.

config에서 활성화:

export default defineConfig({
  createPr: true,
});

또는 실행 시 플래그로 전달:

pubm --create-pr

createPr가 활성화되면:

• pubm이 version bump 커밋이 담긴 pubm/version-packages-* 브랜치를 생성합니다.
• 브랜치를 push하고 베이스 브랜치로의 PR을 엽니다.
• PR에는 changeset 검사를 건너뛰기 위해 자동으로 no-changeset 레이블이 붙습니다.
• PR이 병합되면 태그 push를 통해 기존 릴리스 워크플로가 정상적으로 트리거됩니다.

보호된 브랜치로의 직접 push가 실패할 경우, pubm은 자동으로 PR 모드로 폴백합니다. 폴백 동작만 원한다면 createPr를 명시적으로 설정할 필요가 없습니다.

Changeset 검사 (PR 유효성 검사)

syi0808/pubm-actions GitHub Action을 사용해 모든 PR에 changeset이 포함되도록 강제할 수 있습니다. changeset이 활성화되어 있으면 pubm init이 이 워크플로를 자동으로 생성합니다.

name: Changeset Check

on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]

permissions:
  contents: read
  pull-requests: write

jobs:
  changeset-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: syi0808/pubm-actions@v1
        with:
          skip-label: no-changeset

이 action은 PR diff에서 새 .pubm/changesets/*.md 파일을 감지하고, 형식을 검증한 뒤 결과를 comment로 남깁니다. changeset이 필요 없는 PR(docs, CI config 등)에는 no-changeset 레이블을 추가하여 검사를 건너뜁니다.

다음 단계

• 실패 원인은 Troubleshooting에서 확인합니다.
• CI에서 사용하는 모든 실행 플래그는 CLI Reference에서 확인합니다.
• 프로젝트의 releaseAssets 설정은 Release Assets에서 확인합니다.