Артефакты в CI на ревью: что проверять в GitHub Actions

Зелёный pipeline не гарантирует, что из него можно восстановить сборку или доказать причину падения тестов. На ревью артефактов проверяют не только строку upload-artifact, но и состав файлов, границы доступа, срок хранения и связь с конкретным коммитом. Ниже — чек-лист для GitHub Actions с учётом версии actions/upload-artifact@v4 и типичных соседних решений.

Сначала определите, зачем нужен артефакт

Артефакт в CI — это файл или набор файлов, который job сохраняет после выполнения, чтобы другой job или человек мог использовать его позже. У него должна быть одна понятная роль. Сборка для деплоя, отчёт тестов и диагностический архив живут по разным правилам.

Артефакт должен отвечать на вопрос «что именно произошло или что именно мы собираемся развернуть», а не превращаться в свалку файлов из рабочего каталога.

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

Четыре проверки на ревью

1. Состав и границы пути

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

Для GitHub Actions безопаснее начинать с конкретного каталога сборки и включать ошибку, если ожидаемый путь пуст:

- name: Upload release bundle
  uses: actions/upload-artifact@v4
  with:
    name: app-${{ github.sha }}
    path: dist/
    if-no-files-found: error
    retention-days: 14

На ревью проверьте три вещи: каталог dist/ действительно создаётся предыдущим шагом, в нём нет секретов, а имя содержит идентификатор коммита или другой однозначный идентификатор запуска. Если сборка иногда создаёт несколько файлов, это должно быть описано, а не скрыто за маской вроде **/*.

2. Связь с коммитом и повторяемость

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

На ревью задайте конкретный вопрос: «Сможет ли инженер через месяц понять, из какого коммита собран этот файл, если workflow уже завершён?» Если ответ зависит только от отображаемого имени job или номера запуска, связь слишком хрупкая.

Для публикации пакета и для промежуточной передачи между job применяйте разные имена. Иначе повторный запуск может создать несколько похожих архивов, а следующий job скачает не тот, который ожидался.

3. Срок хранения и стоимость

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

На ревью полезно увидеть таблицу политики:

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

4. Доступ и содержимое логов

Проверка должна охватывать не только сам архив, но и путь, которым он скачивается. В GitHub Actions артефакт доступен в контексте workflow и его разрешений, поэтому нужно выяснить, кто может просматривать запуски и скачивать файлы из pull request.

Особенно внимательно смотрите на:

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

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

Как отличить артефакт от кэша

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

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

Что написать в комментарии к pull request

Хорошее замечание проверяемо и предлагает критерий исправления. Вместо «артефакты настроены небезопасно» напишите:

• «Путь охватывает весь workspace. Укажите каталог результата и добавьте ошибку при отсутствии файлов, иначе пустая сборка станет успешной».
• «В имени нет commit SHA. Как связать скачанный пакет с исходным кодом после повторного запуска?»
• «В архив попадает отчёт с тестовыми cookies. Удалите их до загрузки или ограничьте состав отчёта».
• «Одинаковое имя используется для nightly и release. Разделите имена и проверьте, какой артефакт скачивает job деплоя».
• «Срок хранения не объяснён. Для этого отчёта нужна долгосрочная доступность или достаточно срока ревью?»

Если workflow хранит отчёты тестов, отдельно проверьте их интеграцию с интерфейсом CI. В GitHub Actions загрузка обычного архива и публикация специального test report — разные задачи. Архив сам по себе не превращается в аннотации к тестам.

Где подход ломается

Пустой или частичный пакет

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

Артефакт из неправильной матрицы

При сборке для нескольких версий Node.js, операционных систем или архитектур имена должны различаться. Иначе результаты могут смешаться или стать неочевидными для job, который их скачивает. В имени укажите параметры матрицы и проверяйте, что деплой выбирает только совместимый пакет.

Секрет появляется не в исходном файле

Секрет может попасть в sourcemap, дамп, stack trace или сгенерированный конфиг. Проверка только исходного каталога не заменяет проверку итогового архива. Для production-сборок добавьте автоматическую проверку запрещённых имён файлов и ручной просмотр состава на первых запусках.

Удаление артефакта ломает расследование

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

Что делать дальше

Возьмите один workflow и составьте инвентаризацию: имя артефакта, job-источник, путь, содержимое, потребитель, срок хранения и права скачивания. Затем добавьте проверку, которая завершает сборку при пустом обязательном каталоге, и сохраните commit SHA рядом с результатом.

После этого измеряйте не только длительность pipeline, но и размер архивов, долю пустых загрузок и количество повторных скачиваний после неудачного деплоя. Для GitHub Actions сверяйте синтаксис с документацией актуальной версии actions/upload-artifact: параметры и ограничения action могут меняться.