# What Is the bump-plugin-shas GitHub Action? Purpose and Implementation Guide

> Discover the bump-plugin-shas GitHub Action purpose. This automation detects outdated SHA pins in Git repos, validates commits, and opens pull requests for updates.

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

---

**The bump-plugin-shas GitHub Action is a scheduled automation that daily scans the Claude plugin marketplace, detects outdated SHA pins in external Git repositories, validates new commits, and opens isolated pull requests for each update.**

This workflow solves the operational challenge of maintaining pinned SHA references across external plugins in the `anthropics/claude-plugins-community` repository. Instead of requiring manual updates when upstream plugin repositories advance their `HEAD`, the action automatically proposes validated bumps through discrete, reviewable pull requests.

## How the bump-plugin-shas Action Works

The workflow operates as a **composite action** defined in [`.github/workflows/bump-plugin-shas.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/bump-plugin-shas.yml)【L3-L8】. It consumes the marketplace manifest at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), which contains plugin entries pointing to external Git repositories with specific commit SHAs.

The core logic resides in [`.github/actions/bump-plugin-shas/action.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/bump-plugin-shas/action.yml), which performs three critical functions:

1. **SHA Comparison** – Compares the currently pinned SHA in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) against the latest `HEAD` of the upstream repository.
2. **Validation** – Validates the plugin functionality at the new commit before proposing the change.
3. **Pull Request Creation** – Generates a dedicated branch (`bump/<plugin-name>`) and opens a separate PR for each eligible plugin【L3-L8】.

## Daily Freshness Sweep and SHA Validation

Every night, the scheduled workflow initiates a **freshness sweep** across all external plugin entries. According to the workflow header【L3-L8】, the process specifically targets plugins that reference external Git repositories rather than local paths.

If the upstream `HEAD` has advanced past the pinned SHA, the workflow validates the plugin at the new commit. This validation step ensures that broken or incompatible updates do not reach the main branch. The workflow then creates a **separate pull request per bumped plugin**, allowing maintainers to review each update individually.

## Isolation of Failures Through Branch Strategy

A key design principle of the bump-plugin-shas action is **failure isolation**. Each plugin bump lives in its own branch named `bump/<plugin-name>` with its own dedicated PR【L3-L8】. This architecture ensures that a validation failure in one plugin does not block updates for others, mirroring the behavior of the official `claude-plugins-official` repository.

This per-plugin branching strategy enables granular rollback and targeted review. If a specific upstream commit introduces breaking changes, maintainers can close that individual PR without affecting other pending updates.

## Workflow Dispatch and Validation Triggering

The action uses the default `GITHUB_TOKEN` for authentication, which means commits and PRs are authored by `github-actions[bot]`. However, this creates a specific technical constraint: **PRs opened with the default token do not trigger the `pull_request` event**. Consequently, the required "Validate Plugins" status check does not run automatically on these bot-created PRs.

To circumvent this limitation, the workflow explicitly **dispatches** the [`validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins.yml) workflow on each bump branch after PR creation【L90-L108】. This manual dispatch ensures that validation runs even though the standard event trigger is bypassed, maintaining code quality gates without human intervention.

## Freeze List and Rate Limiting Controls

The action implements two mechanisms to prevent noise and control volume:

**Freeze SHAs List** – The file [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt) contains a list of plugins that are known to be broken at their current `HEAD`【L19-L22】. The workflow loads this list during initialization (step "Load freeze list"【L63-L74】) and excludes those entries from the bump run, preventing endless cycles of failing PRs for problematic upstream repositories.

**Maximum Bump Cap** – The workflow accepts a `max_bumps` input parameter with a default value of **30**【L30-L34】. This cap limits the number of PRs created in a single run, allowing teams to control review volume and prevent notification spam during large upstream synchronization events.

## Targeted and Manual Execution

While the workflow runs on a nightly schedule, it also supports **workflow_dispatch** for manual intervention【L26-L30】. This interface accepts two optional inputs:

- **`max_bumps`** – Override the default 30-PR limit for the current run.
- **`plugin`** – Specify a single plugin name to bump exclusively【L35-L41】.

This targeted bumping capability is essential for urgent security updates or testing specific plugin integrations without triggering a full marketplace sweep.

## How to Use the bump-plugin-shas Action

Trigger the workflow manually using the GitHub CLI to control execution parameters:

```bash

# Bump up to 10 plugins in a single run

gh workflow run bump-plugin-shas.yml \
  -f max_bumps=10

```

For urgent updates or debugging specific plugins, target a single entry:

```bash

# Bump only "my-awesome-plugin"

gh workflow run bump-plugin-shas.yml \
  -f plugin=my-awesome-plugin

```

When invoked, the workflow executes the composite action at `./.github/actions/bump-plugin-shas` (steps 80-86), which performs the SHA comparison and PR creation. It then dispatches validation workflows for each new bump branch (steps 90-119)【L90-L119】.

## Summary

- **The bump-plugin-shas action** automates daily updates of pinned plugin SHAs in the `anthropics/claude-plugins-community` repository.
- **Isolated PRs** per plugin prevent cross-contamination of failures and enable granular review.
- **Manual dispatch validation** works around `GITHUB_TOKEN` limitations by explicitly triggering the validate-plugins workflow on each bump branch.
- **Freeze list** ([`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt)) and **rate limiting** (`max_bumps` parameter) provide operational controls to manage broken plugins and PR volume.
- **Single-plugin targeting** via the `plugin` input allows surgical updates without full marketplace scans.

## Frequently Asked Questions

### Why does the workflow dispatch the validate-plugins action manually?

Because the workflow uses the default `GITHUB_TOKEN` to create pull requests, the resulting PRs are authored by `github-actions[bot]`. GitHub Actions prevents workflows from triggering other workflows via standard events when using the default token to avoid infinite loops. Therefore, the bump-plugin-shas action explicitly dispatches the [`validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins.yml) workflow on each bump branch【L90-L108】 to ensure validation checks run despite the missing `pull_request` trigger.

### What happens if a plugin is broken upstream at HEAD?

The repository maintains a freeze list at [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt)【L19-L22】. Any plugin name listed in this file is excluded from the daily bump run, preventing the workflow from generating failing PRs for known-broken upstream repositories. This list is loaded during the "Load freeze list" step【L63-L74】 and filtered out before SHA comparison begins.

### Can I limit how many plugins get updated in one run?

Yes. The workflow accepts a `max_bumps` input parameter that defaults to 30【L30-L34】. You can override this when triggering the workflow manually via `workflow_dispatch` to create fewer PRs and manage review bandwidth. This cap ensures that a large upstream sync does not overwhelm maintainers with hundreds of simultaneous pull requests.

### How do I update just one specific plugin instead of running a full sweep?

Pass the `plugin` input parameter when triggering the workflow manually【L35-L41】. For example, using the GitHub CLI: `gh workflow run bump-plugin-shas.yml -f plugin=my-awesome-plugin`. This executes the composite action against only that specific entry in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json), creating a single isolated PR for the targeted update.