Переменные GitLab CI: руководство

Переменные GitLab CI — это гибкий способ передавать конфигурацию и секреты в окружение задач CI/CD. Используйте уровни (инстанс, группа, проект, pipeline, job) для контроля области видимости и порядка переопределений. Защитите чувствительные значения через «protected» и «masked», используйте тип “File” для больших секретов, и следуйте правилам именования и проверки, чтобы избежать утечек и ошибок выполнения.

Important: маскирование не заменяет надёжное хранение секретов. Маскируются только строки, соответствующие определённым требованиям формата, и максимум 4 KiB.

Логотип GitLab — стилизованная голова лисы

Быстрые ссылки

Основы
Создание переменной
Установка в .gitlab-ci.yml
Переопределение переменных
Рекомендации по безопасности
Примеры и сценарии
Чеклисты ролей
Сводка

Основы

Переменные в GitLab CI — это простые пары «ключ: значение», которые инжектируются в окружение задач как переменные окружения. Их можно использовать для:

передачи конфигурационных данных;
хранения токенов и ключей (с соблюдением мер безопасности);
удобного переиспользования частей pipeline;
уменьшения дублирования в .gitlab-ci.yml.

Определение в job-скриптах выглядит как стандартные переменные окружения.

Пример вывода переменной в shell-скрипте:

# Пример job-скрипта
echo "$EXAMPLE_VARIABLE"

Если вы хотите вывести буквальные символы $VARIABLE, можно экранировать $ двойным долларом:

# Выведет строку "$EXAMPLE_VARIABLE" вместо её значения
echo "$$EXAMPLE_VARIABLE"

Переменные доступны не только в скриптах — их можно интерполировать в других полях .gitlab-ci.yml (например, в image или артефактах):

build:
  image: $CI_REGISTRY_IMAGE/build-utils:latest
  script:
    - make all

GitLab также предоставляет набор предопределённых переменных (predefined), содержащих информацию о коммите, ветке, pipeline, артефактах и прочем. Эти переменные всегда доступны и служат базой контекста для ваших задач.

Где можно хранить переменные

Переменные можно задавать на нескольких уровнях:

Уровень инстанса (Administrator → Settings → CI/CD) — доступно для всех проектов на сервере;
Уровень группы — применяется ко всем проектам группы;
Уровень проекта — доступно только в конкретном проекте;
Уровень pipeline/job — задаётся в .gitlab-ci.yml или при ручном запуске pipeline.

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

Создание переменной в UI

Переменные добавляются через Settings → CI/CD → Variables в интерфейсе соответствующего уровня (проект/группа/инстанс). Нажмите Add variable и заполните форму.

Скриншот: добавление переменной в интерфейсе GitLab CI

Требования и рекомендации при создании:

Key: уникальное имя переменной. Допускаются буквы, цифры и подчёркивания. Имя должно соответствовать правилам используемой оболочки.
Value: значение переменной. Может быть любым текстом; при выборе типа “Variable” значение инжектируется как строка.
Type: можно выбрать “Variable” или “File”. В режиме “File” значение создаст временный файл, а переменная будет содержать путь до этого файла.
Protected: переменная будет доступна только в pipeline, запускаемых для защищённых веток и тегов.
Masked: GitLab попытается фильтровать значение из логов задач (работает для значений, соответствующих допустимым форматам и до 4 KiB).
Environment scope: ограничивает видимость переменной конкретной средой (environment).

Скриншот: добавление переменной в интерфейсе GitLab CI

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

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

Отметка Protected означает, что переменная доступна только в pipeline, запускаемых для защищённых веток и тегов (protected branches/tags). Хорошая практика — помечать как protected переменные, используемые для деплоя на production.

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

Mask variable скрывает значение в логах задач. Ограничения:

Значение должно соответствовать допустимому формату (наиболее распространённые токены подходят).
Работает для значений ≤ 4 KiB.
Не защищает от утечек через другие каналы (например, если сборка отправляет значение в удалённую систему в явном виде).

Переменные уровня окружения

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

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

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

Пример использования:

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 чаще используются как «псевдо-переменные конфигурации» — они помогают избежать дублирования и делают файл читабельным.

Порядок приоритета переменных

Переопределение значений может происходить на нескольких уровнях. Упрощённый порядок приоритета (с наименьшим приоритетом — внизу):

Значения, переданные при ручном запуске pipeline (Run pipeline) — самые приоритетные для конкретного запуска.
Переменные триггера pipeline (trigger).
Переменные уровня pipeline и job, определённые в .gitlab-ci.yml — job-переменные более специфичны, чем глобальные.
Переменные проекта, группы, инстанса — чем выше уровень, тем ниже приоритет.
Предопределённые переменные GitLab — задаются системой и доступны всегда.

Рекомендуем проверять значение переменной на этапе отладки, чтобы понять, какое определение действует в текущем запуске. Для отладки удобно временно вывести значения в закрытый лог или использовать job, который сохраняет переменные в артефакт (только безопасные данные).

Ручной запуск с локальными переменными

Вы можете запустить pipeline вручную и указать набор переменных, которые будут использованы только для этого запуска. Это делается на странице CI/CD → Pipelines → Run pipeline.

Скриншот: ручной запуск pipeline с переменными

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

Примеры использования и сценарии

Хранение приватных токенов для доступа к реестру образов. Пометьте такие переменные как protected и masked, либо используйте Type: File и предоставьте приложению путь к файлу с секретом.
Разделение конфигурации по окружениям: DEPLOY_URL, API_BASE и т. п. — задавайте с Environment scope: staging/production.
Параметризация сборок: передавайте флаги сборки и версии через переменные в .gitlab-ci.yml, чтобы переиспользовать один pipeline для нескольких целей.
Feature-branch pipelines: задавайте значения, специфичные для ветки, с помощью protected/не-protected комбинации и правил запуска (rules).

Практические шаблоны именования

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

Используйте префиксы по области: CI, DEPLOY, DB, API (например, API_TOKEN_SERVICE1).
Для окружений добавляйте явные суффиксы или используйте Environment scope вместо сложных имён.
Думайте о читаемости: длинные имена допустимы, но избегайте неоднозначных аббревиатур.

Пример:

PRODUCTION_DB_URL — URL базы для production
STAGING_API_TOKEN — токен для staging API
CI_IMAGE_TAG — тег образа, используемый CI

Возможные ошибки и когда система может не подойти

Маскирование не работает: вероятная причина — значение не соответствует допустимому формату или превышает 4 KiB.
Переменная не видна в job: проверьте область видимости (environment scope), protected-статус и приоритет определения.
Конфликт имён или зарезервированное имя оболочки: проверьте, не совпадает ли ключ с системной переменной.
Нелеченые секреты в логах: убедитесь, что build-скрипты не печатают значения и что сторонние утилиты не отправляют их в открытые места.

Когда GitLab variables не подходят:

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

Чеклисты по ролям

DevOps-инженер

Проверить, что секреты помечены как protected и masked при необходимости.
Настроить Environment scope для переменных окружений.
Подключить секрет-менеджер для динамических креденшлов.
Подготовить инструкции отката (rollback) и план реагирования на компрометацию ключей.

Разработчик

Использовать переменные в .gitlab-ci.yml для параметризации сборок.
Не печатать секреты в логах, не добавлять их в артефакты.
Тестировать pipeline с заглушками/фейковыми значениями.

Администратор GitLab (self-hosted)

Контролировать инстанс-level переменные и документировать их назначение.
Ограничивать права на редактирование переменных локальными политиками.
Вести ревизию значений и удалять устаревшие переменные.

Критерии приёмки переменных в новом проекте

Все секреты вынесены в переменные, а не в код.
Для production-значений установлены protected и, где возможно, masked.
Используется Environment scope для отличия staging/production.
Никакие секреты не записываются в публичные логи и артефакты.
Pipeline успешно выполняет полный цикл сборки и деплоя с заданными переменными.

Тесты и приемочные сценарии

Запустить pipeline с фейковыми значениями и убедиться, что функциональность не зависит от реальных секретов.
Запустить ручной pipeline и задать переменную через UI; убедиться, что она перевесила все остальные значения.
Для masked-переменной умышленно echo значения в шаге сборки и проверить, что в логах значение не отображается.
Убедиться, что переменные с Environment scope применяются только при указании соответствующего environment в job.

Модель принятия решений (Mermaid)

flowchart TD
  A[Нужен ли секрет?] -->|Нет| B[Обычная переменная в .gitlab-ci.yml]
  A -->|Да| C{Нужна ли ротация или динамика?}
  C -->|Да| D[Внешний секрет-менеджер]
  C -->|Нет| E{Требуется доступ из множества проектов?}
  E -->|Да| F[Group/Instance переменная]
  E -->|Нет| G[Project переменная]
  F --> H[Пометить как protected если для prod]
  G --> H
  D --> I[Подключить через CI-адаптер]

Советы по миграции и совместимости

При переносе из другого CI проверьте, как ваша система обрабатывает маскирование и файл-тип переменных.
Если у вас уже есть внешние секрет-менеджеры, используйте короткие токены доступа как переменные и подтягивайте полноценные секреты во время рантайма.
Для self-hosted GitLab документируйте инстанс-level переменные и предупреждайте команды о возможных рисках разглашения.

Укрепление безопасности и приватность

Не храните персональные данные или GDPR-существенную информацию в переменных без оценки рисков и прав доступа.
Логи и артефакты должны автоматически проходить проверку на наличие секретов перед публикацией.
Для compliance используйте аудит изменений переменных и ограничивайте доступ к настройкам CI/CD.

Частые ошибки и отладка

Переменная пустая в job: проверьте орфографию Key, область видимости и приоритеты.
Маскирование не сработало: посмотрите формат значения и его длину.
File-тип переменной не читается приложением: убедитесь, что приложение читает путь из переменной, а не ожидает содержимое.

Дополнительные сценарии и альтернативы

Для чувствительных операций рассмотрите применение краткоживущих (ephemeral) токенов, получаемых на этапе выполнения job.
Вместо глобальных переменных используйте инъекции через Vault Agent или интеграции cloud-поставщиков, чтобы избегать долгоживущих секретов.

Терминологический мини-глоссарий

Protected — пометка, ограничивающая видимость переменной только защищёнными ветками/тегами.
Masked — признак, указывающий на попытку скрыть значение в логах.
Environment scope — ограничение видимости переменной конкретной средой deploy.
Type: File — переменная создаётся как временный файл; значение переменной — путь к файлу.

Сводка

Переменные GitLab CI позволяют гибко конфигурировать pipeline и безопасно передавать секреты при соблюдении простых правил. Выбирайте уровень хранения по принципу наименьших привилегий, используйте protected и masked для чувствительных данных, и интегрируйте внешний секрет-менеджер при необходимости динамической ротации. Тестируйте поведение переменных в реальных сценариях и документируйте решения на уровне команды и администрирования.

Ключевые действия на старте:

Проанализируйте, какие значения должны стать переменными.
Перенесите секреты в переменные проекта/группы, установите protected/masked при необходимости.
Обновите .gitlab-ci.yml, чтобы использовать переменные вместо хардкода.
Напишите тестовые job’ы для проверки применения переменных.

Конец руководства.

Переменные GitLab CI: руководство и практики