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

> Learn how to specify a plugin source using a direct Git repository URL in Claude Plugins. Define the source object with url or repo in marketplace.json for validation.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-04

---

**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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md) (line 146, rule I4), this URL must match the regex `^https://[A-Za-z0-9./_-]+$` to ensure security.

```json
{
  "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.

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) to see live implementations.

## Validation and Security Constraints

The [`.github/actions/validate-plugins/action.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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

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

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json), which contains:

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) and [`manifest.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.