> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Mount a GitHub repository as a Mirage filesystem from Node or the browser.

`GitHubVFS` exposes a single repository at a ref as a read-only
filesystem. Reads stream blobs through GitHub's
[REST API](https://docs.github.com/en/rest); it does not imitate another CLI.

Setup steps for the personal access token live at [GitHub Credentials](/home/setup/github).

## Node

```bash theme={null}
pnpm add @struktoai/mirage-node
```

```ts theme={null}
import { GitHubVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const gh = await GitHubVFS.create({
  token: process.env.GITHUB_TOKEN!,
  owner: 'strukto-ai',
  repo: 'mirage',
  ref: 'main',
})

const ws = new Workspace({ '/repo': gh }, { mode: MountMode.READ })
await ws.shell('cat /repo/README.md')
```

The constructor is private: `create` fetches the repo's git tree before it
builds the VFS, so it has to be awaited. Python deliberately differs
here: `GitHubVFS(...)` is an ordinary call that contacts nothing, and
hydrates the tree on first read, which is what lets its `build_vfs`
stay synchronous.

## Browser

```bash theme={null}
pnpm add @struktoai/mirage-browser
```

```ts theme={null}
import { GitHubVFS, MountMode, Workspace } from '@struktoai/mirage-browser'

const gh = await GitHubVFS.create({
  token: GITHUB_TOKEN,
  owner: 'strukto-ai',
  repo: 'mirage',
})
```

The token reaches the browser, so use a fine-grained PAT scoped to read-only access on a single repo.

## Config

| Field | Default | Notes |
| - | - | - |
| `token` | required | Personal access token. Redacted in snapshots. |
| `owner` | required | Repo owner (user or org). |
| `repo` | required | Repo name. |
| `ref` | `HEAD` | Branch, tag, or commit SHA. |
| `baseUrl` | `https://api.github.com` | Override for GitHub Enterprise. |

## Listings under `fresh`

Under `read: fresh`, a cached listing is checked against the head commit
the `ref` resolves to: one small check per command (a shallow
`git/trees/{ref}`), after which every cached listing of the mount at that
commit is served. A mount whose `ref` is a full 40- or 64-hex commit sha
serves its cached listings with no request: github.com refuses a branch or
tag named with 40 or 64 hex characters, so such a ref always names a commit
(a GitHub Enterprise host is assumed to do the same). A repository whose recursive
tree comes back truncated stores no version, so each folder is re-listed
once per command. See
[listings under `fresh`](/home/cache#listings-under-fresh).

## Mount mode

`read`. Writes are not yet exposed.

For the mounted layout (refs, paths, blob caching) see the [Python GitHub docs](/python/vfs/github).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.