📚 Help › Converting a Repository's VCS

Converting a Repository's VCS

Convert an existing Isurus repository from one version-control system to another in place — same repository ID, same issues, labels, webhooks, secrets, and settings — while rewriting on-disk history into the target VCS.

Convert is not Import. Use Import when you create an empty repository and pull history from an external URL. Use Convert VCS when the repository already lives on Isurus and you want to change its VCS type without losing forge metadata. See Migrating from Git for the empty-repo import wizard.

Convert vs Import

Import (wizard) Convert VCS (in place)
Target repo Must be empty Already has history
Source External URL (probe + clone) This repo's on-disk store
repositories.id New empty repo you created Same ID throughout
vcs_kind Chosen at create; already matches target Flipped to the target after cutover
Issues / webhooks Fresh repo (none yet) Preserved
When to use Bring a remote Git/hg/Fossil project onto Isurus Switch VCS on a lived-in Isurus project

Both flows reuse the same cross-VCS conversion edges and modes (full history or snapshot). Same-VCS is rejected — clone and push natively instead.

Supported edges

Any pair among Git, Mercurial, and Fossil (source ≠ target):

Source → Target Typical tools (full fidelity)
git → hg hg convert
hg → git frej / hg-fast-export
git ↔ fossil fossil import/export --git
fossil → hg / hg → fossil Via a Git intermediate

Preserve full history (default) — best when blame and the DAG matter.
Snapshot + history log — tip tree as one commit plus a text history log; better for a clean break or very large repos.

Before you start (hard gates)

Conversion refuses to start unless all of the following hold:

  1. You are the repository owner or a site admin.
  2. The repository is active (not already importing, converting, or verifying).
  3. Target VCS ≠ current VCS, and the edge is supported.
  4. Zero open pull requests — merge or close them first.
  5. No running CI pipelines on the repo.
  6. A CI worker with the import capability is available (same requirement as Import).

Also plan for:

  • Everyone must re-clone with the new VCS client after Activate. Old local clones will not push or pull.
  • Commit IDs change. Bookmarks, badges, and tooling that pin old hashes will not resolve.
  • Existing CI runs stay as history only; they will not rerun against pre-convert SHAs.
  • LFS is not migrated in this version (same as Import).

How to convert

  1. Open the repository → Settings → Danger Zone.
  2. Under Convert version control system, click Convert VCS.
  3. Read the checklist, choose the target VCS and mode, then confirm by typing the org/repo path.
  4. Submit. The repository status becomes converting: pushes and most writes are blocked; a progress page shows packaging → convert → apply.
  5. You can Abort while converting (before verification). That deletes the temporary store and returns the repo to active on the original VCS.

If convert is unavailable, the Danger Zone shows that a CI worker with the import capability is required — ask your admin to enable Import on a machine that has Incus.

Verification (Activate / Rollback)

When conversion succeeds, Isurus cutovers to the new store and sets status to verifying:

While verifying Behavior
Browse Tree, history, issues, settings — UI reads the new VCS
Push / VCS writes Blocked
Banner Repo-wide: Activate <NewVCS> / Rollback to <OldVCS>

Browse and verify files, history, and default branch before unlocking writers.

Activate

  • Confirms the new VCS permanently for day-to-day use.
  • Re-applies release tag names onto the converted store (best-effort; missing tags are flashed as warnings, not a hard failure).
  • Sets the repository active; pushes work again with the new client.
  • Keeps an archive of the previous store for ops retention (no automatic undo after Activate).

Rollback

  • Restores the archived previous disk store and vcs_kind.
  • Discards the converted store.
  • Sets the repository active on the original VCS.
  • Safe during verifying because release retags run only on Activate, not during verification.

There is no third “retry convert” while verifying — Roll back (or Activate), then start a new convert if needed.

What is preserved vs rewritten

Data Fate
Issues, labels, comments, assignees Unchanged
Webhooks, CI secrets, repo settings Unchanged
On-disk history Converted into the new VCS (IDs change)
Open PRs Blocked at start
Closed / merged PRs Rows kept; old nodes may not resolve
CI pipelines Rows kept; SHAs archival
Releases Metadata kept; VCS tags applied on Activate
LFS blobs Not migrated (v1)

After Activate

  1. Share the new Clone URL from the repository page.
  2. Have every collaborator create a fresh clone with the target client (git, hg, or fossil).
  3. Update CI, deploy hooks, and docs that assume the old VCS or old commit hashes.
  4. Re-open pull requests on the new VCS as needed (open PRs were required to be closed before convert).
×