Gitea のアップグレードの進め方：バックアップから、バージョンをまたぐ更新の注意点まで

ソフトウェアは、更新を続けてこそ安全に使い続けられます。Gitea も例外ではなく、新しいバージョンが出るたびに、機能の追加や不具合の修正が入ります。とはいえ、更新の作業には不安がつきものです。「更新したら動かなくなった」「元に戻せない」といった話は、運用の現場で珍しくありません。

その不安の大部分は、更新の仕組みを知り、事前の備えをしておくことで小さくできます。この記事では、Gitea の更新で何が起こるのかを説明し、安全に進める手順をまとめます。確認した時点は2026年11月15日で、ドキュメントの最新の安定版は 28.3.0 です。

更新は、一方通行になりうる

更新でいちばん気をつけたいのは、元に戻せない場合があることです。ドキュメントは、マイナーバージョンをまたぐ更新で、データベースの構造が更新される点を説明しています。新しいバージョンを起動すると、その構造が自動で書き換わり、古いバージョンの Gitea では、そのデータベースを使えなくなります。

ドキュメントの表現を整理すると、次のとおりです。

ここで注意したいのは、戻すことについての表現です。マイナーをまたいで戻すことは、バックアップがなければ、対応していません。パッチ単位でも、戻すことは、推奨されていません。つまり、「更新して、うまくいかなければ戻す」という発想は、そのままでは通用しません。バックアップを取ることが、戻すための唯一の保険になります。

さらに、更新の初回の起動時には、データベースの移行が自動で実行されます。その間、アプリケーションが使えなくなることがあります。更新は、利用者が少ない時間帯に行い、事前に周知しておくのが親切です。

更新の前に、バックアップを取る

手順の最初は、バックアップです。ドキュメントは、データベースを更新する前に、バックアップを常に取るべきだと強調しています。具体的には、次のものを対象にします。

• データベース
• Gitea の設定
• APP_DATA_PATH にあるデータのファイル
• S3 や MinIO など、外部のストレージを使っている場合は、その内容

まず Gitea を停止し、そのうえで取ります。データのボリュームや、オブジェクトストレージのスナップショットを取る方法が使える環境なら、それでも代用できます。gitea dump による取り方と、戻し方は、バックアップとリストアに詳しくまとめています。

取ったあとは、ファイルが実際に作られ、中身が空でないかを確かめます。可能なら、試験用の環境で、一度戻せることを確認しておくと、さらに安心です。

更新の前に確認したい三つの点

バックアップの次に、更新による影響を、事前に確認します。ドキュメントが挙げている点は、次の三つです。

変更点を読む

新しいバージョンには、動作が変わる変更が含まれることがあります。Gitea のブログに掲載されている変更履歴（チェンジログ）で、破壊的な変更がないかを確認します。複数のバージョンをまたぐときは、間のバージョンの変更履歴にも、目を通します。

設定の警告を解消する

管理画面の上部には、廃止が予定されている設定についての警告が表示されることがあります。ドキュメントは、この警告を放置すると、次のバージョンで Gitea が起動を拒否する場合があると述べています。更新の前に、警告の内容を確認し、設定を新しい形式に直しておきます。

カスタマイズしたテンプレートを点検する

画面の見た目を変えるために、テンプレートを独自に変更している場合は、新しいバージョンと合わない可能性があります。合わないテンプレートは、50x 系のサーバーエラーや、レイアウトの崩れを引き起こします。必要なら、カスタマイズを外すか、新しいバージョンに合わせて更新します。

見た目を変えるカスタマイズは、更新のたびに維持の手間が発生します。本当に必要なものだけを残す運用にしておくと、更新が楽になります。

Docker で更新する

Docker を使っている場合の更新は、ドキュメントでは、次の三段階で説明されています。

1. docker pull で、新しいリリースを取得します。
2. 動いているインスタンスを止め、データのバックアップを取ります。
3. docker または docker-compose で、新しいコンテナを起動します。

Docker Compose では、設定ファイルの image のタグを新しいバージョンに書き換え、起動し直す形になります。たとえば、次のようにします。

    image: docker.gitea.com/gitea:28.3.0

バージョンを固定したタグを使っていれば、「いつ、どのバージョンに上げたか」が、設定ファイルの履歴に残ります。latest のようなタグを使うと、意図しないときに新しいバージョンに切り替わるおそれがあります。導入のときの考え方は、Docker Compose で Gitea を導入するで説明しています。

通常版と rootless 版のイメージには、互換性がありません。更新のついでに、もう一方に切り替えることは避けます。

データベースに PostgreSQL を使っている場合は、もう一つの注意があります。PostgreSQL のデータは、新しいメジャーバージョンに、自動では引き継がれません。Gitea の更新と、PostgreSQL の更新は、別の作業として、別の日に計画するほうが、問題の切り分けが楽です。

バージョンを飛ばして更新する場合

「いくつか先のバージョンへ、一度に上げてよいのか」という点は、運用でよく気になります。ドキュメントは、たとえば 1.4.x から、1.5 系の最新である 1.5.y へ、直接更新できると述べています。つまり、同じ系統の中なら、途中のバージョンを経由する必要はありません。

ただし、複数のマイナーバージョンをまたぐ場合は、間のバージョンの変更履歴の確認が、より重要になります。破壊的な変更が複数に分かれて入っていることがあるからです。一度に上げられるかどうかは、変更履歴を読み、試験用の環境で確かめたうえで判断します。

試験用の環境で、先に更新してみる

安全に更新する、もっとも確実な方法は、本番の前に、同じ手順を別の環境で試すことです。次の流れが現実的です。

1. 本番のバックアップから、試験用の環境に復元します。
2. 試験用の環境で、新しいバージョンに更新します。
3. 管理画面の警告、リポジトリの表示、push と clone、プルリクエストの操作を確認します。
4. 問題がなければ、同じ手順を本番で行います。

この手順は、バックアップが戻せることの確認も兼ねています。更新のたびに行う必要はなくても、マイナーバージョンが上がるときや、設定を大きく変えたときには、時間をかける価値があります。

更新の頻度と、計画の立て方

更新を、いつ、どのくらいの頻度で行うかは、運用の方針として決めておく必要があります。ドキュメントは、設定の警告を放置すると、次のバージョンで起動を拒否される場合があると述べています。つまり、更新を長く先送りにするほど、準備の項目が増え、更新の難易度が上がります。

そこで、次のような方針が考えられます。

• パッチの更新は、早めに行います。 同じ系統の中の更新は、データベースの構造が変わらないため、比較的、影響が小さいものです。
• マイナーバージョンの更新は、計画して行います。 変更履歴を読み、試験用の環境で確かめ、バックアップを取ったうえで、日程を決めて実施します。
• 定期的に、現状のバージョンを確認します。 月に一度など、確認の習慣を決めておけば、気づかないうちに古いままになることを防げます。

更新の担当者と、判断する人を、あらかじめ決めておくことも大切です。担当者が一人だけだと、その人が不在のときに、更新が止まります。手順を文書にして、複数人が実行できる状態にしておきます。

更新した直後に確認すること

新しいバージョンを起動したあとは、更新が正しく完了したかを、順に確認します。

1. 起動のログを確認します。 データベースの移行が、エラーなく終わっているかを見ます。
2. 管理画面を確認します。 上部に、新たな警告が表示されていないかを見ます。
3. 画面を確認します。 ログインでき、リポジトリの一覧やファイルの表示が、正しく行えるかを確かめます。
4. Git の操作を確認します。 試験用のリポジトリで、clone、push、プルリクエストの作成を行います。
5. 自動化を確認します。 ワークフローが動き、ランナーが接続されているかを見ます。
6. カスタマイズした画面を確認します。 テンプレートを変更している場合は、レイアウトの崩れや、エラーが出ていないかを確認します。

問題が見つかったときは、慌てて設定をいじる前に、ログを確認します。原因が特定できず、元に戻す必要があるときは、更新前に取ったバックアップから復元します。マイナーバージョンをまたいだあとは、古いバージョンのまま起動できない点を、思い出してください。

更新に失敗したときの考え方

どれほど準備しても、予期しない問題は起こります。そのときのために、判断の基準を決めておきます。

最後の対応が取れるのは、更新の前にバックアップを取っているからです。バックアップを取らずに更新を始めることは、戻る道を自分で閉ざすことに等しいといえます。

手順を文書にして、引き継げる形にする

更新の手順は、頭の中ではなく、文書として残しておきます。次の項目を書いておくと、担当者が代わっても、同じ水準で更新できます。

• 使っているバージョンと、導入の方法（バイナリ、Docker など）
• 設定ファイルと、データの置き場所
• バックアップの取り方と、保管場所
• 更新の手順と、確認する項目
• 問題が起きたときの、連絡先と判断の基準

更新のたびに、文書を見直し、実際の手順とずれていないかを確かめます。文書が古いままだと、いざというときに役立ちません。

更新の履歴も残しておくと便利です。いつ、どのバージョンから、どのバージョンへ上げ、どんな問題があったのかを記録しておけば、次の更新の参考になります。

利用者への知らせ方

更新の間は、移行の処理のために、Gitea が使えなくなることがあります。利用者に、次の内容を事前に知らせておくと、混乱を避けられます。

• 更新を行う日時と、使えなくなる見込みの時間
• 更新の間、push や clone を控えてほしいこと
• 更新後に、画面の見た目や、操作が変わる点があれば、その内容
• 問題が起きたときの、連絡先

更新が終わったら、完了を知らせます。短い連絡でも、利用者が安心して作業を再開できます。

更新の作業を、一人で抱え込まない

更新の当日は、作業をする人と、結果を確認する人を分けると、見落としが減ります。作業する人は手順に集中し、確認する人は、画面と Git の操作を、別の目で見ます。担当が一人しかいない場合でも、更新の前後で、確認の項目を書いたリストを使い、一つずつ印を付けていく方法で、同じ効果が得られます。

更新の手順をまとめる

最後に、更新の流れを、チェックリストの形でまとめます。

更新を恐れる必要はありません。仕組みを知り、バックアップを取り、手順を決めておけば、更新は定期的に行える、通常の保守作業になります。むしろ、更新を先送りにするほど、変更履歴で確認する量が増え、設定の警告を放置することにもなって、あとの負担が重くなります。この記事の内容は、2026年11月15日時点のドキュメントに基づいています。実際の更新は、利用しているバージョンの変更履歴を確かめたうえで、試験用の環境で一度試してから行っていただくと安心です。