Stages of the Validate-Plugins CI Validation Pipeline in Claude Plugins Community

The validate-plugins CI validation pipeline consists of two logical groups—pre-action static checks and the core composite action—that enforce SHA-freeze logic, security invariants, and official Claude CLI schema validation before any plugin change merges.

The validate-plugins workflow in the anthropics/claude-plugins-community repository is a multi-stage CI pipeline that guarantees every Claude plugin stays in a consistent, secure state. Understanding the different stages of the validate-plugins CI validation pipeline helps contributors debug failures and ensures that only properly formatted, secure plugins reach the marketplace.

Pipeline Architecture Overview

The pipeline is divided into two distinct logical groups orchestrated by .github/workflows/validate-plugins.yml. The Pre-action checks run a suite of fast shell scripts that validate repository-wide invariants. The Core Validate-Plugins action is a composite action defined in .github/actions/validate-plugins/action.yml that performs deep validation on changed entries. Together, these stages ensure both structural correctness and repository-specific security policies.

Pre-Action Checks Group

These stages execute before the main composite action begins, catching fundamental errors quickly.

Static Invariant Tests

The first stage runs bash .github/actions/validate-plugins/test-invariants.sh as defined at line 31 of the workflow file. This script performs rapid validation of basic repository invariants without requiring the full Claude CLI setup. It serves as an early filter to prevent obviously malformed changes from consuming additional CI resources.

Bump-Plugin-SHAs Validation

The pipeline validates the SHA-freeze automation through two consecutive test suites:

• Skip/freeze tests (lines 34-36): Executes test-bump.sh to verify that the bump-plugin-shas logic correctly handles skip and freeze scenarios.
• Manifest-synthesis tests (lines 37-38): Runs test-bump-manifest.sh to ensure the automatically generated marketplace manifest remains well-formed after SHA updates.

Ownership and External Resolution Checks

Two stages verify organizational health and external dependencies:

• Owner-liveness-sweep (lines 40-42): Runs test-sweep.sh to flag stale or missing plugin owners.
• External manifest resolution (lines 44-45): Executes test-external-manifest.sh to confirm that external plugin manifests can be fetched and parsed correctly.

Golden Vector Pin Checks

At lines 46-48, the pipeline runs test-pin-check.sh from the scan-plugins action. This golden-vector test ensures that plugin version pins remain stable and have not drifted from expected values, preventing unauthorized version changes.

Core Validate-Plugins Action Stages

Following the pre-action checks, the workflow invokes the composite action at .github/actions/validate-plugins/action.yml, which sequentially executes seven validation stages.

Change Detection (00-detect-changes.sh)

The 00-detect-changes.sh script (lines 22-55) performs the initial analysis by diffing the PR against the base reference. It builds a temporary marketplace.json and produces changes.json, which catalogs:

• Changed marketplace entries
• External sources requiring validation
• In-repo plugin folders with modifications

This artifact determines the scope for all subsequent validation stages.

Policy Invariant Enforcement (11-validate-invariants.sh)

The 11-validate-invariants.sh script (lines 8-90) enforces repository-specific policy invariants labeled I1 through I11. These rules include:

• I1: Alphabetical sorting of plugins (case-insensitive)
• I2: Duplicate plugin name detection
• I3-I11: Description length limits, URL safety validation, and SHA format rules

The script supports a scope-errors-to-changed mode that demotes errors for unchanged entries to warnings, allowing focused review of PR-specific changes.

# From 11-validate-invariants.sh - I1 and I2 implementation

# I1 – plugins[] must be alphabetically sorted (case‑insensitive)

sorted="$(jq -r '[.plugins[].name | ascii_downcase] | . == (.|sort)' -- "$MP")"
[[ "$sorted" == "true" ]] || flag "I1" "plugins[] is not alpha‑sorted by name"

# I2 – no duplicate plugin names

dups="$(jq -r '[.plugins[].name] | group_by(.) | map(select(length>1) | .[0]) | .[]' -- "$MP")"
[[ -z "$dups" ]] || flag "I2" "duplicate plugin names: $(tr '\n' ' ' <<<"$dups")"

CLI Marketplace Validation (20-validate-cli-marketplace.sh)

This stage invokes the official claude plugin validate command against the assembled marketplace.json (referenced in action.yml lines 16-21). It performs schema-level validation to ensure the marketplace file conforms to the Claude plugin specification.

External Plugin Validation (30-validate-cli-external.sh)

For each changed external source identified in the detection phase, the 30-validate-cli-external.sh script (action.yml lines 22-29):

1. Clones the external repository
2. Runs claude plugin validate within the cloned directory
3. Enforces a per-plugin timeout to prevent hanging on unresponsive external sources

Local Plugin Validation (40-validate-cli-local.sh)

The 40-validate-cli-local.sh script (action.yml lines 31-37) executes claude plugin validate on every changed plugin directory inside the repository. This ensures that in-repo plugins meet the same standards as external submissions.

Auxiliary File Parsing (41-validate-aux-files.sh)

At action.yml lines 38-41, the 41-validate-aux-files.sh script parses JSON outputs from previous validation stages. This normalization step makes structured data available for the final reporting phase.

Report Generation (90-report.sh)

The final stage executes 90-report.sh (action.yml lines 43-47), which aggregates results from all preceding stages into a comprehensive markdown report. It sets the composite action's result output to either pass or fail, determining the overall CI check status.

Implementation and Orchestration

The composite action first sets up the execution environment by installing Node 20, jq, and the Claude CLI. The sequential execution order ensures that cheap checks run before expensive ones, and that the changes.json artifact is available for scoped validation. According to the source code in anthropics/claude-plugins-community, the entire pipeline executes on ubuntu-latest runners with fetch-depth: 0 to enable proper git diffing.

Summary

• The validate-plugins CI validation pipeline is organized into pre-action checks and a core composite action with seven sequential stages.
• Pre-action checks verify SHA-freeze logic, owner liveness, external manifest resolution, and golden-vector stability through fast shell scripts.
• The core action detects changes via 00-detect-changes.sh, enforces policy invariants I1-I11, and runs official CLI validation against marketplace, external, and local plugins.
• Final reporting aggregates all stage outputs into a markdown summary with a definitive pass or fail outcome.

Frequently Asked Questions

What triggers the validate-plugins CI validation pipeline?

The pipeline triggers on pull requests and pushes to the repository, as configured in .github/workflows/validate-plugins.yml. The workflow uses fetch-depth: 0 during checkout to ensure complete git history for accurate change detection in the 00-detect-changes.sh stage.

What are the I1-I11 invariants enforced by the pipeline?

These are repository-specific policy rules implemented in 11-validate-invariants.sh covering alphabetical sorting (I1), duplicate name detection (I2), description length constraints, URL safety validation, and SHA format compliance. The script can demote invariant violations for unchanged entries to warnings when scope-errors-to-changed is enabled.

How does the pipeline validate external versus local plugins?

External plugins are processed by 30-validate-cli-external.sh, which clones each repository and runs claude plugin validate with strict timeouts. Local plugins use 40-validate-cli-local.sh to validate only the changed directories within the repository, avoiding unnecessary processing of unchanged code.

Where can I view the detailed validation results?

The 90-report.sh script generates a comprehensive markdown report that aggregates outputs from all validation stages. This report is attached to the workflow run, and the composite action sets a result output to pass or fail based on the aggregate validation state.

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