Claude Plugins Community validate-plugins.yml GitHub Actions Workflow Explained

The validate-plugins.yml GitHub Actions workflow serves as the automated gatekeeper for the Claude Plugins Community marketplace, executing seven distinct validation suites on every pull request to ensure plugin metadata integrity, SHA-pinning correctness, and owner liveness before any changes reach the main branch.

The anthropics/claude-plugins-community repository maintains a curated marketplace of community-built Claude plugins defined in .claude-plugin/marketplace.json. According to the source code in .github/workflows/validate-plugins.yml, the validate-plugins.yml GitHub Actions workflow functions as the continuous integration backbone, automatically triggering whenever contributors modify plugin definitions or validation logic to prevent malformed or insecure plugins from entering the ecosystem.

Workflow Triggers and Execution Context

The workflow activates on three specific events defined in .github/workflows/validate-plugins.yml:

• Pull requests that modify files under .claude-plugin/** (plugin definitions)
• Pull requests that modify .github/actions/** (the validation logic itself)
• Direct pushes to the main branch

This trigger configuration ensures that any change affecting the marketplace or its validation infrastructure undergoes mandatory automated scrutiny before merging. If any validation step fails, the workflow marks the pull request as failing and blocks merges until all invariants pass.

The Seven Core Validation Suites

The workflow orchestrates seven discrete test scripts, each targeting a specific quality or security invariant.

1. Static Invariant Tests

The workflow executes test-invariants.sh from the .github/actions/validate-plugins/ directory to verify that all plugins obey static metadata rules. This script validates required fields, naming conventions, and schema compliance in plugin definitions. Catching malformed metadata at this stage prevents broken plugins from reaching the public marketplace.

2. Version Bump Logic Verification

Using test-bump.sh located in .github/actions/bump-plugin-shas/, the workflow validates the "skip" and "freeze" logic for version bumps. This ensures that SHA-pinning for releases behaves deterministically, allowing maintainers to control exactly which plugin versions appear in the marketplace without unexpected automatic updates.

3. Manifest Synthesis Tests

The test-bump-manifest.sh script validates the generated marketplace manifest after a bump operation. This step confirms that the public marketplace.json file remains internally consistent and properly formatted when the automation synthesizes new plugin versions, guaranteeing that the final artifact matches the expected schema.

4. Owner Liveness Sweep

The workflow runs test-sweep.sh from .github/actions/owner-liveness-sweep/ to verify that plugin owners remain active. This prevents abandoned plugins from lingering in the marketplace, ensuring that every listed plugin has a maintainer who can respond to security issues or API changes.

5. External Manifest Resolution

Executing test-external-manifest.sh from .github/actions/validate-plugins/, the workflow checks that external plugin manifests can be fetched and parsed correctly. This guarantees reliable cross-repository plugin discovery, ensuring that plugins hosted outside the main repository remain accessible and valid.

6. Pin-Check Golden Vector Tests

The test-pin-check.sh script located in .github/actions/scan-plugins/ compares current pin-check results against known good "golden" vectors. This regression detection mechanism ensures that the static pin-check logic remains stable and does not accidentally flag valid plugins as insecure or miss compromised dependencies.

7. Dog-Food Validation

Finally, the workflow invokes the repository's own ./.github/actions/validate-plugins composite action against the live .claude-plugin/marketplace.json file using parameters --marketplace-path, --skip-local-folders true, and --scope-errors-to-changed true. This self-testing step ensures the validation action works correctly on real production data and enforces that external consumers must pin a specific SHA when referencing the action (as documented in the action's README).

Local Development and Testing

Contributors can run the same validation suites locally before opening pull requests to reduce CI turnaround time.

To execute the static invariant tests manually:

cd claude-plugins-community
bash .github/actions/validate-plugins/test-invariants.sh

To run the full validation action locally (mirroring the final CI step):

./.github/actions/validate-plugins/action.yml \
  --marketplace-path .claude-plugin/marketplace.json \
  --skip-local-folders true \
  --scope-errors-to-changed true

For a complete Docker-based simulation of the CI environment, use the act tool:

# Install act (https://github.com/nektos/act)

brew install act

# Run the validate job locally

act -j validate

These local execution paths allow developers to catch failures early without waiting for GitHub Actions runners.

Implementation Architecture and Key Files

The validation pipeline relies on several critical components:

• .github/workflows/validate-plugins.yml - The orchestration layer that defines trigger conditions and step sequences
• .github/actions/validate-plugins/action.yml - The reusable composite action entrypoint implementing core validation logic
• .github/actions/validate-plugins/lib/common.sh - Shared utility functions used across test scripts
• test-invariants.sh - Schema and metadata validation for plugin definitions
• test-bump.sh - SHA-pinning and version bump logic verification (in bump-plugin-shas action)
• test-sweep.sh - Owner account activity verification (in owner-liveness-sweep action)
• test-external-manifest.sh - Cross-repository manifest resolution testing
• test-pin-check.sh - Static analysis regression testing against golden vectors (in scan-plugins action)

This modular architecture separates concerns between workflow orchestration, reusable action logic, and specific test implementations, making the system maintainable as the marketplace scales.

Summary

• The validate-plugins.yml workflow automatically gates every change to the Claude Plugins Community marketplace through seven specialized test suites
• Validation covers static metadata integrity, version bump logic, manifest synthesis, owner liveness, external resolution capabilities, regression testing, and self-validation
• Execution triggers include PRs affecting .claude-plugin/ or .github/actions/ and all pushes to main
• Local execution via shell scripts or the act tool enables pre-commit validation
• The workflow enforces SHA-pinning requirements for security and prevents abandoned plugins from persisting in the marketplace

Frequently Asked Questions

When does the validate-plugins.yml workflow trigger?

The workflow activates on pull requests that modify files in .claude-plugin/** (plugin definitions) or .github/actions/** (validation logic), as well as on every push to the main branch. This ensures both plugin changes and tooling updates undergo mandatory validation according to the workflow definition in .github/workflows/validate-plugins.yml.

How does the workflow prevent broken plugins from entering the marketplace?

The workflow runs test-invariants.sh to enforce static metadata rules and schema compliance. If a plugin definition lacks required fields or violates naming conventions, the test fails and blocks the pull request from merging until the metadata is corrected, catching malformed entries before they reach the public marketplace.json.

What is the purpose of the "dog-food" validation step?

The dog-food step invokes the repository's own validate-plugins action against the live marketplace.json file with flags like --scope-errors-to-changed. This ensures the validation logic works correctly on real production data and verifies that the action can be safely consumed by external repositories that pin specific SHA versions.

Can I run these validations locally before submitting a PR?

Yes. Contributors can execute individual test scripts like bash .github/actions/validate-plugins/test-invariants.sh or use the act tool (act -j validate) to simulate the full GitHub Actions environment locally. This allows catching errors early without waiting for remote CI execution.

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