Настройка непрерывной интеграции в GitLab в Ubuntu 16.04

GitLab Community Edition – это провайдер репозиториев Git с дополнительными функциями для управления проектами и разработки программного обеспечения. Одной из наиболее ценных функций GitLab является встроенный инструмент непрерывной интеграции и развертывания под названием GitLab CI.

Этот мануал поможет настроить GitLab CI для отслеживания обновлений в репозиториях проектов и автоматического тестирования нового кода. Для примера здесь используется простое приложение Node.js. После отправки коммита GitLab использует CI для тестирования кода в контейнере Docker.

Требования

Для начала нужно настроить среду. Вам понадобится сервер GitLab для хранения кода и управления процессами непрерывной интеграции и развертывания. Кроме того, нужно место для запуска тестов кода. Это может быть тот же сервер, на котором установлен GitLab, либо отдельный хост. Более подробное описание требований вы найдете ниже.

 Сервер GitLab с поддержкой SSL

Для хранения исходного кода и настройки задач CI/CD установите на сервер Ubuntu 16.04 экземпляр GitLab. В настоящее время GitLab рекомендует использовать 2 ядра и 4 ГБ оперативной памяти минимум. Чтобы защитить ваш, GitLab нужно защитить с помощью SSL-сертификата. Для этого можно обратиться к сервису Let’s Encrypt. Чтобы получить бесплатный сертификат от Let’s Encrypt, необходимо иметь доменное имя или связанный с ним поддомен.

Подробные инструкции по настройке сервера и сертификата вы найдете здесь:

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

Дополнительный runner-сервер (или несколько серверов)

Runner – это сервер, который проверяет код и автоматически запускает тестирование обновлений. Чтобы изолировать среду тестирования, все тесты следует запускать в контейнерах Docker. Для этого нам нужно установить Docker на runner-сервер.

Примечание: Если у вас будет несколько runner-серверов, установите Docker на каждый из них.

Это можно сделать на сервере GitLab, но лучше использовать дополнительный сервер Ubuntu 16.04, чтобы обеспечить достаточное количество ресурсов и изолировать среду тестирования на отдельном сервере. Инструкции по настройке можно найти в статьях:

Копирование репозитория с GitLab

Сначала нужно создать новый проект, в котором будет разрабатываться простое приложение Node.js. Импортируйте исходный репозиторий с GitHub.

Откройте аккаунт GitLab, нажмите на кнопку с плюсом и выберите New project, чтобы добавить новый проект.

На новой странице введите название проекта в поле Project name. В этом мануале проект будет называться hello_hapi, как клонированный репозиторий.

Затем нажмите Repo by URL в разделе Import project from. Интерфейс предлагает и GitHub, но для этого необходим персональный токен доступа. Кроме того, с GitHub загрузится много лишней информации. Нам нужен только код и история Git, потому приложение проще импортировать по URL–адресу.

Введите URL репозитория GitHub в поле Git repository URL.

https://github.com/do-community/hello_hapi.git

Поскольку это тестовый проект, отметьте репозиторий как Private. Чтобы сохранить проект, нажмите Create project.

Файл .gitlab-ci.yml

В каждом репозитории GitLab CI ищет файл .gitlab-ci.yml, чтобы понять, как тестировать код. В импортированном репозитории уже есть этот файл.

Читайте также: Документация gitlab-ci.yml

Кликните по файлу .gitlab-ci.yml в интерфейсе GitLab. Файл должен содержать такой код:

image: node:latest
stages:
- build
- test
cache:
paths:
- node_modules/
install_dependencies:
stage: build
script:
- npm install
artifacts:
paths:
- node_modules/
test_with_lab:
stage: test
script: npm test

Файл использует синтаксис YAML конфигурации GitLab CI для определения действий, порядка, условий и ресурсов, необходимых для выполнения каждой задачи. При написании собственных файлов GitLab CI вы можете использовать /ci/lint в интерфейсе GitLab, чтобы проверить формат файла.

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

image: node:latest

Далее определяются этапы непрерывной интеграции:

stages:
- build
- test

Вы можете назвать этапы интеграции как угодно, но порядок менять нельзя: иначе вы измените порядок выполнения последующих этапов. Этапы – это теги, которые можно применять к отдельным заданиям. GitLab будет параллельно запускать задания одного и того же этапа и ждать, пока все задания на текущем этапе не будут завершены. Если в файле этапы не определены, GitLab будет использовать три стандартных этапа — build, test и deploy, — и по умолчанию присваивать все задания этапу test.

После этапов в конфигурации находится определение кэша:

cache:
paths:
- node_modules/

Здесь указаны файлы или каталоги, которые можно кэшировать между прогонами или этапами. Это может уменьшить время, затрачиваемое на выполнение заданий. В данном случае кэшируется каталог node_modules, в котором npm будет устанавливать зависимости.

Первая задача (job) называется install_dependencies:

install_dependencies:
stage: build
script:
- npm install
artifacts:
paths:
- node_modules/

Задачи можно называть как угодно, но поскольку имена будут использоваться в интерфейсе GitLab, лучше выбирать описательные имена. Обычно npm install можно комбинировать с другими этапами тестирования, но в руководстве он выделе в отдельный этап, чтобы продемонстрировать взаимодействие между этапами.

Директива stage содержит метку этапа build. Затем нужно указать команды в директиве script. Чтобы указать несколько команд, добавьте в раздел script новые строки.

Подраздел artifacts указывает пути к файлам или каталогам, которые нужно сохранять между этапами. Поскольку команда npm install устанавливает зависимости проекта, следующей задаче нужен доступ к загруженным файлам. Путь node_modules предоставляет такой доступ. Также файлы можно просмотреть или загрузить в пользовательском интерфейсе GitLab после тестирования. Если вы хотите сохранить все, что было создано на определенном этапе, замените весь раздел paths строкой:

untracked: true

Вторая задача называется test_with_lab и объявляет задачу, которая запустит тест.

test_with_lab:
stage: test
script: npm test

Она присваивается этапу test. Этот этап имеет доступ ко всем файлам, сгенерированным на этапе build (в данном случае это зависимости проекта). Раздел script представлен однострочным синтаксисом YAML, который можно использовать, когда имеется только один элемент.

Запуск непрерывной интеграции

Любой новый коммит запустит процесс непрерывной интеграции. Если в среде нет доступных runner-серверов, процесс CI получит состояние «pending». Прежде чем определить runner, запустите процесс CI, чтобы увидеть, как он выглядит в ожидающем состоянии. Как только runner-сервер будет доступен, он немедленно обработает ожидающий процесс.

Вернитесь в GitLab репозиторий проекта hello_hapi. Нажмите кнопку с плюсом и выберите New file.

На следующей странице укажите имя нового файла (допустим, dummy_file) в поле File name.

Нажмите Commit changes.

Теперь вернитесь на главную страницу проекта. Маленький значок паузы появится рядом с последним коммитом. Если вы наведете на него курсор, появится сообщение «Commit: pending».

Это означает, что тесты, которые проверяют новый код, еще не выполнились.

Чтобы получить дополнительную информацию, перейдите в начало страницы и нажмите Pipelines. Вы попадете на страницу обзора конвейера, где увидите, что процесс CI отмечен как stuck.

Примечание: В правой части страницы есть кнопка инструмента CI Lint. Здесь вы можете проверить синтаксис файлов gitlab-ci.yml.

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

Кликните по задаче install_dependencies, чтобы получить подробную информацию о процессе.

На этой странице будет сообщение о том, что задание не выполняется из-за отсутствия runner-сервера. Это нормально, так как в среде пока нет такого сервера. Как только runner-сервер будет доступен, вы сможете использовать этот же интерфейс для просмотра вывода. Кроме того, здесь можно загрузить файлы («артефакты»), созданные во время сборки.

Установка runner-сервера GitLab CI

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

Как говорилось в требованиях, вы можете настроить runner на одном сервере с GitLab CI или использовать другой сервер (чтобы обеспечить достаточно ресурсов). Помните, что какой бы хост вы ни выбрали, вам нужно установить Docker для дальнейшей работы.

Процесс установки сервиса runner GitLab CI похож на процесс установки GitLab. Нужно загрузить сценарий и добавить репозиторий GitLab в индекс apt. После запуска сценария нужно загрузить пакет runner, а затем настроить его для обслуживания экземпляра GitLab.

Для начала загрузите последнюю версию сценария настройки репозитория GitLab CI runner в каталог /tmp.

curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.deb.sh -o /tmp/gl-runner.deb.sh

Просмотрите загруженный скрипт. Это также можно сделать по этой ссылке.

less /tmp/gl-runner.deb.sh

Убедившись, что сценарий не сделает ничего вредоносного, запустите его.

sudo bash /tmp/gl-runner.deb.sh

Сценарий настроит сервер для использования поддерживаемых репозиториев GitLab. Это позволяет управлять пакетами GitLab с помощью стандартных инструментов управления пакетами. Когда сценарий будет выполнен, вы можете установить пакет с помощью apt-get:

sudo apt-get install gitlab-runner

Эта команда установит GitLab CI runner и запустит сервис.

Настройка Gitlab CI Runner

Затем нужно настроить GitLab CI runner для обработки непрерывной интеграции.

Для аутентификации GitLab CI runner на сервере GitLab необходим токен. Тип токена зависит от целей сервиса runner.

Отдельный runner-сервер, предназначенный для одного проекта, используется в тех ситуациях, когда у проекта есть индивидуальные требования к runner-серверу. К примеру, если в файле gitlab-ci.yml есть учетные данные, для аутентификации используется индивидуальный runner-сервер проекта, который не будет принимать соединений от других проектов.

Разделяемый runner-сервер используется для обслуживания нескольких проектов. Он будет принимать задачи всех проектов согласно алгоритму, который учитывает количество задач, выполняемых в настоящее время для каждого проекта. Этот тип runner-серверов более гибкий. Для его настройки нужно войти в учетную запись администратора GitLab.

Далее вы узнаете, как использовать токен для настройки каждого типа runner-сервера.

Сбор данных для настройки индивидуального runner-сервера

Если вы хотите, чтобы runner-сервер был привязан к определенному проекту, откройте страницу проекта в интерфейсе GitLab.

Нажмите Settings в верхней панели навигации и кликните CI/CD Pipelines.

Вы увидите раздел Specific Runners, в котором будут инструкции по настройке индивидуального runner-сервера проекта. Следуйте инструкциям, в шаге 3 скопируйте токен.

Чтобы отключить все разделяемые runner-серверы для этого проекта, нажмите кнопку Disable shared Runners справа. Это опционально.

Пропустите следующий раздел и переходите к регистрации runner-сервера.

Сбор данных для разделяемого runner-сервера

Для регистрации разделяемого runner-сервера войдите как администратор.

Нажмите значок гаечного ключа в верхней панели управления. В разделе Overview нажмите Runners.

Скопируйте токен в верхней части страницы.

Регистрация GitLab CI Runner

С помощью токена можно настроить взаимодействие GitLab CI Runner и сервера GitLab CI. Перейдите на сервер, на котором установлен GitLab CI Runner.

Чтобы зарегистрировать runner-сервер, введите:

sudo gitlab-runner register

Команда задаст ряд вопросов:

  • Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/): Введите домен сервера GitLab (https:// указывает, что трафик шифруется по SSL). По желанию после домена можно добавить секцию /ci.
  • Please enter the gitlab-ci token for this runner: Введите скопированный токен.
  • Please enter the gitlab-ci description for this runner: Введите имя этого runner-сервера. Оно будет отображаться в списке бегунов службы runner-серверов в командной строке и в интерфейсе GitLab.
  • Please enter the gitlab-ci tags for this runner (comma separated): Это теги, которые вы можете присвоить runner-серверу. Задачи GitLab могут с помощью этих тегов корректировать свои требования. В данном случае это поле можно не заполнять.
  • Whether to lock Runner to current project [true/false]: Здесь можно присвоить runner-сервер определенному проекту. Тогда другие проекты не смогут использовать его. Введите false.
  • Please enter the executor: Укажите метод выполнения задач. Введите docker.
  • Please enter the default Docker image (e.g. ruby:2.1): Укажите образ по умолчанию. Он будет использоваться для запуска задач, если в файле .gitlab-ci.yml не указан другой образ. Лучше всего указать общий образ по умолчанию и определить индивидуальные образы в файле .gitlab-ci.yml. Здесь вы можете указать образ alpine:latest.

После этого команда создаст новый runner-сервер.

Вы можете просмотреть доступные runner-серверы GitLab CI.

sudo gitlab-runner list
Listing configured runners                          ConfigFile=/etc/gitlab-runner/config.toml
example-runner                                      Executor=docker Token=e746250e282d197baa83c67eda2c0b URL=https://example.com

Просмотр процесса непрерывной интеграции в GitLab

Вернитесь к проекту GitLab в браузере. в зависимости от того, сколько времени прошло с момента создания runner-сервера, он может запуститься или даже уже обработать процесс.

Независимо от состояния runner-сервера нажмите кнопку running или passed (или failed, если сервер столкнулся с проблемой), чтобы просмотреть текущее состояние процесса CI. Вы можете получить те же данные в меню Pipelines.

Вы попадете на страницу обзора конвейера, где увидите статус процесса GitLab CI.

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

Например, кликните по задаче install_dependencies на этапе build. Вы получите краткий обзор задачи.

Теперь процесс обрабатывается, поскольку появился доступный runner. Это значит, вы можете увидеть результаты установки менеджером npm каждого из пакетов.

Tags: , , ,