How freeze-shas.txt Secures Claude Plugins Through SHA Pinning

The freeze-shas.txt file prevents automatic updates to specific plugins by instructing the CI workflow to skip SHA bumps for listed names, locking them to vetted commits and blocking potentially vulnerable upstream changes.

The anthropics/claude-plugins-community repository uses a simple text file to enforce critical security boundaries. The freeze-shas.txt mechanism acts as a gatekeeper that prevents the automated bump workflow from modifying the source.sha field for designated marketplace plugins, ensuring they remain pinned to known-good commits until explicitly cleared.

What Is freeze-shas.txt?

freeze-shas.txt is a plain-text list located at .github/freeze-shas.txt that contains the names of marketplace plugins requiring static source commit SHAs. Each line in this file represents a plugin whose current source.sha value in the manifest must remain unchanged during automated maintenance workflows.

This lightweight security control allows maintainers to explicitly lock plugins that require additional scrutiny or contain sensitive integrations, preventing the CI system from automatically drifting toward newer, potentially unvetted upstream commits.

How the Freeze Mechanism Works

The security enforcement operates across three coordinated components: the workflow definition, the bump script, and the freeze list itself.

CI Workflow Integration

The .github/workflows/bump-plugin-shas.yml workflow reads .github/freeze-shas.txt and passes its contents as input to the bump action. When the workflow triggers—either on a schedule or via pull request—it invokes .github/actions/bump-plugin-shas/scripts/bump.sh with the freeze list loaded into memory.

Bump Script Logic

Inside scripts/bump.sh, the automation checks each marketplace plugin against the freeze list before attempting any SHA modification. When a match is found, the script logs the specific message:

frozen at current pin (freeze-shas); not bumping

This behavior appears at line 198 of the script, where the logic explicitly bypasses the bump routine for frozen entries. The freeze takes absolute precedence over other configuration flags; as noted in the source code comment at line 235, "freeze-shas takes precedence" over inputs like releases-only, meaning a frozen plugin will never update even if a newer release exists.

Validation and Error Handling

If a plugin name appears in freeze-shas.txt but does not correspond to a currently tracked marketplace entry, the workflow emits a warning message:

freeze-shas: 'frozn-plugin' matches no external

This validation at line 199 prevents silent failures caused by typos or outdated entries, ensuring the freeze list remains accurate and maintainable.

Security Benefits of SHA Freezing

Locking plugin SHAs provides targeted protection against supply chain risks and breaking changes.

Preventing Accidental Upgrades By freezing the source.sha, maintainers block the automated workflow from pulling in upstream changes that might introduce security vulnerabilities or API incompatibilities before proper review.

Override Authority The freeze mechanism supersedes all other bump criteria. Even if a plugin publishes a new release and the workflow runs with releases-only enabled, a frozen entry remains locked at its current commit.

Granular Control The text-based list allows for rapid security responses—maintainers can freeze a compromised plugin immediately by adding one line to .github/freeze-shas.txt without modifying workflow code or action logic.

Managing the Freeze List

Adding or removing plugins from the security freeze requires simple text edits followed by standard git operations.

Freezing a Plugin

To lock a plugin at its current commit, append its name to the freeze file:

# Add the plugin to the security freeze

echo "my-secure-plugin" >> .github/freeze-shas.txt

# Commit the change

git add .github/freeze-shas.txt
git commit -m "Freeze my-secure-plugin at current SHA for security review"

Once committed and pushed, the next CI run will detect the entry and skip any SHA bump attempts for my-secure-plugin, logging the freeze status in the workflow output.

Unfreezing a Plugin

After resolving security concerns or merging necessary upstream fixes, remove the entry to resume normal updates:

# Remove the plugin from the freeze list

sed -i '/my-secure-plugin/d' .github/freeze-shas.txt

git commit -am "Unfreeze my-secure-plugin – allow normal bumping"

The subsequent workflow execution will resume automatic SHA bumping for the plugin according to the standard release tracking rules documented in .github/actions/bump-plugin-shas/README.md.

Summary

• File Location: .github/freeze-shas.txt stores the list of plugins requiring static SHAs.
• Enforcement: The bump-plugin-shas.yml workflow passes the list to scripts/bump.sh, which checks each plugin at line 198.
• Behavior: Frozen plugins log "frozen at current pin (freeze-shas)" and skip all SHA updates.
• Precedence: The freeze overrides releases-only and other bump criteria as noted at line 235.
• Safety: Invalid entries trigger warnings to prevent silent configuration errors.

Frequently Asked Questions

What happens if I add a non-existent plugin to freeze-shas.txt?

The CI workflow emits a warning message identifying the orphaned entry, such as freeze-shas: 'frozn-plugin' matches no external, allowing you to correct typos without the error going unnoticed.

Does freeze-shas.txt override the releases-only setting?

Yes. According to the source code comment at line 235, "freeze-shas takes precedence"—a frozen plugin will never bump to a newer release even if the workflow specifies releases-only: true.

How do I verify that a plugin is currently frozen?

Check the CI logs for the bump-plugin-shas workflow. Frozen plugins display the message frozen at current pin (freeze-shas); not bumping instead of the standard bump statistics.

Can I manually update a frozen plugin's SHA?

Yes. The freeze only blocks the automated scripts/bump.sh logic. You can manually edit the plugin's manifest to change the source.sha value and commit the change directly; the freeze list does not restrict direct repository modifications.

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