Add an Evidence-Backed Repository Listing to Harness Maturity Showcase

If you publish a maturity score for an open-source repository, readers need more than a number. They need to know which commit was measured, which scanner produced the result, and where the raw evidence can be inspected.

Harness Maturity Showcase is a small static site that makes those checks visible. It stores repository listings as data, links each listing to public evidence, and validates the rules in CI. This tutorial shows how to add one reproducible full report without changing the site's ranking code.

TL;DR

You will scan a public repository with the published harness-score package, commit the generated JSON report to that repository, add one record to data/projects.json, and run the showcase's deterministic checks. The important part is the evidence chain: repository, measured commit, scanner version, score, and public report must agree.

Prerequisites

You need:

• Git and a GitHub account.
• Node.js 20 or newer. The showcase declares node >=20.
• A public GitHub repository that you are allowed to scan and modify.
• Permission to open a pull request in your fork of the showcase.

The showcase is MIT-licensed. It is a static HTML, CSS, and JavaScript site with no runtime dependencies. Its own checks run with Node's built-in test runner.

Understand the two contribution paths

The project supports two kinds of entry. A full report participates in the numeric ranking. It includes score, maxScore, level, toolVersion, a measured commit SHA, and a link to a committed JSON report.

A badge-only entry is different. It records a public maturity claim from a repository README, but it does not claim a numeric score. The validator rejects badge entries that include score or maxScore.

Use the full-report path when you can publish the scanner output and identify the exact commit. Use badge-only when the repository displays an official badge but does not publish a full report. Do not turn a badge claim into a measured result by inference.

1. Start from a clean checkout

Create a working copy of the repository you want to measure. The scanner reads files, so the result should be tied to a commit that another person can retrieve later.

git clone https://github.com/your-name/your-project.git
cd your-project
git checkout --detach YOUR_COMMIT_SHA
git rev-parse HEAD

Record the 40-character SHA printed by the final command. The showcase compares reports within the same scanner version and stores the measured commit for reproducibility.

The current showcase refresh documents the same rule: reports are pinned to public default-branch commits, and future refreshes use a new dated directory instead of rewriting historical evidence.

2. Generate the report with the published scanner

Run the published package from outside the repository checkout. The documented command writes JSON to standard output and leaves the scanned project unchanged.

mkdir -p reports
npx --yes harness-score@1.8.1 /path/to/pinned-checkout --json > reports/harness-score.json

On Windows PowerShell, the equivalent redirection is:

New-Item -ItemType Directory -Force reports | Out-Null
npx --yes harness-score@1.8.1 C:\path\to\pinned-checkout --json | Out-File -Encoding utf8 reports\harness-score.json

Use the version that you actually ran in the showcase record. Do not copy a score from a different scanner version. The current release reports version 1.8.1, and the package requires Node.js 18 or newer; the showcase itself requires Node.js 20 or newer.

Inspect the report before committing it. Confirm that its tool.version, level, score, maximum score, and measured commit describe the checkout you intended to scan.

3. Publish the evidence in the scanned repository

Commit the report to the repository you measured. A simple layout is enough:

.
└── harness-score.json

git add harness-score.json
git commit -m "Add Harness Score evidence"
git push origin YOUR_BRANCH

The report URL in the showcase must be public and stable, for example:

https://github.com/your-name/your-project/blob/main/harness-score.json

If you measure a historical commit, link to the report at that commit or to a branch that preserves the exact JSON. A link that later changes to a different report weakens the evidence chain.

4. Add one full-report record

Fork the showcase, edit data/projects.json, and add one object. The contribution guide requires source: "study" for a full report.

{
  "repo": "your-name/your-project",
  "category": "community",
  "level": 3,
  "score": 82,
  "maxScore": 105,
  "toolVersion": "1.8.1",
  "commit": "0123456789abcdef0123456789abcdef01234567",
  "source": "study",
  "evidence": "https://github.com/your-name/your-project/blob/main/harness-score.json"
}

Replace every illustrative value with the corresponding value from your report. The repository name must use owner/name syntax, and each repository may appear only once. The commit must be a complete 40-character hexadecimal SHA.

The category field is part of the site's data model, while the validator focuses on the repository name, source, numeric fields, commit, scanner version, and evidence URL. Keep the record small and avoid adding claims that the report does not contain.

5. Validate before opening the pull request

From the showcase checkout, install its lockfile and run the documented check:

npm ci
npm run check

The check script runs npm run validate and npm test. Validation checks repository names, duplicates, levels from 0 through 4, numeric bounds, scanner versions, complete commit SHAs, public GitHub evidence links, and the badge-only rules.

The test suite checks the page structure, report reproducibility links, scanner-version boundaries, historical rankings, and the separation between full reports and badge-only entries. A passing check confirms the repository's data and site invariants. It does not replace human review of the evidence URL.

Open a focused pull request that changes one listing. Maintainers verify that the linked evidence is public and that the values in data/projects.json match it. If the measured repository changes substantially, generate a new report rather than silently editing the old one.

Why the evidence model matters

A score without a commit is hard to reproduce. A score without a scanner version is hard to compare. A score without a public report asks reviewers to trust a summary they cannot inspect.

The showcase keeps those concerns separate. Rankings are scoped to a scanner version, full reports point to immutable evidence, and badge-only records stay outside numeric ranking. This makes a lower score interpretable: it may reflect the repository, the scanner version, or the measured commit, and the data tells you which inputs to investigate.

The same design also limits what the site can claim. A passing GitHub Actions job proves that the data satisfies structural checks. It does not prove that a repository is secure, production-ready, or better than another project in every engineering dimension.

Failure modes and honest limits

The report is rejected because the commit is invalid

Check that commit contains exactly 40 hexadecimal characters. Do not use a short SHA, a branch name, or the commit that happened after the scan.

A full report does not appear in the ranking

Confirm that source is study, that toolVersion is a semantic version, and that score and maxScore are numbers within bounds. Badge-only entries intentionally do not receive numeric ranking.

The score changed after a refresh

Compare the scanner version, measured commit, and repository contents. The project documents that changes between scanner versions or repository revisions are not, by themselves, evidence of improvement or regression.

The site check passes but the evidence is wrong

This is a review failure, not a validator failure. Open the evidence URL, compare the JSON fields with the record, and verify that the URL is public before asking for review.

Security boundary

The scanner is a read-only file inspection tool for this workflow, but running any package still deserves normal supply-chain care. Pin the version in reproducible instructions, review the package source and lockfile policy appropriate to your environment, and do not scan private repositories or publish sensitive report contents without authorization.

FAQ

Can I submit a private repository?

No. The evidence URL must be public, and the showcase is designed for inspectable open-source data.

Can I submit a score from an older Harness Score version?

Yes, when the report and metadata satisfy the schema, but rankings are separated by scanner version. Use the current published version for a new contribution unless you have a reason to preserve historical evidence.

Does a passing score make a repository mature?

It measures the checks implemented by Harness Score. It does not certify software quality, security, or operational readiness.

Can I add several repositories in one pull request?

The contribution guide asks contributors to keep a submission focused on one repository. Follow that review boundary unless maintainers ask for a batch change.

Takeaway

The useful unit is not a maturity number. It is a number connected to a scanner version, a measured commit, a public report, and a validation path that another contributor can repeat.

If you maintain an open-source repository with an official Harness Score result, submit the smallest complete evidence record you can defend. What additional evidence would make a maturity listing more useful to you: historical snapshots, CI status, or a clearer explanation of each check?

AI assistance disclosure: I used AI assistance to organize and edit this tutorial. The commands, project behavior, version claims, and validation results were checked against the cited repository, its current documentation, and the published package metadata.