🛡️ Swarm Shield Action

Protect your repos from spam PRs by first-time contributors sent by YouTubers/influencers.

Swarm Shield automatically detects and closes pull requests from first-time contributors that:

• Modify protected files (README, CI/CD, etc.)
• Contain spam patterns (promotions, ads, political content, etc.)

Features

✅ Zero configuration needed - Works out of the box ✅ Smart detection - Only targets FIRST_TIME_CONTRIBUTOR, FIRST_TIMER, and NONE ✅ Dual protection - File patterns + content scanning ✅ Auto-close with explanation - Educational message for spam, appeals for legitimate contributors ✅ No spam bombing - Doesn't @ mention maintainers ✅ Customizable - Override default messages and rules

Quick Start

1. Create workflow

Create .github/workflows/swarm-shield.yml:

name: Swarm Shield Protection

on:
  pull_request_target:
    types: [opened]

permissions:
  contents: read
  pull-requests: write

jobs:
  protect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: contriboss/[email protected]
        env:
          GITHUB_TOKEN: ${{ github.token }}

2. Create config

Create .github/swarm-shield.yml:

# Swarm Shield Configuration

# Files that first-time contributors cannot modify
protected_files:
  - pattern: "README.md"
    reason: "Project documentation maintained by core team"

  - pattern: "*.gemspec"
    reason: "Gem specifications require maintainer approval"

  - pattern: ".github/workflows/*"
    reason: "CI/CD workflows require maintainer approval"

# Content patterns to detect in PR diffs (case-insensitive regex)
spam_patterns:
  - pattern: "subscribe.*(to|my|our).*(channel|youtube)"
    reason: "YouTube channel promotion"

  - pattern: "follow.*(me|us|my|our).*(on|at).*(twitter|instagram|tiktok)"
    reason: "Social media promotion"

  - pattern: "(check out|visit).*(my|our).*(course|tutorial|blog|website)"
    reason: "Self-promotion content"

  - pattern: "(bitcoin|crypto|nft).*(join|invest|buy)"
    reason: "Cryptocurrency spam"

# Optional: Custom close message
message: |
  ## 🚫 Pull Request Automatically Closed

  This PR has been automatically closed by Swarm Shield protection.

  **If you were sent here by a YouTuber or influencer** as a "Git tutorial":
  - Go back and **unsubscribe**
  - These spam PRs **harm your GitHub reputation**
  - Real contributions matter; tutorial spam does not

  **If this is legitimate:**
  - Comment explaining your use case
  - A maintainer can reopen if appropriate

3. Done!

That's it. Swarm Shield is now protecting your repo.

How It Works

1. First-time contributor opens PR
2. Swarm Shield checks:
   • Is author_association = FIRST_TIME_CONTRIBUTOR, FIRST_TIMER, or NONE?
   • Does PR modify any protected files?
   • Does PR diff contain spam patterns?
3. If violations found:
   • Posts comment explaining the issue
   • Closes PR automatically
   • Logs violation details
4. Regular contributors bypass entirely

Configuration

Protected Files

Use glob patterns to protect files:

protected_files:
  - pattern: "README.md"              # Exact match
    reason: "Core documentation"

  - pattern: "*.gemspec"              # Wildcard
    reason: "Gem specs"

  - pattern: ".github/workflows/*"    # Directory wildcard
    reason: "CI/CD files"

  - pattern: "**/*.lock"              # Recursive wildcard
    reason: "Lock files"

Spam Patterns

Use regex to detect spam content (case-insensitive):

spam_patterns:
  - pattern: "subscribe.*channel"
    reason: "YouTube promotion"

  - pattern: "\\[sponsored\\]"
    reason: "Advertisement"

  - pattern: "make.*\\$[0-9]+(k|,000).*(day|week)"
    reason: "Get-rich-quick spam"

Note: Escape special regex characters (\\., \\[, etc.)

Custom Message

Override the default close message:

message: |
  ## Custom Title

  Your custom message here.

  Supports **markdown** formatting.

Outputs

The action provides outputs for conditional workflows:

- uses: contriboss/[email protected]
  id: guard
  env:
    GITHUB_TOKEN: ${{ github.token }}

- name: Notify team
  if: steps.guard.outputs.violations-detected == 'true'
  run: echo "Violations: ${{ steps.guard.outputs.violation-count }}"

Available outputs:

• violations-detected: "true" or "false"
• violation-count: Number of violations
• violation-types: JSON array of types (["protected_file", "spam_pattern"])

Why Swarm Shield?

The Problem

YouTubers/influencers send followers to spam open-source repos with meaningless PRs (editing READMEs, etc.) as "Git tutorials". This:

• Wastes maintainer time
• Clutters PR history
• Harms contributors' GitHub reputation
• Normalizes spam contributions

The Solution

Swarm Shield stops spam at the source:

• Educational - Tells spammers to unsubscribe
• Fair - Only applies to first-timers
• Flexible - Legitimate contributors can appeal
• Effective - Auto-closes on detection

Examples

Minimal Setup

Just protect README:

protected_files:
  - pattern: "README.md"
    reason: "Core documentation"

Full Protection

Protect files + scan content:

protected_files:
  - pattern: "README.md"
    reason: "Core documentation"
  - pattern: ".github/workflows/*"
    reason: "CI/CD workflows"

spam_patterns:
  - pattern: "subscribe.*channel"
    reason: "YouTube promotion"
  - pattern: "(bitcoin|crypto).*(invest|join)"
    reason: "Crypto spam"

FAQ

Will this block legitimate first-time contributors?

Only if they modify protected files or add spam content. Legitimate contributors can comment to appeal.

What if I want to allow some first-timers?

They can still open PRs to non-protected files. Maintainers can manually reopen closed PRs.

Does this replace CODEOWNERS?

No, it complements it. CODEOWNERS handles review requirements; Swarm Shield handles spam prevention.

Can I test this?

Yes! Create a test PR from an account that hasn't contributed. Just make sure you can reopen it.

License

MIT © Seuros (Abdelkader Boudih)

Contributing

Contributions welcome! This action itself is protected by Swarm Shield. 😉

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions