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

> Learn how freeze-shas.txt pins Claude plugin versions. Prevent unwanted updates by creating a blocklist to maintain specific Git SHAs for your plugins.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-02

---

**The [`freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/freeze-shas.txt) file in [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/freeze-shas.txt) mechanism provides version pinning to handle these exceptions gracefully.

## What freeze-shas.txt Does

[`freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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}`

```text

# 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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)

2. Append it to [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt):

```bash
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:

```bash

# 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:

```yaml
- 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`](https://github.com/anthropics/claude-plugins-community/blob/main/freeze-shas.txt) at [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/freeze-shas.txt) only affects the automated **Bump Plugin SHAs** workflow. Direct edits to [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) or other manual changes bypass the freeze mechanism entirely.