Как настроить конвейеры непрерывной интеграции (CI) GitLab на Ubuntu 20.04

Каждый разработчик понимает, насколько важен контроль версий для жизненного цикла разработки программного обеспечения. Он позволяет нескольким людям одновременно работать над одним проектом, при этом каждый человек сохраняет свою собственную копию кода и выбирает, когда поделиться ею с остальной командой. Для достижения этого разработчики используют Git-репозитории для помощи в контроле версий. GitLab — это веб-репозиторий Git, который представляет собой нечто большее, чем просто инструмент контроля версий. Он также предоставляет инструменты DevOps, отслеживание проблем, непрерывную интеграцию и развертывание.

GitLab предлагает три варианта на выбор: GitLab Community Edition (CE), GitLab Enterprise Edition (EE) и GitLab SaaS. GitLab CE и GitLab EE — это self-managed решения (управляемые самостоятельно). Это означает, что вы сами скачиваете, устанавливаете и управляете инстансом GitLab. GitLab SaaS размещается компанией GitLab Inc. Таким образом, вам не нужно беспокоиться об установке чего-либо для его использования. Вам нужно лишь создать учетную запись GitLab и начать работу.

В этом руководстве мы покажем вам, как настроить конвейеры непрерывной интеграции (Continuous Integration) с помощью GitLab CI для мониторинга изменений в ваших репозиториях и запуска автоматических тестов для проверки нового кода. Мы начнем с настройки Git-репозитория для размещения кода. Затем мы настроим процесс CI для мониторинга коммитов в репозиторий и запустим CI-раннер для выполнения тестов в изолированном Docker-контейнере.

Предварительные требования

Для начала вам понадобится сервер с установленным программным обеспечением для контроля версий GitLab. Как self-managed версия GitLab, так и SaaS-версия могут запускать автоматические тесты. Однако в бесплатных вариантах SaaS существуют некоторые ограничения по времени (минутам) и ресурсам, предоставляемым для ваших тестов. У вас больше свободы, если вы используете self-managed варианты, поскольку вы можете выделить своему инстансу GitLab столько ресурсов, сколько пожелаете. Следуйте нашему руководству по хостингу собственных Git-репозиториев с помощью GitLab, чтобы узнать, как настроить собственный инстанс GitLab.

Вам понадобится как минимум один сервер для использования в качестве GitLab CI раннера. Однако при желании вы можете использовать и больше серверов. Если вы настроили self-managed инстанс GitLab, вы можете использовать тот же сервер, но мы предпочитаем настроить отдельный сервер для CI-раннера. Это руководство по настройке сервера Ubuntu станет хорошим началом.

Вам понадобится установленный Docker на серверах GitLab CI раннеров для изоляции тестовых сред в Docker-контейнерах. У нас есть руководство по установке и работе с Docker на Ubuntu, которое поможет вам выполнить это требование.

Теперь, когда у нас есть все необходимое, давайте начнем!

Шаг 1. Создание проекта в инстансе GitLab

Мы начнем с создания репозитория проекта на GitLab. В этом руководстве мы будем опираться на приложение Node.js. Поскольку мы не хотим создавать файлы проекта с нуля, GitLab предлагает инструмент для импорта проектов из других репозиториев контроля версий, которым мы и воспользуемся. Импортируемое нами приложение — это простое «hello world»-приложение, созданное с использованием Express.js – минималистичного веб-фреймворка для приложений Node.js. Мы будем реализовывать тесты с использованием Mocha и Chai – это JavaScript-фреймворки, используемые для модульного тестирования. Mocha позволяет проводить асинхронное тестирование, создавать отчеты о покрытии тестами и может использоваться в паре с другими библиотеками утверждений. Chai — это библиотека утверждений. Ее можно использовать с любым тестовым фреймворком, в нашем случае мы будем использовать Mocha в паре с Chai.

Теперь, когда вы знаете основы нашего проекта, войдите в свой инстанс GitLab (self-managed или SaaS), нажмите на ‘плюс’ на верхней панели навигации и выберите ‘New project’. Кроме того, если вы прокрутите страницу вверх на главной странице вашего аккаунта, вы можете нажать на кнопку ‘New project’:

На странице нового проекта нажмите на вкладку Import project:

Затем на открывшейся странице нажмите кнопку Repo by URL:

Хотя здесь есть вариант импорта из GitHub, мы не будем его использовать, так как для этого требуется персональный токен доступа (Personal access token). Нам не нужно настраивать персональные токены доступа, поскольку мы работаем с публичным репозиторием, а импорт просто по URL-адресу выполняется очень просто.

После этого скопируйте следующий URL-адрес и вставьте его в поле Git Repository URL:

Это должно выглядеть следующим образом:

Оставьте репозиторий как Private и нажмите кнопку Create project, когда закончите. Подождите пару секунд, пока проект импортируется из GitHub, и он появится среди ваших репозиториев GitLab. GitLab импортирует проект с теми же данными, что и проект в репозитории GitHub.

Шаг 2: Анализ файла .gitlab-ci.yml

GitLab CI сканирует каждый репозиторий на GitLab на наличие файла с именем .gitlab-ci.yml, чтобы знать, как запускать автоматические тесты. В только что импортированном репозитории вы можете увидеть файл .gitlab-ci.yml среди файлов проекта. Вы можете найти дополнительную информацию о GitLab CI yml на их официальном документации «Keyword reference for the .gitlab-ci.yml file».

Находясь в интерфейсе репозитория GitLab, нажмите на файл .gitlab-ci.yml, чтобы открыть его в браузере. Он должен выглядеть следующим образом:

Обратите внимание на отступы строк. Файл следует строгому GitLab CI YAML синтаксису конфигурации для определения различных действий, которые должны быть выполнены в определенном порядке при определенных условиях. Чтобы убедиться в правильности ваших конфигурационных файлов, GitLab предоставляет утилиту тестирования для валидации. Внутри вашего инстанса GitLab, в репозитории вашего проекта, вы можете перейти в интерфейс CI lint для валидации вашего .gitlab-ci.yml. Нажмите на CI/CD в левом навигационном меню и нажмите кнопку CI lint на появившейся странице:

Директивы в конфигурационном файле рассматриваются ниже.

• Базовый Docker-образ

Первая строка в конфигурационном файле объявляет Docker-образ, который должен использоваться для запуска тестов. Поскольку мы создаем приложение Node.js, мы выберем последний образ Node.js:

• Stages

Затем мы определяем различные этапы, через которые должны пройти наши тесты непрерывной интеграции. У нас есть только два этапа:

При определении имен этапов такие имена, как build или test выбираются произвольно – вы можете выбрать любое имя, которое вам нравится. Однако вы должны правильно упорядочить этапы, так как это определяет порядок выполнения. В нашем случае задачи на этапе build выполняются перед задачами на этапе test . GitLab Runner будет выполнять задачи одного этапа параллельно и будет ждать завершения всех задач, прежде чем начнет выполнять задачи следующего этапа.

• Cache

Определение cache включено для указания файлов и каталогов, которые будут кэшироваться или сохраняться для последующего использования между запусками задач:

Определение кэширования помогает минимизировать время, затрачиваемое на выполнение задач, зависящих от ресурсов, которые вряд ли изменятся между запусками. Мы указываем каталог node_modules для кэширования. Это каталог, в который npm устанавливает зависимости для проекта.

• Jobs

В конфигурации у нас есть две задачи:

• install_dependencies

При именовании задач вы можете свободно выбирать любое имя. Однако рекомендуется использовать описательное имя, так как они используются в интерфейсе GitLab – это может быть полезно при отладке. В сети вы найдете большинство конфигураций, объединяющих npm install с командами на этапе тестирования. Мы разделили их только для того, чтобы показать, как взаимодействуют задачи, так как это довольно небольшой проект. stage директива помечает эту задачу как build – она запускается на этапе build stage.

Директива script указывает команды, которые должны быть выполнены при запуске этой задачи. Вы можете указать несколько команд, добавив строки внутри блока script. Конечно, вам нужно быть аккуратными с отступами и помнить о порядке, в котором должны выполняться скрипты.

Директива artifacts указывает пути к файлам или директориям, которые нужно сохранить и передать между этапами. И снова напоминаем, что правильный порядок этапов крайне важен для того, чтобы у других файлов было всё необходимое для выполнения. Команда npm install установит зависимости в директорию node_modules directory. Объявив её в artifacts, мы делаем её доступной для задач, выполняемых на последующих этапах. Файлы также становятся доступны в интерфейсе GitLab, если вы захотите их скачать.

• test_with_mocha

Эта задача запускается на test этапе. Поскольку эта задача выполняется после того, как задача на этапе build была запущена, артефакты, объявленные на этапе build (которые являются зависимостями для нашего приложения), будут доступны на test этапе. Блок script указывает npm команды для запуска наших тестов. Сначала мы запускаем наше приложение, а затем выполняем тесты для него. Запуск этих команд активирует команды, указанные в разделе package.json (блок scripts):
На этом у вас должно появиться базовое понимание файла .gitlab-ci.yml. Мы говорим «базовое», потому что это всего лишь статическое приложение hello world. Далее давайте посмотрим, как мы можем запустить новый прогон CI.

Шаг 3. Запуск прогона GitLab CI

Вы будете рады узнать, что как только в вашем репозитории появится файл .gitlab-ci.yml, любые новые коммиты, которые вы отправляете в него, будут запускать новый прогон непрерывной интеграции (CI). В случае самостоятельно управляемых (self-managed) инстансов GitLab, если вы не настроили GitLab runner, прогон CI получит статус «pending» (ожидание).

GitLab SaaS предоставляет пользователям общие раннеры (shared runners), которые могут автоматически брать их задачи и выполнять их. Это возможно только в том случае, если общие раннеры свободны и вы не превысили свою квоту. В GitLab SaaS вы можете выбрать, хотите ли вы, чтобы ваш репозиторий использовал shared runners или нет, перейдя в раздел вашего проекта Settings > CI / CD, как показано на скриншоте ниже. На этой странице вы также найдете инструкции по установке GitLab runner, в которые мы подробно углубимся на следующем шаге:

Теперь давайте внесем небольшое изменение, чтобы запустить прогон CI. Вернитесь в репозиторий вашего проекта GitLab node_pipeline:

Нажмите на файл README.md, выделенный выше, чтобы просмотреть его:

Нажмите на кнопку ‘Edit’, чтобы открыть файл для редактирования в браузере, и добавьте немного текста:

После добавления текста прокрутите вниз и нажмите кнопку Commit changes, чтобы сохранить изменения. Вы можете изменить сообщение коммита по своему усмотрению. Оно будет отображаться в качестве заголовка в интерфейсе GitLab во время работы пайплайна. Мы оставили его как Update README.md, так как оно довольно информативно:

После фиксации изменений вернитесь на главную страницу проекта. Вы заметите небольшую paused icon, прикрепленную к последнему коммиту. Если вы наведете курсор мыши на эту иконку, отобразится: ‘Pipeline:pending’:

Это означает, что прогон CI был запущен. Однако тесты еще не были выполнены. В навигационном меню слева нажмите на CI/CD, затем выберите Pipelines. Откроется страница с более подробной информацией о пайплайне. Вы можете видеть, что CI находится в состоянии ожидания (pending) и помечен как зависший (stuck):

Чтобы получить более подробную информацию о прогоне, нажмите на статус pending. Вы увидите представление ниже, отображающее различные этапы прогона и отдельные задачи, связанные с каждым этапом:

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

Это сообщение указывает на то, что задание зависло, так как вы не настроили ни одного активного раннера, способного выполнить это задание. Мы сделаем это на следующем шаге. Как только вы сделаете раннер доступным, задание начнет выполняться автоматически. При выполнении задания вы увидите вывод в этом интерфейсе, а также другие загружаемые артефакты, созданные во время работы задания.

Шаг 4: Настройка службы GitLab CI Runner

Теперь пришло время использовать второй сервер, который мы указали в разделе предварительных требований этого руководства. Мы установим и настроим службу GitLab runner на этом сервере. Вы можете развернуть службу для запуска нескольких экземпляров раннеров для различных проектов на GitLab.

У вас есть возможность развернуть раннер на том же сервере, где размещен ваш собственный (self-managed) экземпляр GitLab. Однако, чтобы гарантировать, что экземпляр не будет ограничен в ресурсах, предпочтительнее настроить отдельный экземпляр CI-раннера. Какую бы конфигурацию вы ни выбрали, должен быть установлен Docker для изоляции тестовых сред.

Процесс установки GitLab CI runner аналогичен процессу установки собственного (self-managed) экземпляра GitLab . Мы начнем с загрузки скрипта для добавления официального репозитория GitLab в источники apt с помощью следующей команды:

Введите пароль root при появлении запроса. Далее вы можете запустить команду для установки последней версии GitLab CI runner:

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

Шаг 5: Получение токенов регистрации и привязка GitLab Runner

Чтобы настроить GitLab CI runner для приема заданий, вам понадобится токен раннера GitLab. Он необходим для аутентификации раннера на вашем сервере GitLab. Существует два типа токенов в зависимости от того, как вы хотите использовать раннер: специфичный для проекта и общий раннер.

Специфичные для проекта раннеры применимы, если у вас есть уникальные требования к раннеру. Например, если в вашем файле gitlab-ci.yml содержатся определения развертывания с уникальными токенами, то для правильной аутентификации в среде развертывания может быть рекомендован конкретный раннер. Еще одно соображение — если ваши этапы непрерывной интеграции содержат ресурсоемкие процессы. В таком случае идеальным вариантом будет использование раннера, специфичного для проекта. Обратите внимание, что специфичный для проекта раннер не принимает задания из других проектов.

Общие раннеры являются универсальными и могут использоваться несколькими проектами. Экземпляр GitLab SaaS, размещенный на GitLab Inc, имеет несколько общих раннеров, которые автоматически подхватят ваши конвейеры, как описано на Шаге 3. Раннеры берут задания из ваших конфигураций на основе алгоритма, учитывающего количество заданий, выполняемых в данный момент для каждого проекта. Общий раннер более гибок, чем специфичный. Его можно настроить из учетной записи администратора экземпляра GitLab. Давайте посмотрим, как получить токены для обоих раннеров.

• Регистрация специфичного для проекта раннера

Чтобы зарегистрировать специфичный для проекта раннер, откройте свой проект в экземпляре GitLab или учетной записи GitLab SaaS. В навигационном меню слева нажмите пункт Settings и выберите опцию CI/CD:

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

В левой части объясняется, как зарегистрировать специфичный для проекта раннер. Это вид экземпляра GitLab SaaS. Вы также можете настроить автоматические раннеры с помощью Kubernetes, но в этом руководстве мы настраиваем раннер вручную:

Далее вам нужно сосредоточиться на разделе, где вам предоставляется токен для этого проекта. Для самостоятельно размещенного инстанса GitLab в URL-адресе будет отображаться домен сервера, на котором запущен ваш инстанс GitLab:

Вы можете отключить общие раннеры для этого проекта, переключив тумблер в правой части в разделе Shared Runners. Затем скопируйте отображаемый токен регистрации в блокнот, так как мы будем использовать его позже.

• Регистрация общего раннера

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

В Admin Panel, нажмите на Runners в разделе Overview левого меню. Откроется страница с инструкциями по настройке Shared Runners:

Скопируйте токен регистрации, отображаемый с правой стороны в разделе Set up a shared Runner manually. Вы будете использовать этот токен для регистрации раннера на следующем шаге.

• Связывание GitLab CI Runner с инстансом GitLab

На этом шаге вы свяжете свой инстанс GitLab с CI-раннером. Снова войдите на сервер, где вы установили службу GitLab runner на Шаге четыре. Чтобы начать процесс регистрации раннера, введите в терминале следующую команду:

Команда предложит вам ответить на ряд вопросов:

• Введите URL-адрес инстанса GitLab (например, https://gitlab.com/):

Укажите доменное имя вашего инстанса GitLab, используя https:// для указания SSL.

• Введите токен регистрации:

Укажите ваш токен регистрации. Здесь вы выберете, хотите ли вы, чтобы этот раннер был привязан к конкретному проекту или был общим. Вы можете указать только один из скопированных ранее токенов для любого из вариантов.

• Введите описание для раннера:

Выберите понятное имя для вашего CI-раннера, так как оно будет отображаться в интерфейсе инстанса GitLab.

• Введите исполнителя (executor): custom, docker-ssh, parallels, virtualbox, docker, shell, ssh, docker+machine, docker-ssh+machine, kubernetes:

Здесь вам предлагаются варианты выбора исполнителя для запуска задач. Введите Docker.

• Введите теги для раннера (через запятую):

Это необязательно. Вы можете ввести любые имена тегов, например, зависимости, которые включает этот раннер. Пока можете оставить это поле пустым.

• Введите Docker-образ по умолчанию (например, ruby:2.6):

Здесь вам нужно указать стандартный образ общего назначения, используемый для запуска задач, если в файле gitlab-ci.yml не указан образ. Введите alpine:latest, так как это небольшой, универсальный и безопасный образ. Нажмите Enter, и раннер будет зарегистрирован и запущен автоматически:

Чтобы просмотреть список доступных на данный момент раннеров, введите следующую команду:

Шаг 6: Подтверждение успешного связывания CI-раннера в GitLab

Затем вернитесь в браузер и перейдите на страницу вашего проекта в инстансе GitLab. В зависимости от того, сколько минут прошло с момента регистрации раннера, вы можете увидеть, что задача в данный момент выполняется:

Или она уже завершена:

После этого перейдите на страницу Pipelines либо через левое меню CI/CD > Pipelines, либо нажав на иконку running, passed, или failed (если в пайплайне возникли ошибки), чтобы просмотреть состояние запуска CI. Здесь мы видим, что один из этапов (build stage) успешно пройден, а другой все еще выполняется:

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

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

Задача была запущена, и вы можете видеть прогресс, когда команда npm устанавливала зависимости. С правой стороны вы можете просмотреть другую связанную информацию. У вас есть возможность скачать артефакты задачи. Вы также можете переключаться между этапами для просмотра других задач из выпадающего списка.

Здесь вы можете увидеть наши тест-кейсы, отображаемые при выборе задачи на этапе тестирования:

Available Runners

В левом меню, если вы нажмете Settings > CI/CD, и развернете раздел Runners разделе вы должны увидеть только что зарегистрированный раннер. В зависимости от того, указали ли вы токен конкретного проекта или общий токен, раннер появится в соответствующем разделе.

Здесь вы можете видеть, что мы зарегистрировали токен конкретного проекта. Раннер отображается в разделе Specific Runners:

Заключение

В этом руководстве вы узнали, как автоматизировать тестирование с помощью GitLab CI. Мы начали с настройки проекта приложения Node.js на GitLab. Проект включал несколько тест-кейсов и gitlab-ci.yml. Мы узнали, что GitLab использует gitlab-ci.yml файл, чтобы определить, что делать при запуске. gitlab-ci.yml файл — это просто конфигурационный файл, содержащий инструкции по сборке и тестированию приложений, написанный в YAML формате, который понятен раннеру GitLab CI.

Нам также удалось настроить раннер GitLab CI на отдельном хосте. Мы зарегистрировали его для получения задач из наших инстансов GitLab при каждом триггере. Хотя это был простой проект, вы можете использовать эту информацию для настройки конвейеров для сложных проектов. Шаги по добавлению проекта в GitLab и привязке раннера GitLab CI остаются прежними. Изменяются только инструкции и этапы в gitlab-ci.yml файле.

Приятной работы!