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

> Understand the freeze-shas feature in the bump-plugin-shas GitHub Action. Learn how to temporarily lock plugin SHA pins and prevent nightly updates while maintaining visibility.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: deep-dive
- Published: 2026-08-30

---

**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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.

```bash

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

```bash

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

```yaml

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

```text
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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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.