Upgrade

DETAILS: 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 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
```

Convert Community Edition to Enterprise Edition

You can convert an existing GitLab Community Edition (CE) container for Docker 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). However, this is not required. Any standard upgrade (for example, CE 14.0 to EE 14.1) should work. The following steps assume that you are converting to the same version.

Take a backup. At minimum, back up the database and the GitLab secrets file.
Stop the current CE container, and remove or rename it.
To create a new container with GitLab EE, replace ce with ee in your docker run command or docker-compose.yml file. Reuse the CE container name, port mappings, file mappings, and version.

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.

WARNING: 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 the gitlab-backup restore command line arguments.