How to Specify a Plugin Source Using a Direct Git Repository URL in Claude Plugins

You specify a plugin source using a direct Git repository URL by defining a source object with either the url or repo field in the plugin's marketplace.json entry, which the validate-plugins GitHub Action validates before installation.

The anthropics/claude-plugins-community repository uses a centralized registry system where each plugin's origin is declared through structured metadata. When you want to distribute a plugin directly from a Git repository rather than bundling it locally, you must configure the source object in the top-level .claude-plugin/marketplace.json file to tell Claude exactly where to fetch the code.

Understanding the Source Object Structure

Every plugin entry in marketplace.json contains a source object that acts as a discriminator-based configuration. This object requires a source field that indicates the type—either "url" for full HTTPS URLs or "repo" for shorthand GitHub references—followed by the corresponding value field.

The CLI treats any plugin with a populated source object as an external source, triggering a clone operation during installation rather than looking for bundled code.

Two Methods to Specify Git Repository Sources

Using the source.url Field (Full HTTPS URL)

For explicit control over the repository location, use the source.url field. According to the validation rules in .github/actions/validate-plugins/README.md (line 146, rule I4), this URL must match the regex ^https://[A-Za-z0-9./_-]+$ to ensure security.

{
  "name": "my-git-plugin",
  "source": {
    "source": "url",
    "url": "https://github.com/example/my-plugin"
  },
  "version": "0.2.1"
}

Using the source.repo Field (Owner/Repo Shorthand)

For public GitHub repositories, you can use the compact owner/repo notation via the source.repo field. This format reduces duplication when hosting on GitHub and is validated by the same validate-plugins action.

{
  "name": "my-git-plugin",
  "source": {
    "source": "repo",
    "repo": "example/my-plugin"
  },
  "version": "0.2.1"
}

Both formats appear throughout the registry—examine entries around lines 16-17, 26-27, and 36-37 in .claude-plugin/marketplace.json to see live implementations.

Validation and Security Constraints

The .github/actions/validate-plugins/action.yml workflow runs on every pull request to enforce source integrity. The validation logic documented in .github/actions/validate-plugins/README.md ensures:

• URL format compliance: Only HTTPS URLs matching the character class [A-Za-z0-9./_-] pass validation
• Discriminator presence: The source field must explicitly declare "url" or "repo"
• Mutual exclusivity: You should provide either url or repo, not both, to avoid ambiguity

If validation fails, the GitHub Action blocks the PR, preventing malformed entries from reaching the marketplace.

Complete Configuration Examples

Basic HTTPS Source

{
  "name": "example-plugin",
  "description": "Demo plugin that uses a direct Git repo as its source.",
  "source": {
    "source": "url",
    "url": "https://github.com/anthropics/claude-plugins-community"
  },
  "version": "1.0.0",
  "author": "Your Name"
}

Repository Shorthand with Commit Pinning

For reproducible builds, pin a specific commit using the optional sha field:

{
  "name": "my-git-plugin",
  "description": "A plugin sourced directly from a Git repo.",
  "source": {
    "source": "url",
    "url": "https://github.com/example/my-plugin",
    "sha": "a1b2c3d4e5f67890123456789abcdef12345678"
  },
  "version": "0.2.1",
  "author": "Alice"
}

Reference Implementation

The tres-finance-plugin demonstrates production usage in tres-finance-plugin/.claude-plugin/plugin.json, which contains:

{
  "source": {
    "source": "url",
    "url": "https://github.com/anthropics/tres-finance-plugin"
  }
}

How the Installation Process Works

When a user installs a plugin with a direct Git repository URL, the Claude CLI performs the following operations:

1. Clone: Creates a temporary directory and clones the specified repository
2. Discovery: Locates the plugin.json and manifest.json files within the cloned structure
3. Registration: Executes the plugin's configuration and registers it for use within Claude

If you omit the source.path field, the CLI treats the repository root as the plugin directory. For sub-directory deployments, specify the path relative to the repository root.

Summary

• Edit .claude-plugin/marketplace.json to specify a plugin source using a direct Git repository URL
• Choose between source.url (full HTTPS) or source.repo (owner/repo shorthand) based on your hosting setup
• Include the discriminator field "source": "url" or "source": "repo" to pass validation
• Validate URL format against the regex ^https://[A-Za-z0-9./_-]+$ before submitting
• Pin specific commits using the optional sha field for version stability
• Submit to the validate-plugins GitHub Action for automated validation before merging

Frequently Asked Questions

What file do I edit to specify a plugin source?

You edit the .claude-plugin/marketplace.json file at the repository root. This central registry file contains an array of plugin objects, each with a source field that defines where Claude should fetch the plugin code.

Can I use private Git repositories?

The current validation rules in .github/actions/validate-plugins/README.md only validate URL format against public HTTPS patterns. Private repositories would require authentication mechanisms not covered by the standard source.url or source.repo fields in the current implementation.

How does Claude validate the URL format?

Claude uses the validate-plugins GitHub Action defined in .github/actions/validate-plugins/action.yml. This action applies the regex ^https://[A-Za-z0-9./_-]+$ (rule I4, line 146) to ensure the URL uses HTTPS and contains only alphanumeric characters, dots, slashes, hyphens, and underscores.

Can I pin a specific commit or branch?

Yes. Add the sha field to your source object with the full commit hash. When present, Claude checks out that specific commit after cloning rather than the default branch, ensuring reproducible plugin versions across installations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}