Upgrade

Tier: Free, Premium, Ultimate Offering: Self-managed

In most cases, upgrading GitLab is as easy as downloading the newest Docker image tag.

Upgrade GitLab using Docker Engine

To upgrade GitLab that was installed using Docker Engine:

  1. Take a backup. As a minimum, back up the database and the GitLab secrets file.

  2. Stop the running container: 

    sudo docker stop gitlab

  3. Remove the existing container: 

    sudo docker rm gitlab

  4. Pull the new image: 

    sudo docker pull gitlab/gitlab-ee:<version>-ee.0

  5. Ensure that the GITLAB_HOME environment variable is defined: 

    echo $GITLAB_HOME

  6. Create the container once again with the previously specified options: 

    sudo docker run --detach \
--hostname gitlab.example.com \
--publish 443:443 --publish 80:80 --publish 22:22 \
--name gitlab \
--restart always \
--volume $GITLAB_HOME/config:/etc/gitlab \
--volume $GITLAB_HOME/logs:/var/log/gitlab \
--volume $GITLAB_HOME/data:/var/opt/gitlab \
--shm-size 256m \
gitlab/gitlab-ee:<version>-ee.0

On the first run, GitLab will reconfigure and upgrade itself.

Refer to the GitLab Upgrade recommendations when upgrading between versions.

Upgrade GitLab using Docker compose

To upgrade GitLab that was installed using Docker Compose:

  1. Take a backup. As a minimum, back up the database and the GitLab secrets file.
  2. Edit docker-compose.yml and change the version to pull.

  3. Download the newest release and upgrade your GitLab instance: 

    docker compose pull
docker compose up -d

Convert Community Edition to Enterprise Edition

You can convert an existing Docker-based GitLab Community Edition (CE) container to a GitLab Enterprise Edition (EE) container using the same approach as upgrading the version.

We recommend you convert from the same version of CE to EE (for example, CE 14.1 to EE 14.1). This is not explicitly necessary, and any standard upgrade (for example, CE 14.0 to EE 14.1) should work. The following steps assume that you are upgrading the same version.

  1. Take a backup. As a minimum, back up the database and the GitLab secrets file.

  2. Stop the current CE container, and remove or rename it.

  3. To create a new container with GitLab EE, replace ce with ee in your docker run command or docker-compose.yml file. However, reuse the CE container name, port and file mappings, and version.

Downgrade GitLab

caution
You must at least have a database backup created under the exact same version and edition you are downgrading to. Restoring the backup is required to revert the schema changes (migrations) made as part of the upgrade. The restore overwrites all newer GitLab database content with the older state. We can therefore only recommend a downgrade, if for example post-upgrade tests reveal problems that can not be resolved quickly.

To downgrade GitLab shortly after an upgrade:

  1. Follow the upgrade procedure, by specifying an earlier version than you have installed.

  2. Restore the database backup you made before the upgrade.

    • Follow the restore steps for Docker images, including stopping Puma and Sidekiq. Only the database must be restored, so add SKIP=artifacts,repositories,registry,uploads,builds,pages,lfs,packages,terraform_state to the gitlab-backup restore command line arguments.