Как пакет доказательств выпуска помогает двум инженерам работать честно

Команде из двух инженеров не нужен комитет по выпускам. Но ей нужна запись, которая быстро отвечает на неприятный вопрос: что именно изменилось в production-выпуске и вызвало такое поведение?

Зелёный CI-пайплайн - не такая запись. Он доказывает, что задания прошли в тех условиях, которые существовали в момент запуска. Обычно он не собирает в одном месте протестированный коммит, результат миграций, изменения зависимостей, развёртывание в production и рабочий путь отката. Когда начинается инцидент, люди ищут эти факты в отдельных вкладках браузера, истории терминала и обрывках переписки. Это медленно, когда клиент ждёт, и опасно, когда кто-то решает сначала откатить изменения, а разобраться позже.

Пакет доказательств выпуска закрывает этот пробел, делая сам выпуск единицей учёта. CI создаёт его из коммита выпуска, прикрепляет к пайплайну и считает неполный пакет неполным выпуском. Это не бюрократия, а небольшой операционный продукт с понятным пользователем: дежурный инженер, в том числе тот, кто развернул изменения шесть недель назад и уже забыл детали.

Пакет должен доказывать выпуск, а не описывать его

Пакет выпуска полезен только тогда, когда его утверждения получены из команд, API или неизменяемых переменных CI. Рукописная заметка «тесты прошли, миграции выглядят нормально» - это обновление статуса, а не доказательство.

Каждому пакету нужен единый идентификатор выпуска. Используйте неизменяемую версию вместе с полным SHA коммита. Если разворачивается container image, добавьте и его digest. Изменяемый тег вроде latest, production или даже v1.8 без digest не показывает, что именно работало после того, как кто-то переназначил тег образа.

Минимальный набор вопросов прост:

• Какой коммит репозитория создал этот выпуск?
• Какие наборы тестов запускались и получил ли CI их результаты?
• Достигла ли база данных ожидаемой версии миграций?
• Какие прямые и транзитивные зависимости изменились?
• Какая среда получила какой артефакт, в какое время и через какое задание развёртывания?
• Может ли инженер выполнить откат и совместима ли с ним база данных?

Заметьте, чего в этом списке нет: текстового пересказа каждого pull request, сырых production-логов, скриншотов дашборда или копии чата с согласованием. Они увеличивают пакет, но не делают его надёжнее. Короткая автоматически созданная сводка изменений может помочь человеку сориентироваться, но повествование нельзя путать с доказательством.

Разница особенно важна во время сбоя. Инженер видит ошибку после развёртывания коммита c7e.... Пакет показывает digest образа, версию миграций, файлы отчётов о тестах и предыдущую production-цель. Инженер может сравнить факты до того, как трогать production. Без пакета он начинает восстанавливать историю выпуска под давлением, и так слабые предположения превращаются в изменения в production.

Один идентификатор выпуска должен проходить через все задания

Создайте идентификатор выпуска один раз в CI-пайплайне и передайте его каждому следующему заданию. Не позволяйте заданиям тестирования, сборки, развёртывания и формирования пакета независимо придумывать метки. Пакет становится ненадёжным, когда развёртывание говорит 2026.07.22.3, образ - main-abc123, а в журнале миграций есть только временная отметка.

В GitLab CI для этого удобно использовать небольшой dotenv-артефакт. GitLab сообщает, что dotenv-отчёт делает значения доступными последующим заданиям пайплайна. Также GitLab предупреждает: пользователи пайплайна могут получить доступ к dotenv-отчётам. Поэтому в них должны быть только идентификаторы и URL, но никогда не учётные данные или токены.

Создайте файл с идентификаторами, которые нужно сохранить:

mkdir -p evidence
RELEASE_VERSION="${CI_COMMIT_TAG:-${CI_COMMIT_SHORT_SHA}-${CI_PIPELINE_IID}}"
IMAGE_REF="registry.example.internal/app@${IMAGE_DIGEST}"
PREVIOUS_RELEASE="${PREVIOUS_RELEASE_VERSION}"

cat > evidence/release.env <<EOF
RELEASE_VERSION=$RELEASE_VERSION
COMMIT_SHA=$CI_COMMIT_SHA
PIPELINE_ID=$CI_PIPELINE_ID
PIPELINE_URL=$CI_PIPELINE_URL
IMAGE_REF=$IMAGE_REF
PREVIOUS_RELEASE=$PREVIOUS_RELEASE
EOF

Формат должен оставаться простым:

RELEASE_VERSION=4f1d9a2-841
COMMIT_SHA=4f1d9a28545170b87e45d34a8d6f4c8e2cbe8c57
PIPELINE_ID=1841
PIPELINE_URL=https://git.example.internal/team/app/-/pipelines/1841
IMAGE_REF=registry.example.internal/app@sha256:8ad4...
PREVIOUS_RELEASE=02bc91e-837

К PREVIOUS_RELEASE команды часто относятся недостаточно внимательно. Это должен быть последний выпуск, подтверждённый в целевой среде, а не предыдущая успешная сборка ветки по умолчанию. Пропущенное production-развёртывание, hotfix-ветка или неудачный deploy могут привести к разным значениям. Пусть задание развёртывания запросит значение в системе развёртывания или небольшом реестре выпусков до любых изменений, а затем сохранит полученную цель как доказательство.

Здесь команды из двух человек часто идут на дорогостоящий компромисс. Они используют SHA коммита как полный идентификатор выпуска и не сохраняют неизменяемую ссылку на артефакт. Это работает, пока сборка воспроизводима, базовый образ не изменился и упаковка конфигурации одинакова в двух сборках одного исходного кода. Идентичность исходного кода и идентичность артефакта, который работает в системе, отвечают на разные вопросы. Нужны обе.

Для доказательства тестов нужны результаты, а не зелёный значок

Доказательства тестирования должны показывать, какие отчёты получил CI и завершилось ли задание успешно, с ошибкой или вообще не запускалось. Зелёный значок - это сводка, которую вычисляет CI. Пакет должен сохранять исходные файлы результатов тестов и короткую сводку, созданную на их основе.

GitLab принимает отчёты JUnit XML и показывает их в представлениях тестов пайплайна и merge request. В документации есть важная деталь, которую легко пропустить: отчёты о тестах не определяют статус задания. Команда тестирования всё равно должна завершаться с ненулевым кодом при ошибках. Так обнаруживается распространённая плохая настройка: обёртка создаёт XML, скрывает ошибку теста и оставляет пайплайн зелёным.

Сделайте запуск тестов и сбор отчётов явными:

unit_tests:
  stage: test
  script:
    - mkdir -p evidence/test-results
    - ./scripts/test-unit --junit evidence/test-results/unit.xml
    - ./scripts/summarize-junit evidence/test-results/unit.xml > evidence/test-summary.json
  artifacts:
    when: always
    access: maintainer
    expire_in: 180 days
    paths:
      - evidence/test-results/
      - evidence/test-summary.json
    reports:
      junit: evidence/test-results/*.xml

Для артефакта отчёта используйте when: always. Если задание тестирования завершилось с ошибкой, неудачный отчёт часто оказывается самым полезным материалом при расследовании выпуска. Однако не позволяйте заданию пакета запускаться после неудачного теста и представлять выпуск как допустимый. При необходимости создавайте пакет для неудачных попыток ради истории диагностики, но помечайте его release_status: blocked и запрещайте развёртывание.

Короткая сводка тестов должна содержать количества и указатели на файлы, а не тысячи имён тестов, вставленных в Markdown:

{
  "suite": "unit",
  "status": "passed",
  "tests": 486,
  "failures": 0,
  "errors": 0,
  "skipped": 7,
  "report": "evidence/test-results/unit.xml",
  "job_url": "https://git.example.internal/team/app/-/jobs/9921"
}

Запускайте каждый класс тестов, который может заблокировать production-выпуск, но называйте его точно. Модульные и интеграционные тесты, миграции на пустой базе, миграции на восстановленной базе, похожей на production, браузерные тесты и smoke-проверки подтверждают разные вещи. Не сворачивайте их в tests: passed. Если браузерные тесты не запускались, потому что preview-среда не стартовала, пакет должен сказать not_run, а не молча скрыть их.

Нужна и политика для тестов в карантине. Такой тест - признанный пробел. Это не пройденный тест, и в пакете нужно указать причину и ответственного за срок устранения. Если за этот срок никто не отвечает, вы не изолировали нестабильный тест. Вы навсегда снизили планку выпуска.

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

Файл миграции в репозитории доказывает только, что кто-то его закоммитил. Успешная команда миграции доказывает, что процесс завершился без ошибки. Ни то ни другое не подтверждает, что целевая база данных достигла ожидаемой версии.

Соберите две записи. До развёртывания сохраните упорядоченный план миграций и текущую версию схемы. После завершения задания миграции запросите целевую базу через команду инструмента миграций для чтения статуса и сохраните полученную версию. Именно post-deploy статус должен попасть в пакет.

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

{
  "environment": "production",
  "database_alias": "primary",
  "tool": "your-migration-tool",
  "before": "202607180915_add_invoice_index",
  "planned": ["202607220840_add_delivery_state"],
  "after": "202607220840_add_delivery_state",
  "status": "applied",
  "job_url": "https://git.example.internal/team/app/-/jobs/9940"
}

Не включайте имена хостов, строки подключения, значения SQL-параметров, содержимое таблиц или учётные данные. Нужно доказать состояние, а не заставлять человека, расследующего инцидент, искать ответ в чувствительном архиве.

Главный инженерный вопрос - совместимость с откатом. Каждой миграции в пакете присваивается одна из трёх меток:

• backward_compatible: старый код приложения может работать с новой схемой.
• requires_expand_contract: сначала разворачивается новый код, затем в одном из следующих выпусков удаляется старая схема.
• irreversible: возврат кода приложения не возвращает базу данных в прежнее состояние.

Команды часто считают down-миграцию доказательством безопасного отката. Это не так. Она может уничтожить данные, записанные после прямой миграции, заблокироваться из-за зависимости другого выпуска от новой схемы или занять больше времени, чем допускает инцидент. Для большинства production-систем безопаснее подход expand-contract: добавить новое поле или таблицу, выпустить код, который читает оба варианта, при необходимости перенести данные, переключить запись и удалить старую форму в следующем выпуске. В пакете нужно указать, на каком этапе находится этот выпуск.

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

Для изменений зависимостей нужны инвентаризация и сравнение

Разница в lock-файле - не отчёт о зависимостях. Это исходный входной материал, в котором часто есть шум из-за порядка, метаданные реестра и косвенные изменения разрешения, которые трудно быстро объяснить. Используйте lock-файл для ревью разработчиками, а для доказательств выпуска - нормализованный список.

SBOM удобен как формат инвентаризации: он фиксирует программные компоненты и связи между ними. В руководстве CycloneDX SBOM описывается как список компонентов и сервисов вместе с отношениями зависимостей. Этой структуры достаточно, чтобы сравнить точный артефакт выпуска с предыдущим production-артефактом, а не делать предположения по pull request.

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

{
  "base_release": "02bc91e-837",
  "target_release": "4f1d9a2-841",
  "added": [
    {"name": "example-parser", "version": "3.4.0", "scope": "runtime"}
  ],
  "changed": [
    {"name": "example-http", "from": "2.8.1", "to": "2.9.0", "scope": "runtime"}
  ],
  "removed": []
}

Разделяйте runtime- и development-зависимости. Плагин линтера может влиять на CI, не меняя поведение production. Библиотека runtime может изменить обработку запросов, даже если код приложения почти не изменился. Это различие помогает при отладке и реагировании на угрозы безопасности.

Не превращайте доказательства зависимостей в формальное сканирование уязвимостей. Сканеры полезны, но их результат означает другое. Инвентаризация показывает, что вошло в состав артефакта. Сканирование показывает, к какому выводу пришёл конкретный сканер в определённый момент и по определённой политике. Сохраняйте эти материалы отдельно. Иначе кто-то увидит 0 findings и ошибочно решит, что в артефакте нет нового или рискованного ПО.

Доказательства развёртывания начинаются до команды deploy

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

Зафиксируйте в задании развёртывания такие поля:

{
  "environment": "production",
  "requested_release": "4f1d9a2-841",
  "requested_image": "registry.example.internal/app@sha256:8ad4...",
  "deployment_id": "deploy-7b93e1",
  "started_at": "2026-07-22T16:18:04Z",
  "completed_at": "2026-07-22T16:21:17Z",
  "result": "succeeded",
  "observed_image": "registry.example.internal/app@sha256:8ad4...",
  "health_check": {"endpoint": "/healthz", "status": 200},
  "job_url": "https://git.example.internal/team/app/-/jobs/9945"
}

Именно post-deploy наблюдение чаще всего выявляет слабую автоматизацию выпуска. Успешный ответ API развёртывания может означать только, что запрос принят, а не то, что новые экземпляры стали здоровыми. Запросите у платформы активную ревизию или digest образа, дождитесь конечного состояния развёртывания и выполните минимальную проверку здоровья через обычный путь трафика. Проверка должна оставаться узкой. Пакет не заменяет отчёт о производительности и не должен содержать данные клиентов, собранные из production.

Артефакты заданий GitLab хорошо подходят для такого процесса: последующие задания пайплайна могут получать артефакты предыдущих этапов, а needs:artifacts ограничивает набор нужных файлов. GitLab также поддерживает ограничения доступа к артефактам, в том числе доступ только для maintainer. Используйте их для пакетов выпуска, поскольку записи о развёртывании и списки зависимостей могут раскрывать операционные детали, которым не место в открытом пайплайне.

Продумайте срок хранения. GitLab отмечает, что срок действия артефакта определяется настроенным expire_in или значением по умолчанию для экземпляра, а последний успешный пайплайн в зависимости от конфигурации может храниться отдельно. Пакет, исчезающий раньше обычного периода поддержки, бесполезен. Пакет, который хранится вечно, может создать проблему с объёмом хранилища и раскрытием информации. Выберите период, связанный со сроком поддержки развёрнутых версий, а исключительные выпуски сохраняйте по обычной политике инцидентов или клиентских записей.

Инструкции по откату должны быть исполнимыми и учитывать условия

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

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

# Rollback for release 4f1d9a2-841

Target: registry.example.internal/app@sha256:17cf...
Deployment action: ./scripts/deploy-production --image registry.example.internal/app@sha256:17cf...
Database condition: compatible. Migration 202607220840_add_delivery_state is expand phase only.
Verification: wait for deployment status `succeeded`, then request /healthz and confirm the observed image digest is sha256:17cf...
Stop condition: do not run schema rollback. Escalate if the target image is unavailable or the health check fails.

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

Не автоматизируйте все решения об откате. Автоматизация может развернуть известный предыдущий артефакт при срабатывании узкого согласованного сигнала, но она не может решить, совместимы ли недавно записанные данные со старым кодом. Для команды из двух инженеров действует простое правило: автоматизируйте сбор доказательств и механику, а решение оставляйте видимым, если совместимость данных или влияние на клиентов неясны.

Популярная рекомендация «всегда откатывать при ошибках» здесь неверна. Некоторые ошибки вызваны внешним провайдером, неудачным feature flag или миграцией, которая сделала возврат небезопасным. Пакет даёт человеку, принимающему решение, достаточно контекста, чтобы выбрать откат, исправление вперёд, отключение флага или локализацию проблемы без догадок.

Собирайте пакет как последнее задание CI

Задание пакета должно получать доказательства от заданий тестирования, миграций, зависимостей и развёртывания, проверять наличие обязательных файлов и формировать один понятный документ вместе с исходными JSON и XML. Не позволяйте каждому заданию дописывать общий Markdown-файл. Параллельные задания создают проблемы с порядком, а неудачная запись может оставить документ, который выглядит полным.

Простая схема GitLab-пайплайна выглядит так:

stages:
  - prepare
  - test
  - build
  - migrate
  - deploy
  - evidence

release_packet:
  stage: evidence
  needs:
    - job: release_identity
      artifacts: true
    - job: unit_tests
      artifacts: true
    - job: dependency_inventory
      artifacts: true
    - job: migrate_production
      artifacts: true
    - job: deploy_production
      artifacts: true
  script:
    - ./scripts/validate-release-evidence evidence/
    - ./scripts/render-release-packet evidence/ > evidence/release-packet.md
    - sha256sum evidence/release-packet.md > evidence/release-packet.sha256
  artifacts:
    access: maintainer
    expire_in: 180 days
    paths:
      - evidence/

Валидатор должен завершаться ошибкой при отсутствии, неоднозначности или несоответствии данных. Он должен отклонять запись о развёртывании, если наблюдаемый образ отличается от запрошенного. Он должен отклонять запись миграции с status: unknown, файл отката без проверенной цели и любой файл доказательств, версия выпуска которого не совпадает с файлом идентификатора. Генератор, заполняющий пробелы значением «N/A», создаёт успокаивающий документ, который скрывает сломанные связи в CI.

При необходимости оставьте одно короткое поле, написанное человеком: заметку о выпуске с предполагаемым влиянием на клиентов, имя feature flag или согласованное исключение. Храните его в системе контроля версий и требуйте ревью исключений. Сами доказательства должны оставаться автоматически созданными.

Для команд, которые используют GitLab CI/CD и Sentry, пакет может ссылаться на ту же строку версии, которая используется для выпуска в системе отслеживания ошибок. Но не копируйте в CI-артефакты дашборд инцидента. Модель выпусков Sentry позволяет связывать развёртывания с выпусками и сопоставлять production-ошибку с записью о развёртывании. Пакет остаётся записью того, что доказал ваш пайплайн, а мониторинг - записью того, что система делала после этого.

Команда из двух инженеров должна делать исключения болезненно заметными

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

Затем изучите пять последних пакетов. Найдите поля, которыми никто не пользовался, команды, завершавшиеся с ошибкой, но не блокировавшие выпуск, и факты, которые постоянно появляются в чате. Исправляйте пайплайн, а не добавляйте длинный чек-лист. Повторяющиеся ручные объяснения показывают, что CI пока не собирает нужные доказательства.

Команде из двух инженеров также нужно простое правило для исключений: если обычное доказательство нельзя получить, выпуск должен объяснять почему, указывать, кто принял пробел, и сообщать, когда команда его устранит. Исключение - не пустое поле, а решение с ответственным.

Такая работа делает небольшую инженерную команду сильнее, а не бюрократичнее. Опыт AppMaster.io в production показал мне, что большой команде не обязательно быть большой, чтобы выдавать высокий результат, если она убирает повторяющуюся неопределённость из процесса доставки. Пакет выпуска делает это узким и практичным способом: следующий инженер получает факты, а не проект по восстановлению истории.