Skip to content

Add support for 503 http code when the GitLab instance is in maintenance mode

What does this MR do?

When GitLab enters maintenance mode, it returns a 503 Service Unavailable HTTP status code along with a Retry-After header. Upon receiving this response, GitLab Runner will begin polling GitLab at the interval specified in the Retry-After header.

Why was this MR needed?

To prevent unnecessarily long waiting times once maintenance on the GitLab instance is completed.

What's the best way to test this MR?

  1. Use GDK with GitLab with the changes made in the branch: 503-in-maintenance-mode (see MR: gitlab!195835)
  2. Put GitLab in maintenance mode
$ gdk rails console
--------------------------------------------------------------------------------
 Ruby:         ruby 3.3.8 (2025-04-09 revision b200bad6cd) [x86_64-linux]
 GitLab:       18.2.0-pre (fcb5f298d3a) EE
 GitLab Shell: 14.42.0
 PostgreSQL:   16.8
------------------------------------------------------------[ booted in 22.71s ]
Loading development environment (Rails 7.1.5.1)
[1] pry(main)> ::Gitlab::CurrentSettings.update!(maintenance_mode: true)
  TRANSACTION (0.2ms)  BEGIN
  ApplicationSetting Update (10.0ms)  UPDATE "application_settings" SET "updated_at" = '2025-06-27 16:30:32.225398', "maintenance_mode" = TRUE WHERE "application_settings"."id" = 1 /*application:console,db_config_database:gitlabhq_development,db_config_name:main,console_hostname:ra-gdk-instance.c.ratchade-6071ea85.internal,console_username:ratchade,line:/lib/gitlab/current_settings.rb:31:in `method_missing'*/
  TRANSACTION (0.4ms)  COMMIT
  ApplicationSetting::Term Load (0.8ms)  SELECT "application_setting_terms".* FROM "application_setting_terms" ORDER BY "application_setting_terms"."id" DESC LIMIT 1 /*application:console,db_config_database:gitlabhq_development,db_config_name:main,console_hostname:ra-gdk-instance.c.ratchade-6071ea85.internal,console_username:ratchade,line:/app/models/application_setting/term.rb:14:in `latest'*/
=> true
[2] pry(main)> exit
  1. Start GitLab Runner and check the Runner log. Runner will go in sleep mode for 30 minutes before polling again for job
Feeding runners to channel                          builds=0 max_builds=10
Feeding runner to channel                           builds=0 max_builds=10 runner=E7fwoAEbT
Checking for jobs...GitLab instance currently unavailable  correlation_id=01JYS3S6GW55FFMWTQZ4WPMF7D runner=E7fwoAEbT status=POST http://localhost:3000/api/v4/jobs/request: 503 Service Unavailable (GitLab Maintenance: system is in maintenance mode)
[...]
Checking for jobs...GitLab instance currently unavailable  correlation_id=01JYS5H42Z7MF9FAREP63ZBGXB runner=E7fwoAEbT status=POST http://localhost:3000/api/v4/jobs/request: 503 Service Unavailable (GitLab Maintenance: system is in maintenance mode)

What are the relevant issue numbers?

#29181 #29353 gitlab#345851 #29218 (closed)

Edited by Romuald Atchadé

Merge request reports

Loading