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

Випуски 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, файли пакетів робочого простору, 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 лише тегом. Після доповнення повторіть пробний запуск — змін бути не повинно.

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

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

Не видаляйте його.
Не надсилайте примусово.
Не переміщуйте на виправлений коміт.
Не використовуйте ту саму семантичну версію для іншого вмісту.

Якщо вміст випуску неправильний, виправте джерело й журнал, а потім опублікуйте наступну версію виправлення. Якщо бракує лише сторінки чи зовнішнього посилання, повторіть ідемпотентне дзеркалювання без зміни тега.

Тег 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, створіть наступну версію виправлення й опублікуйте новий незмінний тег через повну перевірку.

Дзеркало 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 неповне​

Файли супровідника​