claude-code - 💡(How to fix) Fix claude plugin install for source: github plugins requires SSH, undocumented; HTTPS fallback missing [1 comments, 2 participants]

Summary

Installing a plugin whose marketplace entry uses source: github fails on any machine without a working GitHub SSH key. claude plugin install clones via [email protected]:<repo>.git and does not fall back to HTTPS on SSH auth failure. The SSH requirement is not documented anywhere in the plugins or plugin-marketplaces pages, and contradicts the documented behavior of the source: git type, which explicitly supports both HTTPS and SSH URLs.

Environment

• Claude Code (latest as of 2026-04-12)
• macOS 15 / Darwin 25.4.0
• ~/.ssh/ without a GitHub-registered key
• ssh -T [email protected] → Permission denied (publickey)
• https://github.com/... clones work normally via git/gh

Reproduction

1. On a machine without a GitHub SSH key, add a marketplace whose plugins declare source: github. Example: the 37signals marketplace at basecamp/claude-plugins, whose basecamp plugin uses "source": { "source": "github", "repo": "basecamp/basecamp-cli" }.
2. Run claude plugin install basecamp@37signals.
3. Observe the clone failure below.

Actual output

Installing plugin "basecamp@37signals"...
✘ Failed to install plugin "basecamp@37signals": Failed to clone repository: Cloning into '/Users/vid/.claude/plugins/cache/temp_github_...'...
[email protected]: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
  Plugin install failed: exit status 1

Expected

One of:

1. Plugin installer falls back to HTTPS (https://github.com/<repo>.git) when SSH auth fails for a source: github plugin. Matches the behavior of git clone with a standard insteadOf config, and matches what third-party installers already do as a workaround.
2. Plugin installer honors git config --global url."...".insteadOf rewrites, if it does not already. (I have not verified whether the current installer runs through the standard git config; if it does, this may already work — please confirm in docs.)
3. If SSH is intentionally required for source: github, document it prominently in:
   • https://code.claude.com/docs/en/plugins
   • https://code.claude.com/docs/en/plugin-marketplaces
   • The troubleshooting section (currently no entry for Permission denied (publickey) during plugin install).

What the docs currently say

code.claude.com/docs/en/plugin-marketplaces, source: github section:

repo — Required. GitHub repository in owner/repo format ref — Optional. Git branch or tag (defaults to repository default branch) sha — Optional. Full 40-character git commit SHA to pin to an exact version

No mention of SSH, HTTPS, git transport, or GitHub-side auth prerequisites.

By contrast, the same page's source: git section explicitly documents HTTPS and SSH as equivalent:

url — string — Required. Full git repository URL (https:// or git@). The .git suffix is optional... The url field also accepts a GitHub shorthand (owner/repo) or SSH URLs ([email protected]:owner/repo.git).

A user reading the docs would reasonably assume source: github is the convenient shorthand for the GitHub case and behaves like source: git with an HTTPS URL — since HTTPS is the no-auth default for git clones. In practice, it only works if SSH is set up.

Workaround (for users reading this issue)

git config --global url."https://github.com/<owner>/".insteadOf [email protected]:<owner>/
claude plugin install <plugin>@<marketplace>

Scoped to the plugin's org, rewrites SSH clones to HTTPS. This confirms that the clone itself works fine over HTTPS — only the hardcoded transport choice in the installer is blocking.

Impact

• Any plugin using source: github is uninstallable for users without a registered GitHub SSH key. Fresh developer machines, CI runners, sandboxes, and anyone who uses HTTPS + PAT / gh auth — a common and increasingly default setup — all hit this.
• Third-party installers (e.g. basecamp-cli) are papering over this in their own setup flows for the marketplace clone but cannot reach into claude plugin install to do the same for the plugin clone.
• The failure mode is a raw git SSH error with no hint about what Claude Code expected or how to fix it.

Suggested fix

Either (A) make the installer fall back to HTTPS on SSH auth failure for source: github — ideally trying HTTPS first since GitHub's public convention is HTTPS-default for anonymous clones — or (B) document the SSH requirement and add a troubleshooting entry. (A) is preferred because it preserves the documented simplicity of source: github as "just give me owner/repo".