docs(homebrew): document GHCR upload layout gap (blob vs native OCI)#831
Open
brandonpayton wants to merge 1 commit into
Open
Conversation
Add a "GHCR Upload Layout" section to docs/homebrew-publishing.md recording that today's bottle upload (scripts/homebrew-ghcr-upload.sh, oras push) is blob-addressable for the Kandelo VFS fetcher but is not in Homebrew's native version-tagged OCI layout, so a stock guest `brew install` against the GHCR root_url cannot resolve the bottle. Guest brew install remains unsupported. Prevents the homebrew-all package fan-out from implying `brew tap && brew install` works across packages. Docs-only; no code change. Reconciliation to the native OCI layout (brew pr-upload --upload-only, or a version-tagged index emitter) is deferred until guest brew install is a committed goal, per the bottle-publishing research doc's implementation sequence. Bead: kd-7xjc Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a GHCR Upload Layout section to
docs/homebrew-publishing.mdrecordingthat today's bottle upload (
scripts/homebrew-ghcr-upload.sh,oras push) isblob-addressable for the Kandelo VFS fetcher but is not in Homebrew's
native version-tagged OCI layout, so a stock guest
brew installagainst theGHCR
root_urlcannot resolve the bottle. Guestbrew installremainsunsupported.
Why
The
homebrew-allconvoy (kd-1mr) is fanning out across ~73 packages. Withoutthis note, the tap "looking like a tap" (real
Formula/*.rb, a GHCRroot_url)implies
brew tap && brew installworks — it does not. This records the latentblocker so the fan-out does not bake a non-native layout into many packages
under a false install promise.
Docs-only; no code change. This is step 2 (docs-only) of the implementation
sequence in
docs/plans/2026-07-01-homebrew-builtin-vs-custom-bottle-publishing-research.md(PR #823). Reconciliation to the native OCI layout (
brew pr-upload --upload-only, or teaching the uploader to emit a version-tagged OCI index) isdeferred until guest
brew installis a committed goal.Verification (docs-only)
git diff --check: clean.unbreakable doc-path reference.
(
scripts/homebrew-ghcr-upload.sh),root_url(
.github/workflows/reusable-homebrew-bottle-publish.yml→scripts/homebrew-bottle-build.sh), and blob-direct consumption(
host/src/homebrew-vfs-fetch.ts).docs-only change.
Bead:
kd-7xjc(discovered fromkd-1i0u; blockskd-1mr).🤖 Generated with Claude Code