You are here
GitLab
v15.2+ : Omnibus package
As of v15.2, the TurnKey GitLab appliance includes GitLab installed via the Omnibus package. Previous versions of TurnKey GitLab provided a source install. Unfortunately this change will be a bit of a pain for existing user as it will require a manual migration from source to Omnibus. It is anticipated that this short term pain will be well and truly offset by the greater ease of GitLab maintenance/updates moving forward (both end users, as well as TurnKey). This change was initiated following significant feedback from users, some great conversations weighing the pros and cons, plus the ongoing pain of maintaining the source install appliance.
Migrating from previous TurnKey GitLab instances
Unfortunately, there is no simple way to migrate from a source install of GitLab to an Omnibus install of GitLab. It requires a bit of mucking around, including backend DB migration from MySQL DB backend (as used in TurnKey v15.1 and earlier) to PostgreSQL backend (as supplied by Omnibus install in TurnKey v15.2 and later).
However it can be done. The main details are covered in the GitLab docs. Ideally it would be best to migrate your data to an Omnibus install manually first, then manually generate a GitLab backup. The backup that you create, plus your /etc/gitlab directory (or at least your gitlab-secrets.json file), can then be transferred to the new GitLab server. Place the /etc files in the relevant place and restore your backup as per the GitLab docs.
It's worth noting, that if you have a really old version of GitLab, you may need to do some source updates first. There is a thread on the forums, where a user upgraded from GitLab v5.0.2 (TurnKey GitLab v13.0), all the way to current GitLab (v11.x at the time of writing). If you too need to do something like that, then hopefully that thread will be useful. If you need some support, please feel free to start a new thread (need to be logged in - if you don't have a TurnKey forums user account, please register for one).
Due to limitations and changes in the backup process, it is advisable to update to at least GitLab v9.3.0 before you create the backup and migrate your data across to your new server (although it should be possible to migrate to Omnibus on your old server prior to that). Also please note that backups only work when going to/from exactly the same version of GitLab. I.e. the same install method (source or Omnibus), version number and release channel (Enterprise Edition aka "ee"; or Community Edition aka "ce"). Once you have migrated to Omnibus and are on v9.3 or great, then you can migrate data and downgrade the GitLab version if need be. Downgrading the GitLab version on TurnKey is noted below in the Manual Restore Omnibus section.
FWIW, the process of migrating from a non-TurnKey GitLab server to a TurnKey GItLab appliance (v15.2+) will essentially be the same as migrating from a TurnKey server =< v15.1.
TurnKey GitLab and TKLBAM
Restoring from earlier versions of TurnKey (<=v15.1)
Unfortunately TKLBAM backups from GitLab appliances prior to v15.2 (i.e. appliances that include GitLab installed from source) can not be automagically restored to TurnKey GitLab v15.2+ using TKLBAM. Previous appliances must first be manually migrated to Omnibus, as discussed in the above section on manually migrating.
Manually restore Omnibus backup
To restore a GitLab backup, you must exactly match the version the version of GitLab that the backup comes from, to the version you are restoring to. Due to concerns about problems that may occur, this is best done manually. TKLBAM does have experimental support to attempt to do this automagically, if you would like to try that, please read the section below on Automagic version matching. If you would like to proceed with manual restore (recommended) then please read on.