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
ref follows the repository’s default branch. Set base_url 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. 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.Repository owner, a user or an organization. Required unless the
GitHubVFS constructor is given owner.Branch, tag or commit SHA the mount reads. Unset follows the repository’s default branch, resolved on the first read.
Authentication
The mount takes at most one oftoken and app.
- None: with neither, the mount reads a public repository anonymously.
File reads come from
raw.githubusercontent.comat the commit the tree listing named, so they do not count against the REST API’s rate limit, andgrep -rwandrg -wread every file, since code search takes no anonymous requests. The tree listing, and the default branch lookup whenrefis 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
reposcope 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.repositoriesandpermissionsnarrow every token it mints.
\n escapes. It is a string, so it can come from an environment
variable, a dotenv file, 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/main.py is
src/main.py. 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. - Tree fetch: the full tree is fetched on the first read, not when the mount is built, so building a workspace contacts nothing. A repository over 100,000 entries is listed one folder at a time.
- 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,git grep,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.
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 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 -Randtree: one recursive tree listing.
VFS.md
The VFS.md an agent reads with GitHub mounted at/<path>.
- Rendered
- Raw
Virtual Filesystem
Supported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.