Official Plugins

Official plugins live alongside pubm and follow the same release and compatibility expectations as the core project. Use them when you want a supported integration without building your own plugin from scratch.

@pubm/plugin-brew

@pubm/plugin-brew helps CLI projects keep Homebrew formulae in sync with each release. It registers rollback actions that close any Homebrew PRs created if the pipeline fails after the PR is opened.

Good for

• shipping a CLI binary through Homebrew
• updating a dedicated tap repository automatically
• keeping formula checksums aligned with release assets

Typical config

import { defineConfig } from "@pubm/core";
import { brewTap } from "@pubm/plugin-brew";

export default defineConfig({
  plugins: [
    brewTap({
      formula: "Formula/my-tool.rb",
      repo: "https://github.com/my-org/homebrew-tap",
    }),
  ],
});

Options

Option	Type	Description
formula	string	Formula path relative to the repository root.
repo	string	Optional remote tap repository URL. If omitted, the current repository is used.
packageName	string	Optional package name filter. When set, the plugin only runs for releases matching this package name. Useful in monorepos.
assetPlatforms	Record<string, (asset: ReleaseAsset) => boolean>	Optional custom platform matchers. Overrides the default os + arch matching logic.

Platform matching

The plugin uses structured ParsedPlatform data from each ReleaseAsset to match assets to formula platform entries. The default matching logic covers four platforms:

Formula key	Matches when
darwin-arm64	asset.platform.os === "darwin" && asset.platform.arch === "arm64"
darwin-x64	asset.platform.os === "darwin" && asset.platform.arch === "x64"
linux-arm64	asset.platform.os === "linux" && asset.platform.arch === "arm64"
linux-x64	asset.platform.os === "linux" && asset.platform.arch === "x64"

This replaces the previous approach of string-matching asset names (e.g., asset.name.includes("darwin-arm64")), which was fragile when names changed.

Custom platform matchers

Use assetPlatforms when the default os + arch matching is not enough, for example when you only want musl builds for Linux:

brewTap({
  formula: "Formula/mytool.rb",
  assetPlatforms: {
    "darwin-arm64": (asset) =>
      asset.platform.os === "darwin" && asset.platform.arch === "arm64",
    "linux-x64": (asset) =>
      asset.platform.os === "linux" &&
      asset.platform.arch === "x64" &&
      asset.platform.abi === "musl",
  },
})

Each predicate receives a ReleaseAsset and returns true if the asset should be used for that formula entry.

Credentials and preflight checks

@pubm/plugin-brew declares its own credentials and checks automatically. You do not need to configure them manually.

Required credential:

Environment variable	GitHub Secret name	Purpose
PUBM_BREW_GITHUB_TOKEN	PUBM_BREW_GITHUB_TOKEN	GitHub Personal Access Token with repo scope, used to push formula updates and open pull requests.

In local runs, pubm prompts for this token and stores it in the system keyring. In CI, provide the token via the PUBM_BREW_GITHUB_TOKEN environment variable. Run pubm --mode ci --phase prepare or pubm secrets sync to sync the stored token into your repository’s GitHub Secrets so CI workflows can consume it automatically.

The plugin also registers a preflight check that verifies the token is present and has the required repository access before the publish phase begins.

Behavior

The plugin can:

• create a formula scaffold when one does not exist
• update url and sha256 values for release assets using structured platform info
• commit and push formula changes
• fall back to a pull-request workflow when direct push is not appropriate

Related command

pubm brew init

Use this to scaffold a starting formula from package metadata.

brewCore

For contributing to homebrew-core (the default Homebrew repository), use brewCore instead of brewTap:

import { brewCore } from "@pubm/plugin-brew";

export default defineConfig({
  plugins: [
    brewCore({
      formula: "Formula/my-tool.rb",
    }),
  ],
});

Option	Type	Description
formula	string	Formula path relative to the repository root.
packageName	string	Optional package name filter for monorepos.
assetPlatforms	Record<string, (asset: ReleaseAsset) => boolean>	Optional custom platform matchers.

brewCore forks homebrew/homebrew-core, updates the formula, and opens a PR automatically. Like brewTap, it declares the PUBM_BREW_GITHUB_TOKEN credential and a preflight check automatically.

@pubm/plugin-external-version-sync

This plugin keeps non-manifest files aligned with your package version. It registers rollback actions to restore original file contents if the pipeline fails after version sync.

Use it when a release should also update:

• README.md install snippets
• docs examples
• app manifests
• source constants
• metadata JSON files

Typical config

import { defineConfig } from "@pubm/core";
import { externalVersionSync } from "@pubm/plugin-external-version-sync";

export default defineConfig({
  plugins: [
    externalVersionSync({
      targets: [
        {
          file: "src/constants.ts",
          pattern: /export const VERSION = "([^"]+)";/,
        },
        {
          file: "manifest.json",
          jsonPath: "metadata.version",
        },
        {
          file: "README.md",
          pattern: /pubm@([\\w.-]+)/,
        },
      ],
    }),
  ],
});

Target types

regex

Use for arbitrary text files:

{
  file: "README.md",
  pattern: /pubm@([\\w.-]+)/,
}

Requirements:

• the pattern must isolate the version in exactly one capturing group
• the file should have a stable format so release automation can update it safely

json

Use for machine-readable manifests:

{
  file: "manifest.json",
  jsonPath: "metadata.version",
}

When to use pubm sync --discover

If you are not sure where versions appear in your repository, run:

pubm sync --discover

That command scans for likely version references and prints candidate files and paths you can adapt into plugin config.

Choosing between official and custom plugins

Use an official plugin when:

• your need matches an existing integration
• you want a lower-maintenance setup
• the release path is common enough to benefit from standardization

Build a custom plugin when:

• your registry or post-release workflow is organization-specific
• you need custom policy or deployment logic
• you want additional CLI commands for operators

Read the Plugins API Reference if you need to extend beyond the official set.

Coding-agent setup automation

Runtime plugins are only part of the story. This repository also ships a pubm plugin bundle under plugins/pubm-plugin/skills/* for coding-agent workflows such as:

• release setup
• preview-first publish assistance
• version-sync discovery
• plugin scaffolding

If you are integrating pubm into an agent environment, pair runtime plugins with these skill-style assets so setup and publish flows stay explicit and repeatable.

Read the Coding Agent Integration guide for the integration layout.