CI/CD Integration
Relevant source files
The following files were used as context for generating this wiki page:
The CI/CD Integration in pubm provides a robust mechanism for automating the release process of packages across multiple ecosystems, including JavaScript/TypeScript (npm, JSR) and Rust (crates.io). It is designed to work seamlessly in both local and CI environments, ensuring that releases are validated, published, and documented automatically upon specific triggers.
The integration centers around a two-phase workflow—prepare and publish—which separates the collection of credentials from the actual execution of the release. This architecture allows for secure token management and consistent behavior across different CI providers, primarily targeting GitHub Actions as the default platform.
Sources: plugins/pubm-plugin/skills/publish-setup/references/ci-templates.md:3-9, packages/pubm/src/commands/init.ts:107-112
Core CI Workflow Architecture
pubm implements a specialized CI mode (--mode ci) that distinguishes between local preparation and remote execution. This ensures that sensitive operations, like registry pings and login validations, are handled appropriately for headless environments.
The Two-Phase Pipeline
| Phase | Command | Responsibility |
|---|---|---|
| Prepare | pubm --mode ci --phase prepare | Collects registry tokens, validates access, and prepares the environment for a subsequent push. |
| Publish | pubm --mode ci --phase publish | Executes the actual concurrent publication to registries and creates a GitHub Release. |
Sources: plugins/pubm-plugin/skills/publish-setup/references/ci-templates.md:5-10
Execution Logic in CI
When running in publish phase within a CI environment, pubm modifies its standard behavior to ensure stability:
- Skips Local Checks: Prerequisites like branch verification, remote history checks, and working tree cleanliness are bypassed as they are assumed to be handled by the CI runner.
- Skips Development Tasks: Tests, builds, and version bumps are skipped during the
publishphase because they should have occurred prior to the CI trigger. - Concurrent Publishing: It reads manifest versions (e.g.,
package.json,Cargo.toml) and publishes to all configured registries simultaneously, skipping versions already present.
Sources: plugins/pubm-plugin/skills/publish-setup/references/ci-templates.md:12-20
Automation Flow Diagram
The following diagram illustrates the interaction between a developer's local environment and the CI pipeline.
Trigger Strategies
pubm supports multiple trigger strategies depending on the project structure (single-package vs. monorepo).
Tag-Based Triggers
Commonly used for single-package repositories. The workflow is triggered when a tag matching v* is pushed to the repository.
- Trigger:
push: tags: ['v*'] - Logic: The
publishphase reads the version directly from the git tag.
Sources: packages/pubm/src/commands/init-workflows.ts:185-195, plugins/pubm-plugin/skills/publish-setup/references/ci-templates.md:130-135
Commit-Based Triggers
Recommended for monorepos using the changesets workflow. The workflow is triggered by a push to the main branch where the commit message starts with a specific prefix.
- Trigger:
push: branches: [main] - Condition:
if: startsWith(github.event.head_commit.message, 'Version Packages') - Logic: This allows
pubmto handle multiple packages with independent versions in a single CI run.
Sources: packages/pubm/src/commands/init-workflows.ts:154-167, plugins/pubm-plugin/skills/publish-setup/references/ci-templates.md:158-164
Environment and Secret Management
Security in CI is managed through environment variables and GitHub Secrets. pubm requires specific tokens depending on the target registries.
| Secret Name | Target Registry | Permission/Usage |
|---|---|---|
GITHUB_TOKEN | GitHub | Creating releases and uploading assets. |
NODE_AUTH_TOKEN | npm | Publishing to npm. Requires registry-url config in setup-node. |
JSR_TOKEN | JSR | Publishing to JSR. |
CARGO_REGISTRY_TOKEN | crates.io | Publishing to crates.io via cargo publish. |
Sources: plugins/pubm-plugin/skills/publish-setup/references/ci-templates.md:27-37, packages/pubm/src/commands/init-workflows.ts:114-124
Permission Requirements
For GitHub Actions, the id-token: write permission is critical when publishing to npm to support provenance.
permissions:
contents: write
id-token: write
Sources: packages/pubm/src/commands/init-workflows.ts:133-145, plugins/pubm-plugin/skills/publish-setup/references/ci-templates.md:118-121
Automated Setup and Initialization
The pubm init command provides an interactive wizard to scaffold these CI workflows.
Workflow Generation Logic
The init-workflows module detects the project's package manager and monorepo status to generate tailored YAML files.
- Package Manager Detection: Scans for lock files (
bun.lock,pnpm-lock.yaml,yarn.lock,Cargo.lock). - Workflow File Creation: Writes files to
.github/workflows/(e.g.,release.yml,changeset-check.yml). - Gitignore Updates: Automatically updates
.gitignoreto ensure.pubm/*is ignored while keeping.pubm/changesets/tracked.
Sources: packages/pubm/src/commands/init-workflows.ts:4-30, packages/pubm/src/commands/init.ts:88-105, packages/pubm/tests/unit/commands/init-workflows.test.ts:25-50
Changeset Validation
When changesets are enabled, pubm installs a changeset-check.yml workflow. This uses the syi0808/pubm-actions@v1 action to validate that Pull Requests include the necessary versioning documentation.
- Input:
skip-label: no-changesetallows bypassing the check for documentation or CI-only changes. - Output: Posts a status comment on the PR detailing detected changesets or errors.
Sources: packages/pubm/src/commands/init-workflows.ts:39-65, plugins/pubm-plugin/skills/publish-setup/references/ci-templates.md:224-245
Summary
CI/CD Integration in pubm transforms the complex task of multi-registry publishing into a predictable, automated pipeline. By utilizing a two-phase execution model and specialized CI modes, the system ensures that credentials remain secure while the release process remains concurrent and failure-resistant. Whether through tag-based triggers for simple libraries or commit-based triggers for complex monorepos, pubm provides the necessary scaffolding to maintain clean, professional release cycles.