Import a Git repo

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

This article shows you how to import an existing Git repo from GitHub, Bitbucket, GitLab, or other location into a new or empty existing repo in your Azure DevOps project.

Prerequisites

• An organization in Azure DevOps. If you don't have one, you can sign up for one for free. Each organization includes free, unlimited private Git repositories.
• To create or import a repository, you must be a member of the Project Administrators security group, or have the Git project-level Create repository permission set to Allow. For more information, see Set Git repository permissions.
• To use the Azure DevOps Import repository feature, you must have TFS 2017 Update 1 or higher.
• To import a repository using TFS 2017 RTM or earlier, see Manually import a repo using git CLI.
• If you want to use az repos commands, be sure to follow the steps in Get started with Azure DevOps CLI.

Note

When the import of the repository is completed, Azure DevOps sets the Default branch for that imported repository. If the imported repository contains a branch named master, it is set as the default branch, otherwise the first branch (in alphabetical order) of the imported repository is set as Default.

Import into a new repo

1. Select Repos, Files.

   

2. From the repo drop-down, select Import repository.

   

3. If the source repo is publicly available, just enter the clone URL of the source repository and a name for your new Git repository.

   If the source repository is private but can be accessed using basic authentication (username-password, personal access token, etc.), select Requires authorization and enter your credentials. SSH authentication is not supported, but you can manually import a repository that uses SSH authentication by following the steps in Manually import a repo using git CLI.

   

Import into an existing empty repo

On the Files page of the empty Git repository, select Import and enter the clone URL. You will need to provide credentials if the source repository requires authentication.

Note

The import feature disables automated linking for work items mentioned in a commit comment since the work item IDs in the destination project might not be the same as ones in the source project. Automatic linking for work items mentioned in a commit can be re-enabled by navigating to Settings, Version Control, selecting your repository, and choosing Options. For more information on linking commits with work items, see Link work items to commits

Manually import a repo using az repos CLI

You can use az repos import to import a repository to your Azure DevOps project.

Note

You must first create the repository in Azure DevOps before you can import a Git repository. Also, the repository you create must be empty. To create a repo, see Create your Git repo in Azure Repos.

az repos import create --git-source-url
                       [--detect {false, true}]
                       [--git-service-endpoint-id]
                       [--org]
                       [--project]
                       [--repository]
                       [--requires-authorization]
                       [--subscription]
                       [--user-name]

Parameters

Parameter	Description
git-source-url	Required. URL of the source git repository to import.
detect	Optional. Automatically detect organization. Accepted values: false, true.
git-service-endpoint-id	Optional. Service Endpoint for connection to external endpoint.
org, organization	Azure DevOps organization URL. You can configure the default organization by using az devops configure -d organization=<ORG_URL>. Required if not configured as default or picked up via git config. Example: https://dev.azure.com/MyOrganizationName/.
project, p	Name or ID of the project. You can configure the default project using az devops configure -d project=<NAME_OR_ID>. Required if not configured as default or picked up via git config.
repository	Name or ID of the repository to create the import request in.
requires-authorization	Flag to indicate if the source git repository is private. If you require authentication, then generate an authentication token on the source repo and set the environment variable AZURE_DEVOPS_EXT_GIT_SOURCE_PASSWORD_OR_PAT to the value of the token. Then the import request will include authentication.
subscription	Name or ID of subscription. You can configure the default subscription using az account set -s <NAME_OR_ID>.
user-name	User name to specify when the git repository is private.

Example

The following command imports the public repo fabrikam-open-source to the empty Git repo fabrikam-open-source for the default configuration az devops configure --defaults organization=https://dev.azure.com/fabrikamprime project="Fabrikam Fiber".

az repos import create --git-source-url https://github.com/fabrikamprime/fabrikam-open-source --repository fabrikam-open-source
{
  "detailedStatus": {
    "allSteps": [
      "Processing request",
      "Analyzing repository objects",
      "Storing objects",
      "Storing index file",
      "Updating references",
      "Import completed successfully"
    ],
    "currentStep": 6,
    "errorMessage": null
  },
  "importRequestId": 8,
  "parameters": {
    "deleteServiceEndpointAfterImportIsDone": null,
    "gitSource": {
      "overwrite": false,
      "url": "https://github.com/fabrikamprime/fabrikam-open-source"
    },
    "serviceEndpointId": null,
    "tfvcSource": null
  },
  "repository": {
    "defaultBranch": null,
    "id": "0f6919cd-a4db-4f34-a73f-2354114a66c4",
    "isDisabled": false,
    "isFork": null,
    "name": "new-empty-repo",
    "parentRepository": null,
    "project": {
      "abbreviation": null,
      "defaultTeamImageUrl": null,
      "description": "Guidance and source control to foster a vibrant ecosystem for Fabrikam Fiber applications and extensions.",
      "id": "56af920d-393b-4236-9a07-24439ccaa85c",
      "lastUpdateTime": "2021-05-24T21:52:14.95Z",
      "name": "Fabrikam Fiber",
      "revision": 438023732,
      "state": "wellFormed",
      "url": "https://dev.azure.com/fabrikamprime/_apis/projects/56af920d-393b-4236-9a07-24439ccaa85c",
      "visibility": "private"
    },
    "remoteUrl": "https://fabrikamprime@dev.azure.com/fabrikamprime/Fabrikam%20Fiber/_git/fabrikam-open-source",
    "size": 12477,
    "sshUrl": "git@ssh.dev.azure.com:v3/kelliott/Fabrikam%20Fiber/new-empty-repo",
    "url": "https://dev.azure.com/fabrikamprime/56af920d-393b-4236-9a07-24439ccaa85c/_apis/git/repositories/0f6919cd-a4db-4f34-a73f-2354114a66c4",
    "validRemoteUrls": null,
    "webUrl": "https://dev.azure.com/fabrikamprime/Fabrikam%20Fiber/_git/fabrikam-open-source"
  },
  "status": "completed",
  "url": "https://dev.azure.com/fabrikamprime/Fabrikam%20Fiber/_apis/git/repositories/0f6919cd-a4db-4f34-a73f-2354114a66c4/importRequests/8"
}

Manually import a repo using git CLI

The import repo feature was introduced in TFS 2017 Update 1. If you are using TFS 2017 RTM or earlier, you can use the following steps to manually import a repo into TFS. You can also follow these steps to manually import a repo into an Azure DevOps Services repo by replacing TFS with Azure Repos in the following steps.

1. Clone the source repo to a temporary folder on your computer using the bare option, as shown in the following command line example, and then navigate to the repo's folder. When cloning using the bare option, the folder name includes the .git suffix. In this example, https://github.com/contoso/old-contoso-repo.git is the source repo to be manually imported.

   git clone --bare https://github.com/contoso/old-contoso-repo.git
   cd old-contoso-repo.git
   

2. Create a target repo using TFS 2017 RTM, and make a note of the clone URL. In this example, https://dev.azure.com/contoso-ltd/MyFirstProject/_git/new-contoso-repo is the URL for the new target repo.

3. Run the following command to copy the source repo to the target repo.

   git push --mirror https://dev.azure.com/contoso-ltd/MyFirstProject/_git/new-contoso-repo
   

   Warning

   Using --mirror will overwrite all branches in the target repo which includes deleting any branches not in the source repo.

4. If the source repository has LFS objects then fetch them, and copy them from the source repo to the target repo.

   git lfs fetch origin --all
   git lfs push --all https://dev.azure.com/contoso-ltd/MyFirstProject/_git/new-contoso-repo
   

5. Delete the temporary folder by running the following commands.

   cd ..
   rm -rf old-contoso-repo.git
   

Frequently asked questions

Although most of the time the import is successful, the following conditions can cause problems.

• What if my Source repository is behind two-factor authentication?
• What if my source repository does not support multi_ack?
• Can I import from previous versions of Team Foundation Server?
• Can I use MSA-based credentials?
• Can I import from TFVC?
• What if my source repository contains Git LFS objects?

What if my source repository is behind two-factor authentication?

The import service uses REST APIs to validate and trigger import and cannot work directly with repositories that require two-factor authentication. Most Git hosting providers like GitHub and Azure DevOps Services support personal tokens which can be supplied to the import service.

What if my source repository does not support multi_ack?

The import service uses the multi_ack capability of the Git protocol during the import. If the source repository does not provide this capability, the import service can fail to import from the given source. This failure can happen when creating import request or while import is in progress.

Can I import from previous versions of Team Foundation Server?

If the source Git repository is in a TFS version earlier than TFS 2017 RTM, then import will fail. This happens because of a contract mismatch between the latest Azure DevOps Services/TFS and pre-2017 RTM versions of TFS.

Can I use MSA-based credentials?

Unfortunately, MSA (Microsoft Account, formerly Live ID) based credentials will not work. Import service relies on basic authentication to communicate with the source repository. If the username / password you are using are not basic auth then authentication will fail and import will fail. One way to check if the username / password you are using are basic auth or not is to try using Git to clone your repository using the below format

git clone https://<<username>>:<<password>>@<<remaining clone Url>>

Can I import from TFVC?

You can migrate code from an existing TFVC repository to a new Git repository within the same account. While migrating to Git has many benefits, it is an involved process for large TFVC repositories and teams. Centralized version control systems, like TFVC, behave different than Git in fundamental ways. The switch involves a lot more than learning new commands. It is a disruptive change that requires careful planning. For more information, see Import from TFVC to Git.

What if my source repository contains Git LFS objects?

Git import will not import Git LFS objects.

LFS objects can be moved using the following steps:

• Import the repository using import repository feature into Azure DevOps. This will copy over all the Git objects from source to Azure DevOps (this will also import the LFS pointers which are Git objects but not the LFS files)

To move over the LFS files (you will need both Git.exe and LFS client in the same box and access to both source repository and destination repository)

• Clone the imported repository from Azure DevOps to local system, clone will work but it will fail while performing checkout of LFS files
• Add the source repository as remote (say ‘source’)
• Perform git lfs fetch source --all (this will bring over all LFS files from source to your local repository)
• Assuming the destination VSTS repository is your ‘target’ remote
• Perform git lfs push target --all

Can I import updates if the source changes later?

The import service is for initially importing an entire repository. To mirror later changes, you'll need a local clone of the repository with remotes set to both source and destination.

You can sync changes using the following commands. We'll treat the Azure Repos import as origin and the original repo as upstream.

git clone --bare <Azure-Repos-clone-URL>.git
cd <name-of-repo>
git remote add --mirror=fetch upstream <original-repo-URL>
git fetch upstream --tags
git push origin --all

Next steps

New to Git repos? Learn more

Related articles

• Learn more about Git in the Git tutorial