Как установить переменные в ваших конвейерах GitLab CI

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

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

Основы

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

test:
  script:
    - echo "$EXAMPLE_VARIABLE"

Вы можете экранировать символ $, используя синтаксис $$VARIABLE:

test:
  script:
    - echo "$$EXAMPLE_VARIABLE"

В этом примере будет регистрироваться $EXAMPLE_VARIABLE вместо значения переменной EXAMPLE_VARIABLE, как показано выше.

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

build:
  image: $CI_REGISTRY_IMAGE/build-utils:latest

GitLab CI определяет несколько встроенных переменных, которые всегда доступны. К ним относятся сведения о коммите, ветке и мерж-реквесте, с которыми работает конвейер. Предопределенные переменные также предоставляют доступ к учетным данным для каждого задания для доступа к другим функциям GitLab, таким как Container Registry и Dependency Proxy.

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

Определение переменной

Переменные создаются на экране «Настройки» > «CI/CD» > «Переменные» той области, в которой вы хотите, чтобы они были доступны. Для переменной уровня проекта это означает переход в «Настройки» > «CI/CD» на левой боковой панели GitLab при просмотре страницы в пределах проект. Точно так же для переменных уровня группы перейдите к группе и используйте боковую панель, чтобы перейти к ее настройкам CI. Переменные уровня экземпляра расположены по тому же маршруту в области администрирования GitLab.

Разверните раздел «Переменные», чтобы просмотреть все уже определенные переменные. Нажмите синюю кнопку «Добавить переменную», чтобы начать добавление нового элемента в список.

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

Затем установите значение вашей переменной. Если в раскрывающемся списке «Тип» оставить значение «Переменная», это значение будет вводиться как есть каждый раз, когда вы ссылаетесь на переменную в конвейере. Изменение типа на «Файл» введет значение как временный файл в вашу среду сборки; значением переменной окружения будет путь к этому временному файлу. Это может быть более безопасным способом ввода конфиденциальных данных, если ваше приложение готово прочитать окончательное значение из указанного файла.

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

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

Защищенные переменные

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

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

Маскированные переменные

Параметр «Маскировать переменную» — это еще один способ повысить безопасность ваших переменных. Когда этот флажок установлен, GitLab автоматически отфильтрует значение переменной из собранных журналов заданий. Любое непреднамеренное echo $SECRET_VALUE будет удалено, что снизит риск того, что пользователь увидит конфиденциальное значение токена при проверке журналов заданий с помощью веб-интерфейса GitLab.

Для успешного маскирования необходимо, чтобы значения переменных были надежно обнаружены в журналах. Следовательно, он работает только для значений, отвечающих определенным требованиям к форматированию. Большинство распространенных форматов токенов аутентификации, а также все данные в кодировке Base64 будут совместимы. Маскирование работает только для значений размером до 4 КиБ.

Переменные уровня среды

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

Используйте раскрывающийся список «Область среды» в диалоговом окне «Добавить переменную», чтобы выбрать среду для вашей переменной. Переменная будет определена только в конвейерах, которые ссылаются на выбранную среду через поле environment в файле .gitlab-ci.yml.

Установка переменных в .gitlab-ci.yml

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

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

variables:
  DEPLOY_URL: example.com

deploy_staging:
  variables:
    DEPLOY_URL: staging.example.com
    DEPLOY_IS_STAGING_ENV: true
  script:
    - ./deploy.sh

deploy_production:
  script:
    - ./deploy.sh

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

Переопределение переменных

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

Предопределенные переменные GitLab всегда устанавливаются первыми.
Переменные, определенные в .gitlab-ci.yml, устанавливаются следующими (переменные задания более специфичны, чем переменные конвейера).
Переменные, установленные на уровне экземпляра, группы и проекта, накладываются друг на друга.
Переменные из определенного триггера воронки переопределяют все предыдущие.

Вы всегда можете запустить конвейер с определенным значением переменной, используя ручное выполнение. Перейдите на страницу вашего проекта CI/CD > Pipelines и нажмите синюю кнопку «Запустить конвейер» в правом верхнем углу.

Используйте раскрывающееся меню, чтобы выбрать ветвь или тег для запуска конвейера. Затем используйте таблицу «Переменные», чтобы определить переменные для добавления к этому запуску конвейера. Они станут наиболее конкретными значениями, применяемыми на последнем этапе порядка приоритета переменных. Переменные, установленные здесь, не будут сохранены или повторно использованы в каком-либо будущем конвейере.

Краткое содержание

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

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