Understanding the workflow_dispatch Recursion Guard in Claude Plugins Community

The workflow_dispatch recursion guard is GitHub Actions' built-in protection that prevents workflows triggered by the default GITHUB_TOKEN from recursively firing other workflows listening to the same event type, and bump-plugin-shas.yml bypasses it by using a manual workflow_dispatch trigger instead of pull_request events to run validation logic directly.

The anthropics/claude-plugins-community repository relies on automated SHA updates for community plugins, but GitHub's recursion guard normally blocks validation workflows when pull requests are created programmatically. By leveraging the workflow_dispatch recursion guard bypass technique, the repository ensures that automated bumps receive proper validation without triggering infinite workflow loops.

What Is the Workflow Dispatch Recursion Guard?

The Token-Based Protection Mechanism

GitHub Actions implements a recursion guard that suppresses downstream workflow triggers when actions are performed using the default GITHUB_TOKEN. When a workflow creates a pull request using this token, any other workflow configured to run on pull_request events will not trigger, preventing infinite loops where a workflow continuously re-triggers itself.

Comments in .github/workflows/bump-plugin-shas.yml explicitly acknowledge this limitation, noting that the workflow is "opened with GITHUB_TOKEN — don't fire on :pull_request (recursion guard)". This protection ensures that automated processes don't cascade indefinitely, but it also blocks legitimate validation steps when bots open pull requests.

Impact on Automated Validation

In .github/workflows/validate-plugins.yml, the code comments indicate that the validation workflow is "dispatched by bump-plugin-shas.yml against each per-entry bump" precisely because the normal recursion guard would otherwise suppress execution. Without bypassing this guard, the automated SHA bump process would create pull requests that never undergo validation, breaking the repository's integrity checks.

How bump-plugin-shas.yml Bypasses the Guard

Manual Trigger Architecture

The file .github/workflows/bump-plugin-shas.yml implements the bypass by declaring on: workflow_dispatch rather than listening for pull_request events. As noted in line 91 of the workflow, "the bump branch (recursion guard → on:pull_request won't fire on a GITHUB_TOKEN)", confirming the architectural decision to avoid the protected event type.

Because workflow_dispatch triggers are considered explicit user-initiated runs rather than token-generated events, the recursion guard does not apply. This allows the workflow to execute validation steps that would otherwise be blocked when using automated tokens.

Direct Action Invocation

Instead of relying on event propagation, bump-plugin-shas.yml invokes the validation logic directly through the composite action at ./.github/actions/bump-plugin-shas. This approach encapsulates the same validation checks defined in validate-plugins.yml but executes them within the context of the manually triggered workflow.

# .github/workflows/bump-plugin-shas.yml

name: bump-plugin-shas
on:
  workflow_dispatch:  # Bypasses recursion guard by avoiding GITHUB_TOKEN-triggered events

jobs:
  bump:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run bump-plugin-shas action
        uses: ./.github/actions/bump-plugin-shas  # Direct validation invocation

Triggering the Bypass Manually

To execute the SHA bump process without hitting the recursion guard, maintainers invoke the workflow manually using the GitHub CLI:

gh workflow run bump-plugin-shas.yml

This command initiates a workflow_dispatch event that circumvents the token-based protection, allowing the validation logic to execute against newly created bump pull requests where automated triggers would fail.

Summary

• The recursion guard prevents GITHUB_TOKEN-initiated pull requests from triggering additional pull_request workflows to avoid infinite loops.
• The bump-plugin-shas.yml workflow uses workflow_dispatch instead of pull_request events to avoid the guard's suppression.
• Validation occurs through direct action invocation at ./.github/actions/bump-plugin-shas rather than event-driven triggers.
• Manual triggers via GitHub CLI or the Actions tab execute successfully where automated triggers would be blocked by the GITHUB_TOKEN restrictions.

Frequently Asked Questions

Why doesn't GitHub Actions allow workflows to trigger other workflows with the default token?

GitHub prevents this to avoid infinite recursion and runaway compute costs. If a workflow listening to pull_request events created another pull request using the default GITHUB_TOKEN, it would trigger itself indefinitely. The recursion guard blocks this by suppressing downstream workflow triggers for any actions performed by the default token, as referenced in the comments within .github/workflows/validate-plugins.yml.

Can I use workflow_dispatch to bypass the recursion guard for any automated workflow?

Yes, any workflow using workflow_dispatch avoids the recursion guard because GitHub treats manual dispatches as explicit user actions rather than automated token operations. However, this requires either manual intervention or a separate authentication mechanism (like a Personal Access Token) to trigger the dispatch, as the default GITHUB_TOKEN cannot initiate workflow_dispatch events automatically according to the repository's implementation patterns.

How does bump-plugin-shas.yml reference the validation logic if it doesn't use pull_request triggers?

According to the source code in the Claude Plugins Community repository, bump-plugin-shas.yml calls the validation logic directly through the composite action at ./.github/actions/bump-plugin-shas. This action encapsulates the same validation checks defined in validate-plugins.yml but executes them within the context of the manually triggered workflow rather than waiting for a pull_request event to fire.

What happens if bump-plugin-shas.yml used pull_request instead of workflow_dispatch?

If configured with on: pull_request, the workflow would trigger when the automated PR is created, but subsequent validation workflows (like validate-plugins.yml) would be suppressed by the recursion guard. The comment at line 13 of bump-plugin-shas.yml specifically warns against this configuration to ensure validation steps actually execute against bump branches.

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