If you already have a deployed GitLab CE instance with existing projects, but wish to use GitSwarm, it is possible to migrate your GitLab CE data (workflow
Compatible versions
Only the following version combinations of GitLab CE and GitSwarm are supported for migration. This is a hard requirement; the migration process will not work unless your GitLab CE and GitSwarm instances match one of the version combinations below:
| GitLab CE | GitSwarm |
|---|---|
| 8.0.5 | 15.4 |
An existing GitLab CE install
If the GitLab CE instance you're looking to migrate from is not on the above list, you will need to follow these instructions to upgrade as necessary to a supported version (>= 8.0.5).
A new, up-to-date GitSwarm install
If the GitSwarm instance you're looking to migrate to is not on the above list, you will need to follow these instructions to upgrade as necessary to a supported version.
Migrating GitLab CE to an existing GitSwarm (one that has existing users, projects and repositories) will result in this data being overwritten and/or destroyed during the migration. It is highly recommended that you only migrate to a fresh/clean GitSwarm instance to avoid this issue.
If the GitLab CE install from which you are migrating has attachments, you will either need to use the same hostname for your GitSwarm install, or once migration is complete, you will need to change the GitSwarm instance's hostname to match the original GitLab CE instance's hostname.
Recommended Approach
The recommended approach is to upgrade your GitLab CE and GitSwarm instances to the most up-to-date combination (GitLab CE 8.0.5 and GitSwarm 15.4). Upgrading to GitSwarm 15.4 (and GitLab CE 8.0.5) is an absolute requirement for GitSwarm, since migration is not supported in earlier versions. See these instructions for how to upgrade.
It is also recommended that the same hostname be used for both the GitLab CE and GitSwarm instances, since this will ensure that attachments on merge requests and comments will still be downloadable post-migration.
Perform a backup of your source GitLab CE instance
Follow these instructions to perform a backup on the GitLab CE instance from which you are migrating.
After the backup process is complete, it will report the name of the backup file created:
...
done
Dumping uploads ...
done
Dumping builds ...
done
Creating backup archive: 1446498774_gitlab_backup.tar ... done
Uploading backup archive to remote storage ... skipped
...It is important to note the name of the backup file in the above output, as well as the timestamp (numeric) portion of the file. In the above case, the file is called 1446498774_gitlab_backup.tar and the timestamp portion of the file is 1446498774.
Backup files are created under the /var/opt/gitlab/backups/ directory.
Copy the backup archive to the destination GitSwarm instance
The backup process above will result in the creation of a .tar file, which contains a backup of your workflow (users, projects, merge requests) as well as the corresponding Git repositories. You will need to copy the file created above to the GitSwarm instance you are restoring to, and place the file under /var/opt/gitswarm/backups/.
The backup file will be owned by the git user, so you will either need to perform the copy as git, or change the file permissions so the file can be read. For example, with the file above:
chmod a+r /var/opt/gitlab/backups/1446498774_gitlab_backup.tarRestore the backup archive against the destination GitSwarm instance
Before performing the restore, please review the following note, since a workaround regarding attachments may apply to your migration.
Follow these instructions for restoring the backup on your GitSwarm instance, ensuring that you use the correct TIMESTAMP value that you made note of in step 1 of the migration process.
This process will restore the database, upgrade it to the latest GitSwarm schema, and then restore any backed-up repositories to your GitSwarm instance. Once the backup process is complete and your GitSwarm instance has been (re)started, you can then continue with enabling Helix Mirroring for your existing projects, to gain the full benefit of using GitSwarm.
As a final step, if you are using the same FQDN (fully-qualified domain name) for both your GitLab CE and GitSwarm instances, you should ensure that the server SSH keys are the same on both servers. The instructions for doing this can be found here. This is necessary, since users who had previously connected to your GitLab CE instance will already have a server fingerprint stored.
Attachments can only be migrated if the hostname of the GitSwarm instance matches the originating GitLab CE instance.
This is a known issue; the workaround is to ensure that the GitSwarm instance to which you are restoring has the same fully-qualified domain name (FQDN) as the GitLab CE instance from which you took the backup. You will also need to update the external_url entry in /etc/gitswarm/gitswarm.rb before performing the restore.
After performing the restore, running the recommended check results in the following file permissions errors:
Repo base access is drwxrws---? ... no
Try fixing it:
sudo chmod -R ug+rwX,o-rwx /var/opt/gitswarm/git-data/repositories
sudo chmod -R ug-s /var/opt/gitswarm/git-data/repositories
find /var/opt/gitswarm/git-data/repositories -type d -print0 | sudo xargs -0 chmod g+s
For more information see:
doc/install/installation.md in section "GitLab Shell"
Please fix the error above and rerun the checks.
hooks directories in repos are links: ...Tmp directory writable? ... yes
Uploads directory setup correctly? ... no
Try fixing it:
sudo chmod 0750 /var/opt/gitswarm/gitlab-rails/uploads
For more information see:
doc/install/installation.md in section "GitLab"
Please fix the error above and rerun the checks.
Init script exists? ... skipped (omnibus-gitlab has no init script)
Init script up-to-date? ... skipped (omnibus-gitlab has no init script)
projects have namespace: ...These problems can be corrected by running the following commands:
sudo chmod -R ug+rwX,o-rwx /var/opt/gitswarm/git-data/repositories
sudo chmod -R ug-s /var/opt/gitswarm/git-data/repositories
find /var/opt/gitswarm/git-data/repositories -type d -print0 | sudo xargs -0 chmod g+s
sudo chmod 0750 /var/opt/gitswarm/gitlab-rails/uploadsWhen performing a restore, the following database error may be seen:
psql:/var/opt/gitlab/backups/db/database.sql:22: ERROR: must be owner of extension plpgsql
psql:/var/opt/gitlab/backups/db/database.sql:2931: WARNING: no privileges could be revoked for "public" (two occurences)
psql:/var/opt/gitlab/backups/db/database.sql:2933: WARNING: no privileges were granted for "public" (two occurences)Please see this document