git-providers

One interface across GitHub, GitLab, and Bitbucket — user info, repos, and branches, SSRF-guarded.

github → MIT the foundation git api

01What it is

If you build a tool that integrates with "your git provider," you don't actually want three implementations. GitHub, GitLab, and Bitbucket Cloud each have their own REST shape, their own pagination, their own OAuth dance. git-providers folds all three behind a single GitProvider interface, so the same call returns the same shape no matter which forge it hit.

You ask the registry for a provider by name and it hands you the right adapter at runtime — switch from GitHub to GitLab without rewriting your integration. User info, repos, and branches come back normalized; OAuth config reads from the environment or from options you pass. Zero runtime dependencies, native fetch, and the URL construction that touches user input is hardened against SSRF.

git-providers · one shape

// one interface, any forge
const provider = getProvider('github');
const user  = await provider.getUserInfo(token);
const repos = await provider.listRepos(token);
const brs   = await provider.getBranches(
  token, 'askalf/git-providers');

Fig. 1 — the same three calls across GitHub, GitLab, and Bitbucket.

02What it does

One interface across three forges

GitHub, GitLab, and Bitbucket Cloud each implement the same GitProvider interface. User info, repos, and branches come back in one normalized shape — fullName, cloneUrl, defaultBranch, isPrivate — so your code stops caring which provider it's talking to. The owner/name form is used everywhere; the GitLab adapter URL-encodes it to the v4 API's namespace%2Fproject form internally.

A registry that picks the adapter at runtime

Call getProvider('gitlab') and you get the right client back; isValidProvider() narrows an untrusted string from a request body to a known provider before you use it. Switch forges by changing a name, not by rewriting your integration.

OAuth config, from env or from options

Each provider exposes a getXxxOAuthConfig() helper that returns clientId, clientSecret, authorizeUrl, tokenUrl, and scopes. With no arguments it reads <PROVIDER>_CLIENT_ID / <PROVIDER>_CLIENT_SECRET from the environment and returns null if either is missing; pass options to bypass env entirely.

Self-hosted, with SSRF-guarded URLs

Point a custom adapter at GitHub Enterprise Server or self-hosted GitLab with a baseUrl override. Where part of a URL is built from user input — the api-key taxonomy's Jira and Grafana checks — the host is forced through a parser and protocol allowlist, and rejected when it is or DNS-resolves to a loopback, RFC-1918, link-local, CGNAT, or unique-local address.

Tiny, dependency-free, MIT

Around 600 lines of TypeScript, zero runtime dependencies, native fetch. A separate sub-export ships a 40+ entry catalog of API-key (non-OAuth) providers for apps that let users bring their own credentials. MIT-licensed.

03Where it sits

Part of The Foundation.

git-providers abstracts the forge; The Foundation is the datastores and drivers underneath, built to run with a server in production or in-process with none.

pgflex

One Postgres API, two modes — real PG or in-process PGlite.

redisflex

One Redis API, two modes — ioredis or an in-process stand-in.

One interface. Any forge.

git-providers is open source and MIT-licensed. Read the code, read the interface, run it on your own box.

View git-providers on GitHub →