# bump-plugin-shas.yml Workflow Explained: Automated SHA Management for Claude Plugins

> Understand the bump-plugin-shas.yml workflow that automates SHA management for Claude plugins. This daily sweep ensures your marketplace stays current by detecting stale pins and validating new commits.

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

---

**The [`bump-plugin-shas.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/bump-plugin-shas.yml) workflow is an automated daily freshness sweep that detects stale plugin SHA pins, validates new upstream commits with `claude plugin validate`, and opens isolated pull requests to keep the `anthropics/claude-plugins-community` marketplace current while respecting frozen entries.**

The [`bump-plugin-shas.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/bump-plugin-shas.yml) workflow ensures that every plugin listed in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) points to the latest validated upstream commit. Running automatically via cron schedule or manual trigger, this automation maintains security and freshness without batching changes into risky monolithic updates.

## Workflow Architecture and Trigger Conditions

The workflow defined in [`.github/workflows/bump-plugin-shas.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/bump-plugin-shas.yml) operates as a stateful orchestration layer that coordinates SHA detection, validation, and pull request creation. It supports two execution modes:

- **Scheduled execution**: Runs daily at **07:23 UTC** (`cron: '23 7 * * *'`)
- **Manual dispatch**: Triggered via `workflow_dispatch` with optional inputs `max_bumps` (default `30`) and `plugin` (specific slug to target)

Concurrency controls prevent overlapping executions through the `bump-plugin-shas` concurrency group, ensuring that simultaneous runs do not create conflicting pull requests or duplicate validation jobs.

## Step-by-Step Execution Flow

### 1. Load the Freeze List

Before scanning for updates, the workflow reads [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt) to build an exclusion set. This plain-text file contains plugin slugs (one per line, `#` for comments) that must remain pinned at their current SHAs regardless of upstream movement. This mechanism prevents endless PR churn for plugins known to be broken at HEAD.

### 2. Detect and Validate Changes

The workflow invokes the reusable action `./.github/actions/bump-plugin-shas`, which performs the core logic:

- Iterates through every entry in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)
- Compares the recorded SHA against the upstream repository's default branch HEAD
- For stale entries not present in the freeze list, executes `claude plugin validate` to ensure the new commit meets quality standards
- Respects the `max_bumps` limit to prevent notification spam and CI backlog

### 3. Create Isolated Pull Requests

Rather than batching updates, the action creates **one pull request per plugin** on branches named `bump/<plugin-name>`. This strategy isolates failures—a validation error in one plugin blocks only its own PR, not the entire sweep. Each commit is signed automatically using the default `GITHUB_TOKEN`, appearing as authored by `github-actions[bot]`.

The pull request title follows the strict pattern:

```text
Bump <plugin-name> SHA from <old-sha> to <new-sha>

```

### 4. Dispatch Validation Workflows

Because branch protection rules require the "Validate Plugins" check to pass before merging, the workflow fans out dispatch events to [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) for each newly created bump branch:

```bash
gh workflow run validate-plugins.yml --ref "$branch"

```

This ensures the required status check runs against the PR head, satisfying merge requirements without manual intervention.

### 5. Respect Execution Caps

The `max_bumps` input (default `30`) acts as a circuit breaker. If the repository accumulates many stale plugins, subsequent updates queue for the next daily run, preventing CI resource exhaustion and reviewer overload.

## The Freeze-SHA Safeguard Mechanism

The [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt) file provides a manual override to pause automatic updates for specific plugins. To freeze a problematic plugin, add its slug to this file:

```text

# Plugins held at current SHA due to upstream breakage

broken-auth-plugin
legacy-api-client

```

Once committed, the next workflow run will skip these entries even if their upstream repositories have advanced. This is critical for maintaining marketplace stability when upstream maintainers introduce breaking changes.

## Per-Entry Pull Request Strategy

The architectural decision to create **individual PRs per plugin** rather than a single "bump all" PR provides several operational advantages:

- **Failure isolation**: A validation failure in `plugin-a` does not block updates for `plugin-b` through `plugin-z`
- **Revert granularity**: Individual updates can be reverted without affecting other plugin versions
- **Review clarity**: Maintainers can assess the specific changelog of each dependency independently
- **Signed commit compliance**: Each bump branch contains a single, signed commit that satisfies the repository's required signatures policy

## Manual Workflow Dispatch Options

Repository maintainers can trigger ad-hoc runs from the GitHub Actions tab with custom parameters:

```yaml

# Example workflow_dispatch inputs

max_bumps: 10          # Limit this run to 10 bump PRs

plugin: my-awesome-plugin   # Target only this specific slug (omit for full sweep)

```

This is useful for urgent security patches or when onboarding a new plugin that needs immediate synchronization with its upstream repository.

## Summary

- The [`bump-plugin-shas.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/bump-plugin-shas.yml) workflow runs daily at 07:23 UTC to detect drift between pinned SHAs in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) and upstream repository HEADs
- It respects the [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt) exclusion list to hold specific plugins at their current versions
- Each detected update triggers validation via `claude plugin validate` and results in an isolated PR on a `bump/<plugin-name>` branch
- The workflow dispatches [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) against each bump branch to satisfy required status checks
- Execution is capped at 30 bumps per run by default, configurable via `max_bumps` input during manual dispatch

## Frequently Asked Questions

### How often does the bump-plugin-shas.yml workflow run automatically?

The workflow executes on a cron schedule of `23 7 * * *`, which translates to **07:23 UTC daily**. It can also be triggered manually via `workflow_dispatch` at any time from the GitHub Actions tab, allowing maintainers to run freshness checks on-demand outside the scheduled window.

### What prevents the workflow from updating broken plugins?

The [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt) file acts as a blocklist. Any plugin slug listed in this file is excluded from the bump process, keeping it pinned at its current SHA even if the upstream repository has moved forward. This prevents the workflow from opening PRs for plugins known to fail validation at HEAD.

### Why does the workflow create separate PRs instead of batching updates?

The **per-entry PR strategy** isolates risk. If one plugin's new SHA fails `claude plugin validate`, only that specific PR is blocked, while updates for other plugins proceed independently. This approach also simplifies code review by associating each git commit and validation result with exactly one plugin change, making rollbacks precise and history clear.

### Can I run the workflow for just one specific plugin?

Yes. When triggering the workflow manually via `workflow_dispatch`, provide the `plugin` input parameter with the specific slug (e.g., `my-awesome-plugin`). Leave the field empty to process all eligible plugins. You can also adjust the `max_bumps` value to control how many PRs the run will create.