Skip to main content
A repository becomes its file tree at one ref, read through GitHub’s REST API. Owner, repo and ref are set at mount time, so paths start at the repository root.

Setup

A public repository needs no setup: leave out token and the mount reads it anonymously, as in Public repositories. For a private repository, create a fine-grained personal access token with read-only Contents on the repository, then export it:
  1. Open Fine-grained tokens (Settings, Developer settings, Personal access tokens, Fine-grained tokens) and click Generate new token.
  2. Pick the resource owner that holds the repository, then under Repository access choose Only select repositories and pick it.
  3. Under Permissions, set Contents to Read-only.
  4. Click Generate token and copy it. An organization that requires approval keeps the token pending until an admin approves it.
A classic token (Tokens (classic)) also works: select the repo scope for private repositories. That broad scope includes write access, so prefer a fine-grained token for tighter permissions.

Connect

workspace.yaml

Layout

  • The tree mirrors the repository at ref; unset ref follows the default branch.
  • stat shows each file’s git blob SHA.
  • A GitHub App installation can replace the token; the SDK guides show the app block.

Public repositories

With neither token nor app, the mount reads a public repository with no credentials, which is how a browser page mounts one with nothing typed:
workspace.yaml
  • File reads come from raw.githubusercontent.com at the commit the tree listing named, so a read never sees a newer revision than the listing and does not count against the REST API’s rate limit.
  • grep -rw and rg -w read every file instead of asking GitHub code search, which takes no anonymous requests.
  • The tree listing, and the default branch lookup when ref is unset, still cost REST requests, and GitHub allows 60 an hour per IP address without credentials. A token raises that to 5,000.
  • On GitHub Enterprise (base_url set), anonymous reads go through the REST API, one request per file.

Sample runs

The mount is read-only. Act on the repository with the gh CLI, which takes the same token and, unlike the mount, always needs one.

SDK guides

Python

Every config field, the VFS.md and write support.

TypeScript

Every config field, the VFS.md and write support.