CI/CD

pubm ist so gebaut, dass es in lokalen Terminals und in CI-Runntern gleich gut funktioniert. Der wichtige Punkt ist: Die normale pubm-Pipeline kann ausstehende Changesets bereits während des Versionierungsschritts verbrauchen. Du brauchst also keinen zusätzlichen pubm changesets version-Schritt, nur um CI vorzubereiten.

pubm init kann während des Setups CI-Workflows für dich erzeugen. Der Wizard bietet an, .github/workflows/release.yml (tag-gesteuertes Publish) und .github/workflows/changeset-check.yml (PR-Changeset-Durchsetzung) zu erstellen, damit du sie nicht von Hand schreiben musst.

Recommended release model

Use two phases:

fuehre pubm --mode ci --phase prepare lokal oder in einem kontrollierten Release-Job aus
veröffentliche aus CI mit pubm --mode ci --phase publish

pubm --mode ci --phase prepare

pubm --mode ci --phase publish

What CI preparation does

pubm --mode ci --phase prepare ist nicht nur ein Token-Check. Es laeuft durch die Release-Pipeline bis direkt vor das eigentliche Veröffentlichen:

sammelt Registry-Tokens und Plugin-Credentials ein
synchronisiert sie optional mit GitHub Secrets
fuehrt Prüfungen für Voraussetzungen und Pflichtbedingungen aus
fuehrt Tests und Build aus, sofern sie nicht uebersprungen werden
verbraucht ausstehende Changesets während der Versionierung, wenn vorhanden
erstellt den Release-Commit und pusht Tags sowie Branch-Aktualisierungen
fuehrt Publish-Aufgaben im Dry-Run aus, statt wirklich zu veröffentlichen

Daher musst du nach der CI-Vorbereitung nicht noch pubm patch --dry-run ausführen.

Required environment variables

In CI, provide registry tokens with environment variables:

Variable	Registry
`NODE_AUTH_TOKEN`	npm
`JSR_TOKEN`	jsr
`CARGO_REGISTRY_TOKEN`	crates.io

Plugins koennen auch eigene benoetigte Credentials deklarieren. pubm sammelt und löst diese automatisch auf. Bei --ci-prepare fragt es nach fehlenden Werten und synchronisiert sie mit GitHub Secrets. Bei --phase publish liest es die aufgeloesten Werte nur noch aus der Umgebung und bricht mit einem Fehler ab, wenn ein erforderliches Credential fehlt.

Zum Beispiel benoetigt @pubm/plugin-brew:

Variable	Zweck
`PUBM_BREW_GITHUB_TOKEN`	GitHub PAT zum Pushen von Formula-Updates und zum Öffnen von Pull Requests für Homebrew.

Syncing GitHub secrets

Wenn du Tokens bereits lokal über einen CI-Vorbereitungslauf gespeichert hast, kannst du sie so in GitHub Secrets uebertragen:

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

Example GitHub Actions structure

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 }}

Snapshot-Releases in CI

Verwende pubm snapshot, um Vorschauversionen aus der CI zu veröffentlichen, ohne ein echtes Release zu erstellen. Das ist nützlich, um Paketänderungen vor einem vollständigen Release zu testen.

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

Bei Monorepos kannst du die zu snapshotenden Pakete filtern:

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

Snapshot-Versionen werden mit einer temporären Versionsnummer veröffentlicht, die aus der Basisversion, dem Tag, dem Zeitstempel und dem Commit-Hash abgeleitet wird. Sie beeinflussen die normale Release-Versionsverwaltung nicht.

Common CI pitfalls

Shallow checkout

Tag-basierte und verlaufssensitive Operationen brauchen vollständige Git-Informationen. Verwende für Release-Jobs fetch-depth: 0.

Missing registry tokens

pubm kann in CI nicht nachfragen. Fehlt ein Token, schlaegt der Lauf fehl.

npm 2FA token mismatch

Verwende für CI-Veröffentlichungen Automation-kompatible Tokens.

Build output is not present in `contents`

Wenn du aus dist/ veröffentlichst, stelle sicher, dass dein Workflow dist/ tatsaechlich erzeugt, bevor pubm --mode ci --phase publish laeuft.

GitHub Release assets

Wenn dein Projekt releaseAssets in pubm.config.ts nutzt, fuehrt pubm --mode ci --phase publish die Asset-Pipeline aus und laedt die Artefakte automatisch in den GitHub Release hoch.

`GITHUB_TOKEN` requirement

GitHub-Release-Erstellung und Asset-Upload nutzen die GitHub API. Stelle GITHUB_TOKEN bereit, oder alternativ ein fein granulars Token mit contents: write-Berechtigung. Das Token wird für jede GitHub-Release-Erstellung benötigt, nicht nur für Asset-Uploads:

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

GitHub Actions fuegt GITHUB_TOKEN in jedem Workflow-Lauf als eingebautes Secret ein. Du musst es nicht manuell anlegen, sondern nur über die Umgebung weiterreichen.

Build outputs must exist before upload

Die Asset-Pipeline laeuft nach dem Build-Schritt. Stelle sicher, dass dein Workflow die Binärartefakte, zum Beispiel kompilierte Binaries in platforms/*/bin/, erzeugt, bevor pubm --mode ci --phase publish ausgeführt wird. Wenn ein konfiguriertes Glob-Muster beim Upload keine Datei findet, behandelt pubm das als Fehler.

Example with release assets

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       # Must produce platforms/*/bin/mytool
      - run: pubm --mode ci --phase publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

PR-basierter Version-Bump-Workflow

Als Alternative zum direkten Pushen von Version-Bump-Commits kann pubm stattdessen einen Pull Request erstellen. Das ist nützlich, wenn dein Basis-Branch geschützt ist oder du einen Review-Schritt vor der Veröffentlichung möchtest.

In der Konfiguration aktivieren:

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

Oder als Flag zur Laufzeit übergeben:

pubm --create-pr

Wenn createPr aktiviert ist:

pubm erstellt einen pubm/version-packages-*-Branch mit dem Version-Bump-Commit
der Branch wird gepusht und ein PR gegen den Basis-Branch geöffnet
der PR wird automatisch mit no-changeset markiert, um die Changeset-Prüfung zu überspringen
wenn der PR gemergt wird, löst der bestehende Release-Workflow normal über den Tag-Push aus

pubm fällt auch automatisch in den PR-Modus zurück, wenn ein direkter Push in einen geschützten Branch fehlschlägt. Es ist daher nicht nötig, createPr explizit zu konfigurieren, wenn du nur das Fallback-Verhalten möchtest.

Changeset-Prüfung (PR-Validierung)

Verwende die GitHub Action syi0808/pubm-actions, um sicherzustellen, dass jeder PR ein Changeset enthält. pubm init generiert diesen Workflow automatisch, wenn Changesets aktiviert sind.

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

Die Action erkennt neue .pubm/changesets/*.md-Dateien im PR-Diff, validiert ihr Format und hinterlässt einen Kommentar mit dem Ergebnis. Füge das Label no-changeset hinzu, um die Prüfung für PRs zu überspringen, die kein Changeset benötigen (Docs, CI-Config usw.).

Nächste Schritte

Lies den Leitfaden Troubleshooting für die Fehleranalyse.
Lies die CLI-Referenz für alle in CI genutzten Ausführungsflags.
Lies den Leitfaden Release Assets, um releaseAssets in deinem Projekt zu konfigurieren.