Skip to content
Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace
BranchesTags

Repository files navigation

OSS Maintainer Signal banner

OSS Maintainer Signal (oss-signal)

CI Repository health Evidence verification OpenSSF Scorecard GitHub release GitHub Marketplace npm version npm downloads Self audit Maintainer evidence License: MIT

oss-signal is a dependency-light maintainer-readiness CLI and GitHub Action for OSS projects that need repeatable triage, regression gates, CI evidence, SARIF, inventory reports, issue-ready cleanup notes, adoption packs, a transparent rule catalog, and no-fail workflow trials.

It checks the files and automation that reduce maintainer load: README, license, contributing guide, security policy, support policy, funding metadata, maintainer ownership, CI, tests, issue templates, pull request templates, Dependabot, and release notes. The output is a score plus concrete next steps in Markdown, summary, JSON, env, SARIF, inventory, GitHub Issue-ready Markdown, PR-sized maintainer plan, no-fail workflow, adoption-pack, or rule-catalog formats.

Why Maintainers Bookmark It

Job What oss-signal gives you
Prepare a release A repeatable maintainer-readiness report before release day.
Review an unfamiliar repository A quick map of contributor, security, CI, and release signals.
Open a focused cleanup PR Issue-ready notes and PR-sized plans instead of broad audit noise.
Add a low-risk CI check A no-fail trial workflow that uploads Markdown and adoption-pack artifacts.
Audit many repositories Inventory mode for newline-delimited repository target lists.

Fastest public demo:

npx oss-signal SalmonPlays/oss-signal --format summary

30-Second Quick Start

Add a report-only workflow to the current repository:

npx oss-signal --init

This creates .github/workflows/oss-signal-trial.yml, including a manual trigger, pull-request trigger, Markdown report, adoption pack, and artifact upload. It does not add a failing score gate. Existing workflow files are protected unless you explicitly pass --force.

Run a maintainer-readiness report against any public GitHub repository:

npx oss-signal owner/repo --format markdown --output oss-signal-report.md

Generate an editable issue body before posting a cleanup suggestion:

npx oss-signal owner/repo --format issue --output maintainer-follow-up.md

Generate a no-fail GitHub Actions trial workflow:

npx oss-signal owner/repo --format workflow --output .github/workflows/oss-signal-trial.yml

Generate a copyable maintainer adoption pack:

npx oss-signal owner/repo --format adoption --output adoption-pack.md

Inspect the rule weights before posting feedback:

npx oss-signal --list-rules

For the full first-run path, see docs/quickstart.md.

oss-signal example output

Public Verification

If you are evaluating the project itself, the public verification path remains available without interrupting the normal user flow:

Need Link
Shortest verification path REVIEWER_PACKET.md
Current post-submission status docs/selection-update-2026-06-21.md
Latest manual evidence refresh docs/evidence-refresh-2026-06-18.md
Evidence ledger and boundaries docs/evidence-ledger.md
Community engagement and reciprocity boundary docs/community-engagement.md
Public acknowledgements ACKNOWLEDGEMENTS.md
Adoption gap closure plan docs/adoption-gap-closure.md
Independent maintainer trial request docs/independent-workflow-run-request.md
Organic discovery playbook docs/discovery-playbook.md

Current public evidence includes oss-signal@0.10.0 on npm, SalmonPlays/oss-signal@v0.10.0 as a GitHub Action, pinned v0.10.0 workflow examples, a Marketplace listing, public CI/CodeQL/OpenSSF Scorecard/evidence workflows, PASS 16 / SKIP 0 / FAIL 0 evidence verification, one outside-maintainer-accepted PR, and one inbound external contributor PR from a public external fork. The project does not claim broad independent adoption yet.

Who It Helps

  • Maintainers who want a quick view of missing workflow signals before a release.
  • Contributors who want to open small, reviewable documentation or automation PRs.
  • Teams that need a repeatable CI artifact for repository health and maintainer-readiness.
  • Foundations or working groups that need inventory reports across multiple repositories.

Maintainer Evidence Snapshot

The shortest reviewer path is REVIEWER_PACKET.md. Public evidence for the maintainer workflow is also collected in docs/index.md, docs/quickstart.md, docs/evidence-ledger.md, docs/community-engagement.md, ACKNOWLEDGEMENTS.md, docs/trust-center.md, docs/reviewer-evidence.md, docs/adoption-evidence.md, docs/codex-for-oss-fit-gap.md, docs/adoption-gap-closure.md, docs/evidence-refresh-2026-06-18.md, docs/selection-update-2026-06-21.md, docs/independent-workflow-run-request.md, docs/adoption-kit.md, docs/maintainer-trial.md, docs/maintainer-feedback.md, docs/social-launch.md, docs/discovery-playbook.md, docs/architecture.md, docs/security-model.md, docs/json-output.md, docs/plan-output.md, docs/sarif-code-scanning.md, docs/roadmap.md, docs/post-submission-update.md, and docs/brand.md.

Why

Open-source projects often fail quietly because the maintainer workflow is undocumented. oss-signal gives maintainers a repeatable checklist they can run locally, in CI, or before asking contributors to help.

Use Cases

  • Maintainers can run it before publishing a new project.
  • Contributors can attach a report to a cleanup issue or pull request.
  • Teams can gate release readiness with --fail-under.
  • Teams can compare a saved JSON baseline and fail only when a previously passing check regresses.
  • Teams can retain JSON reports and publish a score trend without building their own dashboard first.
  • Foundations and working groups can compare repository hygiene across many projects.
  • CI maintainers can add it as a GitHub Action, show the score in the workflow summary, and publish the report as an artifact.

See docs/maintainer-playbook.md for a concrete maintainer workflow from audit to issue, PR, CI gate, and Code Scanning evidence.

Install

npm install --global oss-signal

Try it without installing:

npx oss-signal SalmonPlays/oss-signal

Use it from GitHub Marketplace: https://github.com/marketplace/actions/oss-signal

For local development:

git clone https://github.com/SalmonPlays/oss-signal.git
cd oss-signal
npm install
npm test

Usage

Audit the current directory:

oss-signal

Show a one-screen maintainer triage summary:

oss-signal SalmonPlays/oss-signal --format summary

Show the rule catalog and scoring weights:

oss-signal --list-rules
oss-signal --list-rules --format json --output rules-catalog.json

Audit a public GitHub repository without cloning it:

oss-signal https://github.com/SalmonPlays/oss-signal
oss-signal platformatic/massimo --format json

Write a Markdown report:

oss-signal /path/to/repo --format markdown --output oss-signal-report.md

--output creates parent directories when needed, so paths such as reports/nightly/oss-signal.md work without pre-creating reports/nightly.

Use JSON in automation:

oss-signal . --format json --fail-under 80

Save a known-good report, then protect it from maintainer-readiness regressions:

oss-signal . --format json --output oss-signal-baseline.json
oss-signal . --format json --baseline oss-signal-baseline.json --fail-on-regression

New rules are reported as newChecks and do not fail the regression gate. A regression means the same rule passed in the baseline and fails now.

Summarize retained JSON reports as a score trend:

oss-signal --trend docs/examples/trend-reports.txt --format markdown --output trend-report.md
oss-signal --trend docs/examples/trend-reports.txt --format json --output trend-report.json

Trend reports sort retained reports by generatedAt, show first-to-latest score movement, and list adjacent regressions, improvements, and volatile checks.

JSON recommendations include priority, impact, category, suggestedFile, and verifyCommand fields so dashboards and cleanup bots can route the next maintainer action without parsing prose.

Write CI-friendly key-value output when a shell step only needs the score contract:

oss-signal . --format env --output oss-signal.env

The env format writes stable OSS_SIGNAL_* keys such as OSS_SIGNAL_SCORE, OSS_SIGNAL_GRADE, OSS_SIGNAL_EARNED_WEIGHT, and OSS_SIGNAL_AVAILABLE_WEIGHT. Inventory mode supports the same format with average score plus aggregate counts and weighted totals.

Print a compact shell-friendly score summary from JSON (jq optional):

oss-signal . --format json | jq -r '"score=\(.score) grade=\(.grade) points=\(.summary.earnedWeight)/\(.summary.availableWeight)"'

See docs/json-output.md for the JSON schema and fixture.

Document intentional exceptions with a local config:

oss-signal . --config .oss-signal.json --format markdown

See docs/configuration.md for not-applicable rules and scoring behavior.

Audit multiple repositories from one newline-delimited inventory file:

oss-signal --inventory docs/examples/inventory-targets.txt --format markdown --output inventory-report.md

See docs/examples/inventory-report.md for a generated inventory report.

Write SARIF for GitHub Code Scanning or other dashboards:

oss-signal . --format sarif --output oss-signal.sarif

See docs/sarif-code-scanning.md for the Code Scanning upload workflow and expected output.

Generate a report that can be attached to an issue:

oss-signal . --format markdown --output docs/maintainer-readiness.md

Generate a maintainer-friendly issue body:

oss-signal platformatic/massimo --format issue --output maintainer-follow-up.md

Generate a PR-sized maintainer plan:

oss-signal platformatic/massimo --format plan --output maintainer-plan.md

See docs/plan-output.md and docs/examples/github-plan.md for an example.

Generate a maintainer adoption pack:

oss-signal platformatic/massimo --format adoption --output adoption-pack.md

The adoption pack combines a local trial command, no-fail workflow YAML, suggested maintainer message, decision checklist, current findings, verification links, and boundaries against overstating adoption.

Generate a no-fail GitHub Actions trial workflow:

oss-signal owner/repo --format workflow --output .github/workflows/oss-signal-trial.yml

See docs/maintainer-trial.md and docs/examples/maintainer-trial-workflow.yml for the generated workflow.

Checks

oss-signal currently checks:

  • Community files: README, license, contributing guide, security policy, code of conduct, changelog, support policy, maintainer ownership
  • Automation: CI workflows, tests, issue templates, pull request template, Dependabot, CodeQL or similar security workflow
  • Package hygiene: package metadata and lockfile presence

See docs/rules.md for rule details and scoring weights.

SARIF output reports failed maintainer-readiness checks as warning-level results. This lets teams upload the audit to code scanning dashboards while keeping the Markdown report available for maintainers. Issue output turns the same findings into a human-reviewed checklist that can be edited before posting. Plan output turns the findings into a PR-sized sequence with suggested files and acceptance criteria.

For GitHub URL audits, oss-signal reads the repository file tree through the GitHub API and also uses GitHub's community profile signal when available. This lets it detect organization-level files such as a shared code of conduct.

Real Output

This repository audits itself at 100/100 (A) and dogfoods the public GitHub Action:

Score: 100/100 (A)

Summary:
- Passed: 16
- Failed: 0
- Total checks: 16

See docs/self-audit.md for the full local self-audit report, docs/examples/github-url-report.md for the GitHub URL audit output, docs/examples/github-summary.txt for compact summary output, docs/examples/github-issue-body.md for issue output, docs/examples/github-plan.md for plan output, docs/examples/maintainer-trial-workflow.yml for workflow output, docs/examples/adoption-pack.md for adoption-pack output, docs/examples/self-audit.sarif for SARIF output, docs/examples/trend-report.json for trend output, and docs/examples/rules-catalog.json for the machine-readable rule catalog.

The Repository health workflow runs the pinned v0.10.0 release commit, uploads the Markdown report and adoption pack as artifacts, includes a SHA256 checksum manifest, and uploads SARIF to GitHub Code Scanning on non-PR runs. The Repository inventory workflow runs the inventory mode from CI and uploads a multi-repository report artifact.

Field Audits

oss-signal has been run against public repositories to produce maintainer-readiness reports, respectful issue drafts, and focused follow-up PRs:

See docs/outreach for the reports and draft issue text. Drafts are not posted automatically; maintainers should only receive specific, useful, and respectful suggestions.

Historical audit reports for Grovanni/oss-signal and noctemlabs/signal-oss remain in the repository as examples, but their public issue or PR links were not verifiable on 2026-06-08 and are not counted as current public evidence.

Additional prepared outreach candidates are tracked in docs/outreach/peer-shortlist-2026-06.md. The shortlist explicitly separates respectful, defensible candidates from low-signal mass outreach.

Additional focused external contribution evidence: icoretech/codex-action PR #24 was merged by an outside maintainer and updates Codex Action README examples to route generated output through environment variables before printing it from shell steps. oss-signal PR #14 was opened by an outside contributor and merged into this repository with a compact JSON score example.

For a compact maintainer/adoption summary, see docs/adoption-evidence.md. For a reviewer-oriented verification path, see docs/reviewer-evidence.md.

Historical self-owned workflow evidence: SalmonPlays/oss-signal-adoption-demo ran SalmonPlays/oss-signal@v0.8.4 and produced a successful workflow run with Markdown, SARIF, Issue-ready, and no-fail workflow artifacts. It is retained as historical public workflow evidence, not as current v0.10.0 adoption evidence.

Example Recommendation Output

Score: 86/100 (B)

Recommended next steps:
- Static security analysis: Add a CodeQL or equivalent security scanning workflow.
- Support policy: Add SUPPORT.md describing where to ask questions.

See docs/examples/minimal-repo-report.md for a small repository example with missing maintainer files.

Exit Codes

By default, oss-signal exits with 0 after writing a report.

When --fail-under <score> is provided, it exits with 1 if the score is below the 0-100 threshold:

oss-signal . --fail-under 80

--max-files must be a positive integer when provided.

When --fail-on-regression is used with --baseline <report.json>, it exits with 1 if a check that passed in the baseline now fails:

oss-signal . --baseline oss-signal-baseline.json --fail-on-regression

The report is still written before either gate exits nonzero, so CI can publish it as evidence.

GitHub Action

Add oss-signal directly to a GitHub Actions workflow:

- uses: SalmonPlays/oss-signal@1bb4418e14be225b5f5b628986ea464241caf7f1 # v0.10.0
  id: oss-signal
  with:
    fail-under: "80"
    output: oss-signal-report.md
    summary: "true"
- run: echo "score ${{ steps.oss-signal.outputs.score }} (${{ steps.oss-signal.outputs.earned-weight }}/${{ steps.oss-signal.outputs.available-weight }} weighted points)"

The Action exposes score, grade, passed, failed, not-applicable, total, earned-weight, available-weight, total-weight, not-applicable-weight, regressions, score-delta, and report-path outputs. Inventory mode uses the average for score and totals for counts and weighted points. Baseline outputs are zero or empty when comparison is disabled. The Action also writes a concise GitHub Actions step summary by default, so reviewers can see the score and recommended next steps without downloading an artifact. Set summary: "false" to disable it.

Protect a committed known-good baseline without forcing every repository to reach an arbitrary score first:

- uses: SalmonPlays/oss-signal@1bb4418e14be225b5f5b628986ea464241caf7f1 # v0.10.0
  id: oss-signal
  with:
    format: json
    baseline: .github/oss-signal-baseline.json
    fail-on-regression: "true"
    output: oss-signal-report.json
- run: echo "${{ steps.oss-signal.outputs.regressions }} regressions, score delta ${{ steps.oss-signal.outputs.score-delta }}"

Baseline comparison also appears in the step summary.

oss-signal GitHub Actions summary

Run an inventory from CI:

- uses: SalmonPlays/oss-signal@1bb4418e14be225b5f5b628986ea464241caf7f1 # v0.10.0
  env:
    GITHUB_TOKEN: ${{ github.token }}
  with:
    inventory: docs/examples/inventory-targets.txt
    output: inventory-report.md
    summary: "true"

Publish a retained-report trend from CI:

- uses: SalmonPlays/oss-signal@5f98a7c560b90dbd1ba87dd0222bae331e0993c9 # trend feature snapshot
  with:
    trend: docs/examples/trend-reports.txt
    format: markdown
    output: oss-signal-trend.md
    summary: "true"

Generate an editable Issue body from CI:

- uses: SalmonPlays/oss-signal@1bb4418e14be225b5f5b628986ea464241caf7f1 # v0.10.0
  with:
    format: issue
    output: maintainer-follow-up.md
    summary: "true"

Full workflow example:

name: Repository health

on:
  pull_request:
  push:
    branches: [main]

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"

jobs:
  oss-signal:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
        with:
          persist-credentials: false
      - uses: SalmonPlays/oss-signal@1bb4418e14be225b5f5b628986ea464241caf7f1 # v0.10.0
        id: oss-signal
        with:
          fail-under: "80"
          output: oss-signal-report.md
          summary: "true"
      - name: Write artifact checksum manifest
        run: sha256sum oss-signal-report.md > oss-signal-artifact-sha256.txt
      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: oss-signal-report
          retention-days: 14
          path: |
            oss-signal-report.md
            oss-signal-artifact-sha256.txt

See docs/examples/github-action-workflow.yml for a copyable workflow, docs/examples/github-inventory-workflow.yml for an inventory workflow, docs/examples/github-trend-workflow.yml for a retained-report trend workflow, and docs/examples/github-code-scanning-workflow.yml for a workflow that uploads SARIF to GitHub Code Scanning.

Upload SARIF to GitHub Code Scanning:

permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
    with:
      persist-credentials: false
  - uses: SalmonPlays/oss-signal@1bb4418e14be225b5f5b628986ea464241caf7f1 # v0.10.0
    with:
      format: sarif
      output: oss-signal.sarif
      summary: "true"
  - uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4
    with:
      sarif_file: oss-signal.sarif

This repository dogfoods the public v0.10.0 release commit in Repository health, which runs SalmonPlays/oss-signal@1bb4418e14be225b5f5b628986ea464241caf7f1 against the repository, uploads Markdown and adoption-pack artifacts with a SHA256 manifest, and publishes SARIF to Code Scanning on non-PR runs.

You can also run the CLI directly in CI:

- run: npx oss-signal . --format markdown --output oss-signal-report.md --fail-under 80

Current Limitations

  • It checks deterministic maintenance signals, not code quality or project importance.
  • GitHub URL mode uses unauthenticated API requests unless GITHUB_TOKEN is set, so very heavy usage may hit GitHub rate limits.
  • A high score does not prove a project is important. It proves the maintainer workflow is documented and automatable.

Roadmap

  • Ecosystem-specific profiles for Python, Rust, Go, and JavaScript packages
  • Release automation and provenance metadata checks
  • Richer maintainer score visualizations over retained reports
  • Organization-level repository inventory dashboards

Release Process

Releases use the checklist in docs/release-process.md. The repository also includes a tag-triggered release workflow that verifies the package, creates a GitHub Release, and publishes to npm with Trusted Publishing provenance.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

Security

Please report security issues privately. See SECURITY.md.

License

MIT

About

Maintainer-readiness CLI and GitHub Action for OSS triage, CI evidence, inventory reports, SARIF, and issue-ready cleanup.

salmonplays.github.io/oss-signal/

Topics

cligithub-actionmaintainer-toolsopen-sourceossrepository-healthsariftriage

Resources

Readme
MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

2 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

Used by

Contributors

Languages