Как передать динамический параметр из CI/CD пайплайна в Docker при сборке образа?

Для передачи динамических параметров (например, версии, хэша коммита, переменных окружения) из CI-системы (GitLab CI, GitHub Actions, Jenkins) в процесс сборки Docker используется механизм Build Arguments (--build-arg).

Типичный сценарий в GitLab CI:

build_image:
  stage: build
  script:
    - docker build 
      --build-arg COMMIT_SHA="$CI_COMMIT_SHA" 
      --build-arg APP_VERSION="$CI_COMMIT_TAG" 
      --build-arg BUILD_DATE="$(date -u +'%Y-%m-%dT%H:%M:%SZ')" 
      -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .

Соответствующий Dockerfile:

# Объявляем аргументы сборки (можно задать значения по умолчанию)
ARG COMMIT_SHA="unknown"
ARG APP_VERSION="latest"
ARG BUILD_DATE

# Используем ARG для инициализации переменных окружения в конечном образе
ENV APP_VERSION=${APP_VERSION} 
    COMMIT_SHA=${COMMIT_SHA} 
    BUILD_DATE=${BUILD_DATE}

# Аргументы также можно использовать на этапе сборки, например, в метаданных
LABEL org.opencontainers.image.revision="$COMMIT_SHA" 
      org.opencontainers.image.version="$APP_VERSION" 
      org.opencontainers.image.created="$BUILD_DATE"

# ... остальные инструкции

Важные нюансы:

• ARG существует только на этапе сборки. Чтобы значение было доступно в рантайме, его нужно явно сохранить в ENV или скопировать в итоговый файл.
• Для секретов (пароли, токены) НЕ используйте --build-arg, так как они останутся в истории слоев. Вместо этого используйте docker build --secret (Docker BuildKit) или стратегию, при которой секреты передаются только на этапе запуска контейнера.
• Изменение любого --build-arg инвалидирует кэш Docker для всех последующих инструкций.