How Plugin Validation CI/CD Works in the Claude Plugins Community Repository

The Claude Plugins Community repository uses a multi-layered GitHub Actions workflow defined in validate-plugins.yml to automatically verify every plugin change through static invariant checks, owner liveness verification, external manifest resolution, and CLI validation before any code reaches the main branch.

The anthropics/claude-plugins-community repository maintains a curated marketplace of Claude plugins that requires rigorous automated testing to ensure security, consistency, and functionality. The plugin validation CI/CD pipeline implements a defense-in-depth strategy that tests everything from file naming conventions to external repository reachability. Understanding this validation architecture helps contributors debug failures and allows other projects to implement similar quality gates for their own plugin marketplaces.

Workflow Triggers and Entry Points

The validation pipeline is orchestrated by .github/workflows/validate-plugins.yml, which executes under three specific conditions.

Automatic triggers activate when pull requests modify files under .claude-plugin/** or the validation actions themselves, and on every push to the main branch. The workflow also supports manual execution via workflow_dispatch, which the automated bump-plugin-shas job uses to validate newly generated branches.

The checkout step retrieves full repository history with fetch-depth: 0 to enable accurate change detection against the base ref, ensuring the pipeline can distinguish between existing and modified marketplace entries.

Pre-Validation Test Suite

Before invoking the core composite action, the workflow runs several specialized test scripts to verify helper utilities and repository hygiene.

Static invariant tests execute test-invariants.sh to catch inexpensive errors like malformed file names and basic JSON schema violations early in the pipeline.

Bump-plugin-shas validation runs two critical checks: test-bump.sh verifies that the automated SHA bumping utility correctly skips frozen entries, while test-bump-manifest.sh ensures synthetic marketplace manifests generate correctly from inline fields.

Owner liveness verification executes test-sweep.sh to confirm that every plugin's listed GitHub owner still maintains a reachable profile, preventing the marketplace from accumulating stale contact information.

External manifest resolution runs test-external-manifest.sh to validate that external plugin references—whether URLs or git submodules—resolve correctly without network timeouts.

Pin-check validation executes test-pin-check.sh to verify that pinned SHA references match established golden vectors, eliminating accidental "floating" references that could introduce untested code.

Core Validation Action Architecture

The pipeline delegates to the composite action defined in .github/actions/validate-plugins/action.yml, which implements the primary validation logic through six sequential Bash scripts.

Change Detection

The 00-detect-changes.sh script builds a comprehensive list of modified marketplace entries, external plugins, and in-repo folders by comparing the current HEAD against the base reference. This targeted approach allows subsequent steps to focus validation resources only on changed components while still enforcing global repository policies.

Policy Invariant Enforcement

The 11-validate-invariants.sh script enforces eleven specific policy rules (I1-I11), including:

• Alphabetical sorting requirements for marketplace entries
• Duplicate name detection to prevent plugin collisions
• Safe-path validation to block directory traversal attempts
• SHA-exempt handling for entries that legitimately omit version pinning

CLI-Based Validation Stages

The action proceeds through three validation scripts that invoke the official @anthropic-ai/claude-code CLI:

1. 20-validate-cli-marketplace.sh runs claude plugin validate against the assembled marketplace.json to verify schema compliance and structural integrity.

2. 30-validate-cli-external.sh (skippable) clones each changed external repository and subjects it to the same CLI validation, respecting the allowed-hosts input parameter to restrict network access to approved domains.

3. 40-validate-cli-local.sh (skippable) validates plugins stored directly within the repository's file structure rather than referenced externally.

Auxiliary File Parsing

The 41-validate-aux-files.sh script parses supplementary JSON files used by in-repo plugins to ensure configuration files remain syntactically valid and conform to expected schemas.

Reporting and Status

The final 90-report.sh aggregates all validation results into a markdown summary posted to the GitHub check run, explicitly setting the status to pass or fail based on cumulative results.

Fail-Fast Mechanisms and Reliability

The validation action installs the Claude CLI with robust retry logic spanning lines 33-91 of action.yml to mitigate transient network failures during native binary downloads. All shell scripts execute with set -euo pipefail, ensuring that any unhandled error immediately terminates the job and prevents merging of invalid content.

Integration with Automated Workflows

The bump-plugin-shas.yml workflow automatically updates pinned SHA references for external plugins and dispatches validate-plugins.yml for each generated bump branch. This integration ensures that newly pinned SHAs pass the full validation suite before the automated bump merges into main, as implemented in bump-plugin-shas.yml lines 113-115.

Using the Validation Action in External Repositories

You can reuse the validation logic in your own Claude plugin projects by referencing the composite action:

# .github/workflows/validate-plugins.yml

name: Validate Claude Plugins
on:
  pull_request:
    paths:
      - '.claude-plugin/**'
      - '.github/actions/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anthropics/claude-plugins-community/.github/actions/validate-plugins@v1
        with:
          marketplace-path: .claude-plugin/marketplace.json
          skip-local-folders: "true"
          scope-errors-to-changed: "true"

Local CLI Validation for Debugging

To reproduce validation failures locally without running the full CI pipeline:

# Install the official Claude CLI globally

npm i -g @anthropic-ai/claude-code@latest

# Validate your marketplace configuration

claude plugin validate .claude-plugin/marketplace.json

Summary

• The validation workflow triggers on plugin-related pull requests, main branch pushes, and manual dispatch events via .github/workflows/validate-plugins.yml.
• Pre-validation tests verify bump utilities, owner profiles, external reachability, and SHA pinning before expensive CLI validation begins.
• The core composite action enforces eleven policy invariants (I1-I11) through scripts/11-validate-invariants.sh, covering naming, sorting, and security constraints.
• Three distinct CLI validation scripts handle the marketplace JSON, external repositories, and local in-repo plugins respectively.
• The bump-plugin-shas workflow automatically validates version bumps by dispatching the validation workflow against generated branches.
• Fail-fast shell settings and CLI retry logic ensure reliable, deterministic validation results that block merging on any error.

Frequently Asked Questions

What triggers the plugin validation workflow?

The workflow triggers when pull requests modify files under .claude-plugin/** or the validation actions themselves, on every push to the main branch, and via manual workflow_dispatch events. This ensures that both human contributions and automated SHA updates undergo identical quality checks before merging.

How does the pipeline handle external plugins referenced by URL?

The 30-validate-cli-external.sh script clones each changed external repository temporarily and runs claude plugin validate against the downloaded code. This step respects an allowed-hosts input parameter that restricts which domains the action can fetch from, preventing supply-chain attacks from untrusted sources.

What are the I1-I11 invariants checked during validation?

The 11-validate-invariants.sh script enforces repository policies including alphabetical ordering of entries, duplicate name detection, safe path validation to prevent directory traversal, and proper handling of SHA-exempt entries. These static checks run before any CLI validation to catch policy violations quickly without expensive network operations.

Can I use this validation system in my own Claude plugin repository?

Yes, the composite action in .github/actions/validate-plugins/ is designed for reuse. Reference it directly from the anthropics/claude-plugins-community repository using the @v1 tag, configuring inputs like marketplace-path and skip-local-folders to match your project structure. The action requires fetch-depth: 0 in the checkout step to enable change detection against base references.

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