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

Вступление

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

В этом руководстве мы покажем, как настроить GitLab CI для отслеживания изменений в ваших хранилищах и запуска автоматических тестов для проверки нового кода. Мы начнем с работающей установки GitLab, где мы скопируем пример репозитория для базового приложения Node.js. После настройки нашего процесса CI, когда новый файл помещается в репозиторий, GitLab будет использовать CI runner для выполнения набора тестов для кода в изолированном контейнере Docker.

Предпосылки

Прежде чем мы начнем, вам нужно настроить начальную среду. Нам нужен защищенный сервер GitLab, сконфигурированный для хранения нашего кода и управления нашими процессами CI / CD. Кроме того, нам нужно место для запуска автоматизированных тестов. Это может быть либо тот же сервер, на котором установлен GitLab, либо отдельный хост. В следующих разделах требования рассматриваются более подробно.

Сервер GitLab, защищенный с помощью SSL

Для хранения исходного кода и настройки наших задач CI / CD нам необходим экземпляр GitLab, установленный на сервере Ubuntu 16.04. В настоящее время GitLab рекомендует использовать сервер с как минимум * 2 ядрами ЦП * и * 4 ГБ ОЗУ *. Чтобы защитить ваш код от несанкционированного доступа или взлома, экземпляр GitLab будет защищен с помощью SSL с помощью Let Encrypt. Для выполнения этого шага вашему серверу необходимо иметь доменное имя или поддомен, связанный с ним.

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

Initial Server Setup с Ubuntu 16.04: создайте пользователя + sudo + и настройте базовый брандмауэр
Как установить и настроить GitLab в Ubuntu 16.04: установить GitLab на сервер и защитите его с помощью сертификата Let’s Encrypt TLS / SSL

Мы покажем, как разделить бегуны CI / CD (компоненты, которые запускают автоматизированные тесты) между проектами и как привязать их к отдельным проектам. Если вы хотите разделить участников проекта с CI между проектами, мы настоятельно рекомендуем вам ограничить или отключить публичные регистрации. Если вы не изменили свои настройки во время установки, вернитесь и следуйте https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-gitlab-on-ubuntu-16-04#restrict -или-отключить-публичные регистрации- (необязательно) [необязательный шаг из статьи по установке GitLab об ограничении или отключении регистрации], чтобы предотвратить злоупотребления со стороны внешних лиц.

Один или несколько серверов для использования в качестве GitLab CI Runners

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

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

Initial Server Setup с Ubuntu 16.04: создайте пользователя + sudo + и настройте базовый брандмауэр (вы не нужно завершать это снова, если вы настраиваете CI runner на сервере GitLab)
Как установить и использовать Docker в Ubuntu 16.04: выполните * шаги 1 и 2 * установить Docker на сервер

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

Копирование репозитория примеров из GitHub

Для начала мы создадим новый проект в GitLab, содержащий пример приложения Node.js. Мы будем import оригинальный репозиторий непосредственно из GitHub, чтобы нам не приходилось загружать его вручную.

Войдите в GitLab, щелкните значок * плюс * в правом верхнем углу и выберите * Новый проект *, чтобы добавить новый проект:

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/new_project_icon_3.png [GitLab добавить значок нового проекта]

На странице нового проекта перейдите на вкладку * Импорт проекта *:

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/import-project.png [имя нового проекта GitLab]

Затем нажмите кнопку * Репо по URL *. Хотя существует опция импорта из GitHub, для нее требуется токен личного доступа, который используется для импорта хранилища и дополнительной информации. Нас интересует только код и история Git, поэтому импорт по URL проще.

В поле * URL-адрес хранилища Git * введите следующий URL-адрес хранилища GitHub:

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

Это должно выглядеть так:

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/new_project_github_url2.png [GitLab новый проект GitHub URL]

Поскольку это демонстрация, лучше всего оставить хранилище с пометкой * Private *. Когда вы закончите, нажмите * Создать проект *.

Новый проект будет создан на основе репозитория, импортированного из GitHub.

Понимание файла .gitlab-ci.yml

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

Нажмите на файл + .gitlab-ci.yml + в интерфейсе GitLab для проекта, который мы только что создали. Конфигурация CI должна выглядеть так:

gitlab-ci.yml

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

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

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

image: node:latest

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

stages:
 - build
 - test

Имена, которые вы здесь выбираете, являются произвольными, но порядок определяет порядок выполнения для последующих шагов. Этапы - это теги, которые можно применять к отдельным заданиям. GitLab будет запускать задания одного и того же этапа параллельно и будет ожидать выполнения следующего этапа, пока все задания на текущем этапе не будут завершены. Если этапы не определены, GitLab будет использовать три этапа, называемые + build,` + test` и + deploy, и по умолчанию назначит все задания этапу` + test + `.

После определения этапов конфигурация включает определение + cache +:

cache:
 paths:
   - node_modules/

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

Наша первая работа называется + install_dependencies +:

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

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

Мы явно помечаем этап как «build» с помощью директивы + stage +. Далее мы указываем фактические команды для запуска с помощью директивы + script +. Вы можете включить несколько команд, добавив дополнительные строки в раздел + script +.

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

Наконец, второе задание + test_with_lab + объявляет команду, которая фактически запустит набор тестов:

test_with_lab:
 stage: test
 script: npm test

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

Теперь, когда у вас есть общее представление о том, как файл + .gitlab-ci.yml + определяет задачи CI / CD, мы можем определить одного или нескольких участников, способных выполнить план тестирования.

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

Поскольку наш репозиторий содержит файл + .gitlab-ci.yml +, любые новые коммиты будут запускать новый запуск CI. Если бегунов нет, запуск CI будет установлен в «ожидание». Прежде чем мы определим участника, давайте запустим запуск CI, чтобы посмотреть, как выглядит задание в состоянии ожидания. Как только бегун становится доступным, он сразу же забирает ожидающий пробег.

Вернувшись в представление репозитория проекта GitLab + hello_hapi +, щелкните значок * плюс * рядом с веткой и именем проекта и выберите в меню * Новый файл *:

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/new_file_button2.png [кнопка нового файла GitLab]

На следующей странице введите + dummy_file + в поле * Имя файла * и введите текст в главном окне редактирования:

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/dummy_file2.png [пустой файл GitLab]

Нажмите * Подтвердить изменения * внизу, когда вы закончите.

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

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/pending_marker_2.png [ожидающий маркер GitLab]

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

Чтобы получить больше информации, перейдите в начало страницы и нажмите * Конвейеры *. Вы попадете на страницу обзора конвейера, где вы увидите, что прогон CI помечен как ожидающий и помечен как «зависший»:

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_index_stuck.png [индекс конвейера GitLab застрял]

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

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_detail_view.png [Подробное представление конвейера GitLab]

Наконец, нажмите на задание * install_dependencies *. Это даст вам конкретную информацию о том, что задерживает запуск:

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/job_detail_view.png [подробный вид работы GitLab]

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

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

Установка службы GitLab CI Runner

Теперь мы готовы установить GitLab CI Runner. Для этого нам нужно установить в системе пакет запуска GitLab CI и запустить службу запуска GitLab. Служба может запускать несколько экземпляров бегуна для разных проектов.

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

Процесс установки службы запуска GitLab CI аналогичен процессу, используемому для установки самого GitLab. Мы загрузим скрипт для добавления репозитория GitLab в наш список исходных кодов + apt +. После запуска скрипта мы загрузим пакет runner. Затем мы можем настроить его для обслуживания нашего экземпляра GitLab.

Начните с загрузки последней версии скрипта конфигурации репозитория бегуна GILab CI в каталог + / tmp + (это репозиторий, отличный от того, который используется сервером GitLab):

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

Не стесняйтесь проверять загруженный скрипт, чтобы убедиться, что вы знакомы с действиями, которые он предпримет. Вы также можете найти размещенную версию скрипта here:

less /tmp/gl-runner.deb.sh

Когда вы будете удовлетворены безопасностью скрипта, запустите установщик:

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

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

sudo apt-get install gitlab-runner

Это установит пакет запуска GitLab CI в систему и запустит службу запуска GitLab.

Настройка GitLab Runner

Далее нам нужно настроить GitLab CI runner, чтобы он мог начать принимать работу.

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

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

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

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

Сбор информации для регистрации конкретного бегуна

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

Отсюда щелкните пункт * Настройки * в левом меню. Затем щелкните элемент * CI / CD * в подменю:

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/project_settings_item2.png [элемент настроек проекта GitLab]

На этой странице вы увидите раздел * Настройки бегунов *. Нажмите кнопку * Expand *, чтобы увидеть больше деталей. В подробном представлении левая сторона объяснит, как зарегистрировать бегун для конкретного проекта. Скопируйте регистрационный токен, показанный в шаге 4 инструкции:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/specific_runner_config_settings2.png [Конфигурационные настройки GitLab, специфичные для бегуна]

Если вы хотите отключить какие-либо активные общие бегуны для этого проекта, вы можете сделать это, нажав кнопку * Отключить общих бегунов * справа. Это необязательно.

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

Сбор информации для регистрации общего бегуна

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

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

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/admin_area_icon2.png [значок области администрирования GitLab]

Скопируйте маркер регистрации, отображаемый в верхней части страницы:

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/shared_runner_token2.png [токен общего доступа GitLab]

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

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

Теперь, когда у вас есть токен, вернитесь на сервер, на котором установлена служба запуска GitLab CI.

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

sudo gitlab-runner register

Вам будет задан ряд вопросов для настройки бегуна:

Пожалуйста, введите URL координатора gitlab-ci (например, https://gitlab.com/)*

Введите доменное имя вашего сервера GitLab, используя + https: // + для указания SSL. При желании вы можете добавить + / ci + в конец вашего домена, но последние версии будут перенаправлены автоматически.

Пожалуйста, введите токен gitlab-ci для этого бегуна *

Токен, который вы скопировали в последнем разделе.

Пожалуйста, введите описание gitlab-ci для этого бегуна *

Имя для этого конкретного бегуна. Это отобразится в списке участников службы runner в командной строке и в интерфейсе GitLab.

Пожалуйста, введите теги gitlab-ci для этого бегуна (через запятую) *

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

Вы можете оставить это поле пустым в этом случае.

Блокировать ли Runner для текущего проекта [true / false] *

Назначает бегуна для конкретного проекта. Он не может быть использован другими проектами.

Выберите «false» здесь.

Пожалуйста, введите исполнителя *

Метод, используемый бегуном для выполнения заданий.

Выберите «докер» здесь.

Пожалуйста, введите изображение Docker по умолчанию (например, рубин: 2,1) *

Изображение по умолчанию, используемое для запуска заданий, когда файл + .gitlab-ci.yml + не содержит спецификации изображения. Здесь лучше указать общее изображение и определить более конкретные изображения в файле + .gitlab-ci.yml +, как мы это сделали.

Мы введем здесь «alpine: latest» в качестве небольшого безопасного значения по умолчанию.

После ответа на запросы будет создан новый исполнитель, способный выполнять задачи CI / CD вашего проекта.

Вы можете увидеть бегунов, которые в настоящее время доступны службе бегунов GitLab CI, набрав:

sudo gitlab-runner list

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

Теперь, когда у нас есть бегун, мы можем вернуться к проекту в GitLab.

Просмотр CI / CD Run в GitLab

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

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/ci_running_icon_2.png [значок запуска GitLab CI]

Или это может быть уже завершено:

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/ci_run_passed_icon_2.png [GitLab CI Run Run Icon]

Независимо от состояния, нажмите на значок * running * или * пройденный * (или * fail *, если вы столкнулись с проблемой), чтобы просмотреть текущее состояние запуска CI. Вы можете получить аналогичный вид, нажав на верхнее меню * Pipelines *.

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

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_run_overview.png [Обзор прогона конвейера GitLab CI]

Под заголовком * Stages * будет кружок, обозначающий состояние каждого из этапов цикла. Если вы щелкнете по сцене, вы увидите отдельные задания, связанные со сценой:

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_run_stage_view.png [запуск конвейера GitLab CI stage_view]

Нажмите на задание * install_dependencies * на этапе * build *. Это приведет вас к странице обзора работы:

изображение: https: //assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_job_overview.png [Обзор работы конвейера GitLab CI]

Теперь вместо отображения сообщения о том, что бегунов нет, выводится задание. В нашем случае это означает, что вы можете видеть результаты установки + npm + каждого из пакетов.

По правой стороне вы можете увидеть и другие предметы. Вы можете просмотреть другие задания, изменив * Stage * и щелкнув по прогонам ниже. Вы также можете просматривать или загружать любые артефакты, созданные при запуске.

Заключение

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

TOC