How freeze-shas.txt Freezes Plugin Versions and Pins Plugins in Claude Plugins Community

The freeze-shas.txt file in .github/freeze-shas.txt creates a blocklist that prevents the Bump Plugin SHAs workflow from updating specific plugins, forcing them to remain at their current Git SHA regardless of upstream changes.

The anthropics/claude-plugins-community repository manages a curated marketplace of Claude plugins. When upstream repositories change, an automated workflow typically proposes updates to keep plugins current. However, some plugins may break at newer commits or require manual intervention before upgrading. The freeze-shas.txt mechanism provides version pinning to handle these exceptions gracefully.

What freeze-shas.txt Does

freeze-shas.txt acts as a hold list for marketplace entries that should not receive automatic SHA bumps. When the Bump Plugin SHAs workflow runs, it reads this file and passes the contents to the bump-plugin-shas action via the freeze-shas input parameter.

According to the source in .github/actions/bump-plugin-shas/scripts/bump.sh (lines 198-199), any plugin appearing in this list is skipped entirely during the bump process with the recorded reason: "frozen at current pin (freeze-shas)".

This prevents the workflow from repeatedly opening failing pull requests for plugins known to be broken at their repository's HEAD commit.

File Format and Location

The manifest lives at .github/freeze-shas.txt and follows a simple line-based format:

• One marketplace entry name per line (the "name" value from .claude-plugin/marketplace.json)
• Lines starting with # are treated as comments and ignored
• Blank lines are skipped
• Names must match the regex pattern [a-z0-9-]{2,64}

# Example .github/freeze-shas.txt

# Plugins temporarily held due to upstream issues

my-dangerous-plugin
another-unstable-plugin
legacy-compat-layer

How the Freeze Mechanism Works

The workflow integration spans three components:

1. Workflow loader (.github/workflows/bump-plugin-shas.yml, step Load freeze list) — reads the file and converts valid lines to a space-separated list
2. Action input (.github/actions/bump-plugin-shas/action.yml) — accepts the list via the freeze-shas parameter
3. Bump script (.github/actions/bump-plugin-shas/scripts/bump.sh) — checks each plugin against the list before processing

The script enforces highest precedence for freeze-shas over other bump-related inputs like sha-exempt or tracking-config (noted at line 235 in bump.sh).

Visibility and Monitoring

After loading, the workflow logs a notice reporting how many entries are frozen (line 74). The script also emits ::warning:: annotations for invalid entries or names that don't match any pinned marketplace entry (lines 139-141) — though in these cases, the pin is not protected.

How to Use freeze-shas.txt to Pin Plugins

Adding a Plugin to the Freeze List

1. Identify the exact marketplace entry name from .claude-plugin/marketplace.json

2. Append it to .github/freeze-shas.txt:

echo "broken-plugin-name" >> .github/freeze-shas.txt
git add .github/freeze-shas.txt
git commit -m "Freeze broken-plugin-name at current SHA"
git push

3. The next scheduled workflow run will respect the freeze and skip bumping that plugin

Removing a Plugin (Unfreezing)

Once upstream issues are resolved, restore normal bumping:

# Remove the plugin from the freeze list

sed -i '/broken-plugin-name/d' .github/freeze-shas.txt

git commit -m "Unfreeze broken-plugin-name"
git push

The subsequent workflow run will resume tracking HEAD for that plugin.

Manual Workflow Invocation

You can also pass a custom freeze list directly when triggering the action:

- uses: ./.github/actions/bump-plugin-shas
  with:
    marketplace-path: .claude-plugin/marketplace.json
    freeze-shas: "plugin-a plugin-b"
    max-bumps: "20"
    pr-mode: per-entry

Key Behaviors and Limitations

Behavior	Implementation Detail
Precedence	freeze-shas overrides all other bump controls
Validation	Invalid names or unmatched entries trigger warnings but no protection
Persistence	Freeze survives until explicitly removed from the file
Granularity	Operates on marketplace entry names, not repository URLs

The freeze-shas mechanism intentionally provides no automatic expiration — this prevents accidental re-enabling of broken plugins through automation gaps.

Summary

• freeze-shas.txt at .github/freeze-shas.txt lists marketplace plugin names to exclude from automatic SHA bumps
• The Bump Plugin SHAs workflow passes this list to the bump-plugin-shas action, which skips matching plugins with reason "frozen at current pin (freeze-shas)"
• Add plugin names to freeze them; delete names to resume normal bumping
• Invalid or non-existent names generate warnings but receive no protection

Frequently Asked Questions

What happens if I freeze a plugin name that doesn't exist?

The workflow emits a ::warning:: annotation but does not fail. The invalid entry is ignored and no protection is applied. Check that your name matches the "name" field in .claude-plugin/marketplace.json exactly.

Can I use freeze-shas.txt with other bump control features?

Yes, but freeze-shas takes precedence over sha-exempt and tracking-config as documented in .github/actions/bump-plugin-shas/scripts/bump.sh line 235. A frozen plugin will never be bumped regardless of other configuration.

How do I know if my freeze is working?

The workflow logs a notice showing how many entries are frozen after loading the file. You can also check the action outputs for skip reasons — frozen plugins show "frozen at current pin (freeze-shas)".

Does freezing protect against manual SHA updates?

No. freeze-shas.txt only affects the automated Bump Plugin SHAs workflow. Direct edits to .claude-plugin/marketplace.json or other manual changes bypass the freeze mechanism entirely.

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