GitHub Actions for Plugin Validation in the Claude Plugins Community Repository

The Claude Plugins Community repository orchestrates plugin validation through a "Validate Plugins" workflow that combines built-in actions like actions/checkout@v4 and actions/setup-node@v4 with four custom composite actions—validate-plugins, bump-plugin-shas, owner-liveness-sweep, and scan-plugins—to enforce schema compliance, repository invariants, and security checks.

The anthropics/claude-plugins-community repository maintains a rigorous continuous integration pipeline to ensure every Claude plugin meets quality and security standards before merging. The GitHub Actions plugin validation system leverages both marketplace actions and custom composite actions defined within .github/actions/ to create a comprehensive verification pipeline that runs on every pull request touching plugin files.

The Validate Plugins Workflow

The validation process centers on .github/workflows/validate-plugins.yml, which defines the orchestration layer for the entire pipeline. This workflow triggers automatically when pull requests modify files within .claude-plugin/** or .github/actions/**, on every push to the main branch, and via manual workflow_dispatch events for ad-hoc validation runs.

The workflow performs change detection against the base ref by fetching full repository history using actions/checkout@v4 with fetch-depth: 0, enabling accurate identification of which plugins require validation in a given pull request.

Environment Setup Actions

Before validation begins, the workflow prepares the execution environment using official GitHub Actions:

• actions/checkout@v4 – Retrieves the complete git history with fetch-depth: 0 to support diff-based change detection against the base branch.
• actions/setup-node@v4 – Provisions Node.js 20, required for installing the @anthropic-ai/claude-code CLI package.
• Inline Bash steps – Install auxiliary utilities including jq and the Claude CLI using robust retry logic to ensure binary availability before validation commences.

Core Validation Logic

The validate-plugins Composite Action

The heart of the validation pipeline resides in .github/actions/validate-plugins/action.yml, a composite action that orchestrates the primary verification steps. This action executes claude plugin validate against the assembled marketplace.json file to verify schema correctness, then applies a suite of repository-specific checks.

The composite action accepts several inputs:

• marketplace-path – Location of the plugin registry file
• skip-local-folders – Boolean to exclude local plugin directories
• fail-on-warnings – Boolean to determine whether warnings should fail the build

Invariant Testing Scripts

Located within .github/actions/validate-plugins/scripts/, helper scripts enforce repository-wide policies:

• 11-validate-invariants.sh – Implements custom invariants (I1–I11) covering requirements such as alphabetical ordering, unique plugin names, and mandatory metadata fields.
• test-external-manifest.sh – Validates resolution and integrity of externally hosted plugin manifests.
• test-invariants.sh – Performs static analysis checks across the plugin registry.

These scripts generate markdown reports summarizing validation results, which the workflow publishes as build artifacts.

Security and Integrity Checks

Beyond schema validation, the workflow invokes specialized composite actions to enforce security policies:

SHA Verification with bump-plugin-shas

The .github/actions/bump-plugin-shas/action.yml composite action ensures immutable references by verifying that plugin SHA commits remain up-to-date and have not been unintentionally modified. This prevents supply chain attacks where plugin code could change without review.

Owner Liveness Verification

The .github/actions/owner-liveness-sweep/action.yml action confirms that plugin authors maintain active GitHub accounts. This check prevents the accumulation of abandoned plugins by verifying that owners are still reachable and their accounts remain unarchived.

Dependency Scanning

The .github/actions/scan-plugins/action.yml action audits plugins for hard-coded dependency pins, generating a "golden vector" report that identifies potential security vulnerabilities or outdated dependencies requiring human review.

Complete Workflow Configuration

The following YAML demonstrates the complete orchestration defined in .github/workflows/validate-plugins.yml:

name: Validate Plugins
on:
  pull_request:
    paths:
      - '.claude-plugin/**'
      - '.github/actions/**'
  push:
    branches: [main]
    paths:
      - '.claude-plugin/**'
      - '.github/actions/**'
  workflow_dispatch:

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

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      # Core validation composite action

      - uses: ./.github/actions/validate-plugins
        with:
          marketplace-path: .claude-plugin/marketplace.json
          skip-local-folders: "true"
          fail-on-warnings: "false"
      
      # Security and integrity checks

      - uses: ./.github/actions/bump-plugin-shas
        if: github.event_name == 'pull_request'
      
      - uses: ./.github/actions/owner-liveness-sweep
        if: github.event_name == 'schedule'
      
      - uses: ./.github/actions/scan-plugins
        if: github.ref == 'refs/heads/main'

Summary

• The validation pipeline uses .github/workflows/validate-plugins.yml to orchestrate checks on every PR and push to main.
• Built-in actions provide the foundation: actions/checkout@v4 retrieves full history, while actions/setup-node@v4 prepares the Node.js 20 environment required for the Claude CLI.
• Custom composite actions handle specialized logic: validate-plugins performs schema checks, bump-plugin-shas ensures immutable references, owner-liveness-sweep verifies account activity, and scan-plugins audits dependencies.
• Invariant scripts located in .github/actions/validate-plugins/scripts/ enforce repository policies I1–I11 through concrete shell implementations.
• The workflow generates markdown reports detailing validation results, enabling maintainers to review schema violations, security warnings, and policy breaches before merging contributions.

Frequently Asked Questions

How does the workflow detect which plugins changed in a pull request?

The workflow uses actions/checkout@v4 configured with fetch-depth: 0 to retrieve complete git history, enabling the validation scripts to perform git diff operations against the base ref. This allows the validate-plugins composite action to identify specific plugin directories modified in the PR and run targeted validation rather than scanning the entire registry.

What are the invariants I1–I11 referenced in the validation scripts?

The invariants I1–I11 represent a codified set of repository policies enforced by .github/actions/validate-plugins/scripts/11-validate-invariants.sh. These rules ensure plugins follow naming conventions, maintain alphabetical ordering in the marketplace registry, include required metadata fields, and satisfy structural requirements specific to the Claude plugin ecosystem.

Can I run the validation workflow manually without creating a pull request?

Yes, the workflow defines workflow_dispatch as a trigger event, allowing maintainers to initiate validation manually from the GitHub Actions tab. When triggered manually, the workflow runs the full validation suite against the current branch state, generating the standard markdown report without requiring a pull request context.

Why does the workflow require Node.js 20 specifically?

The workflow installs the @anthropic-ai/claude-code CLI package, which requires a modern Node.js runtime. The actions/setup-node@v4 step explicitly provisions Node.js 20 to ensure compatibility with the Claude CLI's dependencies and to support the JavaScript-based validation utilities bundled within the custom composite actions.

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