> ## 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 in TypeScript

> Virtualize a GitHub repository from Node or the browser.

`GitHubVFS` mounts one repository at a branch, tag or commit as read-only
files, read through GitHub's [REST API](https://docs.github.com/en/rest). Set up the token as in [GitHub setup](https://docs.mirage.strukto.ai/home/setup/github.md); a public repository needs none.

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

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

const github = await GitHubVFS.create({
  token: process.env.GITHUB_TOKEN!,
  owner: 'strukto-ai',
  repo: 'mirage',
  ref: 'main',
})
const ws = new Workspace({ '/github': github }, { mode: MountMode.READ })

const result = await ws.shell('ls /github && rg -w "def build_vfs" /github/python')
console.log(result.stdoutText)
await ws.close()
```

`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](#authentication).

### Fields

**timeout** `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.

**token** `string`

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.

**app**

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.

**owner** `string` *required*

Repository owner, a user or an organization.

**repo** `string` *required*

Repository name.

**ref** `string`

Branch, tag or commit SHA the mount reads. Unset uses the repository's default branch, resolved on first use.

**baseUrl** `string` (default: '[https://api.github.com](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.

```ts theme={null}
const github = await GitHubVFS.create({
  app: {
    appId: 123456,
    privateKey: process.env.GITHUB_APP_PRIVATE_KEY!,
    installationId: 7890123,
    repositories: ['mirage'],
    permissions: { contents: 'read' },
  },
  owner: 'strukto-ai',
  repo: 'mirage',
})
```

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](https://docs.mirage.strukto.ai/home/service-credentials.md). 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

```text theme={null}
/github/
  README.md
  package.json
  src/
    index.ts
    models/
      user.ts
  tests/
    index.test.ts
```

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`](https://docs.mirage.strukto.ai/home/setup/cli/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](https://docs.mirage.strukto.ai/home/integration/search.md#walk_limit) 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:

```bash theme={null}
npm install @struktoai/mirage-browser
```

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

const github = await GitHubVFS.create({
  owner: 'strukto-ai',
  repo: 'mirage',
})
const ws = new Workspace({ '/github': github }, { mode: MountMode.READ })
```

* 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](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `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.


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