Как известно, основными понятиями TeamCity являются: проекты (подпроекты), билд-конфигурации и шаблоны. Проекты используются для организации иерархии, билд-конфигурации описывают действия (программные шаги), а шаблоны хранят описания часто используемых билд-конфигураций. Однако, на практике иногда возникает необходимость подняться на более высокий уровень абстракции и включить в шаги билд-конфигурации действия из других билд-конфигураций. Для этого используются мета-раннеры.

Мета-раннер (TeamCity Meta-Runners) - это "раннер в раннере", это инструмент, который позволяет выделить из отдельных билд-конфигураций общие повторяющиеся действия и перенести их на уровень выше. Мета-раннеры позволяют использовать шаги одной билд-конфигурации в других билд-конфигурациях целиком, как отдельный параметризуемый шаг. Если шаблон конфигурации можно сравнить с параметризованной функцией в программировании, то мета-раннер - это класс, в понятиях ООП.

Описание мета-раннеров в оригинале: http://confluence.jetbrains.com/display/TCD8/Working+with+Meta-Runner

Как добавить свой мета-раннер

Мета-раннер нужно создавать на уровне того проекта, для подпроектов которого его предполагается использовать. Например, для того, чтобы мета-раннер был доступен во всех проектах нужно создать его на уровне Root project. Для этого нужно добавить новый Build Configuration Template с описанием общих шагов и параметров, которые предполагается выделить для всех подпроектов. В шагах могут использоваться любые команды и другие мета-раннеры.

После того, как темплейт будет создан и все его параметры настроены, необходимо создать на его основе мета-раннер, выбрав пункт меню Actions - Extract meta-runner...

После этого новый мета-раннер будет добавлен на уровне проекта в разделе Meta-Runners в виде xml-конфигурации, которую можно отредактировать как обычный текстовый файл.

После того, как мета-раннер создан на основе какого-либо шаблона, его можно использовать в билд-конфигурациях или их шаблонах любых подпроектов, выбирая из заранее предопределённых Build Steps - шагов конфигурации.

Особенности работы с мета-раннерами

Изменения, внесённые в xml-конфигурацию мета-раннера будут сразу же применены ко всем шагам всех конфигураций, в которых этот мета-раннер использовался. В связи с этим, нужно внимательно относиться к переименованиям и изменениям шагов мета-раннера, если он уже используется.
Мета-раннеры создаются на основе шаблона, однако, после создания теряют с ним связь. Таким образом, при изменении шаблона, старый мета-раннер не изменяется. При необходимости изменения мета-раннера, нужно либо отредактировать его xml-конфигурацию, либо удалить его полностью и создать заново на основе исправленного шаблона.
Переменные шаблона, на основе которого был создан мета-раннер, используются в качестве локальных переменных и имеют больший приоритет для мета-раннера. Это нужно учитывать, если одноименным переменным на уровне мета-раннера и всего проекта нужно задавать различные значения. В этом случае, при запуске мета-раннера он будет использовать предопределённые в нём значения переменных.
При автоматическом извлечении мета-раннера из шаблона, в нём могут присутствовать множество лишних параметров и переменных. Рекомендуется после создания мета-раннера вручную отредактировать его xml-конфигурацию и удалить из неё лишние параметры и переменные.
Нужно учитывать, что настройки VCS-root не сохраняются в xml-конфигурации мета-раннера, поэтому, при использовании внешних репозиториев в его шагах, потребуется точно также определять эти репозитории при включении мета-раннера в других билд-конфигурациях.

Мета-раннеры удобно использовать, когда вам требуется:

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

Пример мета-раннера уровня Root project

Для примера на уровне Root project может быть определён мета-раннер PT-runner: Creating build_info.html with Build Information Summary. Мета-раннер создаёт файл build_info.html в рабочем каталоге сборки %system.teamcity.build.workingDir% на стороне агента TeamCity. Этот файл содержит информацию по успешно завершённой сборке, которую можно добавить в артефакты и подключить на вкладке проекта.

Код мета-раннера

Meta-Runner "PT-runner: Creating build_info.html with Build Information Summary"

<?xml version="1.0" encoding="UTF-8"?>
<meta-runner name="PT-runner: Creating build_info.html with Build Information Summary">
  <description>Creating Build Information Summary</description>
  <settings>
    <parameters>
      <param name="os" value="" spec="text description='Please, define Operation System to work with build' display='normal' label='Project operation system:' validationMode='any'" />
      <param name="capacity" value="" spec="select data_1='' data_2='x64' data_3='x32' description='Please, define build capacity' display='normal' label='Project capacity:' " />
      <param name="technology" value="" spec="select data_1='' data_2='Python' data_3='c++' data_4='c#' data_5='Java' description='Please, define project technology' display='normal' label='Project technology:'" />
      <param name="direct_link_to_build" value="" spec="text description='Please, define template to full path to build in Artifactory' display='normal' label='Direct link to download build:' validationMode='any'" />
    </parameters>
    <build-runners>
      <runner name="Creating link" type="simpleRunner">
        <parameters>
          <param name="script.content"><![CDATA[del build_info.html /Q
echo ^<b^>--- Meta-information about project's build ---^</b^>^<br /^>^<br /^> >> build_info.html
echo ^<b^>Project operation system:^</b^> %os%^<br /^>^<br /^> >> build_info.html
echo ^<b^>Project capacity:^</b^> %capacity%^<br /^>^<br /^> >> build_info.html
echo ^<b^>Project technology:^</b^> %technology%^<br /^>^<br /^> >> build_info.html
echo ^<b^>Artifactory direct link to download build:^</b^> ^<a href="%direct_link_to_build%"^>^<b^>%direct_link_to_build%^</b^>^</a^> >> build_info.html]]></param>
          <param name="teamcity.step.mode" value="default" />
          <param name="use.custom.script" value="true" />
        </parameters>
      </runner>
    </build-runners>
    <requirements />
  </settings>
</meta-runner>

Параметры мета-раннера

Step name: имя шага, отображаемое в билд-логе, если оставить пустым - будет отображаться имя мета-раннера;
Project operation system: описание операционной системы, для которой сделан билд;
Project capacity: разрядность библиотек, используемых в билде;
Project technology: основная технология разработки проекта;
Direct link to download build: прямая ссылка, по которой можно будет скачать билд из Artifactory.

Как использовать мета-раннер

Добавить новый шаг в билд-конфигурацию или шаблон: PT-runner: Creating build_info.html with Build Information Summary.
Заполнить информацию, которую вы желаете отобразить пользователю для успешно завершённых билдов. Все поля являются текстовыми и необязательными к заполнению, можно оставлять пустые значения.
В дополнительных параметрах шага указать его запуск только после успешного выполнения всех предыдущих шагов, для этого выбрать значение поля Execute step: "If all previous steps finished successfully".
Самым первым шагом проекта обязательно добавить шаг с раннером Command Line, выбрать тип раннера Custom script и добавить в него команду: del build_info.html /Q. Это нужно для того, чтобы в случае неудачной сборки в артефакты билд-рана не попал какой-либо старый файл с мета-информацией.
Report Tab, содержащий вкладку Build Info, должен быть настроен на уровне Root project и ожидать появления файла build_info.html в рабочей директории сборки, а значит, этот файл нужно добавить в артефакты билд-конфигурации. Для этого нужно перейти на вкладку General Settings для билд-конфигурации и добавить значение build_info.html в новой строке поля Artifact paths.

Тимур Гильмуллин про автоматизацию и процессы

вторник, 10 июня 2014 г.

Мета-раннеры в TeamCity

Как добавить свой мета-раннер

Особенности работы с мета-раннерами

Пример мета-раннера уровня Root project

Код мета-раннера

Параметры мета-раннера

Как использовать мета-раннер

вторник, 10 июня 2014 г.

Мета-раннеры в TeamCity

Как добавить свой мета-раннер

Особенности работы с мета-раннерами

Пример мета-раннера уровня Root project

Код мета-раннера

Параметры мета-раннера

Как использовать мета-раннер

вторник, 10 июня 2014 г.