Практические приёмы снижения копипасты и упрощения конфигурирования множества сходных проектов в TeamCity.

Статья о мышко-клацательном варианте конфигурирования TeamCity.

Большое число билд-конфигураций сложно поддерживать: проблематика та же, что описывается в принципе DRY программирования. Изначально одинаковое подвергается точечным изменениям, в итоге неочевидно, как конкретно работает каждая конфигурация в отдельности, и системное изменение проблематично произвести. Ниже приведу несколько простых приёмов, которые позволяют существенно снизить нагрузку на поддержку однотипных конфигураций.

Примеры будут про сборку C#-проектов, но специфика не особенно влияет на описываемые приёмы.

Встроенные переменные

Структура проекта и солюшна как правило предсказуема:

MySuperApp
    /src
        MySuperApp.csproj
    /test
        MySuperAppTests.csproj
    MySuperApp.sln

Если же структура от проекта к проекту у вас заметно различается, то предложил бы начать с этого — стандартизировать оформление исходников.

В примере видно, что имена директорий, проектных файлов либо совпадают с именем проекта, либо используют его как префикс со стандартным суффиксом. Если всё это хранится не в монорепе, то, скорее всего, и GIT-репозиторий называется так же. И компонент либо тег в таск-трекере. И конфиг в инструменте деплоя.

Если выделить это имя как переменную, то структура однотипных проектов, как и набор команд для работы с ними, окажутся идентичными и легко параметризуемыми. Достаточно и билд-конфигурацию в TeamCity назвать так же, как проект — «MySuperApp» в рассматриваемом примере.

TeamCity позволяет использовать автоматически наполняемые переменные сборки, чтобы получать информацию о ней. Так можно получить имя конфига:

PROJECT_KEY = %env.TEAMCITY_BUILDCONF_NAME%

а через этот параметр можно определить другие пользовательские параметры, например:

SOLUTION_NAME      = %PROJECT_KEY%.sln
TEST_PROJ          = %PROJECT_KEY%Tests.csproj
APP_BINARY_FILE    = %PROJECT_KEY%.exe
OCTOPUS_DEPLOY_CFG = %PROJECT_KEY%
SRC_REPO           = %GIT_STORAGE_URL%/%TEAM_SPACE%/%PROJECT_KEY%

соответственно, и команды в шагах сборки можно будет переписать с ad-hoc копипастовых dotnet build MySuperApp.sln на универсальное dotnet build %SOLUTION_NAME%.

Другие полезные и часто используемые переменные:

teamcity.build.checkoutDir       - куда тимсити клонировал исходники
teamcity.build.branch            - клонированная ветка VCS (GIT)
teamcity.build.branch.is_default - главная ли ветка собирается
teamcity.build.step.name         - имя данного шага конфига
system.teamcity.build.tempDir    - временная папка под конкретный билд

Временная папка полезна тем, что checkoutDir всё же задумана как кешируемая, поэтому одноразовые вещи туда лучше не складывать; времянка живёт ровно до завершения конкретного билда. Расположения разных папок важно знать, если придётся куда-то передавать полный путь к файлам.

Комбинируя такие параметры, можно налету, а не в процессе конфигурирования сборки, много чего узнавать о текущем проекте, окружении, обстоятельствах сборки. Системные параметры лучше предварительно заворачивать в свои и затем уже свои параметры рассовывать по шагам и в конкретные команды — так проще централизованно добавить суффикс или вроде того.

Параметризация

Задавать параметры конфигурации можно на нескольких уровнях:

ROOT
    /PROJECT
        ( /TEMPLATE )
            /BUILD_CONFIG

с каждого верхнего уровня параметры наследуются, проваливаются вниз. Таким образом, в конкретном билд-конфиге доступны параметры уровня группы конфигов (проекта тимсити) и общие для инстанса.

Очевидно, что для множества, если не всех проектов команды используется один и тот же таск-трекер, VCS и много чего ещё. Такие параметры уместнее задавать не в каждой конфигурации сборки, а один раз на уровне сервера. Приём примитивный, тем не менее сильно упрощает ситуацию с копипастой.

На уровне «проекта» можно задать общие для конфигов параметры, обусловленные тем же принципом, по которому конфиги оказались объединены в одну группу. Здесь же можно переопределить ROOT-параметры, и это переопределение провалится вниз до конфигов.

Некоторые проекты кажутся невероятно уникальными, поскольку в них не должен выполняться некий шаг или, наоборот, в определённых обстоятельствах нужно совершить дополнительное действие. Условное выполнение вполне предусмотрено в TeamCity, вот простейший пример:

условия для запуска или игнорирования шага

в эти условия можно вставлять и свои кастомные параметры.

Напомню, что значения параметров можно переопределять налету с помощью служебных текстовых команд, отправляемых в консоль:

##teamcity[setParameter name='env.MY_VAR' value='hello-world']

так, можно на предварительном «look around» этапе понять, что за проект, каковы обстоятельства сборки, при необходимости дописать что-то в пользовательские параметры, от которых зависит включение либо выключение шагов, и так получится конфигом управлять налету. Это снова расширяет взгляд на возможности стандартизации подхода к сборке множества проектов.

Шаблоны

Кусочки конфигов с несколькими шагами про одно и то же имеют больше шансов на переиспользование, чем весь конфиг целиком. Развивать, дорабатывать и устранять проблемы проще тоже в конкретном компоненте с ограниченной областью ответственности, чем конфиг на 100500 шагов. И TeamCity предоставляет такой инструмент — шаблоны (templates).

Шаги, составляющие по смыслу одно целое, имеет смысл выделять в шаблон. А для конечных конфигов применять уже «крупноблочную сборку» из нескольких шаблонов:

На скриншоте приведён пример конфига на 42 шага, причём кастомных шагов в нём нет совсем, все унаследованы из шаблонов.

При добавлении шаблона в конфиг, все шаги и параметры наследуются кофигом. Шаги при этом управляются как единый блок: если в примере на скриншоте передвинуть любой шаблон выше или ниже, то все его шаги встанут, соответственно, выше или ниже шагов шаблона, который он сместил. Если внести изменения в шаги или параметры на уровне шаблона, то эти изменения «провалятся» в каждый конфиг, использующий этот шаблон.

Контроль

В реальности обстоятельства вынуждают заниматься отладкой, устранением сбоев, поиском решений нестандартных задач. Так возникают вре́менные и не очень отключения шагов, оверрайды команд и параметров, кастомные ad-hoc шаги. Вре́менное всё же должно таким и оставаться, а конфигурирование сборок — стремиться к стандартизации.

Для обнаружения де-факто возникших аномалий можно использовать REST API TeamCity.

Схема взаимодействия такая:

получить список проектов;
в каждом проекте получить список конфигов;
для каждого конфига запросить его XML-определение;
в каждом конфиге осмотреть шаги, триггеры, фичи, VCS.

Аномалией (или ad-hoc вмешательством) является всё что не имеет признака inherited либо он выставлен в false, всё что имеет признак disabled = true. Если шаг задизаблен в шаблоне, то он в наследующих конфигах не отобразится и в XML не попадёт.

Пример запроса для получения определения конфига:

GET /app/rest/buildTypes/id:MySuperApp

Зашедулили в том же TeamCity, направили на почту — своевременно отреагировали, вернули в стойло.

Итого

Простые практики позволяют заметно упростить и систематизировать управление билд-конфигами в TeamCity:

стандартизовать оформления исходников, проектов, конфигов;
использовать встроенные переменные тимсити;
размещать кастомные параметры на подоходящем уровне;
применять тотальную шаблонизацию;
отлавливать аномалии.

Так, вполне можно приблизиться к нулевому конфигурированию проектов: скопировали существующий конфиг, переименовали — готово. Да, это всё ещё копия, но абсолютно лишённая кастомизации, и при внесении изменений в шаблоны, параметры уровня сервера, она эти изменения унаследует. Собственно, к чему и стремились.

Zero-конфиг в TeamCity как цель