GitSwarm to GitLab

Feb 25, 2018 · 668 words · 4 minutes read source control tutorial

So here’s the situation, Perforce released GitSwarm which was a solution for integrating git and Perforce. Unfortunately Perforce now has it’s own git solution called TeamHub, I can’t speak to how good or bad it is as I have not used it, however with this new product they have stopped releasing updates to GitSwarm and removed the documentation on moving to vanilla GitLab so I had to figure out out on my own.

These basic steps assume you are on the latest version of GitSwarm (2016.3-2), and are installing GitLab on a new system be it vm or hardware, you could probably do this on the same system but I haven’t tested that. Also if you install GitSwarm or GitLab from source, commands may vary.

  1. Install GitLab 8.10.13 on your new system, GitSwarm is based on GitLab 8.10.13 and you need to migrate before being able to upgrade to the latest version.
  2. Perform a full backup of the GitSwarm server with the command gitswarm-rake gitswarm:backup:create then copy the backup to your new server with scp or something similar. Depending on the size of your installation, disk IO, network speed, etc. this could take a very long time.
  3. At this point you will need to manipulate the backup’s manifest for it to restore. Extract the manifest with the following command tar -xvf <BACKUP_TAR_FILE> backup_information.yml
  4. Open the newly extracted backup_information.yml in your favorite editor and replace the line “:gitswarm_version: 2016.3-2” with “:gitlab_version: 8.10.13”
  5. Add the updated backup_information.yml to the backup tar with the command tar -uf <BACKUP_TAR_FILE> backup_information.yml, if you want to verify the change then re-extract the backup_information.yml using step 3 and check it’s contents.
  6. Rename the backup tar file changing “gitswarm” to “gitlab” and if the ownership isn’t already git:git, change it to that and move it to the backup directory, by default that’s /var/opt/gitlab/backups.
  7. Time to restore the backup:

    gitlab-ctl stop unicorn
    gitlab-ctl stop sidekiq
    # Verify that unicorn and sidekiq are stopped, could probably stop everything minus postgres but this is the documented procedure by GitLab
    gitlab-ctl status
    gitlab-rake gitlab:backup:restore
    # The warnings described in this article will probably happen, it's fine,
    gitlab-ctl restart
    gitlab-rake gitlab:check SANITIZE=true

    This may take a while to restore everything to GitLab and doesn’t give a ton of feedback.

  8. Assuming you already configured GitLab based off of your old GitSwarm config you should have a running GitLab instance. However even though you should have a running GitLab instance at this point you should probably upgrade it to the latest version as the most recent version as of writing this is 10.5 which has tons of enhancements and bug fixes compared to 8.10.13. If you want to do that, continue working through the steps, otherwise jump to the end.

  9. Now you’ll need to install GitLab 9.5.10 (the latest in the 9.x branch). The reason for this is GitLab upgraded their postgres version and this will take care of that. This will take a long time due to the backup it takes, schema migrations, etc.

  10. And finally upgrade to the latest GitLab version (10.5 as of writing), this will also take a long time based on it taking a backup, the schema migrations, etc.

With this you should have a running GitLab server, a few things that you might still need to do are:

  • Change the DNS entry for your old GitSwarm server to point to your new GitLab server so that users don’t have to change their remotes.
  • Change the public/private keys under /etc/ssh on your GitLab server to match your GitSwarm server in order to prevent clients complaining about Man in the Middle attacks due to identity mismatch.
  • Setup Helix4Git in order to allow mirroring repos in Perforce if you were using that feature (Requires Perforce 2017.1 or greater).
  • Make sure backups are configured on the new server.
  • Explore and enable new features that are available with the new GitLab server not offered by GitSwarm.
  • Upgrade any GitLab CI runners you have to the relative version of GitLab you installed.