8-2 · Глава 8 · 5 мин. чтения

Почему каждой сборке нужен уникальный идентификатор

Узнайте, почему версия приложения — не гарантия уникальности. Как build ID, хеш коммита и метка времени создают надежную идентификацию артефактов в CI/CD.

Почему каждой сборке нужен уникальный идентификатор

Вы только что запустили сборку. В выходной директории появился JAR-файл. Или, может быть, ZIP-архив, или скомпилированный бинарник. Выглядит он так же, как и любая другая сборка на этой неделе. Вы копируете его на сервер, разворачиваете и идете дальше.

Через три дня кто-то сообщает об ошибке в продакшене. Вам нужно выяснить, какой именно артефакт сейчас работает. Вы заходите на сервер, находите файл с именем app-1.0.0.jar и понимаете, что понятия не имеете, сборка это со вторника или с четверга. Обе были помечены как 1.0.0. Обе пришли из одного репозитория. Но что-то пошло не так, и вы не можете проследить проблему до исходного кода.

Вот он — момент, когда отсутствие идентичности артефакта превращается в настоящую операционную головную боль.

Проблема с простым номером версии

Номера версий — это самая базовая форма идентификации. Они дают общее представление о том, с чем вы имеете дело. 1.0.0, 2.3.1, 3.0.0-beta — эти метки помогают людям понимать прогресс и совместимость.

Но на практике одних номеров версий быстро становится недостаточно.

Представьте, что вы собираете версию 1.0.0 сегодня. Завтра вы запускаете ту же сборку из того же исходного кода. Вы получаете еще одну 1.0.0. Теперь у вас есть два разных файла с одинаковой меткой. Какой из них в продакшене? Какой тестировался? Если нужно воспроизвести ошибку, какую 1.0.0 использовать?

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

Что делает идентичность артефакта хорошей

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

Какой код использовался?
Когда это было собрано?
Какой запуск сборки это создал?

Самый распространенный подход объединяет три части информации в один идентификатор.

Build ID (Идентификатор сборки)

Каждый запуск пайплайна получает порядковый номер. В Jenkins он называется номером сборки. В GitLab CI — ID пайплайна. В GitHub Actions — номер запуска. Как бы это ни называлось, это монотонно возрастающее целое число, уникальное в рамках проекта. Сборка 142 всегда отличается от сборки 143.

Но одного build ID недостаточно, чтобы понять, какой код был собран. Нужно больше.

Хеш коммита

Каждый коммит в Git имеет SHA-хеш — длинную шестнадцатеричную строку, которая однозначно идентифицирует точное состояние исходного кода на этот момент. Когда вы объединяете build ID с хешем коммита, вы получаете нечто мощное: «Этот артефакт получен из сборки 142, в которой использовался коммит a3f2c9e».

Если что-то пошло не так, вы можете переключиться на этот точный коммит и увидеть код, который был скомпилирован. Никаких догадок, никаких «кажется, это была та версия, которую мы использовали».

Метка времени (Timestamp)

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

Комбинация build ID, хеша коммита и метки времени дает надежный, читаемый человеком идентификатор. Что-то вроде 142-a3f2c9e-20250321T143022. Это некрасиво, но однозначно.

Вот как можно сконструировать такой идентификатор в CI-пайплайне:

BUILD_ID="${CI_PIPELINE_ID:-142}"
COMMIT_HASH="${CI_COMMIT_SHA:-a3f2c9e}"
TIMESTAMP=$(date +%Y%m%d%H%M%S)
ARTIFACT_NAME="myapp-${BUILD_ID}-${COMMIT_HASH}-${TIMESTAMP}.jar"

echo "Building ${ARTIFACT_NAME}"
# ... шаги сборки ...
cp target/app.jar "dist/${ARTIFACT_NAME}"

Правило неизменяемого артефакта

Как только артефакт получил свой идентификатор, этот идентификатор никогда не должен меняться. Это принцип неизменяемости (immutability).

Неизменяемый артефакт означает:

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

Если нужно пересобрать, вы получаете новый идентификатор. Старый артефакт остается на месте, со своей исходной меткой. Это может показаться расточительным, но это основа отслеживаемости.

Без неизменяемости ваше хранилище артефактов превращается в мешанину перезаписанных файлов и потерянной истории. Вы не можете с уверенностью сказать «это тот артефакт, который тестировался в стейджинге», потому что кто-то мог заменить его новой версией под тем же именем.

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

Где живут артефакты?

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

Если ваши артефакты лежат в папке на CI-сервере или вашем ноутбуке, они исчезнут, когда диск будет очищен, машина заменена или закончится место. Вам нужна централизованная система хранения, доступная всем, кому она нужна: разработчикам, тестировщикам, операционным командам и пайплайнам развертывания.

Это хранилище называется registry (реестр). Это может быть простой файловый сервер, выделенный репозиторий артефактов вроде Nexus или Artifactory или облачное решение вроде реестров контейнеров для Docker-образов. Важно, чтобы это был единый источник истины для всех собранных артефактов.

Когда вы объединяете уникальную неизменяемую идентичность с надежным реестром, вы создаете цепочку ответственности (chain of custody) для каждого созданного вами программного продукта. Вы можете проследить любой работающий экземпляр до его точной сборки, исходного кода и условий, в которых он был создан.

Практический чек-лист

Каждая сборка создает уникальный идентификатор, объединяющий build ID, хеш коммита и метку времени.
Артефакты никогда не перезаписываются и не заменяются с тем же идентификатором.
Хранилище артефактов централизовано и доступно всем командам, которым оно нужно.
Вы можете отследить любой развернутый артефакт до его точного коммита исходного кода.
Ваш процесс развертывания записывает, какой идентификатор артефакта работает в каждой среде.

Резюме

Сборка без уникального идентификатора — это обуза. Вы не сможете эффективно отлаживать проблемы в продакшене, не сможете проверить, что и где работает, и не сможете доверять своему процессу развертывания. Комбинация build ID, хеша коммита и метки времени дает вам простой и надежный способ идентифицировать каждый создаваемый артефакт. Сделайте его неизменяемым, храните в реестре — и вам никогда не придется гадать, какая версия вашего программного обеспечения на самом деле работает.