Connecting Sources

Connecting a Source

A connection lets CodeCargo read a source system. It inventories the source's repositories, which Migrating Repositories copies to GitHub. For Azure DevOps and GitLab, it can also sync pipelines into Migration Assistant without the importer (Azure DevOps, GitLab). A Migration Plan works from the connections in its sandbox.

Connect each source under Migration Assistant → Connections:

• Azure DevOps - See Connecting Azure DevOps
• GitLab (gitlab.com or self-managed) - See Connecting GitLab
• Bitbucket Data Center - See Connecting Bitbucket Data Center
• GitHub Enterprise Server - See Connecting GitHub Enterprise Server

Jenkins has no connection. Bring its jobs in with the importer.

Connecting Azure DevOps

Open Migration Assistant → Connections and click Add connection, then choose Azure DevOps. Choose how to connect: Sign in with Microsoft or Use a personal access token. If you aren't an Azure DevOps administrator, click Copy a link to this page under the choice and send the link to one.

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. If your Microsoft Entra tenant hasn't approved CodeCargo yet, an Entra administrator approves it once for the whole tenant with Review and approve in Microsoft Entra.
2. Choose the organizations, then their projects. Your Microsoft account's organizations are listed. Tick the ones to connect, then choose which of their projects CodeCargo works in. An organization where you aren't a Project Collection Administrator carries a warning, since Azure DevOps may refuse to add CodeCargo there. Organizations this sign-in can't connect are listed under Can't connect with this sign-in, with the reason.
3. Connect. Nothing changes until you click Connect with the organization's name, or Connect N organizations.

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 joins the Contributors group, gets the User role on the project's service connections, and is allowed to edit build pipelines and queue builds. That lets it use the service connections and update the project's pipelines during the migration.

Connect with a Personal Access Token

Use this when nobody can approve Microsoft apps for your tenant. A token connects one organization. Create the token as an Azure DevOps administrator, with these scopes:

• Project and Team (Read), Code (Read), Build (Read & execute), and Service Connections (Read & query)
• To import pipelines too, also Variable Groups (Read), Secure Files (Read), Agent Pools (Read), and Extensions (Read)

Enter the Organization, the Personal access token, and optionally the Token expiry, then click Continue. CodeCargo checks the token and lists the projects it can see. Choose the ones CodeCargo works in, and click Connect with the organization's name.

The token acts as the person who created it. CodeCargo stores it encrypted and cannot revoke it. Disconnecting deletes the stored copy, and you delete the token in Azure DevOps yourself. Azure DevOps does not report a token's expiry, so CodeCargo uses the date you enter only to remind you to replace the token in time.

Managing an Azure DevOps Connection

The connection page shows the connection's status, how many organizations are connected, who connected it, when, and the Microsoft Entra tenant. Add organization connects another organization, by either sign-in method.

Each organization has a card that says how it is connected, such as Connected with Microsoft sign-in · 1 Basic license, or a personal access token and its expiry. Anything that needs attention shows on the card with its fix. The card has these rows:

• Projects - How many of the organization's projects are connected, with Show projects and Change projects. Projects created in Azure DevOps later are not picked up automatically. Add them with Change projects.
• Repositories - How many repositories CodeCargo found and when it last took the inventory. Refresh takes the inventory again, and View opens the repositories.
• Pipelines - The Sync pipelines switch. See Syncing Pipelines.

The card's ⋯ menu has Replace token, for an organization connected with a token, and Disconnect.

If the card says CodeCargo is missing some of the access it needs in this organization's projects, click Update access on the warning and confirm. CodeCargo grants the access in each connected project. Only a Project Collection Administrator can make the change, so unless you signed in from this page already, the confirmation reads Sign in and update access and sends you to Microsoft first.

Change Projects

Change projects on the Projects row opens a checklist of that organization's projects, with the connected ones ticked.

• Microsoft sign-in. Changing projects changes CodeCargo's access in Azure DevOps, and that runs with your permissions. Click Sign in with Microsoft as a Project Collection Administrator of the organization, and you come back with its current project list. If you already signed in from this page, you go straight to the list. If the account can't change the organization, CodeCargo says why: it's from a different Microsoft Entra tenant, the organization isn't connected to a Microsoft Entra directory (connect it under Organization settings, Microsoft Entra), or the account isn't a member.
• Personal access token. The checklist uses the stored token. If the token no longer works, replace it first.

Tick projects to add and clear projects to remove. Keep at least one project; to stop using the organization, disconnect it instead. Click Save changes. A save that removes a project, or that also grants missing access, asks you to confirm first and lists the projects being connected and removed. When pipeline sync is on, pipelines in the projects you add start importing when you save.

Disconnecting an Organization

Disconnect on an organization connected through Microsoft sign-in removes CodeCargo's user from Azure DevOps, which frees its Basic license, 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. 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 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

Pipeline sync imports a connected organization's pipeline definitions into Migration Assistant without the importer. When you connect an organization, tick Also import pipelines from the organizations you add (or Also import pipelines on the token form). Turn it on or off later with the Sync pipelines switch on the organization's Pipelines row. 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 with Change projects.
• 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. Run the importer instead when you want to name the projects yourself, or for Azure DevOps Server.

Connecting GitLab

Open Migration Assistant → Connections, click Add connection, and choose GitLab. Under GitLab instance, choose GitLab.com or Self-managed GitLab. For a self-managed instance, enter its GitLab URL, with its path if GitLab runs under one, for example https://gitlab.example.com. The URL must start with https://.

CodeCargo inventories the projects in the groups you connect, including subgroups. Projects in a personal namespace and projects scheduled for deletion are not included. Each GitLab instance is one connection. Add another with Connect another GitLab instance.

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, click Add group on the instance.

Under What to sync, repositories are always included, and Pipelines starts ticked. Untick it if you don't want pipeline sync. Under Connect with, choose how CodeCargo signs in. GitLab.com offers GitLab sign-in or Access token, and a self-managed instance offers Your OAuth application or Access token. CodeCargo checks the instance's version, the sign-in, and the groups it can reach, then lists the Groups to connect. Select them and connect. Nothing is stored until you do. The check is held for an hour. After that, start again.

• GitLab older than 17.0 connects with a warning.
• An account that can reach more than 10,000 groups with the Reporter role is refused. Connect with a group access token for the groups you want, or with an account that is a member of fewer groups.

Sign in with GitLab

On GitLab.com, choose GitLab sign-in and click Sign in with GitLab:

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. Connect. Nothing is stored until you do.

CodeCargo keeps your sign-in and reads as you, so it sees what you can see in those groups. If GitLab later rejects the stored sign-in, the instance offers Sign in again. A self-managed instance doesn't offer GitLab sign-in. Use your own OAuth application or an access token instead.

Use Your Own OAuth Application

On a self-managed instance, choose Your OAuth application and register CodeCargo with your GitLab:

1. In GitLab, add an application: as an administrator under Admin area > Applications, or under a group's or your own user settings, under Applications.
2. Name it CodeCargo, and set its redirect URI to the address CodeCargo shows. Copy copies it.
3. Keep Confidential selected, select the read_api scope, and save. Copy the application ID and secret GitLab shows.

Enter the Application ID and Secret, click Continue to GitLab, and approve. CodeCargo keeps the sign-in of the person who connects and reads as them, so it sees what they can see in the groups they connect. An application added under Admin area > Applications can be marked Trusted. GitLab then doesn't ask each person who connects to approve it.

Connect with an Access Token

Choose Access token, paste a group access token or a personal access token with the read_api scope, and click Check token. CodeCargo lists every group that token can see at Reporter or higher.

• Group access token - Create it under the group's Settings > Access tokens, with at least the Reporter role, or Maintainer if pipeline import should list the keys of the group's CI/CD variables. Group access tokens need the Premium or Ultimate tier on GitLab.com. A self-managed instance has them on every tier.
• Personal access token - Works on any tier. CodeCargo then reads as its owner.
• Fine-grained personal access token - Select the top-level group, or All groups and projects, since GitLab can't select a subgroup. For the group, give it Read on Group, Project, Branch, and Repository Tag, and for pipeline import also Repository, Variable, Environment, Pipeline Schedule, and Runner. Under User, give it Read on User, Group, and Personal Access Token.

The token is stored encrypted, and the connection shows its expiry when GitLab reports one. CodeCargo reads only the groups you connect. Connecting a group again replaces its token.

Managing a GitLab Connection

Disconnect a group from its ⋯ menu. CodeCargo loses access to the group, its subgroups, and their projects, and deletes the group's stored token. Its projects show Not connected on the Repositories tab, and its pipeline sync stops. Pipelines already imported stay. Nothing changes in GitLab. When the last group that used a GitLab sign-in is disconnected, CodeCargo signs out of GitLab too. A sign-in through your own OAuth application is deleted from CodeCargo without contacting your instance.

The instance has two settings:

• Export storage host (self-managed only) - A self-managed instance can send project export downloads to object storage on another host, such as Amazon S3. Enter that host name when you connect, or later on the instance. Leave it empty when exports download from GitLab itself.
• Relay token (optional) - When GitHub can't reach your GitLab, CodeCargo receives each push to a rewired repository's GitHub copy and tells GitLab to pull, using this token. Use a group access token with the Maintainer role and the api scope. On GitLab 19.2 or later, a fine-grained personal access token with only Pull Mirror: Create also works, and can do less. Enter the token, and optionally Expires on, then click Keep token. CodeCargo never shows it again. Replace and Remove change it later, and the card warns when GitLab refuses the token or it expires. If you disconnect the last group and connect this GitLab again, add the token again. A Migration Plan wave uses it when its GitLab rewire picks Relay.

Syncing GitLab Pipelines

Pipeline sync works for a connected GitLab group the same way as for Azure DevOps, on gitlab.com and self-managed instances: turn it on when you connect, or later on the connection page, and CodeCargo imports the group with the connection's sign-in or access token. Waiting, Take over, and Try again work the same way. These differ:

• While sync is on, projects found the next time CodeCargo inventories the group are imported on their own. Click Refresh inventory on Migration Assistant → Repositories to inventory now.
• Disconnecting the group turns sync off.
• For a group that is not connected, use the GitLab importer.

Connecting Bitbucket Data Center

Open Migration Assistant → Connections, click Add connection, and choose Bitbucket. CodeCargo inventories every project and repository on the server, including personal projects and archived repositories. GitHub Enterprise Importer migrates from Bitbucket Data Center 5.14 or later. Pipelines are not imported from Bitbucket.

Only an organization admin can connect a server, change its settings, or disconnect it.

Connect a Server

Enter the Server URL, for example https://bitbucket.example.com. It must start with https://. Migrating repositories uses Bitbucket's export API, which needs a system administrator. Bitbucket's HTTP access tokens cannot have that permission, so they cannot be used. Under Sign in with, choose one of:

• Username and password - Enter a System administrator username and its Password. Bitbucket 10 turns off password sign-in for its REST API on new servers. If the password is refused, an administrator can turn it back on under Administration > Authentication methods.
• OAuth application link - As a system administrator in Bitbucket, go to Administration > Application links and create a link to an external application. Choose Incoming, name it CodeCargo, give it the System admin permission, and set its redirect URL to the address CodeCargo shows. Enter the Client ID and Client secret it shows, then click Continue to Bitbucket.

CodeCargo checks the server's version, the sign-in, and the system administrator permission. Next, set up SSH access.

SSH Access for Exports

Bitbucket writes each export archive to its shared home, and CodeCargo copies the archive off the server over SFTP. After the check, the server's card shows an authorized_keys line for CodeCargo's key, with Copy. Add it to ~/.ssh/authorized_keys of the operating system account Bitbucket runs as, usually atlbitbucket. It does not go in a Bitbucket user's SSH keys. The line limits the key to SFTP.

Then check the SSH settings on the card and click Save SSH settings:

The account must be able to read and delete files in <shared home>/data/migration/export. Exports at once caps how many exports run on the server at a time, from 1 to 16. Leave it at 2 unless Bitbucket is a cluster. Each node runs at most 2 exports, so set 2 × nodes.

Host keys. The server's first host key is trusted from a check someone starts. A different key seen later waits until someone chooses Trust this key. To add keys yourself, click Add host keys, paste the output of ssh-keyscan -t ed25519 -p <port> <node> for each node, and click Trust these keys. Changing the SSH host or port forgets the trusted keys. A migration from the server cannot start until a host key is trusted.

Managing a Bitbucket Connection

The server's card has a Repositories row with Refresh, View, and Change. On the free plan, a new server starts with no repositories chosen, and the row reads Choose repositories. Click Change to pick them. See On the Free Plan.

While a migration from the server is in progress, its connection cannot be changed. Connecting another server still works.

Disconnect is in the card's ⋯ menu. It wipes the stored password, or the stored OAuth tokens and client secret; the application link stays on the server until you remove it there. CodeCargo's SSH key is deleted too. Remove its line from the server's authorized_keys. Connecting again makes a new key.

Connecting GitHub Enterprise Server

Open Migration Assistant → Connections, click Add connection, and choose GitHub Enterprise Server. CodeCargo inventories the repositories in the organizations you connect. Repositories owned by a user account are not included. Workflows are files in each repository, so they move with it, and there are no pipelines to import.

Only an organization admin can connect an instance, change its settings, or disconnect it.

Connect an Instance

Enter the Host URL, for example https://github.example.com. It must use HTTPS, and may end in /api/v3. Under Authentication, choose how CodeCargo reads the instance:

• Classic personal access token - Paste a Personal access token and click Check token. It must be a classic token, which starts with ghp_, scoped to repo and admin:org, from an account that is an active owner of each organization you connect. Fine-grained and OAuth tokens cannot export migrations.
• GitHub App installation - Register a GitHub App on the instance with Contents read access, generate a private key, and install the App on the organizations you want to connect. Enter the App ID and Private key, and click Check App. CodeCargo encrypts the key and reads repositories with short-lived installation tokens, so the inventory holds only the repositories the installation is granted. Install App on another organization opens the App's install page. Starting a migration still asks for a classic personal access token, since GitHub Enterprise Server accepts only those for migrations.

The check reports the instance's version and who CodeCargo signs in as, then lists the organizations: those the token's account owns, or those the App is installed on. Select up to 50 and click Connect organizations. Each organization shows its outcome, and each one that connects is inventoried straight away. A token organization and an App organization can share a host.

Migrations must be enabled. A site administrator enables GitHub Migrations with a storage provider under Migrations in the Management Console. Without it, an organization still connects, marked Migrations not enabled. Its inventory works, but its repositories cannot be migrated.

Managing a GitHub Enterprise Server Connection

The connection page lists each host with its organizations, who connected it, and when. Each organization shows its repository count and how it is connected, with its token's expiry. Its ⋯ menu has Replace token and Disconnect. Add organizations connects more after a new check, and Connect another host adds another instance. On the free plan, choose which repositories the inventory holds with Change on the Repositories row. See On the Free Plan.

CodeCargo stores a separate encrypted copy of the credentials for each organization. Connecting an organization again replaces them. Disconnect stops CodeCargo reading the organization and wipes its stored copy. Nothing changes on GitHub Enterprise Server.

Archive storage host. When GitHub Enterprise Server stores migration archives outside the instance, in S3 or Azure, enter that storage host under Archive storage host, for example storage.example.com:443, and click Save archive storage host. Leave it empty for local storage. A repository whose archive is on a host that isn't listed fails, and names the host to add.

Next Step

Once a source is connected and inventoried, copy its repositories to GitHub with Migrating Repositories, or plan the whole move with a Migration Plan. To bring in pipelines a connection doesn't sync, use Importing Data.