howto/gitlab.md

@@ -1611,6 +1611,9 @@ file, so they need to be manually approved.
 That is done in `tor-puppet.git`, in the `hiera/roles/gitlab.yaml`
 file, the `profile::gitlab::app::major_version` variable.
 
+Do *not* let Puppet upgrade the package: change the pin by hand on
+disk after changing it in Puppet, then run the upgrade in a `tmux`.
+
 After upgrades, you might need to update the GitLab Registry metadata
 database with:
 
@@ -1621,6 +1624,9 @@ database with:
 Otherwise `containers.torproject.org` will return a 502 error status
 code.
 
+If you have trouble during the upgrade, follow the [upstream
+troubleshooting guide](https://docs.gitlab.com/update/package/package_troubleshooting/).
+
 ## SLA
 
 <!-- this describes an acceptable level of service for this service -->