Back to docs

GitHub OAuth and repo linking

Public-reader guide to the current Proof of Ship account-linking contract.

Step 1

Sign in with GitHub

The documented flow starts at GET /auth/github/start, returns from GitHub at GET /auth/github/callback, and creates a local authenticated session keyed to the GitHub user.

Step 2

Link a public repo

A signed-in builder can link a public GitHub repository when the account is allowed to associate that repo with its profile: owner, org admin, or collaborator with push access.

Step 3

Still verify independently

OAuth and linking do not grant reputation on their own. Receipts, commits, signatures, and public artifacts still need separate verification before a score changes.

Trust boundary

  • OAuth proves identity. In v1, Proof of Ship treats GitHub as the canonical authenticated identity.
  • Repo linking proves relationship. A successful link says the account can legitimately associate that public repository with its profile.
  • Linking does not prove authorship. It does not claim sole authorship, code quality, project impact, or that every line came from the signed-in user.
  • Only public repos are in scope here. The documented payloads and examples cover public-repository linking in v1.

Current status

These routes and payloads are documented as a public contract. That means integrators can build against the route shapes and schemas, but this page does not claim a broadly deployed first-party hosted account settings UI yet.

See status map Read full spec on GitHub

Public endpoints

  • GET /auth/github/start
  • GET /auth/github/callback?code=...&state=...
  • POST /auth/logout
  • GET /api/v1/account
  • GET /api/v1/account/repositories
  • POST /api/v1/account/repositories
  • DELETE /api/v1/account/repositories/{owner}/{repo}