SimpleBeacon AI Guardrails

The AI Circuit Breaker for Pull Requests.

SimpleBeacon scans modified code in every PR, catches credential leaks and AI-generated slop, posts a structured review comment, and blocks merge when your gate fails. Team tier unlocks centralized telemetry so engineering leads can prove ROI to management in one dashboard glance.

---

Install in 60 seconds

Add .github/workflows/simplebeacon.yml:

name: SimpleBeacon Gate

on:
  pull_request:
    branches: [main, master, develop]

permissions:
  contents: read
  pull-requests: write

jobs:
  ai-circuit-breaker:
    runs-on: ubuntu-latest
    steps:
      # Required for diff-only scans — shallow clones break base ref resolution
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: simplebeacon/guardrails@v1
        with:
          license-token: ${{ secrets.SIMPLEBEACON_LICENSE_TOKEN }}
          fail-on: high
          full-scan: false

Open a PR. You get a comment, a job summary, and a red check if the gate trips.

---

What you get on every PR

Output	Description
PR comment	AI Circuit Breaker summary with severity breakdown, file links, and fix hints
Merge block	Exit code 1 when findings meet fail-on threshold
Job summary	Gate pass/fail at a glance in the Actions tab
Inline annotations	High/critical findings on changed files

---

Pricing (Team tier)

Plan	Price	Best for	Unlocks
Community	Free	Solo devs & evaluation	PR diff scan, comments, fail-open on license outage
Team Guardrails	$49/mo	Team leads blocking bad merges	License token, PR guardrails, dashboard access
Team Growth	$149/mo	Multi-repo engineering orgs	Consolidated telemetry, multi-repo metrics, compliance trends

Checkout at simplebeacon.ai/pricing:

• $49/mo → product key startup_monthly (PR guardrails + dashboard)
• $149/mo → product key growth_monthly (multi-repo telemetry + consolidated logs)

Store your license token as SIMPLEBEACON_LICENSE_TOKEN in GitHub repository secrets.

---

How tiers behave in CI

Community (no token) — Fully functional. Scans PR diffs, posts comments, blocks merge on gate failure. No dashboard telemetry.

Team (valid token) — Same guardrails plus metadata-only CI telemetry (scan counts, gates tripped, criticals blocked — never source code) on simplebeacon.ai/dashboard. Show your manager Merges Blocked This Week.

Fail-open policy — If the licensing server is unreachable, the pipeline downgrades to Community mode and prints a warning. Your deployments never break because of a network timeout. Invalid tokens fail closed.

---

Inputs

Input	Required	Default	Description
token	Yes	github.token	GitHub token for PR comments
license-token	No	—	Team license from simplebeacon.ai
fail-on	No	high	Minimum severity to block merge (low, medium, high, critical)
full-scan	No	false	Scan entire repo instead of PR diff
base-ref	No	PR base	Override git diff base ref

---

Troubleshooting

bad revision / unknown revision on diff scan

Your checkout step is using fetch-depth: 1. Set fetch-depth: 0 on actions/checkout@v4.

Gate passes but you expected failure

Confirm fail-on matches finding severity. Run locally: npx simplebeacon scan --gate --diff.

Invalid license token fails the job

Expected (fail-closed). Remove the secret for Community mode or fix the token from your payment email.

---

Local development

npx simplebeacon init --profile standard
npx simplebeacon scan --gate --diff

---

Repository layout

simplebeacon/guardrails/
├── action.yml              # Marketplace action definition
├── README.md               # You are here
├── LICENSE                 # MIT
├── CHANGELOG.md            # Version history
├── CODE_OF_CONDUCT.md      # Community standards
├── CONTRIBUTING.md         # How to contribute
├── SECURITY.md             # Vulnerability reporting
├── PUBLISH.md              # Maintainer release checklist
├── LIVE-VERIFICATION.md    # Pre-customer verification
├── MARKETPLACE.md          # Marketplace listing copy
└── .github/
    ├── dependabot.yml
    ├── workflows/
    │   ├── smoke-test.yml          # Pre-release validation
    │   └── example-simplebeacon.yml # Copy-paste example
    └── ISSUE_TEMPLATE/
        ├── bug-report.yml
        ├── feature-request.yml
        └── config.yml

This repository is intentionally isolated from the SimpleBeacon monorepo. It ships only the GitHub Action — the scan engine runs via npx simplebeacon@latest from npm.

---

Publish checklist

See PUBLISH.md for GitHub Marketplace steps.

See LIVE-VERIFICATION.md before sharing with first paying customers.

---

Support

• Docs: simplebeacon.ai
• Issues: github.com/simplebeacon/guardrails/issues
• Email: support@simplebeacon.ai