Context
GitHub is the source of truth for engineering evidence. The site must never show a claim that the referenced repository does not support at the exact commit cited. It also must not depend on the GitHub API while serving pages.
Options
- Runtime GitHub API calls. Rate limits, fragility and a different answer every day.
- Git submodules. Friction for reviewers, and no validation step.
- Pinned locks, vendored at sync time and validated at build time.
Decision
content/sources.lock.json pins each source repository to a tag and commit SHA. Changing it requires a
reviewed pull request. Sources come in two kinds:
- release-asset: the source repository's release workflow publishes
evidence.lock.jsonwith the verified commit and CI run. The sync downloads it, checks its identity and re-checks every CI run against the GitHub API. - curated: for repositories that do not publish a lock yet, a manifest lives in this repository. The sync verifies every path and every named test function at the pinned commit, and records the real CI conclusion.
The sync uses an HTTPS host allowlist, follows redirects manually and re-checks each one, sends
credentials only to api.github.com, caps response sizes and rejects path traversal. Vendored files are
committed with their hashes. The build is offline and re-checks every hash, so a hand edit fails the
build.
Consequences
- Moving a tag or editing a vendored file fails CI.
- A claim reaches TESTED only if CI at the pinned commit actually succeeded. Having a CI job is not enough.
- Updating evidence means one bot or human pull request per source release.