Upgrading Heptapod from an old version

Heptapod upgrades being mostly just upstream GitLab upgrades, the upstream upgrade instructions readily apply with only a few provision. In this document we will summarize the most important information and point out the Heptapod specifics.

Minimal instructions

Migrating to a new version is a matter of installing the new version and start the application. In the Docker case, that means restarting with the new image.
Some versions must not be jumped over. We call them landmark versions in this page. Instead,
- upgrade to the nearest version in the upgrade_paths,
- let Heptapod run it until all background and batched migrations are finished
- only then can you proceed further to the next landmark version.
Always select the latest patch version (e.g., 0.23.3 instead of 0.23.0), as they may fix bugs in data migrations.
Heptapod does not support upgrades without downtime yet.

Upgrade paths

From Heptapod 17.0 onwards

Since the initial release of Heptapod 17.0.0, the versioning policy is now that Heptapod x.y is always based on GitLab x.y, with the third numbers usually being distinct.

We will not introduce additional upgrade stops, hence fully refer you to GitLab upgrade paths. If by any chance we really had to introduce a new upgrade stop, we would write it explicitely on this page.

In GitLab terminology, an equivalent statement of the policy is that the major and minor versions of GitLab and Heptapod are always equal, and the patch version usually differs.

Examples:

Heptapod 17.0.0 is based on GitLab 17.0.3
Heptapod 17.0.4 is based on GitLab 17.0.4 (coincidence of patch version)

From as far back as Heptapod 0.19, up to Heptapod 1.5

The version immediately following Heptapod 1.5 is 17.0, and the landmark versions are therefore identical to GitLab's except for the patch number (the third): always use the latest z of Heptapod x.y.z.

This is the translation in terms of Heptapod versions of the landmark versions listed in the GitLab upgrade paths documentation:

Heptapod 0.19.3 (GitLab 13.9.1)
Heptapod 0.23.3 (GitLab 13.12.15)
Heptapod 0.24.2 (GitLab 14.0.12)
Heptapod 0.27.4 (GitLab 14.4.5)
Heptapod 0.31.2 (GitLab 14.9.5)
Heptapod 0.32.2 (GitLab 14.10.5)
Heptapod 0.33.1 (GitLab 15.0.5)
Heptapod 0.35.1‡ (GitLab 15.4.6)
Heptapod 0.36.3‡ (only if starting from Heptapod 0.36.0 or 0.36.1).
Heptapod 0.38.1 (GitLab 15.11.13)
Heptapod 0.41.1 (GitLab 16.3.7 + backport for CVE-2024-0402)
Heptapod 1.1.4 (GitLab 16.7.7)
Heptapod 1.5.z (GitLab 16.11.z and the last one before 17.0)

Versions with Heptapod-specific data migrations are indicated with the ‡ symbol.

If you are starting from one of these landmark versions, you still need to check that the background migrations have successfully run.

Please see the details for each version below.

Before Heptapod 0.19

If you need to upgrade an instance running a version older that 0.19, please contact us.

Landmark versions before Heptapod 0.19:

Heptapod 0.12.4 (GitLab 12.2.12)
Heptapod 0.14.3 (GitLab 12.10.14)
Heptapod 0.15.3 (GitLab 13.1.11)

There is no Heptapod version shipping GitLab 13.0 nor 13.8, making the upgrades to Heptapod 0.15 and 0.19 problematic.

Details per version

Heptapod 0.35.1 and 0.36.2

These patch versions introduce the hg_legacy_git_conversion Project setting and prefill it with the BackfillProjectHgLegacyGitConversion batched background migration. The tracking issue is heptapod#745

This setting is an important step in the road to fully native Mercurial, as it will allow us to finally remove the inner conversion to Git in the majority of cases by recording the necessary exceptions.

In version 0.37, we will assume that the setting has been set for all Projects and set the value of the :hg_without_git feature flag to true. The feature flag will be removed entirely in Heptapod >0.37.

The migration has been introduced in the 0.35 series at a time when it was already out of support, to avoid making 0.36 an unnecessary landmark version, whereas 0.35 already was one because that is the case of GitLab 15.4. Hence these rules:

Ugrades from a version before 0.35.1 have to pause at 0.35.1 and don't need to pause at 0.36.2
Upgrades from versions 0.36.0 and 0.36.1 must pause at 0.36.2 and check background migrations.

Heptapod 0.27 (GitLab 14.4)

Upstream upgrade paths tells us to stop migrating at GitLab 14.3, for which there is no Heptapod version: Heptapod 0.26 is based on GitLab 14.2 while Heptapod 0.27 is based on GitLab 14.4.

According to GitLab 14.3 specific instructions, MigrateMergeRequestDiffCommitUsers could be a issue, yet the version that requires it to be fully done is actually GitLab 14.5, and that is a soft requirement. We have also checked that this migration is indeed identical in GitLab 14.4.5 and GitLab 14.3.3.

The other items in upstream 14.3 specific instructions won't cause any problem with Heptapod.