How to Track Release Tags Instead of HEAD in the bump-plugin-shas GitHub Action

To configure a plugin to track release tags instead of HEAD, set "pinType": "tag" in the marketplace entry and specify the tag name in the "pin" field within .claude-plugin/marketplace.json.

The bump-plugin-shas workflow in the anthropics/claude-plugins-community repository automatically monitors upstream plugin repositories for changes. By default, the action tracks the mutable HEAD commit and creates pull requests whenever new code lands on the default branch. For stable production deployments, you can configure the action to track immutable release tags instead, ensuring updates only occur when maintainers publish official releases.

Understanding the Default HEAD Tracking Behavior

By default, the bump-plugin-shas action treats the value in the "pin" field as a raw commit SHA. According to the workflow definition in .github/workflows/bump-plugin-shas.yml, the action compares the pinned SHA against the current upstream HEAD. When new commits land on the default branch, the action generates a pull request to advance the pin to the latest SHA.

This behavior ensures you always ingest the latest code changes. However, it also means your marketplace entries update on every commit, including work-in-progress changes that may not represent stable, tested releases.

Configuring Tag Tracking in marketplace.json

To switch from HEAD tracking to tag tracking, modify the plugin entry in .claude-plugin/marketplace.json. You must make two specific changes:

1. Set the pin to a tag name – Replace the commit SHA with the release tag (e.g., "v1.2.3").
2. Add the pinType field – Include "pinType": "tag" to instruct the action to resolve the reference as a tag rather than a literal SHA.

{
  "name": "quickdesign",
  "source": "https://github.com/anthropics/quickdesign",
  "pin": "v1.5.0",
  "pinType": "tag",
  "description": "Quick design plugin"
}

For legacy manifest formats, the action also supports "trackTag": true, though "pinType": "tag" is the preferred modern syntax as implemented in the anthropics/claude-plugins-community source code.

How the Action Resolves Tags to SHAs

The resolution logic resides in .github/actions/bump-plugin-shas/action.yml. When processing an entry with "pinType": "tag", the action executes git rev-parse <tag> to resolve the tag to its current commit SHA before performing comparisons.

During each scheduled workflow run (triggered at 23:07 UTC daily), the action performs the following steps:

• Loads the manifest – Reads the configuration from the path specified at lines 80-85 of .github/workflows/bump-plugin-shas.yml (default: .claude-plugin/marketplace.json).
• Resolves references – For entries with "pinType": "tag", fetches upstream refs and resolves the tag to a SHA using git rev-parse.
• Compares states – Compares the resolved SHA against the upstream tag's current target.
• Creates bump PRs – When the tag resolves to a new SHA, creates a branch bump/<plugin-name> and opens a pull request that updates the "pin" field to the new tag target.

This mechanism ensures that intermediate commits pushed to the default branch do not trigger updates. Only actual tag movements—typically indicating a new official release—generate bump pull requests.

Complete Configuration Example

Here is a production-ready configuration showing the marketplace manifest entry alongside the relevant workflow invocation:

// .claude-plugin/marketplace.json
{
  "name": "tres-finance-plugin",
  "source": "https://github.com/anthropics/tres-finance-plugin",
  "pin": "v2.3.0",
  "pinType": "tag",
  "description": "Finance-related Claude plugin"
}

# .github/workflows/bump-plugin-shas.yml (excerpt)

- uses: ./.github/actions/bump-plugin-shas
  id: bump
  with:
    marketplace-path: .claude-plugin/marketplace.json
    max-bumps: ${{ inputs.max_bumps || '30' }}
    freeze-shas: ${{ steps.freeze.outputs.list }}
    only: ${{ inputs.plugin }}
    pr-mode: per-entry
    claude-cli-version: latest

After committing the updated marketplace.json, the next scheduled run will begin tracking the v2.3.0 tag. When the upstream repository publishes v2.4.0, the helper scripts in .github/actions/bump-plugin-shas/scripts/* will detect the change and generate a PR updating the pin accordingly.

Reverting to SHA Tracking

To return to tracking raw commits instead of release tags, edit the plugin entry in .claude-plugin/marketplace.json. Remove the "pinType": "tag" field or set it to "sha", then update the "pin" value to the specific commit hash you want to freeze. The subsequent workflow run will resume comparing the pin directly against the upstream HEAD rather than resolving tag references.

Summary

• Default behavior: The bump-plugin-shas action compares pinned SHAs against upstream HEAD and creates PRs on every commit.
• Tag tracking: Set "pinType": "tag" and store the tag name in the "pin" field to track releases instead of HEAD.
• Resolution: The action uses git rev-parse <tag> in .github/actions/bump-plugin-shas/action.yml to convert tags to SHAs before comparison.
• Branch naming: Bump PRs are created from branches named bump/<plugin-name> when tags advance to new commits.
• Key files: Configuration lives in .claude-plugin/marketplace.json, workflow logic in .github/workflows/bump-plugin-shas.yml, and resolution scripts in .github/actions/bump-plugin-shas/scripts/*.

Frequently Asked Questions

How does the bump-plugin-shas action differentiate between tags and SHAs?

The action inspects the "pinType" field in each marketplace entry. When set to "tag", the action treats the "pin" value as a Git reference to be resolved via git rev-parse. When the field is absent or set to "sha", the action treats the pin as a literal commit hash and compares it directly against the upstream HEAD commit.

Can I mix tag tracking and SHA tracking in the same marketplace.json?

Yes. Each plugin entry maintains its own pinType property. You can configure some plugins to track release tags using "pinType": "tag" while others track raw SHAs by omitting the field. The action evaluates each entry independently during the workflow run, allowing heterogeneous tracking strategies within a single manifest.

What happens when a release tag moves to a new commit?

When a maintainer updates a release tag to point to a different commit (force-push or retag), the next workflow run resolves the tag to its new SHA. If this resolved SHA differs from the previous resolution, the action creates a bump pull request updating the "pin" field, even if the tag name (e.g., v1.2.3) remains unchanged.

How do I revert from tag tracking to HEAD tracking?

To revert, remove the "pinType": "tag" field from the plugin entry in .claude-plugin/marketplace.json or change it to "pinType": "sha". Update the "pin" field to contain the exact commit SHA you want to track. The action will resume comparing this SHA against the upstream HEAD during subsequent runs, creating bump PRs whenever new commits land on the default branch.

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