Migrating Repositories

Repository Migration Overview

Before pipelines can move to GitHub Actions, the code they build has to live on GitHub. Migration Assistant can do that move for you: connect a source system, browse every repository CodeCargo can see, and copy the ones you choose to your GitHub organization through GitHub Enterprise Importer — the same engine behind gh ado2gh migrate-repo, driven from the app instead of a terminal.

Supported source systems:

• Azure DevOps - See Connecting Azure DevOps
• GitLab.com - See Connecting GitLab for sign-in, access tokens, and the export that runs before each copy
• Bitbucket (Server and Data Center) - Coming soon
• Gitea - Coming soon
• GitHub Enterprise Server - Coming soon

Each successful copy is recorded as that repository's relocation, so the pipelines you import link to the new GitHub repository automatically and Prepare Rewire knows where everything went. Repositories migrated outside CodeCargo with gh ado2gh are still recognized once discovery traces their Migration Log issue.

The work happens in the Migrate group of the organization sidebar:

• Plan - The Migration Plan, which can copy repositories into a sandbox organization as a dry run before each wave
• Connections - The source systems CodeCargo is connected to, and where you connect a new one
• Repositories - The connected estate, with tabs for Repositories, Migrations, and Custom properties
• Pipelines - The pipeline-side dashboard with its Sources, Batches, and Waves tabs, described on the Migration Assistant overview

Connecting Azure DevOps

Open Migrate → Connections and click Add connection, then choose Azure DevOps. There are two ways to connect an organization.

Sign in with Microsoft

This is the recommended path. You sign in with an Azure DevOps account that administers the organizations you want to connect, and CodeCargo gets its own identity in each of them:

1. Sign in with Microsoft and allow CodeCargo to access Azure DevOps. The first time anyone in your Microsoft Entra tenant connects, an Entra administrator approves CodeCargo for the tenant.
2. Pick the organizations and projects to connect. Your Microsoft account's organizations are listed; select the ones to connect, then choose which of their projects CodeCargo can read. Nothing changes until you confirm.
3. Review what changes in Azure DevOps. The confirmation step lists the organizations being connected and the projects gaining or losing access. Only a Project Collection Administrator of each organization can make these changes.

After setup, CodeCargo works under its own account rather than your sign-in. It appears as a user in each connected organization and holds one Basic license there. Your sign-in is never stored. It is used during setup, and again when you change projects or disconnect an organization.

In each connected project, CodeCargo's user is allowed to edit build pipelines and queue builds, so it can update those pipelines during the migration. Connecting a project grants Edit build pipeline and Queue builds on that user. A project's Contributors group often can queue builds without being allowed to edit pipelines, so those permissions are set on CodeCargo's user directly.

If a connected organization says CodeCargo is missing access it needs here, click Change projects on its row and save with Update access. See Change projects.

Connect with a Personal Access Token

If nobody can approve Microsoft apps for your tenant, click Can't approve Microsoft apps? Connect with a personal access token instead. Enter the organization name, an Azure DevOps personal access token with read access to Project and team, Code, and Build, and optionally the token's expiry date. CodeCargo checks the token, lists the projects it can see, and connects only the projects you select.

The token acts as you. CodeCargo stores it encrypted and cannot revoke it — disconnecting wipes the stored copy, and you delete the token in Azure DevOps yourself. Azure DevOps does not report token expiry, so the date you enter is shown on the connection page purely so you can renew the token in time.

Managing a Connection

The connection page shows who connected it, when, the Entra tenant, and each linked organization with its connected projects. Each organization also has a Repositories row, with how many repositories CodeCargo found and when it last took the inventory, and a Pipelines row with its pipeline sync switch. Refresh takes that organization's inventory again, and View opens its repositories. From here you can:

• Add organizations or projects - Starts a Microsoft sign-in so you can connect an organization that is not connected yet. Projects created in Azure DevOps later are not picked up automatically; add them with Change projects on that organization's row.
• Change projects - On every connected organization's row, change which of its projects CodeCargo is connected to. See Change projects.
• Disconnect an organization - Removes the CodeCargo user from that organization (a Project Collection Administrator must do this; if Azure DevOps refuses, the organization stays connected) or, for a token-connected organization, wipes the stored token. Pipeline sync for that organization turns off, and its import is canceled.

Import pipeline definitions from this page with pipeline sync. Run the importer when you want to name the projects yourself, or for Azure DevOps Server.

Change Projects

Change projects on a connected organization's row opens a picker for that organization only. Other connected organizations are not listed. Nothing changes until you confirm.

On an organization connected with a personal access token, the picker uses the stored token. Reselect the projects CodeCargo reads, or clear the organization to disconnect it.

On an organization connected through Microsoft sign-in, confirm first. Connecting or disconnecting a project changes CodeCargo's access in Azure DevOps. That runs with your permissions, so you may be sent to Microsoft to sign in. Only a Project Collection Administrator of the organization can make the change. Click Sign in and continue. If you already have a Microsoft session from this page, the button is Continue and you are not sent to Microsoft again.

The picker opens on the projects already connected. Choose which to keep. Clear a project to remove access, or clear the organization to disconnect it, then confirm with Update access. The page returns to that organization's project list, open.

If the row says CodeCargo is missing access it needs here. Fix it with Change projects., save with Update access even when you leave the projects as they are. That grants the missing access.

If the account you sign in with cannot change the organization, CodeCargo says why and offers Cancel instead of the picker. Sign in with an account that is a Project Collection Administrator there. Use an account from that organization's Microsoft Entra tenant when it is a different tenant. If the organization is not connected to a Microsoft Entra directory, connect it under Organization settings, Microsoft Entra, then sign in again.

Disconnect from CodeCargo Only

Disconnect on an organization connected through Microsoft sign-in removes CodeCargo's user from Azure DevOps, unless another CodeCargo organization still links that same Azure DevOps organization through Microsoft sign-in. You may be sent to Microsoft to sign in first; you need to be a Project Collection Administrator of that organization. If Azure DevOps refuses the removal, CodeCargo cannot look up its user, or that sign-in cannot happen, the organization stays connected and CodeCargo offers Disconnect from CodeCargo only.

Every CodeCargo organization that connects through the same Microsoft Entra tenant uses the same CodeCargo user in an Azure DevOps organization. A connection made only with a personal access token does not use that user.

While another CodeCargo organization still links it, Disconnect leaves the user in place. Access stays on the projects that organization still uses, and is removed only from projects no other connection uses — including Edit build pipeline and Queue builds. The result says the user stayed. Removing a project takes it off this connection; if another organization still uses it, CodeCargo keeps its access there and says so. The last CodeCargo organization to disconnect removes the user.

Disconnect from CodeCargo only forgets the organization in CodeCargo and changes nothing in Azure DevOps. Pipeline sync turns off and its import is canceled. Use it when you agree to leave Azure DevOps unchanged — for example, when CodeCargo is no longer approved in your Microsoft Entra tenant, or no Project Collection Administrator can sign in. The dialog says whether another CodeCargo organization uses the same user, and the result after you confirm names what is left behind.

• Another organization still uses the user. Leave the user in place, and don't remove CodeCargo from Microsoft Entra while that organization uses it. Removing the user would cut that organization off. The result names any projects only this connection used. Remove CodeCargo's user from each of those projects' Contributors group, service connection security, and pipeline security. If another organization still uses every project, there is nothing else to remove.
• No other organization uses the user. The user may keep its Basic license and project access until an administrator removes it under Organization settings, Users. Remove that user before you remove CodeCargo from Microsoft Entra or connect the organization again.

A stored personal access token is deleted from CodeCargo only. It stays valid until you delete it in Azure DevOps. Pipelines already imported stay. You can connect the organization again afterward; CodeCargo uses the user that is still there.

An organization connected only with a personal access token still disconnects without a Microsoft sign-in: CodeCargo wipes the stored token. If that organization was also connected through Microsoft sign-in, the token disconnect is refused. Sign in as a Project Collection Administrator and disconnect from the connection page, or choose Disconnect from CodeCargo only when no one can sign in.

Syncing Pipelines

When you connect an organization, you can choose to sync its pipelines. Turn pipeline sync on or off later from the connection page. Anyone who can manage the connection can change it.

Turning it on imports every project enabled on the connection. CodeCargo runs that import with the personal access token or the Microsoft sign-in already on the connection — you don't download a credentials file or run a container. Turning it off cancels the import and stops importing projects you grant later. Pipelines already imported stay. Imports that sync starts on its own run as the person who turned it on.

The connection page follows the import from queued to finished. CodeCargo runs one of these imports at a time, so a second one waits. It also waits while someone is importing Azure DevOps with the importer. Take over stops that importer run so CodeCargo can continue. Once the import begins, it shows under Import runs, where Stop import works as for any other run.

• Projects you grant later are imported on their own. A project created in Azure DevOps is not included until you add it here.
• Try again reruns a failed or canceled import with the same projects. Projects granted after that import started are picked up by the next sync, not by trying the old run again.

What comes in matches an Azure DevOps import. Credential values are not imported.

Connecting GitLab

Open Migrate → Connections, click Add connection, and choose GitLab. CodeCargo inventories the projects in the groups you connect, including subgroups, so you can copy them to GitHub from the Repositories tab. Projects in a personal namespace are not included.

You need the Reporter role or higher on a group. Connecting a group includes every subgroup under it. A group that overlaps one already selected — a parent and its subgroup, for example — is refused. You can connect up to 50 groups at a time. To add groups later, run the connection flow again and select them.

Sign in with GitLab

Use Sign in with GitLab when it is offered:

1. Sign in and approve read access. That lists groups and projects. It does not export them.
2. Select the groups to connect. Groups already connected are marked.
3. Confirm. Nothing is stored until you confirm.

If the session expires before you confirm, or GitLab later rejects the sign-in, choose Sign in again. If Sign in with GitLab is not offered, connect with an access token instead.

Connect with an Access Token

Paste a group access token or a personal access token. CodeCargo lists every group that token can see at Reporter or higher. On GitLab.com Free, group access tokens are not available, so use a personal access token. Group access tokens require GitLab Premium or Ultimate.

The token is stored encrypted, and the connection shows its expiry when GitLab reports one. CodeCargo cannot revoke it — disconnecting deletes the stored copy, and you revoke it in GitLab. Connecting a group again replaces its token. Disconnecting marks its projects Missing and does not change GitLab. Disconnecting the last group that used your sign-in revokes that sign-in at GitLab.

If a group accepts requests only from allowed IP addresses, contact your CodeCargo administrator for the addresses CodeCargo uses to reach GitLab.

Syncing GitLab Pipelines

When you connect a GitLab.com group, you can choose to sync its pipelines, and turn pipeline sync on or off later on the connection page. CodeCargo imports the group with its group or personal access token, or with GitLab sign-in. You don't run the importer.

While sync is on, projects found the next time CodeCargo inventories the group are imported on their own. Click Refresh inventory on Migrate → Repositories to inventory now. Turning sync off cancels the import. Pipelines already imported stay. Disconnecting the group turns sync off too.

Waiting, Take over, and Try again work the same way as for Azure DevOps. A self-managed instance has no connection to sync from; use the GitLab importer.

Copying Projects to GitHub

Projects scheduled for deletion are not listed. The Location filter shows the connected groups and subgroups. Pipeline definition counts are not collected on this connection. Import the definitions with pipeline sync or the GitLab importer.

Create the migration the same way as for Azure DevOps. The GitHub token requirements under Stage 3 — Review and Start are the same. These steps differ:

• GitLab token at start. Paste a personal or group access token with the api scope from a Maintainer or Owner. Read access cannot export a project. CodeCargo uses the token to export each project; GitHub never connects to GitLab. The token is kept and deleted on the same schedule as the GitHub token (Tokens after the run), and CodeCargo cannot revoke it.
• Export, then copy. Each project is exported and uploaded before its GitHub copy starts. A project being exported shows as Exporting and counts as in progress. Projects waiting to export stay Pending. Up to four projects are exported at a time. Stop migration aborts an export that has not finished; a GitHub copy already in progress is still left to finish.
• Retry. Retrying a failed project exports it again. An export or upload failure is shown on the row.
• Checks. The row waits until its size is measured. Rename or delete a branch or tag that exceeds Git's 255-byte limit before starting. Git LFS objects are not copied — fetch them from GitLab and push them, as in After the Migration.
• Already migrated. A project copied here is marked Migrated. A copy made outside CodeCargo is not detected, and imported pipelines are not linked to the new GitHub repository automatically.

Forking. When the destination organization does not let members fork private repositories, each private or internal copy arrives with forking off, and you turn it back on in each repository. If the GitHub token in the Start dialog belongs to an organization owner, a note under the token says so and ends with a Member privileges link. Allow forking there before you start if you want those copies to keep it. The note does not stop the migration.

The Repositories Tab

Migrate → Repositories lists every repository CodeCargo can see through its connections, with project, size, pipeline count, and status. Click Refresh inventory to take a fresh inventory of projects, repositories, and pipeline counts; a refresh also runs automatically before a migration starts.

Narrow the table with the Location filter (source system → organization → project), the Status filter, and the search box. Disconnected repositories are hidden by default; tick Show disconnected repositories to include them.

A repository that is already in a migration shows In migration #N (or (draft)) and cannot be selected for another one. A repository may be in one migration at a time.

Custom Properties

The Custom properties tab holds the organization's mapping from source details to GitHub custom properties. A migration with Stamp custom properties on the GitHub copy enabled (the default when a mapping exists) writes the mapped fields on each GitHub copy, so anyone looking at the GitHub repository can trace it back to where it came from. Nothing is stamped until the organization saves a mapping, and a migration can turn stamping off in its settings; its review then reads "Not stamped".

Azure DevOps offers these fields. The first four carry a suggested standard property name and show a Standard badge while they keep it; the overflow menu's Restore standard mappings adds all four at once.

Rename a property, remove one, or Add mapping to include more fields; the overflow menu restores the standard mappings or removes them all. Property names are validated as you type, and CodeCargo reads your GitHub organization's existing property schema so it can warn before a save would redefine a property of a different type.

The mapping applies to the whole organization, and each migration keeps a copy of it from the moment it starts — editing the mapping mid-run does not change what a running migration stamps. Saving does not change repositories that have already been migrated, and never removes a property from your GitHub organization.

Creating a Migration

Select repositories on the Repositories tab and click Migrate selected…. A migration copies from one organization, so the selection must sit within a single one. Choose New migration, or — when a draft already exists for that organization — Add to migration #N.

A new migration asks for a Name (it defaults to "Migration #N"), whether to stamp custom properties on the GitHub copy, and a default Visibility for the targets — Same as the source, Private, or Public. These settings stay editable from the draft's Settings button until the migration starts; repositories added later follow them, while names already proposed keep what they have.

Each draft has its own page with three stages. The page saves as you go — there is no Save button — and a status line beside the stage strip reads "Saving…" or "All changes saved". Landing on the page opens the first stage that still needs work; Continue walks to the next stage in order.

Stage 1 — Repositories

The draft's repositories, with project, size, pipeline count, and a Remove action per row. Click Add repositories to open the inventory in a side sheet and add more; the sheet can also show disconnected, already-in-a-migration, and already-migrated repositories, though none of those can be selected. A migration holds up to 5,000 repositories.

Each row shows Ready, Checking… while its pre-migration checks run, or a reason it cannot be migrated:

• Disabled in Azure DevOps
• Already migrated
• No commits - Empty repositories are refused when you try to add them
• Over GitHub's 40 GiB limit
• A branch name over Git's 255-byte limit - Rename or delete the branch in Azure DevOps first
• No longer in the inventory or Source no longer connected

Pre-migration checks — branch names and Git LFS usage — are read once at inventory time for the repositories a draft holds, so adding repositories never waits on the source. Repositories that use Git LFS carry a warning: they migrate, but need a follow-up step afterwards (see After the Migration).

Stage 2 — Names and Visibility

Every row gets a proposed GitHub name and visibility, and the Check column says whether it is ready:

• Adjusted from X - Characters GitHub does not allow were replaced. Names may use letters, digits, ., -, and _; anything else becomes -.
• Renamed from X: taken on GitHub or … another repository in this migration has that name - The default is the Azure DevOps repository name; when that clashes with a repository already in your GitHub organization or another row in the migration, the row falls back to {project}-{repo}.
• Duplicate in this migration - Two rows would create the same GitHub name. Fix one before starting.

Type in a row's GitHub name to override it; edits are re-checked against your GitHub organization's inventory and the rest of the migration as you type. Enter moves to the next row, Shift+Enter to the previous one, and Escape restores the proposed name. Use the All / Needs a look / Renamed filter to focus on the rows worth reviewing.

To rename in bulk, enter a naming pattern built from {repo}, {project}, and {org} and click Apply pattern. Applying a pattern keeps any names you typed by hand and offers to reset those too. An empty pattern keeps the source name.

Visibility mirrors the Azure DevOps project's visibility by default (a public project gives a public repository, anything else private). Change a single row, or use Set all visibility to choose Private, Public, or Match the project for every row. When your GitHub organization is part of a GitHub Enterprise account, Internal is included there, on each row's visibility select, and in the migration's Settings — including the default you pick when you create the migration. Otherwise Internal is not offered.

Stage 3 — Review and Start

The last stage is locked until the earlier ones are settled, and says which stage still needs attention. Once ready, the Review card summarizes the migration:

• Repositories - Count and total size
• GitHub owner - The organization the copies are created in
• Custom properties - The property names that will be stamped, or "Not stamped"
• After each copy succeeds - The post-migration steps the migration will run

Beside it, the Required to start card names the two credentials the importer needs. GitHub Enterprise Importer copies with its own credentials, which CodeCargo cannot mint on your behalf, so a migration collects both from you at the moment it starts:

GitHub personal access token (classic)

• From an owner of the GitHub organization, or an account that has been granted the migrator role
• Scopes: repo, workflow, and admin:org
• Must be a classic token, not a fine-grained one. If your organization uses SAML single sign-on, authorize the token for it after creating it.
• Also used for post-migration configuration, such as stamping custom properties
• Kept in CodeCargo for up to seven days after the migration finishes so you can retry failures, then deleted. Revoke it on GitHub when you are done.

Azure DevOps personal access token

• Organization-scoped for the organization being migrated, read-only
• Scopes: Code (read), Work Items (read), Identity (read), and Project and Team (read). The importer rejects a narrower token, even though this set can read more than the repositories.
• Kept in CodeCargo for up to seven days after the migration finishes, then deleted. CodeCargo cannot revoke an Azure DevOps token; delete it in Azure DevOps when you are done.

Each credential has a Create one link to the page where it is minted and a Requirements tip with the same details.

Click Start migration to enter both tokens. The GitHub token is checked as you type — CodeCargo reports the account it belongs to, its expiry, missing scopes, and whether the account is an owner of the organization. A member who is not an owner gets a warning rather than a refusal, with the gh gei grant-migrator-role command an owner can run to grant the migrator role, since a granted role cannot be queried. The Azure DevOps token is checked against the organization when the migration starts. Neither token is saved with the draft.

The Migration Run

Once started, the draft's page becomes the run page at the same URL. The header shows the migration's status, when it started, how long it has been running, and when CodeCargo last checked with GitHub; a progress bar counts repositories succeeded, in progress, failed, skipped, and queued. The page refreshes itself as the run progresses.

Each repository row moves through Pending → Queued → In progress → Succeeded → Done (once post-migration steps finish), or ends Failed, Aborted, Skipped, or Preflight failed. Expand a row to see its GitHub migration id, why it failed, any warnings GitHub reported, and the migration log. CodeCargo captures the log when a copy finishes because GitHub deletes it 24 hours after completion; the captured log opens in a side sheet, along with a link to the Migration Log issue on GitHub.

Tokens After the Run

CodeCargo keeps its copies of both tokens for up to seven days after the migration finishes, so failures can be retried and post-migration steps can complete. Two different things can end that hold, and the run's header says which one happened:

• You revoke the GitHub token. Click Revoke token on the run page. CodeCargo asks GitHub to revoke the token, then deletes both copies; the header reads "GitHub token revoked and both copies deleted from CodeCargo". If GitHub refuses the revocation, the header says so and offers to try again, or you can revoke the token on GitHub yourself.
• The hold expires. After seven days CodeCargo deletes its copies without contacting GitHub; the header reads "copies deleted from CodeCargo; the GitHub token was not revoked and is still valid on GitHub". CodeCargo never revokes a token on its own, so revoke it on GitHub when you are done.

CodeCargo cannot revoke an Azure DevOps token in either case; deleting the copy is all it can do. Delete the token in Azure DevOps yourself.

Retrying an item after the copies are gone asks for both tokens again.

CodeCargo keeps at most 100 copies Queued or In progress at a time. On a larger migration, the rest stay Pending until a copy finishes.

Run Actions

• Stop migration - Available while running. Nothing new is queued, queued copies are aborted, and copies already in progress are left to finish so the record is complete.
• Abandon migration - Available while validating, if the run cannot proceed.
• Retry / Skip - On each failed row, and Retry N failed for all of them. A note under the buttons says whether you need to fix something first; when you do, it reads Fix what the row says, then retry. Retry stays available regardless, since you may have fixed something CodeCargo cannot see. Retry does not delete a repository on GitHub. When the row says the target name is already taken — including a name your organization's inventory did not have when the migration started — check what holds that name before you retry:
  • An earlier copy of this repository — Skip the row if that copy is the one you wanted.
  • An empty repository a failed attempt left behind — delete it on GitHub, then Retry under the same name.
  • Anything else — Rename the repository and retry.
• Rename - On a row that Failed, Preflight failed, or Aborted. Anyone who can retry the migration can rename. Click Rename, enter a new GitHub name, and confirm. CodeCargo saves the name and retries that one repository the same way Retry does. If CodeCargo no longer holds the tokens, it asks for them again; the new name is already saved if you stop at that dialog. The name may use letters, digits, ., -, and _, up to 100 characters. A name is refused when another repository in this migration uses it, when it is already taken in the GitHub organization, or when another migration that has started still holds it. GitHub ignores case, so after a name clash a change of case alone is refused. If CodeCargo lost track of this repository's last copy, Rename is refused until you Retry under the current name. That retry follows the copy on GitHub, when there is one, instead of copying the repository again.
• Revoke token - Available the whole time CodeCargo holds the GitHub token, running included, so you never have to wait for a migration to end to get your token back.

If the GitHub rate limit is hit, the page says so and queueing resumes on its own.

After the Migration

When a copy succeeds, CodeCargo:

1. Marks the source repository as migrated on the Repositories tab, with a link to the GitHub copy
2. Syncs and activates the GitHub repository in CodeCargo, so it is ready for workspaces and workflows. If your CodeCargo GitHub App installation is limited to selected repositories, add the new one to it; the remaining steps wait until it is visible.
3. Stamps custom properties from the mapping the run snapshotted when it started, if the migration has stamping enabled
4. Records the relocation from the Azure DevOps location to the GitHub repository. Imported pipelines for that repository link to the new home, and Prepare Rewire treats the migration exactly like one traced from a Migration Log issue.

GitHub Enterprise Importer copies Git data, pull requests, and most metadata, but not everything. Warnings from GitHub — oversized metadata, comments outside a diff — are shown on the row with the detail in the captured log.

git lfs fetch --all
git lfs push --all <github-remote>

The Migrations Tab

Migrate → Repositories → Migrations lists every migration in the organization — drafts, running migrations, and finished ones — with the source organization, its status, repository counts and progress, who created it, and when. Open a draft to continue it, or delete it to free its repositories for another migration.

Next Step

With repositories on GitHub, import their pipeline definitions if you have not already, then map and migrate the pipelines themselves. When the pipelines are ready, finish with Prepare Rewire.