== Upgrade to Bullseye + gitlab 14.x (Recommended) ==

Make sure all the updates to buster is applied and you are on gitlab 13.12.9 (last available version for buster).

Change buster to bullseye for official archive and replace fasttrack related repos with

{{{
deb https://fasttrack.debian.net/debian/ bullseye-fasttrack main contrib
# For dependency packages not in testing only temporarily due to freeze, transitions or delayed by backports-new or NEW.
deb https://fasttrack.debian.net/debian/ bullseye-backports-staging main contrib
}}}

Note 1: backports suite is now bullseye-backports-staging to avoid confusion with official bullseye-backports.

{{{
# apt update
# apt install gitlab-apt-pin-preferences
}}}

Gitlab 14.x requires PostgreSQL 13, upgrade it first:
{{{
# apt install postgresql-contrib
# pg_dropcluster 13 main --stop
# pg_upgradecluster 11 main
# apt purge postgresql-11 postgresql-client-11
}}}

{{{#!wiki important
Upgrade will fail if postgresql database is not upgraded.
}}}

{{{#!wiki important
Remove all unneeded (ruby) packages to prevent errors like `noMethodError: undefined method `preparable=' for #<Arel::Collectors::Composite:0x0000561530ea0538>`

# apt autoremove --purge
}}}

buster-fasttrack versions for some packages are higher than bullseye versions due to initial +fto suffix instead of current ~fto, some ruby native packages needs to be downgraded.

{{{
# apt install gitlab=14.10.5+ds1-1~fto11+1 gitlab-workhorse=14.10.5+ds1-1~fto11+1 \
gitaly=14.10.4+dfsg-1~fto11+1 gitlab-common=14.10.4+dfsg-1~fto11+1 \
ruby-gitaly=14.10.4+dfsg-1~fto11+1 ruby-bootsnap/bullseye-fasttrack \
ruby-rbtrace/bullseye ruby-ffi/bullseye ruby-json/bullseye-fasttrack \
ruby-pg/bullseye ruby-gpgme/bullseye ruby-redcloth/bullseye ruby-re2/bullseye \
ruby-prof/bullseye ruby-yajl/bullseye ruby-unf-ext/bullseye ruby-rinku/bullseye \
ruby-character-set/bullseye nodejs/bullseye ruby-babosa/bullseye yarnpkg/bullseye
}}}

{{{#!wiki important
If you don't upgrade yarnpkg, you'll get `Error: Cannot find module 'babel-runtime/helpers/asyncToGenerator'`
}}}

Note for ruby-team: List of packages that could be potentially removed from the archive (check if there are other reverse dependencies): ruby-font-awesome-rails ruby-gitlab-pg-query ruby-hipchat ruby-jquery-atwho-rails ruby-mimemagic ruby-molinillo ruby-nakayoshi-fork ruby-net-http-persistent ruby-rufus-scheduler

Now hold the gitlab packages and do a dist-upgrade to bullseye
{{{
# apt-mark hold gitlab gitlab-workhorse gitaly gitlab-common ruby-gitaly
# apt dist-upgrade
}}}

Sysvinit script can't start sidekiq anymore. It can be started manually:
{{{
# RAILS_ENV=production DB=postgres GEM_HOME=/var/lib/gitlab/.gem runuser -u gitlab -- sh -c 'cd /usr/share/gitlab && /usr/bin/bundle exec sidekiq -C /etc/gitlab/sidekiq_queues.yml -e $RAILS_ENV'
}}}

Sidekiq is responsible for running background jobs. Make sure they are completed before further upgrading.

Now you can upgrade to gitlab 15.x.

{{{
# apt-mark unhold gitlab gitlab-workhorse gitaly gitlab-common ruby-gitaly
# apt upgrade
}}}

== Buster Fast Track (Upgrade to Bullseye) ==
Gitlab 13.12.9 is available in [[FastTrack|unofficial fasttrack repo]] targeting buster as base distribution. (no open security issues). It is recommended to upgrade to bullseye.

A video demo of the whole installation process with commentary on packaging challenges and troubleshooting steps is available [[https://peertube.debian.social/videos/watch/playlist/05c6b4d1-61b1-4751-bf61-6541307e9e51|on Debian Social Peertube instance]].

{{{#!wiki important
Some packages were needed from personal repo of gitlab maintainer because golang packages could not be uploaded in fasttrack.debian.net because of a [[https://salsa.debian.org/fasttrack-team/support/-/issues/8|bug in dak setup]]. You no longer need this repo and you can safely remove people.debian.org/~praveen/gitaly from your apt sources.
}}}

{{{#!wiki important
Make sure `contrib` section is enabled for `buster` and `buster/updates`
}}}

Modify `/etc/apt/sources.list` to add official `buster-backports` and `contrib` section if missing:
{{{
deb http://deb.debian.org/debian buster main contrib
deb http://security.debian.org/ buster/updates main contrib
deb http://deb.debian.org/debian buster-backports main contrib 
}}}

Import fasttrack archive keyring:
{{{
# apt -t buster-backports install fasttrack-archive-keyring
}}}

And add the following lines for fasttrack repo:
{{{
deb https://fasttrack.debian.net/debian/ buster-fasttrack main contrib
# For dependency packages not in testing only temporarily due to freeze, transitions or delayed by backports-new or NEW.
deb https://fasttrack.debian.net/debian/ buster-backports main contrib
}}}

Optional: To avoid some hours of delay between upload and availability in archive
{{{
deb http://incoming.debian.org/debian-buildd buildd-buster-backports main contrib
}}}

Refresh list of available packages:
{{{
# apt update
}}}

=== sassc regression ===
{{{#!wiki important
Currently gitlab installation is broken due to libsass in buster-backports . See [[DebianBug:953415]] for more details.

A work around is to downgrade libsass and libsass-dev to versions in buster and hold it at the older version.

# apt install libsass1/buster libsass-dev/buster && apt-mark hold libsass1 libsass-dev
}}}

=== gitlab crash work around (install grpc from rubygems.org) ===

To avoid installation crashing with an error message like,

{{{
/usr/share/rubygems-integration/all/gems/gitaly-13.4.6/ruby/proto/gitaly/lint_pb.rb:17: [BUG] Segmentation fault at 0x0000000000000000
ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-linux-gnu]
}}}

{{{#!wiki important
We have to use versions of grpc from rubygems.org (don't forget to remove this version when ruby-grpc is fixed in debian)

# apt -t buster-fasttrack install ruby2.7

# gem install -v 1.30.2 grpc

and follow [[gitlab/troubleshooting#manually_installing_ruby_dependencies]] if you are seeing this crash again
}}}

=== gitlab-sidekiq service failure work around (install google-protobuf from rubygems.org) ===

{{{
# gem install -v 3.17.1 google-protobuf
}}}

and follow [[gitlab/troubleshooting#manually_installing_ruby_dependencies]] if you are seeing any problems related to services not starting or `error 500` in gitlab.

Note: After gitlab is installed remove ruby-google-protobuf package to avoid conflicts.


=== Use apt pinning for resolving dependencies ===

Since buster-backports and buster-fasttrack have lower apt priorities compared to buster, we have to manually give higher priority to packages we want installed from these suites.

{{{
# apt install gitlab-apt-pin-preferences
# apt install gitlab
}}}

''Note: https://gitlab.debian.net is running on this version.''