GitHub materialization

What materialization does

Materialization connects a GitHub repository’s full history to a specific folder in a Vex monorepo. Vex keeps an identity map for the repository and folder so synchronization can preserve the external relationship without treating the whole monorepo as a Git subtree.

It is the right choice when a project must remain a first-class GitHub repository while also living in a shared Vex Home history.

Start a materialization

Use the GitHub import flow to choose the organization, source, target Home path, and virtual repository. Vex records a durable run so it can be inspected and resumed as the source is read and converted.

vex repo import --org <org-slug>

For a scripted path, use the relevant vex import github command with an explicit organization, path, virtual-repository slug, and confirmation.

Two sync directions, one identity map

The source GitHub history and target Vex folder keep distinct identities. Vex uses the identity map to recognize changes that have already crossed the boundary instead of blindly copying commits or treating all same-named paths as equivalent.

Choose the configured sync mode deliberately. A one-time import is not the same as an ongoing two-way sync contract.

Watch a run

The importer reports a durable session ID. Keep the terminal open for the initial local-assisted run, or resume a paused run when needed.

vex repo import --resume <session-id>

The web workflow exposes the same high-level import and authorization process; the local path is often faster for a large initial clone and conversion.

Important boundaries

Materialization is not a substitute for native source control. Once a project is in Vex, use changes, reviews, queues, and explicit sync paths. Use remote Git sync when you only need an external Git relationship rather than a folder-in-monorepo materialization.