howto/upgrades.md

@@ -69,6 +69,18 @@ block certain upgrades. If you want to bypass that, use regular `apt`:
 
     cumin -b 10  '*' 'apt update ; apt upgrade -yy ; TERM=doit dsa-update-apt-status'
 
+### GitLab runner upgrades
+
+Every month or so GitLab publishes a update to the `gitlab-runner` apt
+package. The package is excluded from `unattended-upgrades` to avoid any
+risk of interrupting long-running CI jobs (eg. large shadow sims).
+
+The recommended procedure is to go through each CI machine one at a time,
+pause all the runners on that single machine, ensure no long-running
+shadow sims are being executed, and launch `apt upgrade`. If any regular
+CI jobs are running, systemd will wait up to one hour for them to end,
+then proceed with the package upgrade.
+
 ### Restarting services by hand
 
 After upgrades, there's a Nagios check that might trigger and tell you