OSSBeacon – explainable PR risk for open-source maintainers

OSSBeacon, an open-source maintainer cockpit for pull-request risk, issue triage, and release notes, has reached early public beta with stable release v0.2.0. The tool uses deterministic local heuristics by default, with optional OpenAI summaries via the Responses API, and is designed as a transparent first-pass signal rather than an autonomous gatekeeper.

A lightweight open-source maintainer cockpit for pull-request risk, issue triage, and release notes. OSSBeacon helps maintainers answer three repetitive questions quickly: Where should I focus my PR review? What kind of issue is this, and how urgent might it be? What changed between two release refs? It works with deterministic local heuristics by default. OpenAI summaries are optional and explicitly opt-in. Status:early public beta, stable release v0.2.0 . The project is intentionally small, dependency-free, auditable, and contributor-friendly. OSSBeacon also dogfoods the current main branch on its own pull requests. Maintainers spend a surprising amount of time routing attention rather than writing code. OSSBeacon is designed as a transparent first-pass signal, not an autonomous gatekeeper. - 🟢 Free baseline: no AI key required. - 🔍 Transparent: risk factors are shown, not hidden behind a score. - 🤖 Optional AI: use the OpenAI Responses API only when you request it. - 🔐 Privacy-conscious: AI mode sends compact metadata, not arbitrary repository source files. - 🧩 Zero runtime dependencies: Node.js 20+ is enough. - ⚙️ GitHub Action ready: put the report in your workflow summary, optionally comment on PRs. The lowest-risk first trial is read-only, AI-off, and pinned to the stable release. Copy examples/workflow.yml /closedfiles23-web/ossbeacon/blob/main/examples/workflow.yml into your repository as .github/workflows/ossbeacon.yml .That baseline uses pull-requests: read , does not require an OpenAI key, and writes the report to the GitHub Actions job summary. If the signal is useful, you can later enable a duplicate-free managed PR comment, tune repository-specific risk rules, or opt into AI. For the complete progression, including fork safety and least-privilege permissions, see Adopting OSSBeacon . After a real trial, with useful signals, false positives, missing signals, or setup friction. share an adoption report https://github.com/closedfiles23-web/ossbeacon/issues/new?template=adoption.yml git clone https://github.com/closedfiles23-web/ossbeacon.git cd ossbeacon npm test node src/cli.mjs demo Analyze a public PR: node src/cli.mjs analyze-pr --repo owner/project --pr 123 For private repositories or higher GitHub API limits: export GITHUB TOKEN="..." node src/cli.mjs analyze-pr --repo owner/private-project --pr 123 Enable the optional AI maintainer summary: export OPENAI API KEY="..." node src/cli.mjs analyze-pr --repo owner/project --pr 123 --ai The OpenAI integration uses the Responses API. The default model can be changed through OSSBEACON MODEL or .ossbeacon.json . ossbeacon analyze-pr --repo owner/project --pr 123 ossbeacon analyze-pr --repo owner/project --pr 123 --json ossbeacon analyze-pr --repo owner/project --pr 123 --ai The report considers change size, number of files, sensitive paths, obvious test changes, and configurable thresholds. ossbeacon triage-issue --repo owner/project --issue 42 It proposes a type, labels, priority, and evidence. The heuristic is deliberately conservative. ossbeacon release-notes --repo owner/project --from v1.0.0 --to v1.1.0 Conventional Commit prefixes are grouped into features, fixes, docs, maintenance, and other changes. Add --json to any maintainer command to emit the versioned OSSBeacon report contract rather than internal GitHub API payloads. ossbeacon analyze-pr --repo owner/project --pr 123 --json ossbeacon triage-issue --repo owner/project --issue 42 --json ossbeacon release-notes --repo owner/project --from v1.0.0 --to v1.1.0 --json Reports include schemaVersion and reportType . The v1 contract, compatibility policy, and privacy guarantees are documented in docs/REPORT SCHEMA.md /closedfiles23-web/ossbeacon/blob/main/docs/REPORT SCHEMA.md , with a formal JSON Schema at schemas/report-v1.schema.json /closedfiles23-web/ossbeacon/blob/main/schemas/report-v1.schema.json . External repositories should pin the stable release: name: OSSBeacon on: pull request: types: opened, synchronize, reopened, ready for review permissions: contents: read pull-requests: read jobs: review-signal: runs-on: ubuntu-latest steps: - uses: closedfiles23-web/ossbeacon@v0.2.0 with: github-token: ${{ github.token }} use-ai: 'false' comment: 'false' Stable v0.2.0 includes duplicate-free managed PR comments. When comment: 'true' is enabled, OSSBeacon marks its own report and updates that marked comment on later runs instead of posting duplicates or editing unrelated human and bot comments. For least privilege, use pull-requests: read when comments are disabled. Creating or updating an OSSBeacon PR comment requires pull-requests: write . contents: read is sufficient for the Action's repository access. To enable AI, store an OpenAI API key as a repository secret and pass it to openai-api-key . Do not place API keys in workflow files. OSSBeacon analyzes its own pull requests through .github/workflows/ossbeacon.yml /closedfiles23-web/ossbeacon/blob/main/.github/workflows/ossbeacon.yml . That workflow deliberately uses the trusted Action from @main , keeps AI disabled, and does not check out or execute pull-request code.For same-repository branches it can maintain one OSSBeacon PR comment. For forked pull requests it leaves commenting disabled and still provides the workflow summary. This lets the project exercise current behavior without making external contributors depend on privileged tokens. Downstream projects should continue to use the stable release tag rather than copying this development-only @main choice. Copy .ossbeacon.example.json to .ossbeacon.json and adjust thresholds, sensitive path patterns, or GitHub retrieval limits. { "github": { "maxPrFiles": 1000 }, "risk": { "highThreshold": 70, "mediumThreshold": 35, "largeChangeLines": 600 } } github.maxPrFiles is a safety cap. OSSBeacon paginates changed files up to that limit and clearly warns when a larger PR is intentionally truncated. Assist, do not replace maintainers. Scores never merge or reject code automatically. Explain signals. Every risk score comes with human-readable factors. Minimal data. AI mode gets compact PR or issue metadata rather than complete source files. Safe defaults. Commenting and AI are disabled by default. Portable core. No framework or runtime dependency beyond modern Node.js. See ROADMAP.md /closedfiles23-web/ossbeacon/blob/main/ROADMAP.md . Near-term work includes duplicate-issue hints, repository-specific policies, SARIF output, richer release notes, and adapter interfaces for additional model providers. Contributions are welcome, including docs, tests, rules, provider adapters, UX ideas, and accessibility improvements. Start with CONTRIBUTING.md /closedfiles23-web/ossbeacon/blob/main/CONTRIBUTING.md and check the open issues for a good first issue or help wanted task. If you try OSSBeacon on a real repository, feedback about false positives, missing signals, workflow friction, or useful defaults is especially valuable. Use the Adoption feedback form so the report is easy to compare with other trials. Public repository examples are referenced only with explicit permission. Never include private repository data, credentials, or undisclosed vulnerability details in public feedback. Please do not file public exploit details for a vulnerability in OSSBeacon. Follow SECURITY.md /closedfiles23-web/ossbeacon/blob/main/SECURITY.md . MIT. See LICENSE /closedfiles23-web/ossbeacon/blob/main/LICENSE .