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

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

• Основные положения
• Как определить переменную
• Где задавать переменные
• Переопределение переменных
• Лучшие практики и контрольные списки
• Дополнительно: модели принятия решений, примеры, матрица совместимости

Основы

Переменные в GitLab CI — это пары «ключ=значение», которые попадают в окружение выполняемой задачи как переменные среды. Простейшее использование — ссылаться на переменные в .gitlab-ci.yml и в скриптах задач.

Определение термина: переменная — строка с именем (ключ) и значением; в задачах она доступна как обычная переменная окружения.

Пример простого вызова в задаче (YAML):

test:
  script:
    - echo "$EXAMPLE_VARIABLE"

Если нужно вывести сам текст $EXAMPLE_VARIABLE, а не его значение, экранируйте $ двойным знаком: $$:

test:
  script:
    - echo "$$EXAMPLE_VARIABLE"

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

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

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

Кроме встроенных переменных вы можете определить собственные значения на разных уровнях: instance, group, project и pipeline. В этом руководстве мы фокусируемся на UI, но те же операции доступны через API.

Как определить переменную (UI)

Переменные создаются на экране Settings > CI/CD > Variables для нужного уровня (проект, группа, инстанс). Для проектных переменных зайдите в проект, откройте Settings → CI/CD и разверните секцию Variables. Нажмите кнопку “Add variable”.

• Key — имя переменной: допустимы буквы, цифры и символ подчёркивания. Не используйте зарезервированные слова шелла.
• Value — значение переменной.
• Type — “Variable” (внедряется как значение) или “File” (внедряется как временный файл — переменная окружения будет содержать путь к файлу).
• Protected — переменная доступна только в пайплайнах защищённых веток/тэгов.
• Mask variable — скрывает значение в логах (наличие ограничений по формату и длине).
• Environment scope — ограничивает область действия переменной до конкретной среды (например, staging или production).

Пример: если переменная нужна только для деплоя в release, пометьте её Protected и укажите Environment scope соответствующим образом.

Нажмите “Add variable” для сохранения. Вы можете редактировать или удалять переменные позже через иконку редактирования (карандаш).

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

Protected (защищённые) переменные добавляются только в пайплайны защищённых веток и тэгов. Применяйте их для значений, используемых лишь в релизных или деплойных задачах (например, приватные ключи). Это снижает риск случайной утечки.

Маскируемые переменные

Опция Mask скрывает значения переменных в логах задач. Маскирование работает только для значений, которые GitLab может надёжно обнаружить — это обычно токены популярных форматов и данные в Base64. Маскирование ограничено длиной значения (до 4 KiB).

Важно: маскирование не делает переменную «секретной» по всей цепочке — оно лишь удаляет отображение значения в логах.

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

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

Где ещё задавать переменные: .gitlab-ci.yml

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

Пример: глобальная переменная и её переопределение в задаче:

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 часто используют для уменьшения дублирования конфигурации и могут восприниматься как переменные программирования (они фиксированы вместе с кодом), в отличие от проектных/групповых переменных, которые больше похожи на конфиг.

Порядок приоритета (кратко)

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

1. Встроенные переменные GitLab (predefined).
2. Переменные, определённые в .gitlab-ci.yml (глобальные, затем job-specific).
3. Переменные уровня instance → group → project (последняя применима конкретнее).
4. Переменные, переданные при ручном запуске пайплайна (Run pipeline) или при trigger; они имеют наивысший приоритет для конкретного запуска.

Вы всегда можете вручную запустить пайплайн и задать переменные через UI: CI/CD → Pipelines → “Run pipeline” — в диалоге укажите ветку и таблицу Variables. Такие переменные действуют только для этого запуска.

Практические советы и лучшие практики

• Разнесите области ответственности: храните общие значения на уровне группы; чувствительные секреты — на уровне проекта или instance с ограничениями доступа.
• Используйте Type: File для длинных приватных ключей или сертификатов — это уменьшает риск того, что секрет будет случайно выведен в лог.
• Включайте Protected для секретов, используемых только в релизных процессах.
• Не полагайтесь только на Mask — контролируйте чтение логов и доступ к UI/админке.
• Для повторяемости и тестирования старайтесь задавать «фолбэк»-переменные в .gitlab-ci.yml или добавлять тестовые значения в CI при запуске в тестовых ветках.

Типовые ошибки и когда подход не сработает

• Если перезаписываете переменную в .gitlab-ci.yml, но одновременно ожидаете, что UI-значение будет применено — убедитесь в корректном порядке приоритета.
• Mask не защитит значение в случае, если скрипт записывает секрет в файл или в удалённую систему — контролируйте побочные эффекты.
• При использовании Type: File убедитесь, что приложение умеет читать значение из файла по пути, переданному переменной.
• Если значение превышает ограничения маски (4 KiB) или не соответствует формату, оно не будет замаскировано.

Примеры: реальные сценарии

1. Секретный ключ как файл (deploy key):

• В UI: Add variable → Key: SSH_PRIVATE_KEY, Type: File, Protected: yes
• В .gitlab-ci.yml:

stages:
  - deploy

deploy:
  stage: deploy
  script:
    - eval "$(ssh-agent -s)"
    - ssh-add "$SSH_PRIVATE_KEY"
    - scp -r ./dist user@server:/var/www/
  only:
    - release

2. Разные базы данных для окружений (environment scope):

• В UI: Add variable → Key: DATABASE_URL, Value: …, Environment scope: production
• В .gitlab-ci.yml для staging укажите другой DATABASE_URL с scope staging.

3. Передача URL при ручном запуске: откройте Run pipeline и задайте CUSTOM_TAG=feature-x, он будет доступен только в этом запуске.

Стратегии и модели мышления (mental models)

• Конфигурация vs секрет: воспринимайте проектные/групповые переменные как конфиг, а защищённые/маскируемые — как секреты.
• Иммутабельность кода: значения в .gitlab-ci.yml привязаны к версии кода — их изменение сопровождается изменением репозитория.
• Принцип наименьших прав: держите доступ к уровням (instance → group → project) минимально необходимым.

Роли и контрольные списки

DevOps (ответственность за CI):

• Настроить переменные для доступов к сервисам (Registry, Terraform, Cloud).
• Пометить секреты Protected и Mask при возможности.
• Документировать, какие переменные используются в пайплайнах.

Разработчик:

• Использовать переменные из .gitlab-ci.yml для локального тестирования.
• Не хардкодить секреты в коде проекта.
• Тестировать поведение с разными environment scope.

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

• Ограничить доступ к Settings → CI/CD.
• Использовать instance-level переменные только для действительно общих конфигураций.
• Контролировать логи аудита изменений переменных.

Матрица совместимости и миграции

• UI (Settings → CI/CD) подходит для большинства случаев; API удобен для автоматизации и массовых изменений.
• При миграции из одного уровня в другой ( project → group) проверяйте, что нет конфликтов ключей и что область применения меняется ожидаемо.

Минимальный SOP для добавления секрета

1. Создайте переменную в UI: Key, Type (File если необходимо), Protected, Mask.
2. Добавьте документацию в README проекта: где и зачем используется переменная.
3. Обновите .gitlab-ci.yml, используя переменную, и протестируйте в staging.
4. При необходимости выполните ручной запуск пайплайна с тестовой переменной.
5. Проверьте лог выполнения и убедитесь, что секрет не виден.

Критерии приёмки

• Переменная существует и доступна в нужной области (project/group/instance).
• Для секретов применены флаги Protected и/или Mask по требованиям безопасности.
• Если использован Type: File — приложение корректно читает файл по пути из переменной.
• Поведение пайплайна идентично на локальных тестовых ветках и в staging.

Decision tree: где определить переменную? (Mermaid)

flowchart TD
  A[Нужна переменная?] --> B{Это секрет?}
  B -->|Да| C{Требуется доступ только в защищённых ветках?}
  C -->|Да| D[Project: Protected + Mask/Type:File]
  C -->|Нет| E[Group или Project: Mask]
  B -->|Нет| F{Делится между проектами?}
  F -->|Да| G[Group]
  F -->|Нет| H[.gitlab-ci.yml или Project]

Фактическая карточка (fact box)

• Маскирование: работает для значений до 4 KiB.
• Имена переменных: только буквы A–Z, цифры 0–9 и подчёркивания.
• Type: File — переменная в окружении содержит путь к временному файлу.

Шаблон чеклиста перед релизом

• Все секреты помечены Protected.
• В логах не отображаются чувствительные значения.
• Переменные окружения для production проверены и задокументированы.
• Ни одна переменная не хранится в коде в открытом виде.

Когда стоит выбрать альтернативы

• Если нужно централизованно управлять секретами между множеством CI-систем (не только GitLab), задумайтесь о внедрении внешнего Secret Manager (Vault, AWS Secrets Manager) и интеграции через CI/CD.
• Для динамических секретов с коротким TTL интеграция со сторонним секретным менеджером безопаснее, чем хранение в UI GitLab.

Резюме

Переменные GitLab CI дают мощный и гибкий механизм конфигурации конвейеров: используйте уровни (instance/group/project/pipeline) для логичного распределения значений, помечайте секреты как Protected и Mask, и применяйте Type: File для длинных ключей. Документируйте переменные и следуйте принципу наименьших привилегий, чтобы сократить риск случайной утечки.

Важное замечание: при использовании self-hosted GitLab будьте внимательны с instance-level переменными — они доступны всем пайплайнам и могут привести к непреднамеренному раскрытию данных, если не ограничить доступ.