Что такое Predefined variables в GitLab CI?

Predefined Variables в GitLab CI/CD

В GitLab CI/CD, Predefined Variables (предопределённые переменные) — это набор переменных среды (environment variables), которые GitLab Runner автоматически устанавливает и делает доступными в контексте каждого задания (job) пайплайна. Эти переменные предоставляют критически важную информацию о среде выполнения, самом проекте, текущем пайплайне, коммите и многих других аспектах, что позволяет создавать динамичные, адаптивные и мощные конвейеры автоматизации.

Ключевые категории и назначение Predefined Variables

Предопределённые переменные можно условно разделить на несколько категорий:

• Информация о репозитории и проекте: Данные об исходном коде, с которым работает пайплайн.

    *   `CI_PROJECT_ID`, `CI_PROJECT_NAME`, `CI_PROJECT_PATH`, `CI_PROJECT_URL`
    *   `CI_REPOSITORY_URL`: URL для клонирования репозитория (с учётом токена).
    *   `CI_COMMIT_SHA`, `CI_COMMIT_SHORT_SHA`: Хэш текущего коммита.
    *   `CI_COMMIT_REF_NAME`, `CI_COMMIT_REF_SLUG`: Имя ветки или тега (последний в "slug" формате).
    *   `CI_COMMIT_TAG`, `CI_COMMIT_BRANCH`: Указывают, является ли запуск пайплайна для тега или ветки.

• Информация о пайплайне и задании (Job): Данные о текущем конвейере и конкретной задаче.

    *   `CI_PIPELINE_ID`, `CI_JOB_ID`: Уникальные идентификаторы.
    *   `CI_JOB_NAME`, `CI_JOB_STAGE`: Название задания и стадии, к которой оно принадлежит.
    *   `CI_JOB_TOKEN`: Кратковременный токен для аутентификации при взаимодействии с GitLab API (например, для скачивания артефактов или триггера пайплайнов в других проектах). **Внимание:** Имеет ограниченные права (только для текущего проекта).

• Информация о среде выполнения (Runner): Данные о раннере, на котором выполняется задание.

    *   `CI_RUNNER_ID`, `CI_RUNNER_DESCRIPTION`
    *   `CI_SERVER_HOST`, `CI_SERVER_PORT`: Хост и порт GitLab сервера.

• Информация о пользователе и Merge Request: Данные о событии, инициировавшем пайплайн.

    *   `CI_MERGE_REQUEST_ID`, `CI_MERGE_REQUEST_IID`, `CI_MERGE_REQUEST_TITLE`
    *   `GITLAB_USER_ID`, `GITLAB_USER_LOGIN`, `GITLAB_USER_EMAIL`

Практическое применение и примеры

Предопределённые переменные используются для самых разных целей:

1. Динамическая настройка окружения и артефактов:

   deploy:
     script:
       - echo "Деплой коммита $CI_COMMIT_SHORT_SHA из ветки $CI_COMMIT_BRANCH"
       - ./deploy.sh --env $CI_COMMIT_REF_SLUG
     artifacts:
       name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
       paths:
         - reports/
   

2. Условное выполнение заданий (rules или only/except):

   test:
     script: npm test
     rules:
       - if: $CI_COMMIT_BRANCH == "main"
         when: always
       - if: $CI_PIPELINE_SOURCE == "merge_request_event"
         when: always
       - when: never
   

3. Взаимодействие с GitLab API:

   # Использование CI_JOB_TOKEN для запроса к API
   curl --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://$CI_SERVER_HOST/api/v4/projects/$CI_PROJECT_ID/jobs/$CI_JOB_ID/trace"
   

4. Логирование и отладка:

   debug_info:
     stage: .pre
     script:
       - echo "Проект: $CI_PROJECT_PATH"
       - echo "Пайплайн: $CI_PIPELINE_ID"
       - echo "Раннер: $CI_RUNNER_DESCRIPTION"
       - env | sort | grep CI_  # Вывод всех CI-переменных
   

Важные особенности и лучшие практики

• Документация: Полный и актуальный список всех предопределённых переменных всегда следует смотреть в официальной документации GitLab, так как он расширяется с каждым релизом.
• Переопределение: Большинство predefined переменных нельзя переопределить через настройки проекта или .gitlab-ci.yml. Они устанавливаются системой и предназначены только для чтения.
• Безопасность: Несмотря на то, что некоторые переменные (например, CI_JOB_TOKEN) имеют ограниченную область действия, следует избегать их попадания в логи в открытом виде. Используйте маскирование (masking) для секретных значений, но помните, что predefined переменные по умолчанию нельзя замаскировать.
• Комбинация с пользовательскими переменными: Мощь GitLab CI раскрывается при совместном использовании predefined и custom variables (переменных, заданных в настройках проекта/группы или в .gitlab-ci.yml). Это позволяет создавать универсальные, параметризуемые пайплайны.

Итог: Predefined Variables являются фундаментальным механизмом GitLab CI, обеспечивающим контекст и данные для автоматизации. Их грамотное использование — обязательный навык для DevOps//инженера, работающего с GitLab, так как они лежат в основе построения интеллектуальных, эффективных и безопасных конвейеров доставки и развертывания.