What Is `freeze-shas.txt`? Controlling Plugin SHA Updates in the Claude Plugins Community Repository

The freeze-shas.txt file acts as a version-controlled manifest that prevents specific plugin marketplace entries from receiving automated SHA updates when the upstream repository is known to be broken at HEAD.

In the anthropics/claude-plugins-community repository, the automated bump-plugin-shas workflow periodically scans external plugin repositories for new commits and creates pull requests to update the source.sha pins in marketplace.json. The freeze-shas.txt file provides a critical safety valve that temporarily suspends these automatic bumps for problematic plugins, preventing a cascade of failing validation checks and noisy pull requests.

How the Automated SHA Bump Workflow Operates

The repository maintains plugin references using commit SHA pins to ensure reproducible builds. The workflow defined in .github/workflows/bump-plugin-shas.yml runs on a schedule to detect when plugin repositories have advanced beyond their currently pinned commits.

When the workflow identifies a newer HEAD commit for a plugin, it validates the plugin manifests against the new SHA. If validation succeeds, the workflow generates a per-entry pull request proposing the bump. However, when upstream repositories contain breaking changes—such as malformed manifests or incompatible new fields—continuous bump attempts generate perpetual CI failures.

The Purpose of freeze-shas.txt

The freeze-shas.txt file located at .github/freeze-shas.txt solves this by listing marketplace entry names (slugs) that must retain their current source.sha values regardless of upstream changes. According to the file's header comments (lines 1–8), this represents a point-in-time snapshot of entries that currently fail validation at upstream HEAD.

Preventing Broken Plugin Updates

Entries listed in freeze-shas.txt receive special treatment during the bump process:

• Skip Logic: The workflow scans frozen plugins but skips the actual bump step, logging "frozen at current pin (freeze-shas)" instead of creating a PR
• CI Stability: Prevents continuous generation of failing pull requests for plugins with known upstream issues
• Temporary Holds: Functions as a temporary measure; removing the slug from the file immediately restores normal automated bumping once upstream issues resolve

File Format and Constraints

The file uses a minimal structure optimized for shell parsing:

• One slug per line: Each line contains a single plugin marketplace entry name matching the pattern [a-z0-9-]{2,64}
• Comment support: Lines beginning with # are treated as comments and ignored
• Validation: The workflow emits warnings if a listed name does not correspond to an existing marketplace entry or violates the allowed character pattern

Implementation Details

The freeze mechanism involves three components working together: the workflow loader, the GitHub Action input, and the bump script enforcement.

Loading the Freeze List in the Workflow

The workflow loads and sanitizes the freeze list during the initial setup phase (lines 58–70 of .github/workflows/bump-plugin-shas.yml):

- name: Load freeze list
  id: freeze
  run: |
    set -euo pipefail
    f=.github/freeze-shas.txt
    if [[ -f "$f" ]]; then
      list="$({ grep -vE '^[[:space:]]*(#|$)' "$f" || true; } \
               | tr '\n' ' ' | sed -E 's/[[:space:]]+/ /g; s/^ //; s/ $//')"
    else
      list=""
    fi
    echo "list=$list" >> "$GITHUB_OUTPUT"
    echo "::notice::freeze-shas: $(wc -w <<<"$list") entr(y/ies) held at current pin"

This script strips comments and whitespace, converting the file into a space-separated list consumed by downstream actions.

Passing Frozen Entries to the Bump Action

The workflow passes the sanitized list to the reusable bump action via the freeze-shas input parameter:

- uses: ./.github/actions/bump-plugin-shas
  id: bump
  with:
    marketplace-path: .claude-plugin/marketplace.json
    max-bumps: ${{ inputs.max_bumps || '30' }}
    freeze-shas: ${{ steps.freeze.outputs.list }}
    only: ${{ inputs.plugin }}
    pr-mode: per-entry
    claude-cli-version: latest

As documented in .github/actions/bump-plugin-shas/README.md, the freeze-shas input accepts a space-separated list of entry names to exclude from bumping.

Enforcing Freezes in the Bump Script

The actual enforcement occurs inside .github/actions/bump-plugin-shas/scripts/bump.sh, which checks each candidate plugin against the freeze list before attempting an update:

# Inside .github/actions/bump-plugin-shas/scripts/bump.sh

if [[ " $freeze_shas " == *" $name "* ]]; then
  log "$name: frozen at current pin (freeze-shas); not bumping"
  skipped=$(jq -c --arg n "$name" \
                --arg r "frozen at current pin (freeze-shas)" \
                '. + [{name:$n, reason:$r}]' <<<"$skipped")
  continue
fi

This pattern match ensures that exact name matches are skipped entirely, while the plugin still appears in the skip report for audit purposes.

Managing the Freeze List

When upstream repositories fix validation errors, repository maintainers should remove the corresponding slug from .github/freeze-shas.txt to resume normal automated updates. Conversely, when a newly discovered broken plugin requires immediate exclusion, adding its slug to the file and committing the change immediately protects the CI pipeline from subsequent failed bump attempts.

Summary

• freeze-shas.txt serves as a version-controlled blocklist that prevents automated SHA bumps for specific plugins known to fail validation at HEAD.
• Location: The file resides at .github/freeze-shas.txt and uses a simple one-slug-per-line format with hash-prefixed comments.
• Workflow Integration: The bump-plugin-shas workflow loads this file, passes it to the bump action, and enforces freezes during the validation phase.
• Temporary Safety: Frozen status is reversible; removing a plugin name from the file restores normal automated bumping behavior immediately.
• Validation: The workflow warns against invalid entry names or slugs not present in the marketplace configuration.

Frequently Asked Questions

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

The workflow validates entries against the marketplace configuration and the allowed name pattern [a-z0-9-]{2,64}. If a listed name does not match any pinned marketplace entry or violates the naming convention, the workflow emits a warning in the GitHub Actions logs to alert maintainers of the configuration error, but continues processing valid entries.

Does freezing a plugin prevent the workflow from scanning it entirely?

No. Frozen plugins are still scanned during the detection phase to check for new commits. However, the workflow skips the actual bump step and pull request creation for these entries, logging that they are "frozen at current pin (freeze-shas)" instead of generating updates.

How do I unfreeze a plugin once the upstream issue is resolved?

Simply remove the plugin's slug from .github/freeze-shas.txt and commit the change. The next scheduled workflow run will treat the plugin normally, creating a pull request to bump the SHA if a newer valid commit exists upstream.

Can I use wildcards or regular expressions in freeze-shas.txt?

No. The file only supports exact string matches for individual plugin slugs. The parsing logic in the workflow uses simple string containment checks ([[ " $freeze_shas " == *" $name "* ]]) rather than pattern matching, requiring precise entry names for the freeze mechanism to function correctly.

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