Release Assets Pipeline
Relevant source files
The following files were used as context for generating this wiki page:
- packages/core/src/tasks/runner-utils/manifest-handling.ts
- packages/core/src/tasks/phases/push-release.ts
- packages/plugins/plugin-brew/tests/e2e/asset-pipeline-to-formula.test.ts
- packages/core/tests/unit/tasks/github-release.test.ts
- packages/core/tests/unit/assets/namer.test.ts
- packages/core/tests/unit/tasks/runner-coverage.test.ts
The Release Assets Pipeline is a core subsystem of pubm responsible for discovering, processing, and preparing binary artifacts or files for distribution during the release process. It automates the workflow of taking platform-specific builds, applying compression, generating cryptographic hashes, and renaming them according to specified templates before they are uploaded to targets like GitHub Releases.
This system ensures that assets are consistently formatted and metadata-rich (containing OS, architecture, and checksum information) so that downstream consumers—such as Homebrew formulas or automatic updaters—can reliably locate and verify them.
Pipeline Architecture
The pipeline operates as a sequence of stages that transform raw local files into "Prepared Assets" ready for remote upload. It is triggered during the release phase of the publication lifecycle.
Data Flow Overview
The diagram shows the lifecycle from configuration to the final distribution via GitHub and plugin integrations.
Sources: packages/core/src/tasks/runner-utils/manifest-handling.ts:1-44, packages/plugins/plugin-brew/tests/e2e/asset-pipeline-to-formula.test.ts:74-118
Key Components
| Component | Responsibility |
|---|---|
| Asset Resolver | Normalizes user configuration and resolves glob patterns or placeholders like {platform} into actual file paths. |
| Asset Pipeline | Executes the core logic of processing files: compression, hashing, and naming. |
| Platform Parser | Captures platform metadata (OS, Arch, Vendor, ABI) from directory structures or file names. |
| GitHub Release Task | Handles the physical upload of prepared assets to GitHub and returns public URLs. |
Sources: packages/core/src/tasks/runner-utils/manifest-handling.ts:16-44, packages/core/tests/unit/tasks/github-release.test.ts:145-188
Asset Discovery and Resolution
The pipeline starts by identifying which files need to be processed based on the releaseAssets configuration in pubm.config.ts.
Configuration Handling
The system supports both global asset definitions and package-specific definitions for monorepos. It attempts to find a matching group for the current package being released; if no specific match is found, it falls back to global definitions.
// From manifest-handling.ts: Find relevant group for this package
const relevantGroup = normalizedGroups.find(
(g) => g.packagePath === packagePath,
) ??
normalizedGroups.find((g) => !g.packagePath) ?? { files: [] };
Sources: packages/core/src/tasks/runner-utils/manifest-handling.ts:25-30
Platform Parsing
The pipeline can capture platform information from path segments using variables like {platform}, {os}, and {arch}. This is critical for tools like Homebrew that require specific binaries for different architectures. It also supports aliasing, such as mapping macos to darwin or win to windows.
Sources: packages/plugins/plugin-brew/tests/e2e/asset-pipeline-to-formula.test.ts:167-195
Processing: Compression, Hashing, and Naming
Once files are discovered, they pass through the execution pipeline.
Compression and Hashing
Assets can be compressed into various formats including tar.gz, zip, tar.xz, and tar.zst. If compress is set to false, the original file extension is preserved. During this phase, a SHA-256 hash is generated for every asset to ensure integrity.
Template-based Naming
The pipeline renames assets using a template engine that supports several variables:
{name}: The package name.{version}: The version being released.{platform}: The full platform string (e.g.,linux-x64).{os}/{arch}: Individual platform components.{filename}: The original name of the discovered file.
Sources: packages/core/tests/unit/assets/namer.test.ts:40-101
Integration with Distribution Targets
After processing, assets are handed off to release tasks and plugins.
GitHub Releases
The createGitHubRelease task takes the PreparedAssets and uploads them to the GitHub API. This task is responsible for:
- Checking if a release already exists for the tag.
- Creating the release if missing.
- Uploading each file and collecting the final
browser_download_url.
Plugin Hooks
The pipeline provides uploadAssets and afterRelease hooks. Plugins like plugin-brew use these to receive the final asset list (including URLs and SHA-256 hashes) to update external manifests like Homebrew Ruby formulas.
Sources: packages/core/src/tasks/phases/push-release.ts:153-172, packages/plugins/plugin-brew/tests/e2e/asset-pipeline-to-formula.test.ts:128-144
Summary
The Release Assets Pipeline is a robust automation layer that bridges local build outputs with global distribution. By combining platform detection, integrity hashing, and flexible naming, it allows pubm to support complex multi-platform release strategies with minimal manual configuration. This system is particularly vital for projects that distribute compiled binaries across various operating systems and package managers.