リリースの自動化

Libre WebUI のリリースは、リポジトリのルートからリリーススクリプトを実行して作成します。 このスクリプトは前回のバージョンタグ以降の実際の git 履歴を読み取り、パッケージのバージョンを更新し、 changelog を作成し、リリースチェックを実行したうえで、リリースをコミットしてバージョンタグを作成します。 ビルドとバイナリ公開の基点は GitHub です。リリースのメタデータと名前付き成果物リンクは、 プロジェクトの Forgejo リポジトリへミラーリングされます。

初回のみ必要なローカル設定

依存関係をインストールし、リポジトリのフックを有効にします。

npm install
npm run setup-hooks

フックのセットアップでは、次を設定します。

• Conventional Commit の検証を行う .githooks/commit-msg
• フォーマットを確認する .githooks/pre-commit
• ローカルのコミットメッセージテンプレートとなる .gitmessage

リリースを作成する

タグを付けるブランチのクリーンな worktree で、リリーススクリプトを実行します。

# Patch release
npm run release

# Minor release
npm run release:minor

# Major release
npm run release:major

スクリプトは次の処理を自動的に行います。

1. working tree がクリーンで、次のローカルタグを使用できることを確認します。
2. コミット、ファイル、依存関係、ロケール、未リリースの changelog から根拠を収集します。
3. 収集した根拠に基づいてリリースノートを生成します。
4. package.json、workspace のパッケージファイル、package-lock.json、Helm chart と アプリのバージョン、および CHANGELOG.md を更新します。
5. フォーマット、lint、ビルド、テスト、セキュリティ監査、npm 公開の dry-run を含む npm run release:check を実行します。
6. すべてのチェックに合格した後にのみ、リリースをコミットして注釈付きバージョンタグを作成します。

Changelog の生成

ファイルを変更せずに、次の changelog セクションをプレビューします。

npm run changelog

生成したセクションで CHANGELOG.md を手動更新します。

npm run changelog -- update

既定では、changelog の生成時に 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 の必須ワークフローがすべて成功するまで待ってから、タグを公開してください。

どちらのサービスにもバージョンタグがまだ存在しないことを確認し、そのタグ 1 つだけを 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 と、 参照先のコミット SHA の両方を検証します。関係のないローカルタグまで公開する可能性があるため、 git push --tags は絶対に使用しないでください。

CI のリリース経路

v* タグをプッシュすると、GitHub のリリースワークフローが実行されます。このワークフローは次を行います。

• npm run release:check を実行
• macOS、Windows、Linux 向けの Electron 成果物をビルド
• 一致する CHANGELOG.md セクションから GitHub Release を作成
• リリースレコードと名前付き成果物リンクを Forgejo へミラーリング
• Docker イメージをビルド
• リリースタグと同じバージョンで Helm chart を公開
• NPM_TOKEN を使って npm パッケージを公開

タグを付ける前に、同じチェックをローカルで実行できます。

npm run release:check

Forgejo へのリリースミラー

ミラーでは、暗号化された GitHub Actions シークレット FORGEJO_TOKEN として保存された Forgejo の personal access token を使用します。トークンには write:repository スコープだけを付与し、 所有者が libre-webui/libre-webui へ書き込めることを確認してください。トークンをコミットしたり、 出力したりしてはいけません。

ミラーは意図的に冪等になるよう設計されています。タグでリリースを検索し、存在しないリリースレコードだけを作成し、 GitHub Release のメタデータと一致させ、すでに存在する成果物リンクはスキップします。そのため、ネットワーク障害や ワークフロー障害の後に再試行すると、リリースや成果物を重複させることなく、未完了の処理だけが完了します。

Forgejo のリリース成果物は、対応する公開 GitHub browser_download_url への名前付き外部リンクです。 バイナリのホストは GitHub のままで、Forgejo には数十 GB のデスクトップ成果物を複製せず、 同じダウンロード可能なファイル名が表示されます。ソースアーカイブは、各サービス上の正確なタグから個別に生成されます。

1 件のリリースをプレビューまたはバックフィルする

Forgejo に書き込まず、変更内容を確認します。

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

メンテナーの secret manager から 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 の匿名 API 制限を超える数のリクエストが必要なため、 dry-run を含め、--all には GITHUB_TOKEN が必要です。--dry-run を使用しない場合は、 さらに FORGEJO_TOKEN も必要です。

--all の処理では両 API をページ送りし、すべての Git タグではなく GitHub Release オブジェクトを対象とします。 意図的に GitHub Release を持たないタグは、Forgejo でもタグだけのままです。バックフィル後にもう一度 dry-run を 実行してください。保留中の変更がないと報告されるはずです。

タグを変更不可能にするポリシー

公開済みのバージョンタグは変更できません。どちらかのリモートにタグが存在した後は、次を守ってください。

• 削除しない。
• force-push しない。
• 修正済みコミットへ移動しない。
• 同じ semantic version を異なる内容に再利用しない。

公開したリリース内容が誤っている場合は、ソースと changelog を修正し、次の patch version を公開してください。 リリースページまたは外部成果物リンクだけが欠けている場合は、タグに触れず、冪等なミラーを再実行します。

Forgejo の v0.8.6 タグでは、二重リリースミラーリングの導入時に、明示的な承認を得た一度限りの再調整が 行われました。同一のソースツリーを記述しながら異なるコミット履歴をたどっていた、2 つの過去のタグオブジェクトを 修復したものです。この監査済みの移行は、公開済みタグを移動する前例にはなりません。

Helm のバージョンポリシー

Helm chart の version と appVersion、ルートパッケージのバージョン、およびリリースタグは、 意図的に同じ semantic version を使用します。リリーススクリプトはこれらを同時に更新し、CI は不一致を拒否します。

chart は、変更不可能な v* リリースタグからのみ公開されます。変更した chart の内容を既存の chart version で 公開しないでください。chart の変更は次のアプリケーションリリースに含め、新しいバージョンを付ける必要があります。

Chart version 0.14.1 には、そのリリースが semantic Docker tags より前に作成されたため、一度限りの digest override が 含まれています。この digest は検証済みの multi-architecture 0.14.1 image を示します。リリーススクリプトは次のリリースを 作成するときにこの override を消去し、それ以降、既定の image は chart の appVersion から解決されます。

Docker ワークフローは同じ v* リリースタグから、semantic-version tag を GHCR と Docker Hub へ公開します。 Helm の公開処理は、一致する公開 Docker Hub image を最大 20 分待ちます。見つからない場合、既定 image のない chart を 公開せず失敗します。同梱の Ollama image は個別に設定でき、既定では upstream の latest tag を使用します。

Conventional Commits

コミットメッセージには Conventional Commit 形式を使用してください。

<type>[optional scope]: <description>

一般的な type：

• feat：ユーザー向け機能
• fix：バグ修正
• docs：ドキュメント更新
• refactor：内部コードの再構成
• perf：パフォーマンス改善
• test：テストカバレッジ
• chore：保守、リリース、ビルド作業

破壊的変更には ! を使用します。

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

トラブルシューティング

Working Directory がクリーンでない

リリース前にローカルの変更をコミットまたは stash します。

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

リリース対象の変更がない

前回のタグ以降のコミットを確認します。

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

Changelog を手動編集する必要がある

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 release を作成して、完全なゲートを通して新しい変更不可能なタグを公開します。

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 Commit の検証
• .githooks/pre-commit - フォーマットの事前チェック
• scripts/release.js - リリースのオーケストレーション
• scripts/mirror-forgejo-releases.mjs - 冪等な Forgejo リリースミラーとバックフィル
• scripts/generate-changelog.js - changelog のプレビュー/更新コマンド
• scripts/lib/releaseNotes.js - 根拠の収集と changelog の生成
• .github/workflows/release.yml - タグ駆動の CI リリースワークフロー
• .github/workflows/helm-publish.yml - Helm の検証とタグ公開

Conventional Commits の詳細は、https://www.conventionalcommits.org/ を参照してください。