Автоматизация выпусков

Выпуски Libre WebUI создаются из корня репозитория скриптом выпуска. Он читает фактическую историю Git с предыдущего тега версии, обновляет версии пакетов, записывает журнал изменений, запускает проверки, создаёт коммит выпуска и тег версии. GitHub служит источником сборок и публикации бинарных файлов; метаданные выпуска и именованные ссылки на артефакты зеркалируются в репозиторий Forgejo проекта.

Однократная локальная настройка

Установите зависимости и включите хуки репозитория:

npm install
npm run setup-hooks

Настройка хуков задаёт:

.githooks/commit-msg для проверки Conventional Commits
.githooks/pre-commit для проверки форматирования
.gitmessage как локальный шаблон сообщения коммита

Создание выпуска

Запускайте скрипт в чистом рабочем дереве на ветке, которой будет присвоен тег:

# Patch release
npm run release

# Minor release
npm run release:minor

# Major release
npm run release:major

Скрипт автоматически:

Проверяет чистоту рабочего дерева и доступность следующего локального тега.
Собирает факты из коммитов, файлов, зависимостей, локалей и невыпущенных записей журнала.
Генерирует примечания к выпуску из этих фактов.
Обновляет package.json, файлы пакетов workspace, package-lock.json, версии чарта Helm и приложения, а также CHANGELOG.md.
Запускает npm run release:check, включая форматирование, линтинг, сборки, тесты, аудит безопасности и пробную публикацию npm.
Только после успешных проверок создаёт коммит выпуска и аннотированный тег версии.

Генерация журнала изменений

Просмотрите следующую секцию без изменения файлов:

npm run changelog

Обновите CHANGELOG.md вручную из сгенерированной секции:

npm run changelog -- update

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

Полезные переопределения:

CHANGELOG_AI=0 npm run release:minor
CHANGELOG_AI_MODEL=glm-5.2:cloud npm run changelog
OLLAMA_BASE_URL=http://127.0.0.1:11434 npm run release

Отправка выпуска

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

git -c push.followTags=false push \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  HEAD:refs/heads/main
git ls-remote \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  refs/heads/main

git -c push.followTags=false push \
  https://github.com/libre-webui/libre-webui.git \
  HEAD:refs/heads/main
git ls-remote \
  https://github.com/libre-webui/libre-webui.git \
  refs/heads/main

Оба полученных SHA ветки должны совпадать с локальным коммитом выпуска. Перед публикацией тега дождитесь успешного завершения обязательных процессов GitHub именно для этого коммита.

Убедитесь, что тег версии отсутствует в обеих службах, затем отправьте один тег сначала в Forgejo, потом в GitHub:

git ls-remote \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  'refs/tags/vX.Y.Z' 'refs/tags/vX.Y.Z^{}'
git ls-remote \
  https://github.com/libre-webui/libre-webui.git \
  'refs/tags/vX.Y.Z' 'refs/tags/vX.Y.Z^{}'

git -c push.followTags=false push \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  refs/tags/vX.Y.Z:refs/tags/vX.Y.Z
git -c push.followTags=false push \
  https://github.com/libre-webui/libre-webui.git \
  refs/tags/vX.Y.Z:refs/tags/vX.Y.Z

git ls-remote \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  'refs/tags/vX.Y.Z' 'refs/tags/vX.Y.Z^{}'
git ls-remote \
  https://github.com/libre-webui/libre-webui.git \
  'refs/tags/vX.Y.Z' 'refs/tags/vX.Y.Z^{}'

Замените vX.Y.Z тегом выпуска. Для аннотированного тега проверьте SHA объекта тега и развёрнутого коммита. Никогда не используйте git push --tags: он может опубликовать посторонние локальные теги.

Процесс выпуска CI

Отправка тега v* запускает процесс выпуска GitHub. Он:

Выполняет npm run release:check
Собирает артефакты Electron для macOS, Windows и Linux
Создаёт GitHub Release из соответствующей секции CHANGELOG.md
Зеркалирует запись и ссылки артефактов в Forgejo
Собирает образы Docker
Публикует чарт Helm той же версии, что и тег
Публикует пакет npm с NPM_TOKEN

Ту же проверку можно выполнить локально перед тегированием:

npm run release:check

Зеркало выпусков Forgejo

Зеркало использует персональный токен Forgejo, хранящийся как зашифрованный секрет GitHub Actions FORGEJO_TOKEN. Дайте токену только область write:repository, убедитесь, что владелец может писать в libre-webui/libre-webui, и никогда не коммитьте и не печатайте токен.

Зеркало намеренно идемпотентно. Оно ищет выпуски по тегу, создаёт только отсутствующие записи, согласует метаданные GitHub и пропускает существующие ссылки. Повтор после сетевой ошибки завершает недостающую работу без дубликатов.

Артефакты Forgejo представлены именованными внешними ссылками на публичный GitHub browser_download_url. GitHub остаётся хостом бинарных файлов, а Forgejo показывает те же имена без копирования десятков гигабайт. Исходные архивы независимо генерируются из точного тега каждой службой.

Предпросмотр или дополнение одного выпуска

Проверьте изменения без записи в Forgejo:

node scripts/mirror-forgejo-releases.mjs --tag vX.Y.Z --dry-run

Загрузив FORGEJO_TOKEN и GITHUB_TOKEN из менеджера секретов сопровождающего, зеркалируйте выпуск:

node scripts/mirror-forgejo-releases.mjs --tag vX.Y.Z

Точный тег должен существовать в GitHub и Forgejo и указывать на одинаковый объект тега и развёрнутый коммит.

Предпросмотр или дополнение всех выпусков

Сверьте каждый GitHub Release с Forgejo:

node scripts/mirror-forgejo-releases.mjs --all --dry-run

Дополните отсутствующие или неполные Forgejo Release:

node scripts/mirror-forgejo-releases.mjs --all

GITHUB_TOKEN требуется для --all, включая пробные запуски, поскольку точная сверка тегов и поиск артефактов превышают анонимный лимит API GitHub. FORGEJO_TOKEN также нужен без --dry-run.

Путь --all постранично обходит оба API и рассматривает объекты GitHub Release, а не каждый Git-тег. Тег без намеренно созданного GitHub Release остаётся в Forgejo только тегом. После дополнения повторите пробный запуск — изменений быть не должно.

Политика неизменяемых тегов

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

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

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

Тег Forgejo v0.8.6 был единожды и с явным разрешением выровнен при внедрении двойного зеркала. Это исправило два исторических объекта тегов с одинаковыми деревьями, но разными линиями коммитов. Проверенная миграция не является прецедентом перемещения опубликованных тегов.

Политика версий Helm

version чарта Helm, его appVersion, версия корневого пакета и тег выпуска намеренно используют одну семантическую версию. Скрипт повышает их вместе, CI отклоняет расхождение.

Чарт публикуется только из неизменяемого тега v*. Не публикуйте изменённый чарт под существующей версией. Изменение должно пройти через следующий выпуск приложения.

В версии чарта 0.14.1 есть одноразовое переопределение digest, поскольку выпуск предшествует семантическим Docker-тегам. Digest идентифицирует проверенный многоархитектурный образ 0.14.1. Следующий выпуск очищает переопределение; затем образ по умолчанию соответствует appVersion.

Процесс Docker публикует семантический тег в GHCR и Docker Hub из того же тега v*. Публикация Helm ждёт до 20 минут соответствующий публичный образ Docker Hub и завершается ошибкой вместо публикации чарта без образа. Встроенный образ Ollama настраивается независимо и по умолчанию использует upstream-тег latest.

Conventional Commits

Сообщения коммитов должны соответствовать Conventional Commit:

<type>[optional scope]: <description>

Распространённые типы:

feat: пользовательская функция
fix: исправление ошибки
docs: обновление документации
refactor: внутренняя реструктуризация
perf: улучшение производительности
test: тестовое покрытие
chore: обслуживание, выпуск или сборка

Несовместимые изменения используют !:

git commit -m "feat!: remove deprecated endpoint"
git commit -m "fix(auth)!: change token validation"

Устранение неполадок

Рабочий каталог не чист

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

git status --short
git add .
git commit -m "fix: resolve pending changes"

Нет изменений для выпуска

Проверьте коммиты после предыдущего тега:

git log $(git describe --tags --abbrev=0)..HEAD --oneline

Журнал требует ручной правки

Отредактируйте CHANGELOG.md и зафиксируйте исправление до публикации тега:

git add CHANGELOG.md
git commit -m "docs: refine changelog"

Откат локального коммита выпуска

Если коммит и тег ещё не отправлены:

git tag -d v0.12.0
git reset --soft HEAD~1

Если тег уже есть в любой удалённой службе, не удаляйте и не заменяйте его. Исправьте проблему в main, создайте следующую patch-версию и опубликуйте новый неизменяемый тег через полную проверку.

Зеркало Forgejo неполно

Сначала убедитесь в совпадении SHA объекта тега и развёрнутого коммита в обеих службах. Затем просмотрите и повторите выпуск:

node scripts/mirror-forgejo-releases.mjs --tag vX.Y.Z --dry-run
node scripts/mirror-forgejo-releases.mjs --tag vX.Y.Z

Ошибка авторизации означает, что FORGEJO_TOKEN отсутствует, истёк, принадлежит пользователю без доступа или не имеет write:repository. Отсутствующий или иной удалённый тег исследуется отдельно; зеркало никогда не создаёт и не перемещает Git-теги.

Файлы сопровождающего

.gitmessage - шаблон сообщения коммита
.githooks/commit-msg - проверка Conventional Commits
.githooks/pre-commit - предварительная проверка форматирования
scripts/release.js - оркестрация выпуска
scripts/mirror-forgejo-releases.mjs - идемпотентное зеркало Forgejo и дополнение
scripts/generate-changelog.js - предпросмотр/обновление журнала
scripts/lib/releaseNotes.js - сбор фактов и генерация журнала
.github/workflows/release.yml - процесс выпуска CI по тегу
.github/workflows/helm-publish.yml - проверка Helm и публикация тега

Подробнее о Conventional Commits: https://www.conventionalcommits.org/.

Однократная локальная настройка​

Создание выпуска​

Генерация журнала изменений​

Отправка выпуска​

Процесс выпуска CI​

Зеркало выпусков Forgejo​

Предпросмотр или дополнение одного выпуска​

Предпросмотр или дополнение всех выпусков​

Политика неизменяемых тегов​

Политика версий Helm​

Conventional Commits​

Устранение неполадок​

Рабочий каталог не чист​

Нет изменений для выпуска​

Журнал требует ручной правки​

Откат локального коммита выпуска​

Зеркало Forgejo неполно​

Файлы сопровождающего​