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.4.3с исправлением (так лучше всего). - Включить "Allow re-deployment" для репозитория в Artifactory. Для стабильных релизов не советую: пользователи могут получить разные пакеты под одной и той же версией.
- Удалить сломанную версию из 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 |