Import and mirror from GitHub

GitHub is an optional connection. You can import a repository to make Overlane its home, or mirror it to keep GitHub as the origin while Overlane runs review, CI and the code map on a copy.

overlane repo import acme/app
overlane repo import acme/app --copy --name app-native

An import copies history, branches and tags. The default is a mirror. With --copy it is a one-time import after which Overlane is the origin and there is nothing to sync from.

One writable side

Exactly one side of a mirror takes pushes. For a mirror made by import, GitHub is the writable side and the Overlane copy is read-only. A push, a new branch, a branch deletion or a merge on the Overlane copy is refused with a message that names the GitHub repository to push to and the command to change sides.

overlane repo mirror set app --writable overlane
overlane repo mirror set app --writable external

Making Overlane the writable side makes the GitHub side the one to leave alone (make it read-only or archive it). Overlane then keeps GitHub’s main, release/* branches and tags up to date by pushing to it, when the Overlane GitHub App can write there. It only moves a branch forward and never deletes or rewrites anything on GitHub; a ref someone moved on GitHub is left alone and reported. From then on repo sync is refused, because it would overwrite pushes made on Overlane. Changing the side is a policy change: under supervised autonomy it waits for an approval.

overlane repo sync app

A rewritten history

When a sync finds a branch whose old commits are no longer in it, the same is true after a force-push on a native branch. Overlane then:

• records the commits that became unreachable;
• marks the branch’s code index stale and queues a rebuild from the new tip;
• treats evidence recorded for those commits as stale, so a task that points at one is not verified by it and its checks are pending again.

The rebuild runs on the next push or on the scheduled sweep, or on demand:

overlane repo index show app
overlane repo index run app

The 1 GB limit and large repositories

Native repositories are limited to 1 GB each. An import over the limit is refused with guidance to keep the repository on GitHub and connect it; Overlane still reviews and runs CI there. A sync that finds a mirror has grown past the limit is refused the same way, and a push that would cross it is refused.

A large monorepo is indexed by shard. The index plan splits the file list by path prefix into shards of at most 2,000 files, and each shard job checks out only its own paths. repo index show prints the plan.

An older job never replaces a newer snapshot: each index job carries the sequence number of the push event that started it, and a job whose sequence is behind the applied snapshot is ignored.

Command reference: repo import, repo sync, repo mirror set, repo index show and repo index run.