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

The 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 workflow ensures that every plugin listed in .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 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 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
• 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:

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 for each newly created bump branch:

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 file provides a manual override to pause automatic updates for specific plugins. To freeze a problematic plugin, add its slug to this file:

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

# 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 workflow runs daily at 07:23 UTC to detect drift between pinned SHAs in marketplace.json and upstream repository HEADs
• It respects the .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 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 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.

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