在 Visual Studio 中設定 GitLab 作為 NuGet Packages 來源

TLDR

• GitLab Package Registry 可作為私有 NuGet 套件庫，透過 GitLab CI/CD 自動化打包與發佈。
• 使用 dotnet nuget add source 指令並搭配 CI_JOB_TOKEN 可在 Pipeline 中自動化發佈流程。
• 若發生 NU1101 錯誤，通常是因為 CI_JOB_TOKEN 缺乏跨專案或跨群組的存取權限，需在 GitLab 的「Job token permissions」中進行設定。
• 在 Visual Studio 中，需使用具備 read_api 權限的 Personal Access Token 進行驗證。
• 若 Visual Studio 反覆要求輸入憑證，請檢查 %AppData%\NuGet\NuGet.Config 是否正確寫入 <packageSourceCredentials> 區塊。

---

設定 GitLab CI/CD 自動發佈

GitLab 並未提供直接上傳 .nupkg 檔案的 UI 介面，建議透過 GitLab CI/CD 實現自動化流程。以下為建議的 .gitlab-ci.yml 設定：

image: 'mcr.microsoft.com/dotnet/sdk:8.0'

stages:
 - pack
 - publish

variables:
 NUGET_PACKAGES_DIRECTORY: '.nuget'

before_script:
 - export PROJECT_FILE=$(find . -type f -name "*.csproj" | head -n 1)
 - export PROJECT_DIR=$(dirname "$PROJECT_FILE")
 - export PROJECT_NAME=$(basename "$PROJECT_FILE" .csproj)
 - dotnet nuget add source "${CI_API_V4_URL}/groups/${PACKAGES_GROUP_ID}/-/packages/nuget/index.json" --name gitlab-packages --username gitlab-ci-token --password ${CI_JOB_TOKEN} --store-password-in-clear-text

pack:
 stage: pack
 tags:
   - docker
 script:
   - dotnet pack $PROJECT_DIR --configuration Release --output $NUGET_PACKAGES_DIRECTORY
 artifacts:
   paths:
     - $NUGET_PACKAGES_DIRECTORY/*.nupkg

publish:
 stage: publish
 tags:
   - docker
 script:
   - dotnet nuget add source "${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab-project --username gitlab-ci-token --password ${CI_JOB_TOKEN} --store-password-in-clear-text
   - cd $NUGET_PACKAGES_DIRECTORY
   - for pkg in *.nupkg; do dotnet nuget push "$pkg" --source gitlab-project; done

處理 CI/CD 權限問題

什麼情況下會遇到這個問題：當專案需要引用其他專案的套件，或在 CI/CD 流程中執行 dotnet restore 時。

若執行時出現 error NU1101: Unable to find package，是因為 $CI_JOB_TOKEN 預設僅限存取自身專案。請依照以下步驟擴充權限：

1. 前往「Settings」→「CI/CD」。
2. 在「Job token permissions」區塊點擊「Add group or project」。
3. 新增需要存取的群組或專案。

TIP

使用 --verbosity detailed 參數可以協助除錯，確認是否為權限不足導致無法解析相依套件。

在 Visual Studio 中設定 GitLab 套件來源

建立存取 Token

在 Visual Studio 中讀取私有套件，需建立 Personal Access Token：

1. 進入「Preferences」→「Access Tokens」。
2. 建立新 Token 並勾選 read_api 權限。
3. 複製並妥善保存 Token。

設定 Visual Studio

1. 進入「工具」→「選項」→「NuGet 套件管理員」→「套件來源」。
2. 加入 URL：https://{GitLab Domain}/api/v4/groups/{Group 流水號}/-/packages/nuget/index.json。
3. 系統提示時，帳號輸入 GitLab 帳號，密碼輸入剛才產生的 Token。

解決重複輸入憑證問題

什麼情況下會遇到這個問題：Visual Studio 無法正確將憑證寫入設定檔，導致每次開啟專案都需重新驗證。

若發生此狀況，請手動透過命令列將憑證寫入 NuGet 設定：

dotnet nuget add source "https://{GitLab Domain}/api/v4/groups/{Group 流水號}/-/packages/nuget/index.json" --name=GitLab --username={GitLab 帳號} --password={Access Token}

執行後，請檢查 %AppData%\NuGet\NuGet.Config 是否已包含 <packageSourceCredentials> 區塊。

異動歷程

1. 2025-03-30

   • 初版文件建立。