# How freeze-shas.txt Secures Claude Plugins Through SHA Pinning > Learn how freeze-shas.txt secures Claude plugins by SHA pinning, preventing vulnerable upstream changes and locking plugins to vetted commits. - Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community) - Tags: security - Published: 2026-09-04 --- **The [`freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/freeze-shas.txt) is a plain-text list located at [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/bump-plugin-shas.yml) workflow reads [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/bump-plugin-shas/scripts/bump.sh) with the freeze list loaded into memory. ### Bump Script Logic Inside [`scripts/bump.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/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: ```text 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`](https://github.com/anthropics/claude-plugins-community/blob/main/freeze-shas.txt) but does not correspond to a currently tracked marketplace entry, the workflow emits a warning message: ```text 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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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: ```bash # 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: ```bash # 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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/bump-plugin-shas/README.md). ## Summary - **File Location**: [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt) stores the list of plugins requiring static SHAs. - **Enforcement**: The [`bump-plugin-shas.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/bump-plugin-shas.yml) workflow passes the list to [`scripts/bump.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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.