What Is the freeze-shas Feature in the bump-plugin-shas GitHub Action?

The freeze-shas input allows repository owners to temporarily lock specific plugin SHA pins, preventing the nightly bump process from updating them while maintaining full visibility in workflow logs.

The bump-plugin-shas action in the anthropics/claude-plugins-community repository automates the process of updating SHA pins for external plugins listed in the marketplace. The freeze-shas feature provides a targeted safety mechanism that pauses automated updates for specific plugins without removing their version pins entirely, making it ideal for security freezes or temporary holds while awaiting upstream fixes.

How freeze-shas Works in the bump.sh Script

The implementation of freeze-shas centers in .github/actions/bump-plugin-shas/scripts/bump.sh, where the action processes input validation and skip logic.

Input Parsing and Validation

When the workflow receives the freeze-shas input, the script stores it in the FREEZE_SHAS environment variable at lines 33-38. Before applying any freezes, the script validates each plugin name against the pattern ^[a-z0-9][a-z0-9-]{1,63}$ at lines 33-44.

Invalid names trigger a warning rather than a fatal error. This design choice ensures that a typo does not silently leave a plugin unfrozen; instead, maintainers receive immediate feedback while the workflow continues processing other plugins.

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

FREEZE_SHAS=" ${INPUT_FREEZE_SHAS} "

# Validation loop ensures plugin names match allowed pattern

for name in ${INPUT_FREEZE_SHAS}; do
  if [[ ! "${name}" =~ ^[a-z0-9][a-z0-9-]{1,63}$ ]]; then
    echo "::warning::Invalid plugin name in freeze-shas: ${name}"
  fi
done

Skip Logic During Plugin Discovery

During the discovery loop at lines 94-100, the script checks each plugin against the FREEZE_SHAS list. When a match occurs, the script logs the skip operation, adds a record to the skipped JSON array with the reason "frozen at current pin (freeze-shas)", and immediately continues to the next entry. No cloning, validation, or SHA comparison occurs for frozen plugins.

This early exit strategy reduces unnecessary Git operations and network traffic while ensuring the frozen state appears explicitly in workflow summaries.

# Freeze check implementation (lines 94-100)

if [[ "${FREEZE_SHAS}" =~ " ${plugin_name} " ]]; then
  echo "${plugin_name}: frozen at current pin (freeze-shas); not bumping"
  skipped+=("{\"name\":\"${plugin_name}\",\"reason\":\"frozen at current pin (freeze-shas)\"}")
  continue
fi

freeze-shas vs. sha-exempt: Key Differences

The anthropics/claude-plugins-community repository provides distinct mechanisms for handling plugin updates, and understanding the boundaries between them prevents configuration errors.

• freeze-shas: Maintains the existing source.sha value and skips all update attempts. The pin remains intact in the registry, but the automated process ignores it temporarily. Use this for security holds or when awaiting critical upstream patches.

• sha-exempt: Removes the SHA pin entirely, effectively excluding the plugin from the bumping process without tracking its version. This is documented in .github/actions/bump-plugin-shas/README.md as a distinct input with different semantic intent.

Implementing freeze-shas in Your Workflow

Configure the freeze-shas input in your workflow YAML to protect specific plugins during automated runs. The input accepts a space-separated or newline-separated list of plugin names as defined in action.yml.

# .github/workflows/bump-plugin-shas.yml

name: Bump Plugin SHAs
on:
  schedule:
    - cron: '23 7 * * *'   # nightly run

  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  bump:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-plugins-community/.github/actions/bump-plugin-shas@v1.2.3
        with:
          marketplace-path: .claude-plugin/marketplace.json
          max-bumps: 20
          # Freeze specific plugins at their current SHA

          freeze-shas: |
            my-secure-plugin
            legacy-api

During execution, frozen plugins generate explicit log entries:

my-secure-plugin: frozen at current pin (freeze-shas); not bumping
legacy-api: frozen at current pin (freeze-shas); not bumping

These entries also populate the skipped JSON array, which the action renders in the GitHub workflow summary under the Skipped section.

Summary

• The freeze-shas feature in the bump-plugin-shas action temporarily locks plugin SHA pins while preserving them in the registry.
• Input validation in bump.sh warns about malformed plugin names without failing the entire workflow.
• Frozen plugins are skipped early in the discovery loop at lines 94-100, preventing unnecessary Git operations.
• The feature differs fundamentally from sha-exempt, which removes pins entirely rather than freezing them.
• Frozen states appear explicitly in workflow logs and JSON summaries for audit visibility.

Frequently Asked Questions

What happens if I misspell a plugin name in freeze-shas?

The validation logic in bump.sh checks each name against the pattern ^[a-z0-9][a-z0-9-]{1,63}$. If a name fails validation, the script outputs a ::warning:: annotation in the GitHub UI but continues processing other plugins. This prevents typos from creating silent failures where a plugin remains unprotected, though the misspelled entry itself will not freeze any plugin.

How is freeze-shas different from removing a plugin from the marketplace?

Using freeze-shas keeps the plugin entry and its current source.sha intact in the marketplace registry; the automation simply skips update attempts. Removing a plugin from the marketplace eliminates the entry entirely, which stops both updates and any future references to that plugin. Additionally, sha-exempt removes the pin without removing the plugin, serving yet another distinct use case.

Can I freeze all plugins at once using a wildcard?

No, the freeze-shas input requires explicit plugin names. The script performs literal string matching padded with spaces (" ${plugin_name} "), so wildcards or pattern matching are not supported. You must list each plugin name individually to enforce the freeze.

Where can I see which plugins were frozen during a workflow run?

Frozen plugins appear in two locations: the GitHub Actions logs show the message "frozen at current pin (freeze-shas); not bumping" for each frozen entry, and the workflow summary page displays them under the Skipped section with the JSON reason field. This dual visibility ensures that security freezes are auditable by repository maintainers without requiring deep log inspection.

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