How External Consumers Must SHA-Pin the validate-plugins Action

The anthropics/claude-plugins-community repository enforces SHA-pinning through mandatory documentation in the action README and automated verification via the CI pin-check script.

The validate-plugins composite action in the Claude Plugins Community repository provides validation logic for plugin marketplaces. To guarantee immutable execution environments, the repository requires that any external workflow referencing this action must use a fixed Git SHA rather than mutable branch references. This policy protects downstream consumers from unexpected breaking changes while maintaining strict validation contracts.

Documentation Requirements in the Action README

The official policy requiring SHA-pinning is documented in .github/actions/validate-plugins/README.md. This file explicitly states that external consumers must reference the action by commit SHA to ensure version stability.

According to the README: "External consumers MUST pin a SHA — see the action README."

This documentation serves as the primary contract between the maintainers and downstream users, establishing that branch references such as @main or @v1 are prohibited for external repositories.

CI Enforcement Through Automated Pin-Checks

Beyond documentation, the repository programmatically enforces this requirement through the Validate Plugins workflow defined in .github/workflows/validate-plugins.yml.

The Pin-Check Step

Lines 46-52 of the workflow file contain a dedicated verification step that executes the pin-check script:

# Validate Plugins workflow (lines 46-52)

- name: scan-plugins pin-check golden vectors
  run: bash .github/actions/scan-plugins/test-pin-check.sh

This step runs on every pull request, scanning both the local repository and any dependent repositories for usages of the validate-plugins action.

How the Script Validates Pinning

The test-pin-check.sh script inspects workflow files for action references. If it detects that a consumer repository references anthropics/claude-plugins-community/.github/actions/validate-plugins using a branch name (such as @main) instead of a 40-character SHA commit hash, the script exits with an error code. This failure blocks the CI job and prevents the pull request from merging.

The sha-exempt Input and Action-Level Policy

The validate-plugins action includes an input parameter named sha-exempt defined in .github/actions/validate-plugins/action.yml (lines 26-34). This parameter allows specific plugins within the marketplace to omit the source.sha field in their configuration.

However, the sha-exempt input does not waive the requirement for the action itself to be SHA-pinned. The action-level SHA-pinning rule exists independently of plugin-level SHA exemptions. Even if a consuming repository sets sha-exempt: true when calling the action, the CI pin-check will still require that the action reference in the workflow file points to a specific commit SHA.

Correct Implementation for Downstream Repositories

External workflows must reference the action using the full 40-character commit SHA. Below is the correct implementation pattern for a downstream repository's workflow file:

# .github/workflows/validate.yml in a downstream repository

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude plugins validation
        uses: anthropics/claude-plugins-community/.github/actions/validate-plugins@a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0   # ← pinned SHA

        with:
          marketplace-path: .claude-plugin/marketplace.json

Using a branch reference will trigger a CI failure:

uses: anthropics/claude-plugins-community/.github/actions/validate-plugins@main   # ❌ will cause CI failure

Summary

• Documentation mandate: The README.md in .github/actions/validate-plugins/ explicitly requires external consumers to SHA-pin the action.
• Automated enforcement: The test-pin-check.sh script runs in .github/workflows/validate-plugins.yml (lines 46-52) and fails CI if it detects non-pinned references.
• Separation of concerns: The sha-exempt input governs plugin metadata requirements, not the action reference format.
• Immutable execution: SHA-pinning guarantees that validation logic remains constant across workflow runs, preventing supply chain attacks and breaking changes.

Frequently Asked Questions

What happens if my workflow uses a branch reference instead of a SHA?

The CI check will fail. The test-pin-check.sh script scans for branch references like @main or @v1 and exits with an error, blocking your pull request from merging until you update the reference to a specific commit SHA.

Does setting sha-exempt to true allow me to use a branch reference for the action?

No. The sha-exempt input (defined in .github/actions/validate-plugins/action.yml lines 26-34) only permits individual marketplace plugins to omit SHA values in their metadata. It does not affect how you reference the validate-plugins action itself in your workflow file.

Where is the automated pin-check logic implemented?

The verification logic resides in .github/actions/scan-plugins/test-pin-check.sh. This script is invoked by the Validate Plugins workflow in .github/workflows/validate-plugins.yml at lines 46-52 during every CI run.

Why does the repository require SHA-pinning for external consumers?

Pinning to a specific commit SHA ensures immutable validation behavior. Without this requirement, a downstream repository could automatically pull in new validation logic that changes rule enforcement, potentially breaking existing plugins or allowing unsafe submissions to pass undetected.

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