# How the bump-plugin-shas.yml Workflow Functions in the Anthropic Claude Plugins Community

> Discover how the bump-plugin-shas.yml workflow automatically updates Claude plugin SHA pins, creates PRs, and ensures validation in the anthropics/claude-plugins-community repo.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: internals
- Published: 2026-09-11

---

**The [`bump-plugin-shas.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/bump-plugin-shas.yml) workflow is a scheduled GitHub Actions pipeline that automatically updates SHA pins for Claude plugins in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json), creates individual pull requests for each outdated plugin, and triggers validation workflows to ensure new commits pass all checks.**

The [`bump-plugin-shas.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/bump-plugin-shas.yml) workflow in the `anthropics/claude-plugins-community` repository automates the maintenance of externally pinned plugin versions. This GitHub Actions pipeline runs daily to detect when upstream plugin repositories have advanced beyond their recorded SHAs, ensuring the Claude plugin marketplace stays current while isolating potential breaking changes into separate, validated pull requests.

## Workflow Triggers and Inputs

The workflow supports both automated and manual execution modes to provide flexibility in maintenance operations.

### Scheduled Daily Execution

Configured in [`.github/workflows/bump-plugin-shas.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/bump-plugin-shas.yml) at lines 26-29, the workflow triggers automatically at **07:23 UTC each day** using a cron schedule. This ensures the plugin marketplace is checked regularly for upstream changes without requiring manual intervention.

### Manual Dispatch with Parameters

Developers can trigger the workflow manually via `workflow_dispatch`, supplying optional inputs defined at lines 30-42:

- **`max_bumps`**: Limits the number of plugins updated in a single run (default: `30`). This prevents overwhelming the repository with too many simultaneous pull requests.
- **`plugin`**: Specifies a single plugin name to target. When left empty, the workflow processes all stale plugins currently in the marketplace.

## Required Permissions

The workflow requests specific write permissions to function correctly within the repository ecosystem. According to lines 43-46 of the workflow definition, it requires:

- **`contents: write`**: To create branches and commits with updated SHA values.
- **`pull-requests: write`**: To open individual PRs for each plugin bump.
- **`actions: write`**: To trigger the companion [`validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins.yml) workflow on newly created bump branches.

## Core Job: The SHA Bumping Process

The `bump` job orchestrates the detection and update of outdated plugin SHAs through a four-step process.

### Repository Checkout and Freeze List Loading

The workflow begins by checking out the repository code using `actions/checkout@v4` (lines 56-57). It then loads [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt) (lines 58-74), which enumerates plugins intentionally frozen at their current SHAs. The workflow parses this file into a space-separated string, filtering out comment lines to identify which plugins should be excluded from automatic updates.

### The Custom Bump Action

The core logic resides in `.github/actions/bump-plugin-shas` (referenced at lines 78-88). This custom composite action performs several critical operations:

1. **Parses [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)** (lines 83-85): Reads the current plugin manifest to identify pinned SHAs.
2. **Compares upstream HEAD**: Determines which plugins have moved past their recorded SHA values, excluding any entries in the freeze list.
3. **Creates signed commits**: For each outdated plugin, generates a new branch named `bump/<plugin-name>` and creates a signed commit using `createCommitOnBranch` to meet organizational signature policies.
4. **Opens individual PRs**: Creates **one pull request per plugin** (per-entry mode), isolating each SHA update for independent review and testing.

### Validation Workflow Dispatch

After creating pull requests, the workflow dispatches the [`validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins.yml) pipeline for each new branch (lines 90-119). Using `gh workflow run`, it triggers validation against the PR head. Because GitHub's `GITHUB_TOKEN` prevents recursive `pull_request` events on automated PRs, this explicit dispatch bypasses the recursion guard, ensuring each bump PR receives the required "Validate Plugins" status check.

## The Freeze-SHAs Mechanism

The file **[`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt)** (referenced in lines 19-21) serves as an exclusion list for problematic plugins. Each line contains a plugin slug, with optional `#` comments for documentation. Plugins listed here are skipped during the bump process, preventing the creation of failing PRs for repositories known to be broken at their current HEAD. This mechanism allows maintainers to temporarily halt updates for specific plugins without modifying the workflow code.

## Controlling Workload and Concurrency

The `max_bumps` input parameter (default: 30) caps the number of per-entry PRs created in a single execution. According to lines 22-24, when the backlog of outdated plugins grows, maintainers can increase this limit via manual dispatch to clear the queue faster, though they must monitor overall PR volume to avoid overwhelming reviewers.

## Manual Invocation Example

You can manually trigger the workflow from the command line using the GitHub CLI to target a specific plugin:

```bash
gh workflow run bump-plugin-shas.yml \
  -f max_bumps=1 \
  -f plugin=example-plugin

```

This command sequence:

1. Loads the current freeze list from [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt).
2. Checks if `example-plugin` has a newer upstream SHA in its repository.
3. Creates a branch `bump/example-plugin` with a signed commit updating the SHA in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json).
4. Opens a pull request for the change.
5. Dispatches [`validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins.yml) against the new branch to attach the required validation check.

## Key Implementation Files

- **[`.github/workflows/bump-plugin-shas.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/bump-plugin-shas.yml)**: Main workflow orchestrating the automated bump process.
- **[`.github/actions/bump-plugin-shas/action.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/bump-plugin-shas/action.yml)**: Reusable action definition handling SHA comparison and PR creation.
- **[`.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)**: Bash script implementing the bump logic, including [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) parsing and freeze list application.
- **[`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml)**: Validation pipeline triggered on each bump PR (see lines 13-20 for `workflow_dispatch` guards).
- **[`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt)**: Exclusion list for plugins frozen at specific SHAs.
- **[`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)**: Source of truth manifest containing plugin entries and their pinned SHAs.

These components implement a robust, automated pipeline that maintains the Claude plugin marketplace while ensuring each change is isolated, signed, and validated.

## 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 or via manual dispatch to check for outdated plugin SHAs in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json).
- It creates **individual pull requests** for each plugin requiring updates, using signed commits on branches named `bump/<plugin-name>`.
- The **freeze list** ([`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt)) allows exclusion of broken plugins from automatic updates.
- Each bump PR triggers the [`validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins.yml) workflow via explicit dispatch to bypass GitHub's token recursion guards and attach required status checks.
- The `max_bumps` parameter controls batch size to prevent PR volume overload.

## Frequently Asked Questions

### How does the workflow handle plugins that are broken at their upstream HEAD?

The workflow references [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt) to identify plugins that should be excluded from automatic updates. Any plugin slug listed in this file is skipped during the SHA comparison phase, preventing the creation of failing pull requests for repositories with known issues. This freeze mechanism allows maintainers to temporarily halt updates without workflow modifications.

### Why does the workflow trigger validate-plugins.yml separately instead of relying on the pull_request event?

Because the workflow creates PRs using the default `GITHUB_TOKEN`, GitHub's recursion guard prevents these automated PRs from triggering additional `pull_request` events. To ensure each bump PR receives the required "Validate Plugins" check, the workflow explicitly dispatches [`validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins.yml) using `gh workflow run` immediately after creating each branch, bypassing the event restriction while still validating the new SHA.

### What permissions does bump-plugin-shas.yml require and why?

The workflow requires `contents: write` to create branches and commits, `pull-requests: write` to open PRs, and `actions: write` to trigger the validation workflow. According to lines 43-46 of the workflow definition, these permissions enable the pipeline to modify repository files, create reviewable changes, and initiate the companion validation checks needed for each plugin update.

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

Yes, using the `plugin` input parameter with `workflow_dispatch`. You can trigger a manual run via the GitHub CLI or web interface, specifying the exact plugin name in the `plugin` field. When provided, the workflow targets only that plugin (if its SHA is outdated and not frozen), allowing targeted updates without processing the entire marketplace backlog.