claude-code - 💡(How to fix) Fix [DOCS] Plugin marketplace docs omit deleted-`ref` behavior when `sha` is pinned [1 participants]

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:

{
  "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:

Total scope: 1 page affected