Upgrading a Docker installation
- Tier: Free, Premium, Ultimate
- Offering: GitLab Self-Managed
In most cases, upgrading GitLab is as easy as downloading the newest Docker image tag.
Upgrade GitLab using Docker Engine
To upgrade a GitLab instance that was installed using Docker Engine:
-
Create a backup. As a minimum, back up the database and the GitLab secrets file.
-
Stop the running container:
sudo docker stop gitlab
-
Remove the existing container:
sudo docker rm gitlab
-
Pull the new image:
sudo docker pull gitlab/gitlab-ee:<version>-ee.0
-
Ensure that the
GITLAB_HOME
environment variable is defined:echo $GITLAB_HOME
-
Create the container 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 reconfigures and upgrades itself.
Refer to the GitLab Upgrade recommendations when upgrading to different versions.
Upgrade GitLab using Docker compose
To upgrade a GitLab instance that was installed using Docker Compose:
-
Take a backup. As a minimum, back up the database and the GitLab secrets file.
-
Edit
docker-compose.yml
and change the version to pull. -
Download the newest release and upgrade your GitLab instance:
docker compose pull docker compose up -d
Downgrade GitLab
The restore overwrites all newer GitLab database content with the older state. A downgrade is only recommended where necessary. For example, if post-upgrade tests reveal problems that cannot be resolved quickly.
You must have at least a database backup created with the exact same version and edition you are downgrading to. The backup is required to revert the schema changes (migrations) made during the upgrade.
To downgrade GitLab shortly after an upgrade:
-
Follow the upgrade procedure, by specifying an earlier version than you have installed.
-
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 thegitlab-backup restore
command line arguments.
-
Follow the restore steps for Docker images, including
stopping Puma and Sidekiq. Only the database must be restored, so add