Pbuf Registry
pbufio20 estrellas
Self-hosted Protobuf schema registry in Go — OIDC/RBAC, multi-source vendoring (pbuf, buf.build, Git), go_package patching, drift detection, Web UI & MCP server
- Transporte
- stdio
- Estado
- Local
Potencia tu agente
Instalación del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
Aún no hay una versión empaquetada en el registro. Sigue el README del repositorio.
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
Abrirpbuf-registry is an Apache-2.0, self-hosted Protocol Buffers schema registry written in Go—complete with OIDC / OAuth2 SSO, per-module RBAC, multi-source vendoring (pbuf-registry, buf.build, and Git), automatic option go_package rewriting, breaking-change & transitive drift detection, a dark-mode Vue 3 Web UI, and a built-in Model Context Protocol (pbuf mcp) server for AI coding agents.pbuf-registry? (Comparison vs. Buf & Git)option go_package Rewriting (gen_out)pbuf-registry, buf.build, and Git)pbuf drift diff)pbuf mcp)pbuf)pbuf.yaml)
pbuf)
pbuf-registry
pbuf-registry?Once gRPC microservices split across repositories, teams typically face an uncomfortable choice: copy .proto files via brittle Git scripts, or pay per-seat SaaS pricing for private schemas, SSO, and RBAC.
pbuf-registry solves three real pain points out of the box:
option go_package Rewriting (gen_out): Eliminate conflicting upstream option go_package declarations across Go repositories. Set gen_out: gen in pbuf.yaml and pbuf vendor automatically rewrites option go_package in downloaded .proto files to match your local go.mod module path.pbuf.yaml: Pull internal schemas from pbuf-registry, upstream packages from buf.build (BSR), and raw .proto subtrees from Git repositories in a single manifest.All components live in this monorepo and are released together under unified semantic versions:
┌──────────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ push / pull ┌───────────────────────────┐ │
│ │ pbuf │ ◄───────────────► │ pbuf-registry │ │
│ │ (CLI tool) │ │ gRPC :6777 / HTTP :8080 │ │
│ └──────┬───────┘ │ Debug/Metrics :8082 │ │
│ │ vendor │ PostgreSQL backend │ │
│ ▼ └─────────────▲─────────────┘ │
│ ┌──────────────┐ │ │
│ │ buf.build │ ┌─────────────┴─────────────┐ │
│ │ & Git repos │ │ pbuf-registry-ui │ │
│ └──────────────┘ │ Web UI (Vue 3 + nginx) │ │
│ └───────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────┘
option go_package Rewriting (gen_out)Anyone managing Go gRPC microservices across multiple repositories has hit conflicting option go_package declarations in upstream .proto files. When you set gen_out: gen on any dependency in pbuf.yaml, pbuf vendor reads your local go.mod module path and automatically rewrites option go_package in every downloaded .proto file:
syntax = "proto3";
package acme.payment.v1;
-option go_package = "github.com/acme/payment-service/api/payment/v1;paymentv1";
+option go_package = "github.com/acme/order-service/gen/payment/v1";
pbuf-registry, buf.build, and Git)Consumer services can pull schemas from pbuf-registry, the Buf Schema Registry (buf.build), and Git repositories in a single pbuf.yaml:
version: v1
name: myorg/order-service
registry:
addr: registry.example.com:6777
export:
paths:
- api
modules:
# 1. From pbuf-registry — pinned, auditable, drift-tracked, go_package patched
- name: myorg/payment-service
tag: v2.1.0
out: third_party
gen_out: gen
# 2. From Buf Schema Registry (buf.build) — public or private (via BUF_TOKEN / ~/.netrc)
- name: buf.build/bufbuild/protovalidate
tag: v0.14.0
out: third_party
# 3. From a Git repository — pinned to a tag or branch
- repository: https://github.com/googleapis/googleapis
path: google/api
tag: common-protos-1_3_2
out: third_party
When a module version modifies, deletes, or incompatibly changes .proto files compared to prior tags or downstream dependencies, the background proto-parser indexes the AST and records drift events with severity levels (INFO, WARNING, CRITICAL) and upgrade recommendations. You can also run pbuf drift diff locally or in CI before pushing a tag:
# Compare local .proto edits against the latest published tag in the registry (exits non-zero on CRITICAL)
pbuf drift diff
pbuf drift diff --against v2.0.0 --format markdown
# List all unacknowledged drift events across the registry
pbuf drift list
# Drift events for a specific module, optionally filtered by tag
pbuf drift module payment-service --tag v2.1.0
# Evaluate transitive dependency drift status for a module
pbuf drift dependencies order-service --tag v1.4.0
pbuf mcp)pbuf includes a built-in Model Context Protocol (MCP) server (pbuf mcp) over stdio. Connect Claude Code, Cursor, Antigravity, or GitHub Copilot directly to your organization's live Protobuf registry so AI coding assistants can inspect module tags, pull .proto definitions, query parsed AST metadata (messages, fields, RPCs, enums), and check breaking drift statuses without hallucinating wire types.
Every schema push gets a tag. Published tags are immutable: once pushed, the content at a tag never changes. Draft tags (--draft) can be overwritten during development and are automatically cleaned up after 7 days by the compaction daemon.
pbuf modules push v2.1.0 # Stable — permanent and immutable
pbuf modules push v2.1.0-rc1 --draft # Draft — mutable, auto-expires after 7 days
Engineers and CI pipelines can authenticate using:
pbuf login via OAuth 2.0 Device Authorization Flow, or Web UI Authorization Code + PKCE Flow)pbuf_user_* / pbuf_bot_*) with explicit read, write, or admin permissions per module or globally (*)SERVER_STATIC_TOKEN) for bootstrap and administrative automation.proto source files at any tag, explore parsed messages/services/enums/fields, and review dependency drift alerts — either in public read-only mode or authenticated via Bearer token or OIDC SSO.git clone https://github.com/pbufio/pbuf-registry.git
cd pbuf-registry
make cert-gen # Generates TLS certificates in gen/certs/
export SERVER_STATIC_TOKEN=my-secret-token
make run-prod # Starts PostgreSQL, Registry, Daemons, and Web UI
localhost:6777http://localhost:8080http://localhost:80pbuf CLIcurl -fsSL https://raw.githubusercontent.com/pbufio/pbuf-registry/main/scripts/install.sh | sh
# Initialize pbuf.yaml for your module
pbuf init myorg/payment-service localhost:6777
# Save your registry token to ~/.netrc
pbuf auth "${SERVER_STATIC_TOKEN}"
# Register the module and push your .proto files as v1.0.0
pbuf modules register
pbuf modules push v1.0.0
# Pull all configured dependencies into third_party/
pbuf vendor
See examples/ for a complete end-to-end walkthrough with sample .proto files.
pbuf)brew install pbufio/tap/pbuf
Install the latest release to /usr/local/bin:
curl -fsSL https://raw.githubusercontent.com/pbufio/pbuf-registry/main/scripts/install.sh | sh
Install a specific version or to a custom directory:
# Specific version
curl -fsSL https://raw.githubusercontent.com/pbufio/pbuf-registry/main/scripts/install.sh | sh -s -- -v v0.10.0
# Custom install directory (no sudo required)
INSTALL_DIR=$HOME/.local/bin curl -fsSL https://raw.githubusercontent.com/pbufio/pbuf-registry/main/scripts/install.sh | sh
go install)Requires Go 1.25+:
go install github.com/pbufio/pbuf-registry/cmd/pbuf@latest
Option 1: PowerShell
$release = Invoke-RestMethod "https://api.github.com/repos/pbufio/pbuf-registry/releases/latest"
$version = $release.tag_name
$plainVersion = $version.TrimStart('v')
$arch = if ([Environment]::Is64BitOperatingSystem) { "amd64" } else { "386" }
$url = "https://github.com/pbufio/pbuf-registry/releases/download/$version/pbuf_${plainVersion}_windows_${arch}.zip"
$output = "$env:TEMP\pbuf.zip"
Invoke-WebRequest -Uri $url -OutFile $output
Expand-Archive -Path $output -DestinationPath "$env:TEMP\pbuf" -Force
Move-Item -Path "$env:TEMP\pbuf\pbuf.exe" -Destination "$env:USERPROFILE\bin\pbuf.exe" -Force
Remove-Item -Path $output, "$env:TEMP\pbuf" -Recurse -Force
Option 2: Manual Binary Download
Download pre-built archives for Linux, macOS, and Windows (amd64 / arm64) from the GitHub Releases page.
make build-cli
# Binary is output to ./bin/pbuf
pbuf.yaml)pbuf reads pbuf.yaml from the current working directory.
pbuf.yaml Schemaversion: v1
name: myorg/my-service
registry:
addr: registry.example.com:6777 # Registry gRPC address (host or host:port; defaults to :443 or :80)
insecure: false # Set to true only for plaintext HTTP/gRPC in local dev
oidc: # Optional defaults for `pbuf login`
issuer: https://idp.example.com
client_id: pbuf-cli
export:
paths: # Directories whose .proto files are exported on `pbuf modules push`
- api
- proto
modules:
# 1. pbuf-registry dependency
- name: myorg/common-protos
path: common/v1 # Optional: restrict vendoring to a subfolder or single .proto file
tag: v1.2.0
out: third_party # Destination directory for downloaded .proto files
gen_out: gen # Optional: rewrites `option go_package` in downloaded .proto files
# 2. Buf Schema Registry (buf.build) dependency
- name: buf.build/bufbuild/protovalidate
path: buf/validate # Optional: filter by path prefix
tag: v0.14.0 # Tag, commit ref, or `branch:` (defaults to "main" if omitted)
out: third_party
gen_out: gen # Optional: rewrites `option go_package`
# 3. Git repository dependency
- repository: https://github.com/googleapis/googleapis
path: google/api # Required for Git modules: subfolder or single .proto file in repo
tag: common-protos-1_3_2 # Git tag (or use `branch: main`)
out: third_party
gen_out: gen # Optional: rewrites `option go_package`
pbuf-registryModules with a name (not starting with buf.build/) and no repository field are pulled from the configured registry.addr over gRPC:
modules:
- name: pbufio/pbuf-registry
tag: v0.9.0
path: api/pbuf-registry/v1 # Optional: only vendor files under this prefix
out: third_party
gen_out: gen # Optional
buf.build)Modules whose name starts with buf.build/<owner>/<module> are downloaded directly from the Buf Schema Registry reflection API (https://buf.build/buf.reflect.v1beta1.FileDescriptorSetService/GetFileDescriptorSet) and reconstructed into .proto files—without requiring a pbuf-registry server connection:
modules:
- name: buf.build/googleapis/googleapis
tag: main
path: google/type
out: third_party
Private BSR Modules Authentication:
BUF_TOKEN environment variable (export BUF_TOKEN=...), orbuf.build in ~/.netrc:
machine buf.build
password <your-buf-token>
Modules with a repository URL are cloned with a shallow single-branch fetch (depth: 1) at the specified tag or branch:
modules:
- repository: https://github.com/protocolbuffers/protobuf
path: examples/addressbook.proto
tag: v24.4
out: proto
Private Git Repositories Authentication:
Add credentials for your Git host in ~/.netrc:
machine github.com
login <github-username>
password <personal-access-token>
go_package Patching (gen_out)When a dependency in modules specifies gen_out, pbuf vendor inspects your local go.mod module name and automatically sets or rewrites option go_package in every vendored .proto file for that dependency to:
<go.mod module name>/<gen_out>/<relative directory of .proto file>
For example, if your go.mod declares module github.com/myorg/order-service, out: third_party, and gen_out: gen, a vendored file at third_party/payment/v1/payment.proto will have its go_package patched to github.com/myorg/order-service/gen/payment/v1.
pbuf initInitializes a pbuf.yaml file in the current directory.
# Interactive TUI prompt
pbuf init
# Non-interactive (defaults registry to pbuf.cloud when omitted)
pbuf init myorg/payment-service
pbuf init myorg/payment-service registry.example.com:6777
pbuf authStores a static, user, or bot token in ~/.netrc (creating the file with 0600 permissions if it does not exist) for the host configured in pbuf.yaml (registry.addr, or localhost if pbuf.yaml is not present):
pbuf auth pbuf_bot_abc123...
pbuf loginAuthenticates with an OIDC identity provider using the OAuth 2.0 Device Authorization Flow (RFC 8628) and saves the resulting ID token / access token to ~/.netrc.
# Using flags
pbuf login --issuer https://idp.example.com --client-id pbuf-cli --scope "openid profile email"
# Using environment variables
export PBUF_OIDC_ISSUER=https://idp.example.com
export PBUF_OIDC_CLIENT_ID=pbuf-cli
pbuf login
# Or using registry.oidc.issuer and registry.oidc.client_id from pbuf.yaml
pbuf login
pbuf vendorDownloads all dependencies listed under modules: in pbuf.yaml (supporting pbuf-registry, buf.build BSR, and Git repositories) and applies go_package patching where gen_out is configured:
pbuf vendor
pbuf modules)All pbuf modules commands use the name and registry settings from pbuf.yaml.
# Register the module in pbuf-registry
pbuf modules register
# Push .proto files from export.paths with an immutable tag
pbuf modules push v1.0.0
# Push a temporary draft tag (mutable, auto-deleted after 7 days)
pbuf modules push v1.1.0-rc1 --draft
# List all modules in the registry
pbuf modules list
# Get module metadata, tags, and dependencies (uses name from pbuf.yaml if omitted)
pbuf modules get
pbuf modules get myorg/payment-service
# Update all pbuf-registry dependencies in pbuf.yaml to their latest published tag
pbuf modules update
# Delete a specific tag of the current module
pbuf modules delete-tag v1.1.0-rc1
# Delete the current module and all of its tags
pbuf modules delete
pbuf metadata)Retrieves parsed AST metadata (packages, messages, fields, nested types, enums, and gRPC services/methods) indexed by the background proto-parser:
# Uses module name from pbuf.yaml when omitted
pbuf metadata get
pbuf metadata get myorg/payment-service v1.0.0
pbuf drift)Inspects local uncommitted breaking changes, file-level drift events, and cross-module dependency drift:
# Compare local .proto files in export.paths against the latest (or specified) registry tag
pbuf drift diff
pbuf drift diff --against v1.2.0 --format markdown --fail-on critical
# List unacknowledged drift events (default --unacknowledged-only=true)
pbuf drift list
# List all drift events (including acknowledged)
pbuf drift list --unacknowledged-only=false
# Get drift events for a specific module (optionally filtered by tag)
pbuf drift module myorg/payment-service
pbuf drift module myorg/payment-service --tag v2.0.0
# Print a tabular report of dependency drift status and recommendations
pbuf drift dependencies myorg/order-service
pbuf drift dependencies myorg/order-service --tag v1.4.0
# Acknowledge a drift event by ID
pbuf drift acknowledge <event-id> --by alice
pbuf mcp)pbuf mcp runs a standard JSON-RPC 2.0 Model Context Protocol (MCP) server over stdio. It connects to the registry configured in pbuf.yaml (or via PBUF_REGISTRY_ADDR and PBUF_REGISTRY_INSECURE environment variables) using credentials from ~/.netrc.
mcp.json){
"mcpServers": {
"pbuf-registry": {
"command": "pbuf",
"args": ["mcp"],
"env": {
"PBUF_REGISTRY_ADDR": "pbuf.cloud:6777"
}
}
}
}
pbuf users)Requires admin privileges (Static Admin Token, a user with admin permission on *, or an OIDC user in adminGroups).
# Create a human user or CI bot (outputs one-time token: pbuf_user_* or pbuf_bot_*)
pbuf users create alice --type user
pbuf users create ci-deployer --type bot
# List users with pagination
pbuf users list --page-size 50 --page 0
# Get a user by UUID
pbuf users get <user-id>
# Update user name or active status
pbuf users update <user-id> --name "Alice Smith"
pbuf users update <user-id> --inactive
pbuf users update <user-id> --active
# Rotate a user or bot token (immediately invalidates the old token)
pbuf users regenerate-token <user-id>
# Grant and revoke permissions (read, write, admin) for a module or globally ("*")
pbuf users grant-permission <user-id> myorg/payment-service --permission write
pbuf users grant-permission <user-id> "*" --permission read
pbuf users list-permissions <user-id>
pbuf users revoke-permission <user-id> myorg/payment-service
# Delete a user or bot
pbuf users delete <user-id>
pbuf-registryPrerequisites: Docker and Docker Compose
git clone https://github.com/pbufio/pbuf-registry.git
cd pbuf-registry
make cert-gen
export SERVER_STATIC_TOKEN=your-strong-admin-token
make run-prod # Starts PostgreSQL, Registry, Compaction, Proto-Parser, and Web UI
make stop-prod # Stops the stack
Pin specific image versions via REGISTRY_VERSION and REGISTRY_UI_VERSION (both default to latest):
REGISTRY_VERSION=v0.9.0 REGISTRY_UI_VERSION=v0.9.0 SERVER_STATIC_TOKEN=your-token docker compose up -d
For local development with ACL seeding and auto-generated dev tokens:
make run # Starts docker-compose.dev.yml and seeds sample ACL users/tokens
make stop # Tears down dev environment
The Helm chart is published to GitHub Container Registry (OCI) and the GitHub Pages Helm Repository:
# Option 1: Install directly from GHCR OCI registry
helm install my-pbuf-registry oci://ghcr.io/pbufio/charts/pbuf-registry \
--version 0.9.0 \
--set postgresql.enabled=false \
--set secrets.databaseDSN="postgres://user:pass@host:5432/pbuf_registry?sslmode=require" \
--set secrets.staticToken="your-admin-token" \
--set ui.enabled=true
# Option 2: Install via Helm repository
helm repo add pbuf https://pbufio.github.io/pbuf-registry
helm repo update
helm install my-pbuf-registry pbuf/pbuf-registry \
--set secrets.staticToken="your-admin-token"
See charts/pbuf-registry/README.md for the full configuration values table, including External Secrets Operator (ESO), Ingress, Web UI, and OIDC SSO settings.
pbuf-registry-ui)The Web UI is included in docker-compose.yml and the Helm chart (ui.enabled=true), or can be run standalone via Docker:
docker run -d \
-p 8080:80 \
-e API_BASE_URL=http://your-registry:8080 \
-e API_TOKEN=${SERVER_STATIC_TOKEN} \
-e PUBLIC_ENABLED=true \
--name pbuf-ui \
ghcr.io/pbufio/pbuf-registry-ui:latest
See ui/README.md for full Web UI configuration, proxy architecture, and OIDC SSO setup.
The pbuf-registry server binary (cmd/main.go) provides three subcommands:
Configure SERVER_GRPC_AUTH_ENABLED=true / SERVER_HTTP_AUTH_ENABLED=true and set SERVER_GRPC_AUTH_TYPE / SERVER_HTTP_AUTH_TYPE to one of:
static-token — Authenticates all requests against SERVER_STATIC_TOKEN (full admin access).acl (or token) — Full role-based access control:
SERVER_STATIC_TOKEN grants full superadmin access.pbuf_user_* and pbuf_bot_* tokens are looked up via SHA-256 prefix digest and verified against bcrypt hashes in PostgreSQL (pgcrypto).oidc — Enables OIDC / OAuth2 JWT verification plus full fallback support for SERVER_STATIC_TOKEN and pbuf_user_* / pbuf_bot_* tokens:
jwks_uri via /.well-known/openid-configuration (or explicit JWKSURL) and verifies RS256/ES256 JWT signatures, iss, aud (clientId), and exp.autoProvision: true.admin permission automatically if the user's groups claim intersects adminGroups.Permissions can be granted for a specific module name (e.g., myorg/payment-service) or globally (*). Unauthenticated users are allowed read-only access to public read endpoints (ListModules, GetModule, PullModule, GetModuleDependencies, GetMetadata, GetModuleDriftEvents, GetModuleDependencyDriftStatus).
Configuration is loaded from the embedded internal/config/config.yaml and overridden by environment variables (replacing . with _ in uppercase):
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install pbuf CLI
run: |
curl -fsSL https://raw.githubusercontent.com/pbufio/pbuf-registry/main/scripts/install.sh | sh -s -- -v v0.9.0
pbuf auth "${{ secrets.PBUF_TOKEN }}"
- name: Vendor dependencies
run: pbuf vendor
- name: Push schema on release tag
if: startsWith(github.ref, 'refs/tags/v')
run: |
pbuf modules register || true
pbuf modules push "${{ github.ref_name }}"
.pbuf_setup: &pbuf_setup
before_script:
- curl -fsSL https://raw.githubusercontent.com/pbufio/pbuf-registry/main/scripts/install.sh | sh -s -- -v v0.9.0
- pbuf auth "${PBUF_TOKEN}"
vendor:
<<: *pbuf_setup
script:
- pbuf vendor
:6777 by default): Primary API for all registry, metadata, drift, and user management operations. Proto definitions: api/pbuf-registry/v1/:8080 by default): HTTP/JSON transcoded API. OpenAPI/Swagger specification: gen/pbuf-registry/v1/registry.swagger.json:8082 by default): Health check and Prometheus metrics (/metrics).Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
make Targets# Setup & Code Generation
make init # Install required Go protoc plugins, mockery, and golangci-lint
make api # Regenerate Go/gRPC/HTTP/Swagger code from api/pbuf-registry/v1/
make mocks # Regenerate test mocks with mockery
# Build
make build # Build registry server binary to bin/pbuf-registry
make build-cli # Build pbuf CLI binary to bin/pbuf
make build-migrations # Build database migrations binary to bin/pbuf-migrations
make build-ui # Build Web UI production bundle in ui/dist
# Test & Lint
make test # Run all Go unit tests (server + CLI) with race detector
make test-ui # Run Web UI unit tests (node --test)
make test-ui-e2e # Run Web UI Playwright E2E tests
make lint # Run golangci-lint
make lint-charts # Lint Kubernetes Helm chart in charts/pbuf-registry/
make test-e2e # Run binary + PostgreSQL E2E test suite
make test-compose-e2e # Run full Docker Compose + CLI + Playwright UI E2E suite
Self-hosted Protobuf schema registry in Go — OIDC/RBAC, multi-source vendoring (pbuf, buf.build, Git), go_package patching, drift detection, Web UI & MCP server
Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
Este registro no indica ninguna variable de entorno obligatoria.
Pbuf Registry se ejecuta localmente por stdio.
Última comprobación: 2026-10-27. Self-hosted Protobuf schema registry in Go — OIDC/RBAC, multi-source vendoring (pbuf, buf.build, Git), go_package patching, drift detection, Web UI & MCP server