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

The bump-plugin-shas.yml workflow is a scheduled GitHub Actions pipeline that automatically updates SHA pins for Claude plugins in 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 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 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 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 (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 (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 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 (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:

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.
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.
4. Opens a pull request for the change.
5. Dispatches validate-plugins.yml against the new branch to attach the required validation check.

Key Implementation Files

• .github/workflows/bump-plugin-shas.yml: Main workflow orchestrating the automated bump process.
• .github/actions/bump-plugin-shas/action.yml: Reusable action definition handling SHA comparison and PR creation.
• .github/actions/bump-plugin-shas/scripts/bump.sh: Bash script implementing the bump logic, including marketplace.json parsing and freeze list application.
• .github/workflows/validate-plugins.yml: Validation pipeline triggered on each bump PR (see lines 13-20 for workflow_dispatch guards).
• .github/freeze-shas.txt: Exclusion list for plugins frozen at specific SHAs.
• .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 workflow runs daily at 07:23 UTC or via manual dispatch to check for outdated plugin SHAs in 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) allows exclusion of broken plugins from automatic updates.
• Each bump PR triggers the 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 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 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.

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