Skip to content

Install the marketplace-verified snapshot by default in plugin add - #11242

Open
StavWasPlayZ wants to merge 3 commits into
omacom:quattrofrom
StavWasPlayZ:plugin-add-verified-snapshot
Open

StavWasPlayZ wants to merge 3 commits into
omacom:quattrofrom
StavWasPlayZ:plugin-add-verified-snapshot

Conversation

@StavWasPlayZ

@StavWasPlayZ StavWasPlayZ commented Sep 10, 2026 •

Copy link
Copy Markdown

Discussion: #11236

The plugin marketplace verifies exact commits, but omarchy plugin add clones whatever upstream HEAD is at that moment. The marketplace calls this out itself (VERIFICATION.md, "Installation boundary"). In the 2026-09-10 catalog, 814 of the 2,687 plugins with a verified snapshot have upstream commits past that snapshot, so the install command gives users code the marketplace never checked.

This makes the existing command install what the badge describes. Nothing changes on the marketplace side: it keeps showing omarchy plugin add <url> --enable.

Behavior

omarchy plugin add <url> looks the repo up in https://plugins.omarchy.org/catalog.json before cloning:

  • Verified snapshot listed → clones, checks out that exact commit before validation, and says newer upstream commits (if any) are unverified and that verification is not a security audit.
  • Listed without a snapshot / not listed / not GitHub → installs upstream HEAD with a warning.
  • Catalog unreachable or unparseable → installs upstream HEAD with a warning, as the command does today.
  • --head → installs upstream HEAD with a warning, without asking the marketplace.
  • --commit <sha> → installs exactly that commit and pins the plugin there, without asking the marketplace. It takes a full 40-character hash, can't be combined with --head, checks the commit out before validation, and refuses if upstream doesn't have it.
  • Snapshot no longer available upstream → refuses, since a vanished snapshot is what a rewritten or compromised repository looks like, and prints the --head command for installing HEAD on purpose.

omarchy plugin update keeps each plugin on the track it was added with, recorded as omarchy.channel in the checkout's .git/config:

  • verified → fast-forwards to the marketplace's newest verified snapshot (one catalog fetch for a whole bulk update). A withdrawn snapshot or delisted repo leaves the plugin where it is and names --head.
  • head, or no channel (every checkout that exists today) → unchanged: fetch origin HEAD, diff, confirm, fast-forward, validate, roll back on failure.
  • pinned → left where it is; the command prints how to move or release the pin.
  • omarchy plugin update <id> --commit <sha> moves a plugin to that commit (forwards or backwards) and pins it: diff, confirm, refuse on local changes, validate, roll back on failure.
  • omarchy plugin update <id> --head switches a verified or pinned plugin to following upstream HEAD permanently.

Implementation

  • bin/omarchy-plugin-marketplace-lookup (new, hidden): normalizes https://, git@github.com: and ssh:// GitHub URLs, fetches the catalog at most once (only when a URL names GitHub), and prints <state> <verified-commit> <upstream-commit> per URL. Only a single root-plugin community listing counts; suites, monorepos and duplicates are treated as having no usable snapshot. OMARCHY_PLUGIN_CATALOG_URL overrides the catalog location for tests.
  • bin/omarchy-plugin-add: --head, --commit, the lookup, per-state notices, checkout-before-validate, and the channel record.
  • bin/omarchy-plugin-update: --head, --commit, per-channel update paths sharing one diff/confirm/merge/validate/rollback routine, and a reset-based pin move for --commit, since a pin may move backwards. The origin is read from remote.origin.url rather than git remote get-url, so a user's insteadOf rewrites don't hide the GitHub URL.
  • Manual, docs/omarchy-shell.md and shell/README.md describe the new behavior.

Tests

  • New test/shell.d/plugin-marketplace-test.sh (21 cases, fully offline: local catalog file, url.<path>.insteadOf to redirect the github.com URL to a local upstream) covers lookup classification, verified install, --head, unverified/unlisted/unreachable warnings, refusal when the snapshot is gone upstream, verified-track updates, withdrawn snapshots, --head switching, pre-existing checkouts staying on HEAD, and --commit pins: installing, updates leaving them alone, moving them in either direction, releasing them with --head, commits upstream doesn't have, and malformed or conflicting flags.
  • test/shell.d/plugin-add-test.sh now points at an empty local catalog so its GitHub-URL guard cases never reach the network.
  • ./test/all: the plugin, menu and CLI tests pass. Six shell test files fail in my environment (bar-icon-geometry, config, locate, runtime-smoke, snapper, unowned-system-paths), and all six fail the same way on an unmodified quattro checkout.
  • Checked by hand against the live catalog: dizziee.cline-model-usage installed at its verified snapshot f63086268b23 while upstream HEAD is f7b8b2989c2b.

Notes

  • The fallback that fetches a snapshot by id when it isn't in the cloned history isn't covered by a test: a local clone copies every object, so the path can't be reached offline.
  • If a pinned commit isn't in the default branch's history, a later update --head can't fast-forward and reports it as local changes; reinstalling works around it.
  • This touches the same update flow as Validate plugin updates before changing installed checkouts #10711; whichever lands second will need a rebase.

🤖 Generated with Claude Code

omarchy plugin add now looks the repo up in the plugin marketplace catalog
and checks out the verified snapshot before validating it. Unlisted,
unverified, and unreachable cases install upstream HEAD with a warning, and
--head installs HEAD on purpose. A verified snapshot that upstream no longer
has refuses the install instead of falling back to HEAD. omarchy plugin
update keeps each plugin on the track it was added with; existing checkouts
keep following HEAD.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@DanielThyselius

Copy link
Copy Markdown

I maintain a plugin that is listed and snapshot-verified on the marketplace, and I ran into exactly the gap this PR closes.

The listing page shows every visitor:

This Omarchy command clones the repository's current HEAD. It is not bound to the marketplace's verified snapshot and may install a different commit. Check the installed commit before enabling it.

That notice is accurate and there is nothing a plugin author can do about it. omarchy plugin add runs a bare git clone with no ref, and omarchy plugin update fast-forwards to origin/HEAD, so the published install command can never match the commit the marketplace actually reviewed. The marketplace says the same thing from its side: VERIFICATION.md states that commit-bound installation "remains unavailable until Omarchy provides an exact-SHA installation and update interface."

So the verification pipeline is complete end to end except for the last hop, and this PR is the last hop.

One detail in support of the omarchy.channel design, in case the PR gets slimmed down in review: a naive pin breaks silently. git merge --ff-only FETCH_HEAD against a detached HEAD succeeds, so a pinned checkout would quietly advance to HEAD on the next omarchy plugin update unless update is made pin-aware. I tested that. Keeping the update side is not optional.

Happy to test this against a real listed plugin if that is useful.

omarchy plugin add --commit <sha> installs exactly that commit and records
the plugin as pinned. Plain updates leave a pinned plugin where it is;
omarchy plugin update <id> --commit <sha> moves the pin in either direction,
and --head releases it to follow upstream HEAD.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@StavWasPlayZ

Copy link
Copy Markdown
Author

Added explicit commit pinning as suggested by @bypasser-passing in #11236 (comment) (f830da7)

pin_to_commit runs with set -e suspended, so a failed git reset was ignored:
validation passed on the old tree and the plugin was recorded and reported as
pinned to a commit it was never moved to.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@StavWasPlayZ

StavWasPlayZ commented Sep 19, 2026 •

Copy link
Copy Markdown
Author

Updating here: Emailing DHH directly regarding this matter, I received confirmation that these concerns will be addressed in a future update:

We have a big update coming for the plugin system. Ryan is on it 👍. Meanwhile, you can always have your local agent review updates/installs first.

Keeping this PR up just in case it becomes relevant, though I'd be more than fine closing it.

@omarchybot omarchybot added the enhancement New feature or request label Sep 27, 2026
@jandrusk

Copy link
Copy Markdown

Strong improvement — installing the marketplace-verified snapshot by default is the right default, and the warnings are clear that verification ≠ a security audit.

One product nit while you're rebasing (conflicts with quattro): on unreachable marketplace, this still installs unverified HEAD (with a warning). Fail-closed / require --head (or an explicit --yes) when the catalog can't be fetched would match the "refusing vanished verified commits" stance elsewhere. Not a blocker if intentional.

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

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants