Теги в Git: какой способ выбрать для релиза

Для Git тег — не просто подпись к коммиту: лёгкий тег хранит ссылку на объект, аннотированный добавляет автора, дату и сообщение, а подписанный позволяет проверить цифровую подпись. Если выбрать вариант наугад, в репозитории может не хватить сведений о выпуске или CI не увидит тег, который вы рассчитывали опубликовать вместе с релизом.

Три варианта — три разных задачи

Ниже — команды для Git 2.x; базовый синтаксис тегов в этой версии давно стабилен. Все примеры создают тег v1.4.0 на текущем коммите. В реальном релизе сначала убедитесь, что это именно проверенный коммит выпуска, а не случайное состояние рабочей ветки.

• Лёгкий тег — простая ссылка на коммит. Подходит для локальных отметок и ситуаций, когда к тегу не нужно прикладывать сведения о выпуске.
• Аннотированный тег — отдельный объект Git с автором, датой и сообщением. Обычно это практичный выбор для публичных релизов.
• Подписанный тег — аннотированный тег с цифровой подписью. Он нужен, когда проект или процесс поставки требуют проверки подписи.

Сноска: объект Git — сущность, которую Git хранит в репозитории под хешем. Лёгкий тег — указатель на объект коммита, а аннотированный тег сам становится отдельным объектом, содержащим метаданные.

Сравнение подходов

Разница заметна и при просмотре. Команда git show показывает сообщение и метаданные аннотированного тега; у лёгкого тега отдельного сообщения нет. Подпись не делает релиз автоматически безопасным: проверяющей стороне ещё нужно понимать, какому ключу доверять.

Для общего релиза выбирайте аннотированный тег по умолчанию. Подписывайте его только тогда, когда команда умеет проверять подписи и понимает, кому доверяет.

Как создать и отправить выбранный тег

У всех трёх вариантов команда создания похожа, но результат отличается. Чтобы отметить не текущий коммит, укажите после сообщения нужный хеш коммита; перед публикацией проверьте, что выбрали правильную точку истории.

Лёгкий тег

git tag v1.4.0

Эта команда ставит лёгкий тег на текущий коммит. Она не запрашивает сообщение и не создаёт объект аннотированного тега.

Аннотированный тег

git tag -a v1.4.0 -m "Release 1.4.0"

Флаг -a создаёт аннотированный тег, а -m задаёт его сообщение. Для релиза это сообщение стоит сделать узнаваемым: например, указать версию и назначение выпуска.

Подписанный тег

git tag -s v1.4.0 -m "Release 1.4.0"

Команде нужна настроенная среда для подписи, совместимая с конфигурацией Git. Если подпись не создаётся, не подменяйте её аннотированным тегом молча: сначала уточните требования процесса выпуска и настройки ключа.

Создание тега само по себе не отправляет его в удалённый репозиторий. Опубликовать конкретный тег можно так:

git push origin v1.4.0

А команда ниже отправляет аннотированные теги, которые относятся к отправляемым веткам и отсутствуют на сервере:

git push origin --follow-tags

Это не то же самое, что без разбора отправить все локальные теги: --follow-tags выбирает аннотированные теги, связанные с отправляемыми ссылками. Если процесс выпуска должен отправлять ровно одну версию, явная публикация её имени проще для проверки.

Когда что выбирать

• Вы помечаете локально коммит для себя. Берите лёгкий тег: дополнительные метаданные не дадут пользы, если тег не участвует в релизе и не нужен коллегам.
• Вы выпускаете версию для пользователей. Берите аннотированный тег. Сообщение и автор помогут понять, что именно обозначает точка в истории.
• Проект требует подтверждать источник выпуска. Используйте подписанный тег и договоритесь, какие ключи принимаются и кто проверяет подпись.

Тегирование — не система версионирования само по себе. Если проект использует схему имён вроде v1.4.0, придерживайтесь её последовательно; Git не проверит, соответствует ли номер содержимому выпуска и не занято ли это имя смыслом в вашей команде.

Что ломается чаще всего

Тег создали, но на сервере его нет

Обычный git push не означает, что вы опубликовали все локальные теги. Отправьте нужный тег явно или используйте согласованный с командой вариант публикации. Проверьте результат через git ls-remote --tags origin: в выводе должен быть тег с нужным именем.

Повторно использовали имя

Git позволяет переместить тег принудительно, но для уже опубликованного релиза это опасно: у коллег и CI может остаться прежнее соответствие имени и коммита. Не передвигайте выпущенный тег без согласованной процедуры. Если выпуск ошибочен, выясните, как команда исправляет релизы, и предупредите потребителей.

Подпись есть, доверия нет

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

CI запускается не на том состоянии

Имя тега должно указывать на нужный коммит, а конфигурация CI — реагировать на теги и получать их при checkout. Условия запуска и глубина клонирования зависят от конкретной CI-системы: проверяйте их документацию и тестируйте выпуск на отдельном пробном теге, а не на имени производственного релиза.

Что настроить дальше

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