GitHub materialization

What materialization does

Materialization connects a GitHub repository’s full history to a specific folder in a Composal monorepo. Composal 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 Composal Home history.

Start a materialization

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

com repo import --org <org-slug>

For a scripted path, use the relevant com 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 Composal folder keep distinct identities. Composal 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.

com 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 Composal, 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.