1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
---
stage: Enablement
group: Geo
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# GitLab in maintenance mode **(PREMIUM SELF)**
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2149) in GitLab Premium 13.9.
In maintenance mode, most write operations are disabled at the application level.
This means that GitLab is effectively in a read-only mode for all non-administrative
users (administrators are still able to edit application settings). Regular users
are able to log in to GitLab, view the interface and perform other read-only
operations, such as `git clone` or `git pull`.
## Enable maintenance mode
There are three ways to enable maintenance mode as an administrator:
- **Web UI**:
1. Navigate to the **Admin Area > Application settings > General** and toggle
the maintenance mode. You can optionally add a message for the banner as well.
1. Click **Save** for the changes to take effect.
- **API**:
```shell
curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?maintenance_mode=true"
```
- [**Rails console**](../operations/rails_console.md#starting-a-rails-console-session):
```ruby
::Gitlab::CurrentSettings.update_attributes!(maintenance_mode: true)
::Gitlab::CurrentSettings.update_attributes!(maintenance_mode_message: "New message")
```
## Disable maintenance mode
There are three ways to disable maintenance mode:
- **Web UI**:
1. Navigate to the **Admin Area > Application settings > General** and toggle
the maintenance mode. You can optionally add a message for the banner as well.
1. Click **Save** for the changes to take effect.
- **API**:
```shell
curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?maintenance_mode=false"
```
- [**Rails console**](../operations/rails_console.md#starting-a-rails-console-session):
```ruby
::Gitlab::CurrentSettings.update_attributes!(maintenance_mode: false)
```
## Behavior in maintenance mode
When maintenance mode is enabled, a banner is displayed at the top of the page.
The banner can be customized with a specific message.
An error is displayed when a user tries to perform a write operation that isn't allowed.
The API will return a 403 or 503 error for failed write requests.
NOTE:
In some cases, the visual feedback from an action could be misleading, for example
when starring a project, the **Star** button changes to show the **Unstar** action,
however, this is only the frontend update, and it doesn't take into account the
failed status of the POST request. These visual bugs are to be fixed
[in follow-up iterations](https://gitlab.com/gitlab-org/gitlab/-/issues/295197).
### Application settings
In maintenance mode, admins can edit the application settings. This will allow
them to disable maintenance mode after it's been enabled.
### Logging in/out
All users can log in and out of the GitLab instance.
### CI/CD
In maintenance mode:
- No new jobs are started. Already running jobs stay in 'running'
status but their logs are no longer updated.
- If the job has been in 'running' state for longer than the project's time limit,
it will **not** time out.
- Pipelines cannot be started, retried or canceled in maintenance mode.
No new jobs can be created either.
Once maintenance mode is disabled, new jobs are picked up again. The jobs that were
in the running state before enabling maintenance mode, will resume, and their logs
will start getting updated again.
### Git actions
All read-only Git operations will continue to work in maintenance mode, for example
`git clone` and `git pull`, but all write operations will fail, both through the CLI
and Web IDE.
Geo secondaries are read-only instances that allow Git pushes because they are
proxied to the primary instance. However, in maintenance mode, Git pushes to
both primary and secondaries will fail.
### Merge requests, issues, epics
All write actions except those mentioned above will fail. So, in maintenance mode, a user cannot update merge requests, issues, etc.
### Container Registry
In maintenance mode, `docker push` is blocked, but `docker pull` is available.
### Auto Deploys
It is recommended to disable auto deploys during maintenance mode, and enable
them once maintenance mode is disabled.
### Background jobs
Background jobs (cron jobs, Sidekiq) will continue running as is, because maintenance
mode does not disable any background jobs.
[During a planned Geo failover](../geo/disaster_recovery/planned_failover.md#prevent-updates-to-the-primary-node),
it is recommended that you disable all cron jobs except for those related to Geo.
You can monitor queues and disable jobs in **Admin Area > Monitoring > Background Jobs**.
### Geo secondaries
The maintenance mode setting will be propagated to the secondary as they sync up.
It is important that you do not disable replication before enabling maintenance mode.
Replication and verification will continue to work in maintenance mode.
|
