CI для NuGet-библиотек: версия из имени ветки и публикация в два реестра

Published: 2026-05-29

Общим .NET-библиотекам нужен другой пайплайн, чем приложениям. Docker-образа нет, деплоя в Kubernetes тоже, есть только dotnet pack и dotnet nuget push. Самое интересное здесь - управление версиями и публикация в два реестра: в GitLab Package Registry для быстрых внутренних итераций и в Artifactory для стабильных релизов, которыми пользуются другие команды.


Версию задаёт имя ветки

У нас договорённость: версия пакета зашита в имя ветки.

rel/1.4.2   →  версия пакета 1.4.2

CI-джоба достаёт её подстановкой параметров shell:

bashVERSION=${CI_COMMIT_BRANCH##*/}
# rel/1.4.2 → 1.4.2

##*/ отрезает всё до последнего / включительно. Никаких внешних утилит, никакого git describe, никаких правок .csproj в CI.

То есть инженер создаёт релизную ветку с нужной версией в имени, ветка запускает пайплайн, а dotnet pack записывает эту версию в метаданные .nupkg:

bashdotnet build -p:Version=$VERSION -c Release src/
dotnet pack  -p:Version=$VERSION -c Release --no-build src/

-p:Version= при сборке переопределяет <Version> из .csproj, не трогая сам файл. --no-build в pack берёт уже собранный результат.


Джоба сборки целиком

yamlbuild:
  image: registry.example.com/ci-images/dotnet-build:net8
  stage: build
  script:
    - VERSION=${CI_COMMIT_BRANCH##*/}
    - dotnet restore -p:Configuration=Release src/
    - dotnet build  -p:Version=$VERSION -c Release src/
    - dotnet pack   -p:Version=$VERSION -c Release --no-build src/
  artifacts:
    expire_in: 1 day
    paths:
      - "**/*.nupkg"
  tags:
    - office-dind

Файлы .nupkg попадают на стадию push через artifacts. expire_in: 1 day хватает: после публикации в оба реестра файл уже никому не нужен.


Публикация в GitLab Package Registry

У каждого проекта в GitLab есть встроенный NuGet-фид. Внешние учётные данные не нужны: CI_JOB_TOKEN - короткоживущий токен, который GitLab выдаёт на одну джобу:

yamlpush:
  image: registry.example.com/ci-images/dotnet-build:latest
  stage: push
  script:
    # Удалить устаревший source 'push', если он остался от предыдущего запуска
    - |
      if dotnet nuget list source | grep -q "push \["; then
        dotnet nuget remove source push
      fi
    - dotnet nuget add source \
        "${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/packages/nuget/index.json" \
        --name push \
        --username gitlab-ci-token \
        --password $CI_JOB_TOKEN \
        --store-password-in-clear-text
    - dotnet nuget push "**/*.nupkg" --source push
  tags:
    - office-dind

CI_JOB_TOKEN перестаёт действовать, как только джоба завершилась, поэтому --store-password-in-clear-text здесь допустим: учётные данные нигде надолго не сохраняются.

Проверка grep -q "push \[" нужна потому, что в nuget.config внутри образа уже может быть source с именем push, оставшийся от сборки самого образа. Без проверки dotnet nuget add source падает с ошибкой "source already exists".


Публикация в Artifactory (стабильные релизы)

Artifactory - реестр для внешних команд. Туда попадают только стабильные релизы, только из веток rel/* и только когда джобу вручную запускает один из назначенных инженеров:

yamlpush_artifactory:
  image: registry.example.com/ci-images/dotnet-build:latest
  stage: push
  variables:
    # Список пакетов из этого репо для внешней публикации (через пробел)
    PACKETS: >-
      MyCompany.Api.Schema
      MyCompany.Api.Schema.Serialization
      MyCompany.Api.Schema.XmlUtils
  script:
    - |
      if dotnet nuget list source | grep -q "push \["; then
        dotnet nuget remove source push
      fi
    - VERSION=${CI_COMMIT_BRANCH##*/}
    - dotnet nuget add source \
        "https://artifacts.example.com/repository/nuget-releases/index.json" \
        --name push \
        --username $REGISTRY_NUGET_USERNAME \
        --password $REGISTRY_NUGET_PASSWORD \
        --store-password-in-clear-text
    - |
      for pkg in $PACKETS; do
        dotnet nuget push "**/${pkg}.${VERSION}.nupkg" --source push
      done
  rules:
    - if: $CI_COMMIT_BRANCH =~ /^rel\/.*/ && $GITLAB_USER_LOGIN =~ /^(alice|bob)$/
      when: manual
    - if: "$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS"
      when: never
  tags:
    - office-dind

Что здесь важно:

Публикация пакетов по одному в цикле. dotnet nuget push "**/*.nupkg" отправил бы все пакеты репозитория. Если в репо 3 публичных пакета и 5 внутренних вспомогательных проектов, внутренним в Artifactory делать нечего. Переменная PACKETS перечисляет ровно то, что уходит наружу.

Ручной запуск и проверка пользователя. when: manual защищает от случайной публикации. Проверка $GITLAB_USER_LOGIN - второй барьер: даже если кто-то создаст ветку rel/, кнопку публикации в Artifactory смогут нажать только определённые люди. GitLab проверяет это ещё на уровне rules, до обращения к Vault и к любым учётным данным.

Учётные данные. $REGISTRY_NUGET_USERNAME и $REGISTRY_NUGET_PASSWORD - групповые CI-переменные GitLab с флагами masked и protected, поэтому они доступны только в защищённых ветках.


Источники NuGet в образе для сборки

В образе для сборки лежит nuget.config, который направляет dotnet restore во внутренний NuGet-прокси (Artifactory или групповой фид GitLab):

xml<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="internal" value="https://artifacts.example.com/repository/nuget-group/index.json" />
  </packageSources>
  <packageSourceCredentials>
    <internal>
      <add key="Username" value="%NUGET_USERNAME%" />
      <add key="ClearTextPassword" value="%NUGET_PASSWORD%" />
    </internal>
  </packageSourceCredentials>
</configuration>

%NUGET_USERNAME% и %NUGET_PASSWORD% - переменные окружения, которые попадают в образ через build args. В итоге dotnet restore в CI просто работает, а в YAML пайплайна нет никакой настройки источников: образ и так знает, где лежат пакеты.


Правила workflow для пайплайнов библиотек

Библиотеки не деплоятся в Kubernetes, поэтому workflow проще:

yamlworkflow:
  rules:
    - if: $CI_MERGE_REQUEST_ID
    - if: $CI_COMMIT_BRANCH == "dev"
    - if: $CI_COMMIT_BRANCH =~ /^rel\/.*/
    - if: "$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS"
      when: never

Стадий sonarqube, deploy и autotests здесь нет, только build и push. Весь .gitlab-ci.yml репозитория библиотеки - это 5 строк переопределённых переменных и один include:.


Особый случай: повторный выпуск версии

Допустим, баг в 1.4.2 нашли уже после публикации в Artifactory. Запушить 1.4.2 ещё раз не получится: по умолчанию Artifactory такое отклоняет. Варианты:

  1. Выпустить 1.4.3 с исправлением (так лучше всего).
  2. Включить "Allow re-deployment" для репозитория в Artifactory. Для стабильных релизов не советую: пользователи могут получить разные пакеты под одной и той же версией.
  3. Удалить сломанную версию из Artifactory вручную через UI и запушить заново.

Мы выбираем первый вариант: ветка rel/1.4.3 создаётся от того же коммита, что и rel/1.4.2, и сверху добавляется коммит с исправлением.


Что может пойти не так

dotnet nuget add source падает с "source already exists". В образе для сборки уже может быть source с именем push. Это решает проверка if dotnet nuget list source | grep -q "push \[". Убедитесь, что она есть в каждой джобе публикации.

В пакет попала не та версия. Если VERSION=${CI_COMMIT_BRANCH##*/} выполнится в ветке вроде feature/my-thing, версией станет my-thing, а это не semver. Добавьте блок rules, чтобы сборка и упаковка запускались только в ветках rel/*.

Artifactory отклоняет публикацию с 400 "artifact already exists". Релизные репозитории по умолчанию запрещают повторную публикацию. Либо поднимите версию (создайте rel/1.4.3), либо включите "Allow Re-deployment" в настройках Artifactory для этого репозитория. Второй вариант для стабильных релизов не советую.

CI_JOB_TOKEN истёк до публикации. Токен действует, только пока идёт джоба. Если сборка долгая и загрузка артефакта начинается уже после истечения токена, dotnet nuget push вернёт 401. Публикуйте в той же джобе или передавайте токен через короткоживущий артефакт.


Итог

Задача Решение
Версия пакета Имя ветки rel/X.Y.Z
Внутренняя публикация GitLab Package Registry + CI_JOB_TOKEN, без сохранённых учётных данных
Внешняя публикация Artifactory: только rel/*, вручную и только назначенными людьми
Выборочная публикация Переменная PACKETS со списком пакетов, внутренние наружу не уходят
Учётные данные для restore nuget.config в образе для сборки
Скорость сборки Образ с уже установленным dotnet-sonarscanner экономит ~90 с на джобу без dotnet tool install