Upgrading

Upgrading Arbinel works like upgrading Forgejo: replace the binary or image and start the instance, and Arbinel runs the migrations automatically. Follow Forgejo’s upgrade guide for the procedure.

Version numbers

Arbinel has its own version numbers. Each Arbinel release is built on exactly one Forgejo release. That Forgejo release is the version the Arbinel release is compatible with and can replace.

The Arbinel number does not encode the Forgejo number. You cannot tell from an Arbinel version alone which Forgejo release it is built on, so look it up as described below.

Arbinel merges Forgejo’s stable branch regularly, typically every week and soon after a Forgejo security release. An Arbinel release published after such a merge is built on the newer Forgejo release.

Find the Forgejo release

The following places show the Forgejo release a build is based on:

Where	What it shows
The release notes	“Arbinel <version>, built on Forgejo v<forgejo version>”, with a link to Forgejo’s release.
Site administration, configuration page, Server configuration	Arbinel version and Forgejo compatibility.
forgejo --version	The Forgejo version, followed by release name <Arbinel version>.
The API’s version endpoint, /api/v1/version	The Forgejo version only, in Forgejo’s format.
The container image label org.opencontainers.image.description	“Arbinel, a soft fork of Forgejo, built on Forgejo <forgejo version>.”

For the Forgejo changes between two Arbinel releases, read Forgejo’s release notes for the Forgejo releases between them. The changelog issue lists the changes in Arbinel.

Upgrade

1. Read the release notes of every Arbinel release you skip, and Forgejo’s release notes for the Forgejo releases they are built on.
2. Back up, flush the queues and replace the binary or image as Forgejo’s upgrade guide describes.
3. Start the instance. Forgejo’s migrations run first, then Arbinel’s own.
4. Check that the configuration page in the site administration shows the new Arbinel version.

You can skip Arbinel releases. Arbinel’s migration chain runs every missing step in order, as Forgejo’s does.

Caution

You cannot downgrade to an older Arbinel release once a newer one has migrated the database. The older release refuses to start and names the schema version it found. Restore the backup you took before the upgrade instead.

Upgrade to a new Forgejo major version

Arbinel keeps one branch per Forgejo major version. When Forgejo publishes a new major version, Arbinel merges it into a new branch, and later Arbinel releases are built on it.

Treat an Arbinel release that moves to a new Forgejo major version as a Forgejo major upgrade:

• Read the known upgrade issues for that version in Forgejo’s upgrade guide. They apply to Arbinel unchanged.
• Take the full backup that Forgejo requires before a major upgrade.
• Check How Arbinel differs from Forgejo. The maintainers update it on every Forgejo major release, and it notes features that Arbinel built first and Forgejo now also ships.

Note

The moving container tags, such as :0 or :0.4, follow Arbinel’s version numbers. A moving tag can take you to a release built on a new Forgejo major version, so check the release notes before you pull.

Switch between Arbinel and Forgejo

An Arbinel instance can also move to a later Forgejo release, and back. Because Arbinel never changes Forgejo’s migration chain, Forgejo’s migrations apply cleanly to an Arbinel database. Switch from Forgejo explains which features stop working and which data stays.