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. 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 0.19

This is the translation in terms of Heptapod versions of 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) (might still change upstream)
Heptapod 0.33.1 (GitLab 15.0.5) (might still change upstream)
Heptapod 0.35.0 (GitLab 15.4.6) (might still change upstream)

Please see the details for each versions 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.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.