Из какого коммита образ: записываем revision и source в LABEL

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

Dockerfile поддерживает LABEL с парами ключ–значение. Для распространённых полей удобно использовать имена OCI: org.opencontainers.image.source и org.opencontainers.image.revision. Это даёт инструментам и людям согласованный словарь. Сами значения всё равно сообщает процесс сборки, поэтому их качество зависит от того, как он получает ревизию.

Минимальный образ с метаданными

В этом примере образ не содержит приложения. Он нужен, чтобы проверить запись и чтение полей без запуска процесса внутри контейнера.

FROM scratch
ARG VCS_REF
ARG SOURCE_URL
LABEL org.opencontainers.image.revision="$VCS_REF" \
      org.opencontainers.image.source="$SOURCE_URL"

Сохраните Dockerfile и выполните сборку с непустыми значениями: docker build --build-arg VCS_REF=demo-revision --build-arg SOURCE_URL=https://example.invalid/team/app -t metadata-demo .. Затем прочитайте поле командой docker image inspect metadata-demo --format '{{ index .Config.Labels "org.opencontainers.image.revision" }}'. Ожидается demo-revision.

Адрес example.invalid здесь намеренно служит учебным значением. В рабочей сборке SOURCE_URL должен указывать на настоящий репозиторий, а VCS_REF — на проверенную ревизию, например полный CI_COMMIT_SHA. Не выдавайте ручную подпись demo-revision за реальный идентификатор коммита.

Метаданные описывают, но не доказывают

LABEL можно записать произвольным текстом. Наличие правильного на вид SHA не доказывает, что образ действительно собран из этого кода. Для подтверждения происхождения нужны доверенный процесс сборки и при необходимости проверяемые свидетельства и подписи. Метка решает практическую задачу навигации: от полученного образа быстро перейти к исходникам и сборке.

Если локальная рабочая копия содержит незакоммиченные изменения, один git rev-parse HEAD описывает только последний коммит. Файлы в build context могут уже отличаться от него. Поэтому для выпуска лучше собирать из контролируемого checkout и отдельно проверять чистоту входа. Иначе честно выглядящая метка будет вести к неполному описанию исходников.

Не записывайте в LABEL токены, приватные адреса с учётными данными и содержимое секретной конфигурации. Метаданные доступны тем, кто получил образ. Для диагностики обычно достаточно ссылки на репозиторий, ревизии и идентификатора сборки без чувствительных параметров.

Где проверять результат в pipeline

Проверьте метки после сборки до публикации. Пустое значение должно остановить выпуск, если связь с исходниками обязательна. Удобно отдельно сохранить небольшой manifest, где рядом находятся revision и идентификатор собранного образа. Тогда человек сможет сопоставить артефакт CI и registry без чтения всего build-лога.

Не путайте label в конфигурации конкретного образа с annotation верхнего уровня многоплатформенного индекса. У них похожие ключи, но разное место хранения. Пример использует Dockerfile LABEL и читает Config.Labels локального образа. Для index annotations нужен отдельный инструмент и соответствующий путь проверки.

При замене метаданных меняется конфигурация образа, поэтому новый image ID сам по себе ожидаем. Не требуйте неизменного ID после добавления LABEL; сравнивайте нужное содержимое и проверяйте, что связь с ревизией стала доступна.

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

Ещё по теме

• ARG работает в FROM, но пуст внутри RUN: область действия аргумента сборки
• COPY --link: как отделить слой приложения от предыдущих шагов сборки