что такое pipeline в gitlab
Как запустить несколько пайплайнов с помощью GitLab CI/CD
Запуск и визуализация пайплайнов при настройке GitLab CI/CD для нескольких проектов.
Непрерывная интеграция (CI) — это практика автоматизации сборки и тестирования кода до его слияния с основной веткой. Она позволяет разработчикам вливать код довольно часто и рано, снижая при этом риск внесения новых ошибок в главный репозиторий исходного кода.
Хотя CI проверяет, что новый код не сломается при интеграции с другим кодом в том же репо, прохождение всех тестов на этом репо — это только первый шаг. После запуска CI в коде важно развернуть и запустить тесты в реальной среде. Переход от CI к непрерывной доставке и деплою (CD) является следующим шагом к “взрослому” DevOps. Развертывание и последующее повторное тестирование позволяют тестировать код одного проекта вместе с другими компонентами и сервисами, которые, возможно, управляются другими проектами.
Зачем мне нужно убедиться, что мой код работает с другими компонентами?
Хорошим примером может служить архитектура микросервисов. Обычно микросервисы управляются в разных проектах, где каждый микросервис имеет свой собственный репозиторий с пайплайном. Кроме того, очень часто каждая команда разработчиков несёт ответственность за отдельные микросервисы и конфигурации пайплайнов. Как программист, вы возможно захотите убедиться, что изменения в вашем коде не нарушают функциональность зависимых от него микросервисов. Поэтому вы можете запускать тесты на них дополнительно к тестам для вашего проекта.
Пайплайн кросс-проекта
При запуске пайплайна проекта, вам также нужно будет запустить кросс-проектные пайплайны, которые в конечном итоге развернут и протестируют последнюю версию всех зависимых микросервисов. Для достижения этой цели вам нужен простой, гибкий и удобный способ запуска других пайплайнов в рамках CI вашего проекта. GitLab CI/CD предлагает легкий путь запуска кросс-проектного пайплайна путем добавления специального задания в файл конфигурации CI.
GitLab CI/CD конфигурационный файл
Добавление job для запуска кросс-проектного пайплайна
Начиная с GitLab 11.8, GitLab предоставляет новый синтаксис конфигурации CI/CD для запуска кросс-проектных пайплайнов, его можно найти в правилах конфигурации пайплайна. Следующий код иллюстрирует настройку bridge job для запуска нисходящего пайплайна:
В приведенном выше примере, как только deploy job (задача развертывания) на этапе деплоя выполнится успешно, запустится задание для Android bridge. Его первоначальный статус будет в ожидании. GitLab создаст нисходящий пайплайн в проекте mobile/android, и, как только он будет создан, Android job выполнится успешно. В этом случае mobile/android является полным путем к этому проекту.
Пользователь, создавший вышестоящий пайплайн, должен иметь права доступа к нижестоящему проекту (в данном случае mobile / android). Если нижестоящий проект не может быть найден или у пользователя нет прав доступа для создания там пайплайна, Android job получит статус failed.
Обзор графиков от восходящего до нижестоящего пайплайна
GitLab CI/CD позволяет визуализировать конфигурацию пайплайна. На приведенном ниже рисунке этапы сборки, тестирования и деплоя являются частями восходящего (upstream) проекта. Как только deploy job выполнено успешно, четыре кросс-проекта будут запущены параллельно, и вы сможете перейти к ним, щелкнув на одну из нисходящих (downstream) job.
На приведенном ниже рисунке виден нисходящий пайплайн «Сервис — Финансы». Теперь можно прокрутить влево к восходящему пайплайну, прокрутить вправо назад к нисходящему или выбрать другой нисходящий пайплайн.
Определение ветки нижестоящего пайплайна
Можно указать имя ветки, которое будет использовать нисходящий пайплайн:
Используйте ключевое слово проекта, чтобы указать полный путь к нисходящему проекту. Используйте ключевое слово branch, чтобы определить имя ветки. GitLab будет использовать коммит, который в данный момент находится в HEAD ветки при создании нисходящего пайплайна.
Передача переменных в нисходящий пайплайн
Когда-нибудь вам возможно захочется передать переменные в нисходящий пайплайн. Вы можете сделать это с помощью ключевых слов для переменных, как и при определении обычной job.
Переменная ENVIRONMENT будет передаваться каждой job, определенной в нисходящем пайплайне. Она будет доступна в качестве переменной среды каждый раз, когда GitLab Runner выбирает job.
Итого о кросс-проектном пайплайне
Пайплайны могут быть сложными структурами с множеством последовательных и параллельных задач, и, как мы только что узнали, иногда они могут запускать нисходящие пайплайны. Чтобы упростить понимание потока пайплайна, включая нисходящие пайплайны, в GitLab есть графики пайплайнов для просмотра пайплайнов и их статусов.
GitLab CI для непрерывной интеграции и доставки в production. Часть 1: наш пайплайн
Итак, GitLab CI: что можно ещё рассказать о нём? На хабре уже есть статьи про установку, про настройку раннеров, про командное использование, про GitLab Flow. Пожалуй, не хватает описаний того, как используется GitLab CI в реальном проекте, где задействовано несколько команд. А в современном мире разработки ПО это действительно так: ведь есть (как минимум) разработчики, тестировщики, DevOps- и релиз-инженеры. С подобным разделением на команды мы работаем уже несколько лет. В этой статье я расскажу о том, как мы, используя и улучшая возможности GitLab CI, реализовали и применяем в production для коллектива из нескольких команд процессы непрерывной интеграции (CI) и отчасти доставки приложений (CD).
Наш пайплайн
Если вы сталкивались с CI-системами ранее, то понятие пайплайна вам знакомо — это последовательность выполнения стадий (здесь и далее в статье для термина stage использую перевод «стадия»), каждая из которых включает несколько задач (здесь и далее в статье job — «задача»). От момента внесения изменений в код до выката в production приложение по очереди оказывается в руках разных команд — подобному тому, как это происходит на конвейере. Отсюда и возник термин pipeline («конвейер» — один из вариантов дословного перевода). В нашем случае это выглядит так:
Краткие пояснения по используемым стадиям:
Как это используется?
Начну с рассказа о пайплайне с точки зрения его использования — то, что можно назвать user story. Тут выяснится, что на самом деле пайплайна у нас даже два: укороченный для веток и полноценный для тегов. И вот как выглядят эти последовательности:
Пайплайн и стадии в деталях
Задачи на стадии build собирают приложение. Для этого мы используем свою разработку — Open Source-утилиту dapp (о её основных возможностях читайте и смотрите в этой статье + видео), которая хорошо ускоряет инкрементальную сборку. Поэтому сборка запускается автоматически для веток с префиксами feature_ (код приложения), infra_ (код инфраструктуры) и тегов, а не только для нескольких традиционно «главных» веток (master/develop/production/release).
Обновлено 06 сентября 2019 г.: в настоящее время проект dapp переименован в werf, его код переписан на Go, а документация значительно улучшена.
Следующая стадия — staging — это набор сред для разработчиков, DevOps-инженеров и тестировщиков. Здесь объявлено несколько задач, разворачивающих приложения из веток с префиксами feature_ и infra_ в урезанных средах для быстрого тестирования новой функциональности или инфраструктурных изменений (код сборки приложения хранится в репозитории приложения).
Стадии pre-production и production доступны только для тегов. Обычно тег вешается после того, как релиз-инженеры принимают несколько merge-запросов из протестированных веток. В целом можно сказать, что мы используем GitLab Flow с тем лишь отличием, что нет автоматического развёртывания на production и потому нет отдельных веток, а используются теги.
Стадия approve — это две задачи: approve и not approve. Первая включает возможность развёртывания на production, вторая — выключает. Эти задачи существуют для того, чтобы в случае проблем на production было видно, что развёртывание происходило не просто так, а с согласия релиз-инженера. Однако суть не в лишении кого-то премии, а в том, что непосредственно развёртывание на production проводит зачастую не сам релиз-инженер, а команда DevOps. Релиз-инженер, запуская задачу approve, разрешает тем самым «нажать на кнопку» deploy to production команде DevOps. Можно сказать, что эта стадия выносит на поверхность то, что могло бы остаться в почтовой переписке или в устной форме.
Такая схема взаимодействия хорошо себя показала в работе, однако пришлось потрудиться, чтобы реализовать её. Как оказалось, GitLab CI не поддерживает из коробки некоторые нужные вещи…
Всё довольно просто и скорее всего понятно. Для каждой задачи используются следующие директивы:
Он демонстрирует возможность формата YAML определять общие блоки и подключать их в нужное место на нужном уровне. Подробнее см. в документации.
Таким образом, задачи на стадиях build, testing, staging, pre-production, которые должны быть доступны для веток infra_, feature_ и тегов, принимают следующий вид:
А задачи на стадиях approve и production, которые доступны только для тегов, имеют такой вид:
Что дальше?
Полная реализация задуманного стала возможной только благодаря нескольким патчам к GitLab и использованию артефактов задач. Подробнее об этом читайте в следующей части статьи: «GitLab CI для непрерывной интеграции и доставки в production. Часть 2: преодолевая трудности».
Руководство по CI/CD в GitLab для (почти) абсолютного новичка
Или как обзавестись красивыми бейджиками для своего проекта за один вечер ненапряжного кодинга
Наверное, у каждого разработчика, имеющего хотя бы один пет-проект, в определённый момент возникает зуд на тему красивых бейджиков со статусами, покрытием кода, версиями пакетов в nuget… И меня этот зуд привёл к написанию этой статьи. В процессе подготовки к её написанию я обзавёлся вот такой красотой в одном из своих проектов:
В качестве среды разработки использовалась VS Code c расширением GitLab Workflow (для валидации файла настроек прямо из среды разработки).
Краткое введение
CD — это когда ты только пушнул, а у клиента уже всё упало?
Что такое CI/CD и зачем нужно — можно легко нагуглить. Полноценную документацию по настройке пайплайнов в GitLab найти также несложно. Здесь я кратко и по возможности без огрехов опишу процесс работы системы с высоты птичьего полёта:
Таким образом, имеем:
Соответственно, задача при настройке CI/CD сводится к тому, чтобы создать набор задач, реализующих все необходимые действия для сборки, тестирования и публикации кода и артефактов.
Потому, что когда появилась необходимость создать приватные репозитории под пет-проекты, на GitHub’e они были платными, а я — жадным. Репозитории стали бесплатными, но пока это не является для меня поводом достаточным переезжать на GitHub.
Потому что там настройка элементарная — даже не требуются знания командной строки. Интеграция с внешними провайдерами git — в пару кликов, импорт SSH-ключей для отправки коммитов в репозиторий — тоже, пайплайн легко настраивается даже не из шаблона.
Исходная позиция: что имеется и чего хочется
Описанные требования органично ложатся на следующую модель пайплайна:
Собираем конфигурацию
Готовим аккаунты
Создаём новый проект
Переходим в Atrifacts, жмём Create feed
Жмём Connect to feed, выбираем Visual Studio, из блока Machine Setup копируем Source
Идём в настройки аккаунта, выбираем Personal Access Token
Создаём новый токен доступа
Копируем созданный токен — после закрытия модального окна значение будет недоступно
Заходим в настройки репозитория в GitLab, выбираем настройки CI/CD
Раскрываем блок Variables, добавляем новую
На этом предварительная настройка завершена.
Готовим каркас конфигурации
Теперь при запуске пайплайна с хранилища образов Microsoft будет скачан указанный образ, в котором и будут исполняться все задачи из конфигурации.
Следующий этап — добавить stage‘ы. По умолчанию GitLab определяет 5 этапов:
Ничего не мешает объявить их явно, впрочем. Порядок, в котором указаны этапы, влияет на порядок, в котором они выполняются. Для полноты изложения, добавим в конфигурацию:
Для отладки имеет смысл получить информацию об окружении, в котором исполняются задачи. Добавим глобальный набор команд, который будет выполняться перед каждой задачей, с помощью before_script :
Осталось добавить хотя бы одну задачу, чтобы при отправке коммитов пайплайн запустился. Пока что добавим пустую задачу для демонстрации:
Всё логично — по умолчанию runner’ы (отвечающие за исполнение скриптов задач, и предоставляемые GitLab’ом) используют bash для исполнения команд. Можно исправить это дело, явно указав в описании задачи, какие теги должны быть у исполняющего пайплайн раннера:
Отлично! Теперь пайплайн выполняется.
Продолжим создание скелета конфигурации, добавив все задачи, описанные выше:
Получили не особенно функциональный, но тем не менее корректный пайплайн.
Настройка триггеров
Из-за того, что ни для одной из задач не указаны фильтры срабатывания, пайплайн будет полностью исполняться при каждой отправке коммитов в репозиторий. Так как это не является желаемым поведением в общем случае, мы настроим фильтры срабатывания для задач.
Вспомним набор требований — сборка и тестирование только для merge request, упаковка и отправка в Azure DevOps — для merge request и пушей в мастер, генерация документации — для пушей в мастер.
Для начала настроим задачу сборки кода, добавив правило срабатывания только при merge request:
Теперь настроим задачу упаковки на срабатывания на merge request и добавление коммитов в мастер:
Как видно, всё просто и прямолинейно.
Также можно настроить задачу на срабатывание только если создан merge request с определённой целевой или исходной веткой:
Настройка сохранения артефактов
Во время выполнения задачи build job у нас будут созданы артефакты сборки, которые можно переиспользовать в последующих задачах. Для этого нужно в конфигурацию задачи добавить пути, файлы по которым нужно будет сохранить и переиспользовать в следующих задачах, в ключ artifacts :
Пути поддерживают wildcards, что определённо упрощает их задание.
Если задача создаёт артефакты, то каждая последующая задача сможет их получить к ним доступ — они будут располагаться по тем же путям относительно корня репозитория, по которым были собраны из исходной задачи. Так же артефакты доступны для скачивания на сайте.
Теперь, когда у нас готов (и проверен) каркас конфигурации, можно переходить собственно к написанию скриптов для задач.
Пишем скрипты
Естественно, есть некоторые нюансы, из-за которых мы несколько усложним команды.
Собираем данные покрытия кода
Coverlet после запуска тестов выводит в консоль статистику по запуску:
GitLab позволяет указать регулярное выражение для получения статистики, которую потом можно получить в виде бейджа. Регулярное выражение указывается в настройках задачи с ключом coverage ; в выражении должна присутствовать capture-группа, значение которой и будет передано в бейдж:
Здесь мы получаем статистику из строки с общим покрытием по линиям.
Публикуем пакеты и документацию
Оба действия у нас назначены на последний этап пайплайна — раз уж сборка и тесты прошли, можно и поделиться с миром наработками.
Для начала рассмотрим публикацию в источник пакетов:
Если в проекте не присутствует файл конфигурации nuget ( nuget.config ), создадим новый: dotnet new nugetconfig
Зачем: в образе может быть запрещён доступ на запись к глобальным (пользовательской и машинной) конфигурациям. Чтобы не ловить ошибки, просто создадим новую локальную конфигурацию и будем работать с ней.
Теперь настроим создание документации:
Лирическое отступление про docfx
Раньше при настройке проекта я указывал источник кода для документации как файл решения. Основной минус — документация создаётся и для тестовых проектов. В случае, если это не нужно, можно задать такое значение узлу metadata.src :
Промежуточный итог
Вот такую простую конфигурацию можно составить буквально за полчаса и пару чашек кофе, которая позволит при каждом запросе слияния и отправке в мастер проверять, что код собирается и тесты проходят, собирать новый пакет, обновлять документацию и радовать глаз красивыми бейджиками в README проекта.
Кстати о бейджиках
Ради них ведь всё и затевалось!
Бейджи со статусами пайплайна и покрытием кода доступны в GitLab в настройках CI/CD в блоке Gtntral pipelines:
Бейдж со ссылкой на документацию я создавал на платформе Shields.io — там всё достаточно прямолинейно, можно создать свой бейдж и получать его с помощью запроса.
Azure DevOps Artifacts также позволяет создавать бейджи для пакетов с указанием актуальной версии. Для этого в источнике на сайте Azure DevOps нужно нажать на Create badge у выбранного пакета и скопировать markdown-разметку:
Добавляем красоты
Выделяем общие фрагменты конфигурации
Во время написания конфигурации и поисков по документации, я наткнулся на интересную возможность YAML — переиспользование фрагментов.
Как видно из настроек задач, все они требуют наличия тега windows у раннера, и срабатывают при отправке в мастер/создании запроса на слияние (кроме документации). Добавим это во фрагмент, который будем переиспользовать:
И теперь в описании задачи можем вставить объявленный ранее фрагмент:
Названия фрагментов должны начинаться с точки, чтобы не быть интерпретированными как задача.
Версионирование пакетов
При создании пакета компилятор проверяет ключи командной строки, и в их отсутствие — файлы проектов; найдя узел Version, он берёт его значение как версию собираемого пакета. Выходит, чтобы собрать пакет с новой версией, нужно либо обновить её в файле проекта, либо передать как аргумент командной строки.
Добавим ещё одну хотелку — пусть младшие два номера в версии будут годом и датой сборки пакета, и добавим пререлизные версии. Добавлять эти данные в файл проекта и проверять перед каждой отправкой можно, конечно — но можно ведь это делать и в пайплайне, собирая версию пакета из контекста и передавая через аргумент командной строки.
Данную задачу решает следующий скрипт:
Добавляем скрипт в задачу pack and deploy job и наблюдаем сборку пакетов строго при наличии заданной строки в сообщении коммита.
Итого
Потратив примерно полчаса-час времени на написание конфигурации, отладку в локальном powershell и, возможно, пару неудачных запусков, мы получили несложную конфигурацию для автоматизации рутинных задач.
Конечно, GitLab CI/CD гораздо обширнее и многограннее, чем может показаться после прочтения этого руководства — это совершенно не так. Там даже Auto DevOps есть, позволяющий
automatically detect, build, test, deploy, and monitor your applications
Теперь в планах — сконфигурировать пайплайн для развёртывания приложений в Azure, с использованием Pulumi и автоматическим определением целевого окружения, что будет освещено в следующей статье.
Создание переиспользуемых пайплайнов для GitLab CI на bash
А если добавить к этому возможности include и extends, можно делать достаточно интересные вещи: создавать шаблонные джобы и пайплайны, выносить их в отдельные репозитории и повторно использовать в разных проектах без копирования кода.
Но к сожалению, не всё так радужно, как хотелось бы. Инструкция script в GitLab CI очень низкоуровневая. Она просто выполняет те команды, которые ей переданы в виде строк. Писать большие скрипты внутри YAML не очень удобно. По мере усложнения логики количество скриптов увеличивается, они перемешиваются с YAML делая конфиги нечитаемыми и усложняя их поддержку.
Мне очень не хватало какого-то механизма, который бы упростил разработку больших скриптов. В результате у меня родился микрофреймворк для разработки GitLab CI, про который я и хочу рассказать в этой статье (на примере простого пайплайна для сборки docker-образов).
Пример: Сборка docker-образов в GitLab
Я хочу рассмотреть процесс создания пайплайна на примере простой задачи, которую часто встречал у разных команд: создание базовых docker-образов в GitLab для их повторного использования.
Например, команда пишет микросервисы и хочет для них для всех использовать свой собственный базовый образ с набором предустановленных утилит для отладки.
Или другой пример, команда пишет тесты и хочет используя services прямо в GitLab создавать для них временную базу данных (или очередь, или что-то ещё) используя свой собственный образ.
Но предположим, что нам необходимо создать чуть более сложный пайплайн, который будет работать следующим образом:
На каждый коммит должен запускаться пайплайн с двумя джобами:
Подобный пайплайн должен достаточно хорошо работать. Он будет быстро пересобирать все изменённые докерфайлы при каждом коммите. При этом у разработчиков останется возможность вручную пересобрать сразу всё, если это потребуется.
Структура репозитория для такого пайплайна может выглядеть следующим образом:
В интерфейсе гитлаба подобный пайплайн может выглядеть следующим образом:
Результатом работы такого пайплайна станет набор docker-образов, которые можно будет найти в Container Registry проекта:
А теперь попробуем создать пайплайн, который бы решал нашу задачу.
Шаг 1: Решение «в лоб»
Здесь мы делаем следующее:
Выполняет поиск всех докерфайлов при помощи команды:
Выполняет поиск всех докерфайлов, изменённых в последнем коммите при помощи команды:
Данный пайплайн работает но есть очевидные проблемы:
Скрипты обоих джобов практически полностью дублируются (за исключением поиска докерфайлов)
Скрипты сильно загромождают конфиг, усложняя его понимание.
В этом месте появляется тот микрофреймворк для разработки GitLab CI про который я упоминал в самом начале.
GitLab CI Bootstrap
Дать возможность разбивать большие скрипты на более мелкие и подключать одни скрипты к другим, чтобы улучшить структурирование кода и упростить его поддержку.
Дать возможность выносить скрипты и джобы (со скриптами) в отдельные репозитории, чтобы повторно использовать их в разных проектах.
В таких джобах будет включаться механизм загрузки скриптов (который описан ниже), который позволяет загружать скрипты из текущего репозитория или из любого другого репозитория внутри того же экземпляра GitLab.
При этом для загрузки скриптов не нужны специальные токены доступа. Загружать скрипты можно даже из внутреннего или приватного репозиториев. Главное, чтобы у разработчика, запустившего пайплайн был доступ на чтение к этим репозиториям.
Итак, давайте посмотрим, как это поможет нам упростить наш пайплайн для сборки docker-образов.
Шаг 2: Выносим все скрипты в отдельный файл
Шаг 3: Переносим пайплайн в отдельный репозиторий
Мы сделали работающий пайплайн и вынесли его скрипты в отдельный файл, но пока этот пайплайн находится в том же репозитории, что и докерфайлы. Это означает, что если другая команда захочет использовать его для сборки своих докерфайлов, им придётся скопировать все скрипты. А это в свою очередь означает, что если нам необходимо будет внести в пайплайн какие-нибудь изменения, то потом их нужно будет внести и всем командам, которые скопировали себе пайплайн.
Вместо этого мы можем вынести пайплайн в отельный репозиторий и предложить нескольким командам подключить его через include.
Однако для этого придётся внести в пайплайн небольшое изменение. Дело в том, что поскольку скрипты теперь будут фактически расположены не в том же репозитории, где запускается пайплайн, джоб должен как-то это понять и определить, откуда загрузить скрипты. Это делается при помощи специальных переменных, которые добавляются в пайплайн.
Наш репозиторий с докерфайлами теперь будет выглядеть так:
Сам пайплайн в отдельном репозитории будет выглядеть следующим образом:
Шаг 4: Разбиваем большие скрипты на отдельные файлы
Мы вынесли пайплайн в отдельный репозиторий и теперь другие команды могут подключать его в свои проекты простым инклюдом. Изменения, которые мы будем вносить в пайплайн будут автоматически отражаться на всех командах и нам не придётся ходить по командам с просьбами обновиться на последнюю версию.
Также хочу отметить, что эта функция всегда загружает каждый файл только один раз, даже если вызов функции include с этим файлом встретится несколько раз.
Поэтому мы можем разбить наш файл dockerfiles.gitlab-ci.sh на несколько более мелких:
Заключение
В данной статье мы прошли по шагам создания переиспользуемого пайплайна для GitLab CI с использованием bash и GitLab CI Bootstrap.
Чтобы не увеличивать статью я описал только самые основные возможности своего микрофреймворка. Кроме этого он также позволяет:
Подключать скрипты из нескольких репозиториев по цепочке. Т.е. общий пайплайн, вынесенный в отдельный репозиторий сам по себе может также подключать скрипты из ещё нескольких репозиториев. Это создаёт большой простор для создания целых библиотек для GitLab CI.
Получать доступ к произвольным файлам в подключаемом репозитории. Это можно использовать для написания скриптов на других языках, таких как Python или C#.
Делать хуки на определённые функции. Это позволяет разработчикам, использующим общий пайплайн расширять его логику при необходимости.
Если нужно, я могу рассказать про эти возможности в комментариях.
Я пока не могу сказать, что мой микрофреймворк близок к версии 1.0. Ещё есть вещи, над которыми стоит поработать. Тем не менее, ранние его версии я успешно использовал в нескольких проектах и это действительно сильно упростило мне разработку.