# Understanding the workflow_dispatch Recursion Guard in Claude Plugins Community

> Learn about GitHub Actions workflow_dispatch recursion guard and how bump-plugin-shas.yml bypasses it using manual triggers for validation. Understand GitHub Actions event handling.

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

---

**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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml), the code comments indicate that the validation workflow is *"dispatched by [`bump-plugin-shas.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins.yml) but executes them within the context of the manually triggered workflow.

```yaml

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

```bash
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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins.yml)) would be suppressed by the recursion guard. The comment at line 13 of [`bump-plugin-shas.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/bump-plugin-shas.yml) specifically warns against this configuration to ensure validation steps actually execute against bump branches.