Skip to main content
GitHubVFS mounts one repository at a branch, tag or commit as read-only files, read through GitHub’s REST API. Set up the token as in GitHub setup; a public repository needs none.

Install

Configure

GitHubVFS.create is awaited: it fetches the repository tree before it returns. Unset ref uses the repository’s default branch. Set baseUrl for GitHub Enterprise. A GitHub App can replace token; see Authentication.

Fields

number
default:"DEFAULT_TIMEOUT"
Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
string
secret
GitHub token: a personal access token, an OAuth token or an App installation token. At most one of token and app is set; with neither, the mount reads a public repository anonymously.
A GitHub App installation mirage mints and refreshes tokens for. At most one of token and app is set; with neither, the mount reads a public repository anonymously.
string
required
Repository owner, a user or an organization.
string
required
Repository name.
string
Branch, tag or commit SHA the mount reads. Unset uses the repository’s default branch, resolved on first use.
string
default:"'https://api.github.com'"
GitHub API root; set it for GitHub Enterprise.
Fields marked secret are redacted in snapshots.

Authentication

The mount takes at most one of token and app.
  • None: with neither, the mount reads a public repository anonymously. File reads come from raw.githubusercontent.com at the commit the tree listing named, so they do not count against the REST API’s rate limit, and grep -rw and rg -w read every file, since code search takes no anonymous requests. The tree listing, and the default branch lookup when ref is unset, still cost REST requests: 60 an hour per IP address without credentials. On GitHub Enterprise, anonymous reads go through the REST API, one request per file.
  • Token: a fine-grained personal access token with read-only Contents on the repository, or a classic token with the repo scope for a private repository. A token raises the REST limit to 5,000 requests an hour.
  • GitHub App: with app, Mirage mints the App’s installation tokens itself and replaces each before its hour runs out, so a long-lived mount keeps reading. repositories and permissions narrow every token it mints.
The private key is the PEM GitHub generates (PKCS#1) or PKCS#8, with real newlines or \n escapes, and works in Node, the browser and Cloudflare Workers. It is a string, so nothing reads a file: pass it from an environment variable, a Worker secret, or a secret store through a pointer. An installation token cannot ask who it is, so gh repo clone NAME without an owner clones from the account the App is installed on.

Layout

The tree mirrors the repository at ref: /github/src/index.ts is src/index.ts. Owner, repo and ref are set at mount time, never in the path. stat shows each file’s git blob SHA.

Behavior

  • Read only: no command changes files. Act on the repository with the gh CLI.
  • Fresh reads: under read: fresh, each command checks the head commit of ref once. A ref that is a full commit SHA needs no check. A repository whose tree GitHub truncates re-lists each folder once per command.
  • Walk limit: each file is one request, so grep -r, find and the other walks stop after 5000 files and keep what they printed. A glob matching more, tar -c, cp -r, rm -r and the other whole-tree commands are refused above it.

Browser

The browser GitHubVFS from @struktoai/mirage-browser takes the same fields. A public repository needs no token, so a page mounts it with nothing typed:
  • Each visitor’s tree listing counts against the 60 anonymous REST requests an hour GitHub allows their IP address; file reads come from raw.githubusercontent.com and do not.
  • A private repository needs token, which reaches the page, so use a fine-grained token scoped to read-only access on one repository.
  • Keep a GitHub App’s private key on a server: in the browser the page can read it.

Integration

GitHub answers these commands through its own API, so fewer files are read. See Integration.
  • grep -rw and rg -w: GitHub code search names the files to read when the mount has a credential, the scope holds more than 100 files, the mounted ref is the default branch (the only one code search indexes), the tree was listed in full and the search returns every hit (100 at most). Otherwise every file is read. Code search can miss recent pushes, and files it never indexes are always read.
  • find: one recursive tree listing.
  • du: one recursive tree listing.
  • ls -R and tree: one recursive tree listing.