RepoLens

RepoLens fails a pull request that adds a new maintenance problem to a Node repository on GitHub Actions: an unpinned action, a write-scoped token, a test, lint or build script that CI never runs, a lockfile that disagrees with package.json, a gap in Dependabot. Problems that already exist are reviewed once and recorded in a baseline, so they don't block anyone.

Product guide: https://repolens.whago.net/

RepoLens and OpenSSF Scorecard

Scorecard checks several of the same things. The difference is what each one reports.

	RepoLens	OpenSSF Scorecard
Reports	Only what this pull request made worse than the reviewed baseline	A 0 to 10 rating for the whole repository
Existing problems	Accepted once with a reason, owner and expiry	Counted on every run
Who can accept a problem	The baseline is read from the base branch, so a pull request cannot approve its own regression	Not applicable
Checks both have	Pinned actions, token permissions, Dependabot coverage	Pinned-Dependencies, Token-Permissions, Dependency-Update-Tool
Only here	test/lint/build scripts reachable from a PR workflow, package.json and lockfile agreement (npm, pnpm, Yarn, Bun), tracked .env files	Branch protection, code review, maintenance activity, signed releases, fuzzing, SAST
Output	Annotations on new findings, job summary, SARIF	SARIF, badge, public results API

Use Scorecard for the overall picture and RepoLens as the merge gate that keeps a pull request from making it worse.

The website is documentation only. Repository inspection runs in the CLI or the pinned GitHub Action; nothing is uploaded.

Install

Node.js 20.11 or newer. RepoLens is not on the npm registry; install the package tarball from a GitHub Release, which also carries its SHA-256 digest and a build attestation:

npm install --global \
  https://github.com/rad1092/repolens/releases/download/v0.4.0/rad1092-repolens-0.4.0.tgz
repolens --version

v0.4.0 is not published yet. Until it is, install https://github.com/rad1092/repolens/releases/download/v0.3.0/rad1092-repolens-0.3.0.tgz, which reads npm lockfiles only.

The unscoped repolens name on npm belongs to another project.

Start the gate

Run setup once from a committed Git repository:

repolens setup .

Setup writes exactly three files:

• .repolens.json — rule policy and reviewed exceptions
• .repolens/baselines/accepted.json — compact baseline schema v3
• .github/workflows/repolens.yml — SHA-pinned pull-request gate

The baseline records who accepted the current findings, why, and until when. By default the owner is your git config user.name, the reason is an initial review note and the acceptance expires in 90 days. Teams can set them:

repolens setup . \
  --owner "Platform team" \
  --reason "Existing findings reviewed in maintenance review 42" \
  --expires 6m

--expires takes an RFC 3339 time or a duration such as 30d, 12w, 6m or 1y. The generated workflow reads its gate policy from .repolens.json instead of duplicating it, and pins the RepoLens Action to the commit behind this release's tag. To pin a different reviewed commit, pass --action-sha <40-character-sha>.

Review the files, then commit them in a change separate from future debt acceptance:

git add .repolens.json .repolens .github/workflows/repolens.yml
git commit -m "chore: enable RepoLens maintenance gate"

Confirm that the configuration, baseline, and baseline commit are usable:

repolens doctor .
repolens baseline check . --offline

On pull requests, the Action reads the baseline from the base branch. A pull request cannot edit that baseline and use the edit to approve its own regressions.

What it validates

RepoLens v0.4 covers a small contract:

Rule area	Validation
GitHub Actions	YAML parses; a pull-request trigger exists; token permissions are explicit and read-only
Action supply chain	Third-party uses: references are pinned to full commit SHAs
CI wiring	Real test, lint, and build scripts are reachable from a pull-request workflow through npm, pnpm, yarn or bun run
Node manifest	package.json parses and verification scripts are not placeholders
Lockfile	The lockfile of the package manager in use (package-lock.json, pnpm-lock.yaml, yarn.lock or text bun.lock) parses, agrees with package.json, and has an entry for every direct dependency. packageManager in package.json decides which one is expected. Binary bun.lockb is not read
Dependency automation	Dependabot v2 parses and covers npm (or bun) plus GitHub Actions at the repository root
Credential filename risk	Tracked .env-style files are reported without reading or printing their values
Update context	Declared, locked, latest, and change type are shown for the updater to review

A file merely existing never counts as proof that it works. RepoLens parses the configuration and traces script wiring, but labels configured commands as configured-not-executed.

Use dedicated tools for the analysis they own:

• OpenSSF Scorecard for an overall security posture rating
• actionlint for complete GitHub Actions linting
• zizmor for GitHub Actions security analysis
• CodeQL, Semgrep, or SonarQube for source analysis
• Trivy or another vulnerability scanner for known vulnerabilities
• Dependabot or Renovate for update proposals

Baselines and exit codes

The baseline stores only actionable finding identities plus:

• the reviewer and reason
• acceptance and expiration timestamps
• the Git commit on which the review was based

It is not a saved presentation report and it never updates implicitly.

repolens baseline accept . \
  --reason "Remaining findings reviewed in maintenance review 42" \
  --owner "Platform team"

This is the beginning of the README. Read the rest at the original. Read the full README ↗