OSSRank

A static-first public data product for finding top GitHub contributors by country using simple public metrics: commits, public pull requests, repositories, and followers.

OSSRank is designed for https://ossrank.dev/. Set OSSRANK_SITE_URL in Cloudflare Pages if the production host changes so generated canonical URLs, Open Graph URLs, robots.txt, and sitemap.xml stay aligned with the live domain. V1 includes a conservative live GitHub REST/GraphQL collector plus fixture mode for deterministic tests. The primary user flow is home page country selection → country contributor table, sorted by commits by default and sortable by public PRs, repo count, or followers. A single projects page is included separately.

What it builds

• A polished static website in dist/ ready for Cloudflare Pages.
• Generated SEO assets: per-route canonical URLs, Open Graph/Twitter metadata, robots.txt, sitemap.xml, Cloudflare Pages _headers, and duplicate-route _redirects.
• Versioned JSON snapshots under data/latest/ and immutable run snapshots under data/runs/<date>/.
• A public manifest at /data/latest/manifest.json with completed shards, failed shards, stale pages, API mode, duration, and source commit.
• A focused country-selection homepage, country contributor pages, one projects page, methodology, badges, and raw JSON.
• GitHub Actions for validation, weekly refresh, daily hot-page refresh, and manual shard refresh.

Current routes

• /
• /countries/australia/top-github-contributors/
• /countries/australia/ redirects to /countries/australia/top-github-contributors/
• /global/
• /projects/
• /agentic/
• /momentum/
• /rising/
• /sitemap.xml
• /robots.txt
• /methodology/
• /badges/users/octo-kiwi/au.svg
• /data/latest/manifest.json

Data contract

Each ranking snapshot includes:

• kind, slug, name, and title
• generated_at, fresh_until, and status
• method, source_run, and candidate_count
• explicit caveats
• compact history
• ranked entries

The public site copies data/latest/* into dist/data/latest/* so pages and API-like JSON stay in sync.

Local development

pnpm install
pnpm test
pnpm run build

Useful scripts:

pnpm run refresh:fixtures   # create deterministic demo snapshots
pnpm run refresh:live       # collect live GitHub API snapshots using OSSRANK_GITHUB_TOKEN
pnpm run validate:data      # validate manifest + shard integrity
pnpm run build              # generate dist site
pnpm run release:check      # run the full local release gate
pnpm run deploy:cloudflare  # deploy dist with Wrangler
bash scripts/validate.sh    # StackForge validation wrapper

Live refreshes use GitHub GraphQL search and contribution APIs. GitHub Actions' default GITHUB_TOKEN is an integration token and can return Resource not accessible by integration; configure a repository secret named OSSRANK_GITHUB_TOKEN with a classic or fine-grained PAT that can read public repository/user metadata.

pnpm run release:check runs the fixture refresh, data validation, static site build, CLI smoke, test burst verification, type checks, and npm pack --dry-run.

CLI usage

After pnpm run build:cli, run deterministic ranking checks against the bundled fixtures:

node dist-cli/cli.js rank contributors --input fixtures/contributors.json --limit 5 --format table
node dist-cli/cli.js rank projects --input fixtures/projects.json --limit 5 --format json

For live refreshes, provide a GitHub token through OSSRANK_GITHUB_TOKEN and start with a small limit:

OSSRANK_LIMIT=20 pnpm run refresh:live
node dist-cli/cli.js token-check --require-graphql-search

Live refreshes write the same data/latest snapshot contract used by the static site. Review the generated manifest and caveats before publishing or deploying refreshed data.

GitHub Actions secrets and environment

Configure these repository secrets before running refresh/deploy workflows:

• OSSRANK_GITHUB_TOKEN — GitHub PAT used by weekly/manual live refresh. Needs read-only access to public repository/user metadata and GraphQL search/contribution APIs.
• CLOUDFLARE_ACCOUNT_ID — Cloudflare account id for Pages deploys. Stored as a secret so the public repo does not hardcode account metadata.
• CLOUDFLARE_API_TOKEN — Cloudflare API token for Wrangler Pages deploys. Scope it to the ossrank Pages project where possible.

Optional runtime/build variables:

• OSSRANK_SITE_URL — canonical production URL, defaults to https://ossrank.dev.
• OSSRANK_LIMIT — candidate limit for live refresh runs; workflow dispatch defaults to 20.

Cloudflare Pages

wrangler.toml sets pages_build_output_dir = "dist" and the deploy script runs:

wrangler pages deploy dist --project-name ossrank

For a connected Git deployment, configure Cloudflare Pages with:

• Build command: pnpm run build
• Build output directory: dist
• Node version: 22
• Environment variable: OSSRANK_SITE_URL=https://ossrank.dev

Methodology guardrails

OSSRank must stay honest:

• Use official GitHub APIs only; never scrape GitHub HTML.
• Treat GitHub profile location text as unverified free text.
• Rank observed public signals, not private contributions. Contributor pages prioritize one-year GitHub GraphQL commit totals, one-year public pull request totals, repository count, and followers. Raw commit totals stay visible, but ranking uses a per-user burst-adjusted commit signal when a short anomalous daily spike exceeds that contributor's adaptive baseline cap.
• Preserve last-known-good data when refreshes fail.
• Keep the product flow simple: choose a country, view contributors, sort by commits/public PRs/repos/followers, or view the single projects page.
• Avoid claims of complete global coverage, endorsement, nationality, employment status, or identity attributes.

Roadmap

• Add deeper GitHub GraphQL contribution and pull-request collection with low-concurrency backoff and checkpoint/resume.
• Generate contributor detail pages and full project badges.
• Add compact historical charts and route tests for ambiguous aliases.
• Connect ossrank.dev to Cloudflare Pages.

Contributing

See CONTRIBUTING.md. Changes should be small, reviewable, and verified before review.

License

MIT

Verification

Run these checks before opening a PR or publishing a release:

pnpm test
pnpm run package:smoke
pnpm run release:check