Настройка TeamCity для сборки тех. документации

Данная инструкция предназначена для технических писателей, работающих с таким программным обеспечением как TeamCity и GitLab.

TeamCity — билд-сервер для обеспечения непрерывной интеграции, подробный мануал на английском языке можно найти здесь [1].

GitLab — это веб-приложение для хостинга исходного кода проектов, основанное на системе контроля версий Git. Своим функционалом GitLab очень напоминает GitHub, однако заточен под командную работу, в то время как GitHub отдает предпочтение индивидуальной работе. Документация по GitLab находится тут [2].

Настройка GitLab

(Подразумевается, что у Вас уже есть учетная запись и установлен на компьютер GitBash.)

Генерация SSH ключа

Для работы с GitLab необходимо «привязать» учетную запись к компьютеру, с которого будут передаваться данные. Для этого нужно сгенерировать SSH ключ. На странице своей учетной записи, в боковом меню нажимаем Profile Settings → SSH Keys. И на странице SSH Keys нажимаем кнопку Add SSH Key. В предложении «Paste your public key here. Read more about how to generate a key on the SSH help page» последние слова являются ссылкой. Переходим по ссылке. Открывается страница Help. Далее вызываем Git Bash. Прописываем команду cat ~/.ssh/id_rsa.pub. Если для данного компьютера уже был сгенерирован SSH ключ, то он отобразится после ввода команды. Далее идет команда ssh-keygen -t rsa -C «your mail». Можно скопировать эту команду со страницы help. После этого идет команда cat ~/.ssh/id_rsa.pub. Отобразившийся ключ копируется и вставляется в поле Key на странице Add an SSH Key. Поле Title заполняется автоматически. После нажатия Add key ключ сохранится.

Создание проекта

Теперь можно создавать проект. Возвращаемся в основное меню, нажимаем Projects и в открывшемся окне зеленую кнопку New Project. В окне Project path заносим имя проекта. Это то имя, которое будет отображаться в «пути». Далее нажимаем Create Progect. Проект создан. Если потребуется ввести изменение в проект, кнопка настроек находится в верхнем правом углу. Далее в боковом меню выбираем Members. В открывшемся окне в строке People из выпадающего меню выбираем teamcity, в строке Project Access — Developer. Сохраняем, нажав Add users to project.

Основные команды

Возвращаемся на страницу проекта. Внизу есть поле Command line instructions, в котором прописаны основные команды.

В первую очередь, в командной строке Git Bash вводятся команды из поля Git global setup.

Последовательность команд для перемещения документов в репозиторий GitLab

cd "Имя пути" - команда для перехода в папку с нужными документами 

git init - команда, создающая в папке с документами скрытую папку git 

git remote add origin git@... git - указывает, в репозиторий какого проекта будут помещены документы. git@... git это путь, прописанный в строке SSH на главной странице проекта в GitLab 

git add . - команда добавления всех файлов, находящихся в папке. Если нужно добавить несколько файлов, тогда используется  

git add "имя файла" "имя файла" 

git commit 

git push -u origin master - после этого документы добавлены в репозиторий 

master — имя ветки (по умолчанию), в которую добавляются документы.

Последовательность команд для замены документов в репозитории GitLab

git status - показывает изменения. Файлы, которые изменились, выделены красным цветом

git add "имя файла" "имя файла" - добавление измененных файлов

git status - если git add прошла успешно, измененные файлы станут зелеными

git commit

git push -u origin master

Дополнительные команды

ls - команда просмотра содержимого папки

rm имя файла - удаление файла

history - просмотр истории

git checkout -b имя ветки - создание ветки

git push origin имя ветки - добавление ветки в репозиторий

git branch - просмотр списка веток

Настройка TeamCity

От имени администратора создаем новый проект. Для этого нажимаем в правом верхнем углу Administration и в открывшемся окне Create project. В поле Name вводим имя проекта. Нажимаем Save.

Переходим во вкладку VCS root. Чтобы осуществить сборку, TeamCity должен знать, где хранятся данные. Настройки VCS определяют, как TeamCity общается с системой контроля версий, в данном случае, с GitLab. Нажимаем Create VCS root. В поле Type of VCS лучше оставить по умолчанию <Guess from repository URL>. Копируем с главной страницы проекта в GitLab строку SSH: git@… git и вводим в поле Repository URL. Нажимаем Create. Если все сделано правильно, появится новая запись в окне Name на странице VCS root. Примечание — На момент подключения репозитория к TeamCity, он не должен быть пустым.

Теперь настроим параметры сборки. Возвращаемся в General Settings и нажимаем Create Build Configurations. Задаем имя в поле Name. При этом ID сгенерируется автоматически. Нажимаем Creat. Автоматически откроется страница Version Control Settings. Здесь либо в поле Attach existing VCS root из выпадающего меню выбираем уже существующий VCS и нажимаем Attach. Либо создаем новый, нажав Create в поле Create new VCS root. Далее автоматически откроется страница Auto-detected Build Steps. Нажимаем configure build steps manually. В поле Runner type выбираем нужный тип сборки. Допустим Command Line. Заполняем основные поля. В примере с Command Line необходимо выбрать, как будет выполняться сборка: по скрипту (Custom script), записанному в поле Custom script или скрипт будет читаться из файла (Executable with parameters), указанного в поле Command executable. Нажимаем Save. Переходим во вкладку Triggers. Нажимаем Add New Trigger. Из выпадающего меня выбираем VCS Trigger и, ничего не меняя, нажимаем Save. Данный этап необходим для того, чтобы TeamCity запускал сборку каждый раз, когда в репозитории GitLab будут изменения.

Вернемся на страницу Version Control Settings. В поле VCS checkout mode следует выбрать, куда будут сохранятся результаты сборки: на сервер (Automatically on server) или на агента (Automatically on agent (if supported by VCS roots)). В поле Checkout directory указывается, в папку с каким именем: автоматическим (Auto (recommended)) или определенным (Custom path). Имя задается в строке ниже.

Теперь можно нажать Projects в верхнем левом углу, выбрать и открыть свой проект. Кнопка Run справа запускает процесс сборки. После выполнения сборки в случае неудачи можно открыть Build Log и посмотреть, на каком этапе произошел сбой.

Если принципиально, чтобы сборке участвовал свой агент, Возвращаемся в настройки проекта (верхней правый угол Edit Configuration Settings) и переходим во вкладку Agent Requirements. Нажимаем Add New Requirements. В открывшемся окне в Parameter Name указываем teamcity.agent.name, Condition → equals, Value → имя агента. Нажимаем Save.

Для того, чтобы результаты сборки можно было наблюдать непосредственно на странице сборки проекта, необходимо при настройке сборки Build Configuration Settings, во вкладке General Settings, в области Artifact paths прописать, какой результат сборки нужно выводить. Сохраните результаты и выполните сборку еще раз. На странице сборки проекта, в строке сборки, появится кнопка Artifacts с вложенным файлом.