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.
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
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.
GitHub token: a personal access token, an OAuth token or an App installation token. Exactly one of
token and app is set.A GitHub App installation mirage mints and refreshes tokens for. Exactly one of
token and app is set.Branch, tag or commit SHA the mount reads. Unset uses the repository’s default branch, resolved on first use.
Authentication
The mount takes exactly one oftoken and app.
- Token: a fine-grained personal access token with read-only Contents
on the repository, or a classic token with the
reposcope for a private repository. A public repository still needs a token; one with no scopes reads it. - 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.repositoriesandpermissionsnarrow every token it mints.
\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
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
ghCLI. - Fresh reads: under
read: fresh, each command checks the head commit ofrefonce. Arefthat 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,findand the other walks stop after 5000 files and keep what they printed. A glob matching more,tar -c,cp -r,rm -rand the other whole-tree commands are refused above it.
Browser
The browserGitHubVFS from @struktoai/mirage-browser takes the same fields.
- The token 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 -rwandrg -w: GitHub code search names the files to read when 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 -Randtree: one recursive tree listing.