將 Git 存放庫匯入專案

2025-07-03

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

本文說明如何將現有的 Git 存放庫從 GitHub、Bitbucket、GitLab 或其他位置匯入 Azure DevOps 專案中的新或空白現有存放庫。

必要條件

類別	需求
專案存取	專案的成員。
許可	- 在私人項目中檢視程式碼：至少基本權限。 - 複製或貢獻私人專案中的程式碼：作為貢獻者安全群組的成員或在專案中具有相應的許可權。 - 設定分支或存放庫許可權：管理分支或存放庫的許可權許可權。 - 變更預設分支：編輯原則存放庫的許可權。 - 匯入存放庫：專案管理員成員安全組或 Git 專案層級建立存放庫許可權設定為允許。如需詳細資訊，請參閱設定 Git 存放庫許可權。
服務	啟用 Repos。
工具	選擇性。使用 az repos 命令：Azure DevOps CLI。

注意

在公用專案中，具有 項目關係人 存取權的使用者具有 Azure Repos 的完整存取權，包括檢視、複製及參與程式代碼。

類別	需求
專案存取	專案的成員。
許可	- 查看程式碼：至少基本權限。 - 複製程式碼或貢獻程式碼：屬於參與者安全組的成員或具有專案中的對應許可權。
服務	啟用 Repos。

匯入至新的存放庫

執行下列步驟以匯入新的存放庫：

注意

匯入存放庫完成時，Azure DevOps 會 設定該匯入存放庫的預設 分支。如果匯入的存放庫包含名為 main的分支，則會設定為預設分支，否則匯入存放庫的第一個分支（依字母順序）會設定為 Default。

在瀏覽器中，登入您的組織，然後選取 [存放庫]>[檔案]。
從存放庫下拉式清單中，選取 [ 匯入存放庫]。
輸入來源存放庫的複製URL，以及新 Git 存放庫的名稱。

顯示 [匯入存放庫] 對話框的螢幕快照，其中包含公開可用的範例存放庫 URL。

選取 [匯入存放庫]。

資料庫被匯入。

匯入現有的空白存放庫

在空白 Git 存放庫的 [ 檔案] 頁面上，選取 [ 匯入]，然後輸入複製 URL。如果來源存放庫需要驗證，請提供認證。

顯示將存放庫匯入現有存放庫的螢幕快照。

注意

匯入功能會停用認可批注中所提及之工作專案的自動化連結，因為目的地專案中的工作專案標識碼可能與來源專案中的工作專案標識碼不同。您可以流覽至設定、版本控制，選取您的存放庫，然後選擇選項，以重新啟用認可中提及的工作專案自動連結。如需使用工作專案連結認可的詳細資訊，請參閱將工作專案連結至認可

使用 az repos CLI 手動匯入存放庫

您可以使用 az repos import 將存放庫匯入 Azure DevOps 專案。

您必須先在 Azure DevOps 中建立存放庫，才能匯入 Git 存放庫。此外，您建立的存放庫必須是空的。若要建立存放庫，請參閱在 Azure Repos 中建立 Git 存放庫。

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

參數

參數	描述
`git-source-url`	必要。要匯入的來源 Git 存放庫 URL。
`detect`	選擇性。自動偵測組織。接受的值： `false`、 `true`。
`git-service-endpoint-id`	選擇性。與外部端點連線的服務端點。
`org`、`organization`	Azure DevOps 組織 URL。您可以使用`az devops configure -d organization=<ORG_URL>`來設定預設組織。如果未設定為預設，或未透過 git 組態挑選，則必須。範例：`https://dev.azure.com/MyOrganizationName/`。
`project`、`p`	項目的名稱或識別碼。您可以使用 `az devops configure -d project=<NAME_OR_ID>` 來設定預設專案。如果未設定為預設，或透過 git 組態取得，則為必要。
`repository`	用來建立匯入要求之存放庫的名稱或標識碼。
`requires-authorization`	標誌用於指出來源 Git 存放庫是否為私有。如果您需要驗證，請在來源存放庫上產生驗證令牌，並將環境變數 `AZURE_DEVOPS_EXT_GIT_SOURCE_PASSWORD_OR_PAT` 設定為令牌的值。為了增強安全性，建議您盡可能使用 Microsoft Entra ID 令牌。然後匯入要求會包含驗證。
`subscription`	訂用帳戶的名稱或識別碼。您可以使用 `az account set -s <NAME_OR_ID>` 設定預設訂用帳戶。
`user-name`	指定 Git 存放庫為私人時的用戶名稱。

範例

下列命令會將公用存放庫 fabrikam-open-source 匯入預設組態的空白 Git 存放庫 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"
}

使用 git CLI 手動匯入存放庫

使用 bare 選項將來源存放庫複製到您計算機上的暫存資料夾，如下列命令行範例所示，然後流覽至存放庫的資料夾。使用 bare 選項複製時，資料夾名稱會包含 .git 後綴。在此範例中， https://github.com/contoso/old-contoso-repo.git 是要手動匯入的來源存放庫。
```
git clone --bare https://github.com/contoso/old-contoso-repo.git
cd old-contoso-repo.git
```
建立目標存放庫，並記下複製URL。在此範例中， https://dev.azure.com/contoso-ltd/MyFirstProject/_git/new-contoso-repo 是新目標存放庫的URL。
執行下列命令，將來源存放庫複製到目標存放庫。
```
git push --mirror https://dev.azure.com/contoso-ltd/MyFirstProject/_git/new-contoso-repo
```
警告

使用 --mirror 會覆寫目標存放庫中的所有分支，包括刪除不在來源存放庫中的任何分支。

如果來源存放庫有 LFS 物件，請擷取它們，然後將它們從來源存放庫複製到目標存放庫。

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

執行下列命令來刪除暫存資料夾。
```
cd ..
rm -rf old-contoso-repo.git
```

常見問題集 (FAQ)

雖然匯入最常成功，但下列條件可能會導致問題。

如果我的來源存放庫位於雙因素驗證後方，該怎麼辦？
如果我的來源存放庫不支援multi_ack，該怎麼辦？
我可以從舊版內部部署匯入嗎？
我可以使用 MSA 型認證嗎？
我可以從 TFVC 匯入嗎？
如果我的來源存放庫包含 Git LFS 物件，該怎麼辦？

問：如果我的來源存放庫位於雙因素驗證後方，該怎麼辦？

答：匯入服務會使用 REST API 來驗證和觸發匯入，而且無法直接使用需要雙因素驗證的存放庫。

大部分的 Git 裝載提供者都支援可提供給匯入服務的驗證令牌：

Microsoft Entra ID 令牌（建議）： Microsoft Entra ID 令牌提供更佳的安全性，而且是建議的驗證方法。您可以透過以下方式取得這些權杖：

Azure CLI （用於開發/測試）：

az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv

服務主體 （適用於生產/自動化案例）：
- 在 Microsoft Entra ID 中註冊應用程式
- 建立應用程式的客戶端密碼
- 在 Azure DevOps 中授與應用程式適當的許可權
- 使用服務主體的憑證以程式化方式取得令牌

個人存取令牌（替代）：GitHub 和 Azure DevOps 也支持個人存取令牌。

問：如果我的來源存放庫不支援multi_ack，該怎麼辦？

答：匯入服務會在匯入期間使用 Git 通訊協定的 multi_ack 功能。如果來源存放庫未提供這項功能，匯入服務就無法從指定的來源匯入。建立匯入要求或匯入進行時，可能會發生此失敗。

問：我可以從舊版匯入嗎？

答：如果來源 Git 存放庫位於早於 2017 RTM 的內部部署版本，則匯入會失敗，因為最新 Azure DevOps 與舊版之間的合約不符。

問：我可以使用 MSA 型認證嗎？

答：不幸的是，MSA（Microsoft 帳戶）型認證無法運作。匯入服務依賴基本身份驗證來與來源存放庫通訊。如果您使用的使用者名稱和密碼不是基本身份驗證，則驗證和匯入會失敗。檢查您使用的使用者名稱/密碼是否為基本身份驗證的其中一種方式，就是嘗試使用 Git 來複製您的存放庫，格式如下：

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

問：我可以從 TFVC 匯入嗎？

答：您可以將程式代碼從現有的 TFVC 存放庫移轉至相同帳戶內的新 Git 存放庫。雖然移轉至 Git 有許多優點，但對於大型 TFVC 存放庫和團隊來說，這是一個繁瑣的過程。集中式版本控制系統，例如TFVC，其行為與 Git 在基本方面不同。切換牽涉到比學習新的命令還多。這是一項干擾性變更，需要仔細規劃。如需詳細資訊，請參閱從 TFVC 匯入至 Git。

問：如果我的來源存放庫包含 Git LFS 物件，該怎麼辦？

答：Git 匯入不會匯入 Git LFS 物件。

您可以使用下列步驟來移動 LFS 物件：

使用匯入存放庫功能將存放庫匯入 Azure DevOps。此動作會將所有 Git 物件從來源複製到 Azure DevOps，此動作也會匯入 Git 物件的 LFS 指標，但不會匯入 LFS 檔案

若要移動 LFS 檔案，您需要在相同的環境中同時擁有 Git.exe 和 LFS 用戶端，並且能夠存取來源存放庫和目的地存放庫。

將匯入的存放庫從 Azure DevOps 複製到本機系統。複製可運作，但在執行 LFS 檔案檢出時失敗
將來源存放庫新增為遠端，例如“source”
執行 git lfs fetch source --all，這會將來源的所有 LFS 檔案帶入本機存放庫
假設目的地 VSTS 存放庫是「目標」遠端
執行 git lfs push target --all

問：如果來源稍後變更，我可以匯入更新嗎？

答：匯入服務是一開始匯入整個存放庫。若要反映後續的變更，您需要該存放庫的本機克隆，同時將遠端設定為來源和目的地。

您可以使用下列命令來同步變更。我們將 Azure Repos 匯入視為 origin ，並將原始存放庫視為 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

下一步

Git 存放庫的新功能？深入了解

深入瞭解 Git 工作流程