Publish a pattern

Publishing does not upload content. It registers the Git ref that already contains the validated bundle.

Before publishing

1. Set scope: shareable only after removing project-specific language.
2. Increment the bundle's semantic version.
3. Run patterns validate <bundle-dir>.
4. Commit and push the bundle to a public GitHub repository.
5. Create an immutable tag or use a commit SHA for consumers.

For a monorepo of independent patterns, a pattern-specific tag is unambiguous:

git tag vertical-slice-use-case-v0.2.0
git push origin vertical-slice-use-case-v0.2.0

Register the ref

First merge the manifest change into the repository's default branch. The server indexes that branch's current HEAD; it does not index the tag or branch currently checked out on your machine.

From the directory that contains the bundle's patterns.yaml (or a child of it), the CLI can infer the remote and subdirectory:

cd patterns/vertical-slice-use-case
patterns publish

Or provide it explicitly:

patterns publish owner/repo/path-to-pattern

The command uses GITHUB_TOKEN or the token returned by gh auth token. The service verifies push access to prevent someone else from indexing a repository they do not control.

A successful publish returns 201 with the indexed entry wrapped in { "data": { ... } }. A name already claimed by another indexed ref returns 409: the machine ID is globally unique across the directory — this applies even to a second ref of your own — and there is no self-service unpublish, so choose a distinctive name before the first publish.

Update an indexed pattern

Push or merge the new manifest to the default branch, then run patterns publish again for the same ref. The index row is rebuilt from that branch's resolved commit. Existing pinned installations do not move. To adopt a new tag, consumers explicitly add that tag again:

patterns add owner/repo/path-to-pattern#pattern-name-v1.3.0

patterns update re-resolves the recorded ref; when that ref is an old immutable tag, it remains on the old version.