GitSwarm-EE 2017.2-1 Documentation

Updating GitLab with Perforce

Path changes

As of GitSwarm 2017.2-1, the following paths have changed:

Additionally, the main configuration file has changed from /etc/gitswarm/gitswarm.rb to /etc/gitlab/gitlab.rb

Upgrading from releases older than GitSwarm 2017.2-1:

All content that is currently residing in any of the above listed directories, should get copied over to the new locations, automatically.
However, It is highly recommended to backup your system before attempting an upgrade!
Feel free to contact support for any assistance with this upgrade.

Pre-update considerations

If you are using CentOS or RHEL, and have updated the OS distribution on your GitLab server from 6.x to 7.x, you need to update the URL in the Perforce repository configuration. For example, if /etc/yum.repos.d/perforce.repo contains:

baseurl=http://package.perforce.com/yum/rhel/6/x86_64

you must edit that line to read:

baseurl=http://package.perforce.com/yum/rhel/7/x86_64

After such an adjustment, we recommend that you run the following command to remove any old dependencies:

sudo yum clean all

Pre-update checks

As of GitSwarm 2016.3-2, the package installation will check the current setting for user['home'] and ensure that it is not set to a reserved directory (/opt/gitswarm, /opt/perforce or /opt/rh). As of Helix GitSwarm 2017.2, the package installation will also check if user['home'] is set to the reserved directory /opt/gitlab. If it is set to a reserved directory, the installation will fail with an error like the following:

ERROR:
ERROR: "user['home']" set to reserved directory '/opt/gitswarm'.
ERROR: '/opt/gitswarm', '/opt/perforce' and '/opt/rh' are reserved directories
ERROR: for GitSwarm and should not be used for "user['home']".
ERROR:
ERROR: Please edit:
ERROR:
ERROR:     /etc/gitswarm/gitswarm.rb
ERROR:
ERROR: update "user['home']" and ensure that it is not set to a reserved
ERROR: directory (as listed above).
ERROR: If you are upgrading your GitSwarm installation, please migrate
ERROR: your installation to the new setting for "user['home']" before
ERROR: attempting to upgrade your GitSwarm installation.  Detailed instructions
ERROR: on how to migrate your home directory can be found in our online
ERROR: documentation here:
ERROR:
ERROR:    https://www.perforce.com/perforce/doc.current/manuals/gitswarm/update/README.html#changing-gits-home-directory
ERROR:

If you are upgrading your GitSwarm instance, please follow these instructions to migrate git's home directory to a new home directory.

Update dependencies

If you have any repos mirroring their content into Helix Git Fusion, we strongly recommend that you update Helix Git Fusion and the Helix Versioning Engine prior to updating GitSwarm.

Important: Depending on the version of the helix-p4d you may have installed previously, there may be schema/data migrations required (updating the helix-p4d package does not automatically restart the service). Schema/data migrations in the Helix Versioning Engine are typically performed by running p4d -xu. For more information, see the Upgrading p4d section in the Helix Versioning Engine Administrator Guide: Fundamentals.

Important: If you are upgrading from GitSwarm 2015.3 or prior, and you had GitLab CI enabled, you must update to GitSwarm 2015.4 before you update to GitSwarm 2016.3 or later.

Updating GitLab from Perforce

  1. Run Perforce's bootstrap script to install GitLab.

    curl https://package.perforce.com/bootstrap/gitswarm-ee.sh | sudo sh -

    The script should add the Perforce package repository, and install our latest version of GitLab. The update will create a backup of your existing GitLab data before fully installing.

  2. Check the application status.

    Check if GitLab and its environment are configured correctly:

    sudo gitlab-rake gitlab:check

    If you find that GitLab does not seem to be operating correctly after the update, it could be that one or more GitLab services did not restart correctly. Should this happen, run:

    sudo gitlab-ctl restart

Configuration Checks

As of 2016.3-2, GitSwarm will check the configured home directory and will fail its configuration phase if it's set to a reserved directory (/opt/gitswarm, /opt/perforce, /opt/rh). As of 2017.2, Helix GitSwarm will also check if the configured home directory is set to the reserved directory /opt/gitlab. Setting git's home directory to a reserved directory can break git clone/pull/fetch/push operations over SSH.

If you encounter the following error when running sudo gitlab-ctl reconfigure

Recipe: gitswarm::default
* ruby_block[Checking home directory for 'git'] action run

================================================================================
Error executing action `run` on resource 'ruby_block[Checking home directory for 'git']'
================================================================================

RuntimeError
------------
Cannot set home directory for 'git' to '/opt/gitswarm'

you must edit /etc/gitlab/gitlab.rb and modify the following key, changing the path to a non-reserved directory.

user['home'] = ...

Changing git's home directory

If you have an existing installation that uses a reserved directory for user['home'], please update your configuration and use the following procedure to migrate to the new home directory

  1. Stop all GitLab services except postgresql

    sudo gitlab-ctl stop
sudo gitlab-ctl start postgresql

  2. Change `user['home'] and reconfigure GitLab

    sudo gitlab-ctl reconfigure

  3. Rebuild git's authorized keys

    sudo gitlab-rake gitlab:shell:setup

    Important This command will rebuild the authorized_keys file in the 'git' user's new home directory. If this file contains anything, it must be backed up beforehand as it will be deleted and replaced with the authorized keys generated by the rake task.

  4. Restart GitLab

    sudo gitlab-ctl start

New configuration options

  1. Check the application status.

    Check if GitLab and its environment are configured correctly:

    sudo gitlab-rake gitlab:check