Skip to content

[FIX] Pin marketplace install to the v0.2.0 release tag#24

Open
Jr-kenny wants to merge 2 commits into
FhenixProtocol:mainfrom
Jr-kenny:pin-marketplace-ref
Open

[FIX] Pin marketplace install to the v0.2.0 release tag#24
Jr-kenny wants to merge 2 commits into
FhenixProtocol:mainfrom
Jr-kenny:pin-marketplace-ref

Conversation

@Jr-kenny

Copy link
Copy Markdown

Closes #21

What this does

Adds ref: "v0.2.0" to the git-subdir source in marketplace.json, so /plugin install fhenix-toolkit resolves to the exact tagged commit instead of floating on main's HEAD. Went with pinning to the existing v0.2.0 tag rather than waiting for a v0.2.1 cut, since v0.2.0 is byte-identical to main right now. That closes the gap immediately without changing what anyone gets today.

Also:

  • docs/release-process.md: bumping ref is now the fourth version-sync step on each release cut, with a note that the ref is dangling until the tag is pushed
  • docs/known-flaws.md: removed the "default install floats on default-branch HEAD" entry
  • CHANGELOG.md: entries under Unreleased for both fixes

One extra find: installs were failing for HTTPS-only users

While testing the pin I hit Permission denied (publickey) on install. The bare FhenixProtocol/fhenix-toolkit shorthand in the source url gets resolved to an SSH clone (git@github.com:...), so anyone without GitHub SSH keys configured couldn't install at all, independent of this change. Switched the url to the full HTTPS form and installs work cleanly. Worth knowing this was already broken on main for that set of users.

Answer to the open question (does marketplace update re-read a new ref?)

Yes. Tested locally against the real GitHub repo:

  1. Fresh marketplace add + install with ref: "v0.2.0" lands on commit f6f2e51, which is exactly git rev-list -n1 v0.2.0. The pin works.
  2. Changed the ref, then ran /plugin marketplace update followed by /plugin update fhenix-toolkit. The install moved to the new tag's exact sha (verified against git rev-list -n1 again). No remove + re-add needed.

One caveat that's documented behavior in Claude Code: update detection keys off the plugin version, not the ref. A ref bump with an unchanged version string is silently skipped for existing installs. Not a problem for the release flow since version and ref bump together in the same cut, and the release doc now calls this out explicitly.

The git-subdir source had no ref, so /plugin install fhenix-toolkit
pulled whatever was on main's HEAD instead of the tagged release. The
version in Discover was just a label with no tie to the installed code.

v0.2.0 is byte-identical to main right now, so pinning ref to v0.2.0
makes installs deterministic without changing what anyone gets today,
and closes the 'install floats on HEAD' known flaw.

While testing the pin locally, found that the bare owner/repo shorthand
in the source url resolves to an SSH clone, so installs failed with
'Permission denied (publickey)' for anyone without GitHub SSH keys.
Switched the url to the full HTTPS form, which installs cleanly.

Tested with a local marketplace add against the real GitHub repo:
fresh install lands on the exact sha of v0.2.0 (f6f2e51), and after a
ref change, /plugin marketplace update + /plugin update moves the
install to the new tag's sha. No remove + re-add needed. Update
detection keys off the plugin version though, so a ref bump only
propagates when the version bumps with it. The release process bumps
both together, and the docs now say so.

Also added the ref bump as a fourth version-sync step in the release
process, with a note that the ref only resolves once the tag is pushed.
@Jr-kenny Jr-kenny requested review from a team and toml01 as code owners June 11, 2026 10:12
@Zhekinmaksim

Copy link
Copy Markdown

Nice catch on the SSH-url resolution - that one bites silently.

One suggestion: pin sha alongside ref. Per the marketplace spec, when both are set the sha is the effective pin, so the install resolves to an exact commit. A tag can still be force-moved, so ref alone isn't a hard integrity guarantee. It also matches the convention anthropics/claude-plugins-official uses (every entry there carries ref + sha).

v0.2.0 is an annotated tag that peels to f6f2e511bb4194c393c4f32829b5b0172eb01782 (same as current main HEAD, which lines up with your "byte-identical to main" note):

"source": {
  "source": "git-subdir",
  "url": "https://github.com/FhenixProtocol/fhenix-toolkit.git",
  "path": "plugins/fhenix-toolkit",
  "ref": "v0.2.0",
  "sha": "f6f2e511bb4194c393c4f32829b5b0172eb01782"
}

The release process would then bump both together, which fits the version-sync step you already documented.

A tag can be force-moved, so ref on its own isn't a hard integrity guarantee. Pinning the sha next to it means the install resolves to one exact commit no matter what happens to the tag later. f6f2e51 is the commit v0.2.0 points at, same as main's HEAD right now, so this doesn't change what anyone gets today.

It also lines up with what claude-plugins-official does, every git-subdir entry there carries both ref and sha.

The thing to watch is the release process. With both set the sha is the effective pin, so a future ref bump that leaves a stale sha would quietly keep installs on the old release. The tagged commit doesn't exist yet when the release PR is written, so the docs now say to bump ref at cut time, pin the sha right after tagging, and move the two together.

marketplace.json still parses and the pinned sha matches what v0.2.0 resolves to.
@Jr-kenny

Copy link
Copy Markdown
Author

Yeah, ref on its own still floats if the tag ever gets force-moved, so pinning the commit is worth doing. Added it as f6f2e51, which is what v0.2.0 points at and where main's HEAD sits right now, so nothing changes about what installs today.

Pinning the sha did surface one thing on the release side: with both set the sha is the effective pin, so a future ref bump that leaves a stale sha would quietly keep everyone on this commit instead of the new tag. The tagged commit doesn't exist yet when the release PR goes up, so I wrote the docs to bump ref at cut time and pin the sha right after tagging, and to keep the two moving together.

Pushed in 45b0a85. marketplace.json still parses and the sha matches what v0.2.0 resolves to.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEAT] Pin marketplace source to release tag (close 'install floats on HEAD' known-flaw)

2 participants