[DOCS] Plugin marketplace docs omit deleted-`ref` behavior when `sha` is pinned

Status Fixed / completed

Maintainer reply None cached

Activity 3 comments · opened May 14, 2026 · closed Jun 23, 2026

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/plugin-marketplaces

Section/Topic

Plugin sources, especially Marketplace sources vs plugin sources, the git-based source examples, and Plugin installation failures

Current Documentation

The docs currently say:

Plugin source — where to fetch an individual plugin listed in the marketplace. Set in the source field of each plugin entry inside marketplace.json. Supports both ref (branch/tag) and sha (exact commit).

You can pin to a specific branch, tag, or commit: ``json { "name": "github-plugin", "source": { "source": "github", "repo": "owner/plugin-repo", "ref": "v2.0.0", "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" } } ``

Plugin installation failures Verify plugin source URLs are accessible Check that plugin directories contain required files For GitHub sources, ensure repositories are public or you have access Test plugin sources manually by cloning/downloading

What's Wrong or Missing?

A. The docs show `ref` and `sha` together, but never explain the resolution rules

The page documents that a plugin source can include both ref and sha, but it does not say what Claude Code does when both fields are present. That leaves marketplace authors guessing whether sha is the true install pin, whether ref must continue to exist upstream forever, or whether both values must resolve successfully.

B. The troubleshooting section does not cover the deleted-`ref` + pinned-`sha` case

The v2.1.141 changelog fixed claude plugin install for plugins whose marketplace ref no longer exists upstream when a sha is also pinned. The current troubleshooting guidance is still generic, so users and marketplace maintainers have no documentation telling them that this combination is supported or how to reason about it when a branch/tag is removed after publication.

Suggested Improvement

Add an explicit note near the git-based plugin source schemas and examples. For example:

When both ref and sha are set on a plugin source, Claude Code installs the exact commit pinned by sha. As of v2.1.141, installation can still succeed if the upstream branch or tag named by ref has been deleted, as long as the pinned commit is still available from the repository.

Also add a troubleshooting bullet under Plugin installation failures, for example:

If a plugin source pins both ref and sha, a deleted upstream branch or tag should not block installation on Claude Code v2.1.141 or later. If installation still fails, verify that the pinned sha still exists and that the repository is accessible.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/plugin-marketplaces | 239-245, 277-295, 969-978 | The page documents combined ref/sha plugin sources and generic install-failure troubleshooting, but not the deleted-ref behavior fixed in v2.1.141 |

Total scope: 1 page affected

View original on GitHub ↗

3 Comments

coygeek · 4 months ago

Verified against the latest docs; this still appears unresolved.

coygeek · 3 months ago

Issue #58873 Verification

Title: [DOCS] Plugin marketplace docs omit deleted-ref behavior when sha is pinned
Issue Date: Unknown
Verification Date: 2026-06-23
Status: RESOLVED

---

Issue Summary

This issue reports that the plugin-marketplaces documentation page documents both ref and sha on git-based plugin sources but never explains the resolution rules when both are set together. It also notes that the v2.1.141 changelog fixed claude plugin install for plugins whose marketplace ref no longer exists upstream when a sha is also pinned, but the current troubleshooting section does not mention this combination or how to reason about deleted refs.

---

Verification Results

Claim 1: The docs show `ref` and `sha` together, but never explain the resolution rules

Status: RESOLVED

At https://code.claude.com/docs/en/plugin-marketplaces, line 251 explicitly documents the resolution rule for the combined ref + sha case:

The git-based source types below are github, url, and git-subdir. When both ref and sha are set on any of them, the sha is the effective pin. Claude Code fetches and checks out the pinned commit directly. On most git hosts, including GitHub, GitLab, and Bitbucket, this means installation succeeds even if the branch or tag named by ref has since been deleted upstream, as long as the commit is still reachable from the repository. Some servers, such as AWS CodeCommit, do not support fetching commits by SHA. On those servers the ref must still exist and the pinned commit must be reachable from it.

This statement directly addresses Claim 1: it states that sha is the effective pin, explains how Claude Code resolves the install (fetches and checks out the pinned commit directly), and qualifies which git hosts support that behavior.

Verdict: Resolved. The exact rule requested by the reporter is now documented.

Claim 2: The troubleshooting section does not cover the deleted-`ref` + pinned-`sha` case

Status: RESOLVED

At https://code.claude.com/docs/en/plugin-marketplaces, line 1009 inside the Plugin installation failures troubleshooting section explicitly covers the deleted-ref + pinned-sha case:

If the source pins both ref and sha, a deleted upstream branch or tag does not block installation on most git hosts, including GitHub, GitLab, and Bitbucket. On servers that do not support fetching commits by SHA, such as AWS CodeCommit, the ref must still exist and the pinned commit must be reachable from it. If the install still fails, confirm the pinned commit still exists in the repository

This troubleshooting bullet (lines 999-1009) is positioned exactly where the issue asked for it (under Plugin installation failures), and it covers both the supported-host behavior and the AWS CodeCommit exception.

Verdict: Resolved. The exact troubleshooting guidance requested by the reporter is now present.

---

Current State

| Claim | Status |
|-------|--------|
| 1. Resolution rules for combined ref + sha are documented | RESOLVED |
| 2. Troubleshooting covers deleted-ref + pinned-sha case | RESOLVED |

---

Suggested Fix

N/A - issue has been resolved.

---

References

URL: https://code.claude.com/docs/en/plugin-marketplaces
Lines 242-251: Marketplace sources vs plugin sources note followed by the resolution rule for combined ref + sha plugin sources
Lines 282-294: GitHub plugin source example with both ref and sha set
Lines 999-1009: Plugin installation failures troubleshooting section, including the new bullet that documents deleted-ref + pinned-sha behavior on supported hosts and the AWS CodeCommit exception

---

Conclusion & Recommendation

Primary Concern: The plugin-marketplaces page showed combined ref/sha plugin sources and listed generic troubleshooting bullets but never explained what happens when both are set or what to do when the upstream ref is deleted.

Resolution Status: RESOLVED

Recommendation: CLOSE

The page now contains explicit language in both the schema explanation (line 251) and the troubleshooting section (line 1009) that documents the combined ref + sha resolution rule and the deleted-ref behavior the issue asked for, covering both supported hosts and the AWS CodeCommit exception.

github-actions[bot] · 1 month ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.