GitLab 유지 관리 모드

요약

유지 관리 모드를 사용하면 관리자가 유지 관리 작업을 수행하는 동안 쓰기 작업을 최소화할 수 있습니다. 유지 관리 모드가 활성화되면 새로운 작업이 들어오지 않고 내부 상태 변경이 최소화되므로 진행 중인 작업이 비교적 빨리 완료됩니다.

유지 관리 모드를 사용하면 관리자가 유지 관리 작업을 수행하는 동안 쓰기 작업을 최소화할 수 있습니다. 주된 목표는 내부 상태를 변경하는 모든 외부 작업을 차단하는 것입니다. 내부 상태에는 PostgreSQL 데이터베이스가 포함되지만 특히 파일, Git 저장소 및 컨테이너 저장소가 포함됩니다.

유지 관리 모드가 활성화되면 새로운 작업이 들어오지 않고 내부 상태 변경이 최소화되므로 진행 중인 작업이 비교적 빨리 완료됩니다. 이 상태에서는 다양한 유지 관리 작업이 더 쉬워집니다. 서비스를 완전히 중지하거나 그렇지 않으면 필요한 것보다 짧은 기간 동안 추가로 저하시킬 수 있습니다. 예를 들어 cron 작업을 중지하고 큐를 비우는 것이 상당히 빠를 수 있습니다.

유지 관리 모드는 내부 상태를 변경하지 않는 대부분의 외부 작업을 허용합니다. 상위 수준에서 HTTP POST, PUT, PATCH 및 DELETE 요청은 차단되며 특수 케이스 처리 방법에 대한 자세한 개요를 확인할 수 있습니다.

유지 관리 모드 활성화#

관리자로서 다음 방법 중 하나로 유지 관리 모드를 활성화합니다:

웹 UI:
1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Maintenance Mode를 확장하고 Enable Maintenance Mode를 토글합니다. 배너에 대한 메시지를 선택적으로 추가할 수도 있습니다.
4. Save changes를 선택합니다.

API:

curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?maintenance_mode=true"

유지 관리 모드 비활성화#

세 가지 방법 중 하나로 유지 관리 모드를 비활성화합니다:

웹 UI:
1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Maintenance Mode를 확장하고 Enable Maintenance Mode를 토글합니다. 배너에 대한 메시지를 선택적으로 추가할 수도 있습니다.
4. Save changes를 선택합니다.

API:

curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?maintenance_mode=false"

유지 관리 모드에서 GitLab 기능 동작#

유지 관리 모드가 활성화되면 페이지 상단에 배너가 표시됩니다. 배너는 특정 메시지로 커스터마이즈할 수 있습니다.

허용되지 않는 쓰기 작업을 수행하려고 하면 오류가 표시됩니다.

유지 관리 모드 배너 및 오류 메시지

Note

경우에 따라 작업의 시각적 피드백이 오해를 일으킬 수 있습니다. 예를 들어 프로젝트에 별점을 줄 때 Star 버튼이 Unstar 작업을 표시하도록 변경됩니다. 그러나 이는 UI만 업데이트하며 POST 요청의 상태를 고려하지 않습니다.

관리자 기능#

시스템 관리자는 애플리케이션 설정을 편집할 수 있습니다. 이를 통해 활성화된 후 유지 관리 모드를 비활성화할 수 있습니다.

인증#

모든 사용자가 GitLab 인스턴스에 로그인하고 로그아웃할 수 있지만 새 사용자는 생성할 수 없습니다.

해당 시간에 LDAP 동기화가 예약되어 있는 경우 사용자 생성이 비활성화되어 있으므로 실패합니다. 마찬가지로 SAML 기반 사용자 생성도 실패합니다.

Git 작업#

git clone 및 git pull과 같은 모든 읽기 전용 Git 작업은 계속 작동합니다. 모든 쓰기 작업은 CLI 및 Web IDE 모두에서 다음 오류 메시지와 함께 실패합니다: Git push is not allowed because this GitLab instance is currently in (read-only) maintenance mode.

Geo가 활성화된 경우 기본 및 보조 모두에 대한 Git 푸시가 실패합니다.

병합 요청, 이슈, 에픽#

앞서 언급된 것을 제외한 모든 쓰기 작업이 실패합니다. 예를 들어 사용자는 병합 요청이나 이슈를 업데이트할 수 없습니다.

수신 이메일#

이메일로 새 이슈 답글, 이슈(새 Service Desk 이슈 포함), 병합 요청 생성이 실패합니다.

발신 이메일#

알림 이메일은 계속 도착하지만 비밀번호 재설정과 같이 데이터베이스 쓰기가 필요한 이메일은 도착하지 않습니다.

REST API#

대부분의 JSON 요청에서 POST, PUT, PATCH 및 DELETE가 차단되고 API는 오류 메시지와 함께 503 응답을 반환합니다: GitLab Maintenance: system is in maintenance mode. 다음 요청만 허용됩니다:

HTTP 요청	허용된 라우트	참고
`POST`	`/admin/application_settings/general`	관리자 UI에서 애플리케이션 설정 업데이트 허용
`PUT`	`/api/v4/application/settings`	API로 애플리케이션 설정 업데이트 허용
`POST`	`/users/sign_in`	사용자 로그인 허용.
`POST`	`/users/sign_out`	사용자 로그아웃 허용.
`POST`	`/oauth/token`	사용자가 처음으로 Geo 보조에 로그인 허용.
`POST`	`/admin/session`, `/admin/session/destroy`	GitLab 관리자를 위한 Admin Mode 허용
`POST`	`/compare`로 끝나는 경로	Git 리비전 라우트.
`POST`	`.git/git-upload-pack`	Git pull/clone 허용.
`POST`	`/api/v4/internal`	내부 API 라우트
`POST`	`/admin/sidekiq`	Admin 영역에서 백그라운드 작업 관리 허용
`POST`	`/admin/geo`	관리자 UI에서 Geo 노드 업데이트 허용
`POST`	`/api/v4/geo_replication`	보조 사이트에서 특정 Geo 특정 관리자 UI 작업 허용

GraphQL API#

히스토리

허용 목록에 GeoRegistriesUpdate 뮤테이션 추가가 GitLab 16.2에서 도입.

POST /api/graphql 요청은 허용되지만 뮤테이션은 오류 메시지 You cannot perform write operations on a read-only instance와 함께 차단됩니다.

허용되는 유일한 뮤테이션은 레지스트리를 재동기화하고 재검증하는 데 사용되는 GeoRegistriesUpdate입니다.

지속적 통합#

새 작업이나 파이프라인이 시작되지 않습니다(예약된 것 포함).
이미 실행 중인 작업은 GitLab Runner에서 실행이 완료된 경우에도 GitLab UI에서 running 상태를 유지합니다.
프로젝트의 시간 제한보다 오래 running 상태인 작업은 타임아웃되지 않습니다.
파이프라인을 시작, 재시도 또는 취소할 수 없습니다. 새 작업도 생성할 수 없습니다.
/admin/runners의 러너 상태가 업데이트되지 않습니다.
gitlab-runner verify는 ERROR: Verifying runner... is removed 오류를 반환합니다.

유지 관리 모드가 비활성화된 후 새 작업이 다시 선택됩니다. 유지 관리 모드를 활성화하기 전에 running 상태였던 작업은 재개되고 로그가 다시 업데이트되기 시작합니다.

Note

유지 관리 모드가 꺼진 후 이전에 running이었던 파이프라인을 재시작해야 합니다.

배포#

파이프라인이 완료되지 않으므로 배포가 진행되지 않습니다.

유지 관리 모드 중에는 자동 배포를 비활성화하고 비활성화되면 다시 활성화해야 합니다.

Terraform 통합#

Terraform 통합은 실행 중인 CI 파이프라인에 의존하므로 차단됩니다.

컨테이너 레지스트리#

docker push는 오류 denied: requested access to the resource is denied와 함께 실패하지만 docker pull은 작동합니다.

패키지 레지스트리#

패키지 레지스트리를 사용하면 패키지를 설치할 수 있지만 게시할 수 없습니다.

백그라운드 작업#

백그라운드 작업(cron 작업, Sidekiq)은 백그라운드 작업이 자동으로 비활성화되지 않으므로 그대로 계속 실행됩니다. 백그라운드 작업이 인스턴스의 내부 상태를 변경할 수 있는 작업을 수행하므로 유지 관리 모드가 활성화된 동안 일부 또는 전체를 비활성화할 수 있습니다.

계획된 Geo 장애 조치 중 Geo와 관련된 것을 제외한 모든 cron 작업을 비활성화해야 합니다.

큐를 모니터링하고 작업을 비활성화하려면:

오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Monitoring > Background jobs를 선택합니다.
Sidekiq 대시보드에서 Cron을 선택하고 Disable All을 선택하여 작업을 개별적으로 또는 한 번에 모두 비활성화합니다.

인시던트 관리#

인시던트 관리 기능이 제한됩니다. 알림 및 인시던트 생성이 완전히 일시 중지됩니다. 따라서 알림 및 인시던트에 대한 알림 및 호출이 비활성화됩니다.

기능 플래그#

개발 기능 플래그는 API를 통해 켜거나 끌 수 없지만 Rails 콘솔을 통해 토글할 수 있습니다.
기능 플래그 서비스는 기능 플래그 확인에 응답하지만 기능 플래그는 토글할 수 없습니다.

Geo 보조#

기본이 유지 관리 모드인 경우 보조도 자동으로 유지 관리 모드로 전환됩니다.

유지 관리 모드를 활성화하기 전에 복제를 비활성화하지 않는 것이 중요합니다.

Admin UI를 통한 레지스트리의 복제, 검증 및 수동 재동기화 및 재검증 작업은 계속 작동하지만 기본으로 프록시된 Git 푸시는 작동하지 않습니다.

보안 기능#

이슈 생성이나 병합 요청 생성 또는 승인에 의존하는 기능은 작동하지 않습니다.

취약점 보고서 페이지에서 취약점 목록을 내보내는 것은 작동하지 않습니다.

발견 사항이나 취약점 오브젝트의 상태를 변경하는 것은 UI에 오류가 표시되지 않더라도 작동하지 않습니다.

SAST와 시크릿 감지는 아티팩트를 생성하기 위해 CI/CD 작업 통과에 의존하므로 시작할 수 없습니다.

사용 사례 예시: 계획된 장애 조치#

계획된 장애 조치 사용 사례에서 기본 데이터베이스의 일부 쓰기는 빠르게 복제되고 수가 많지 않으므로 허용됩니다.

같은 이유로 유지 관리 모드가 활성화될 때 백그라운드 작업을 자동으로 차단하지 않습니다.

결과 데이터베이스 쓰기는 허용됩니다. 여기서 트레이드오프는 더 많은 서비스 저하와 복제 완료 사이에 있습니다.

그러나 계획된 장애 조치 중에 Geo와 관련되지 않은 cron 작업을 수동으로 끄도록 사용자에게 요청합니다. 새 데이터베이스 쓰기 및 비 Geo cron 작업이 없으면 새 백그라운드 작업이 전혀 생성되지 않거나 최소화될 것입니다.

GitLab 유지 관리 모드

Tier: Premium, Ultimate
Offering: GitLab Self-Managed

원문 보기

번역일: 2026-05-22

요약

유지 관리 모드 활성화#

관리자로서 다음 방법 중 하나로 유지 관리 모드를 활성화합니다:

웹 UI:
1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Maintenance Mode를 확장하고 Enable Maintenance Mode를 토글합니다. 배너에 대한 메시지를 선택적으로 추가할 수도 있습니다.
4. Save changes를 선택합니다.

API:

curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?maintenance_mode=true"

유지 관리 모드 비활성화#

세 가지 방법 중 하나로 유지 관리 모드를 비활성화합니다:

웹 UI:
1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Maintenance Mode를 확장하고 Enable Maintenance Mode를 토글합니다. 배너에 대한 메시지를 선택적으로 추가할 수도 있습니다.
4. Save changes를 선택합니다.

API:

curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?maintenance_mode=false"

유지 관리 모드에서 GitLab 기능 동작#

유지 관리 모드가 활성화되면 페이지 상단에 배너가 표시됩니다. 배너는 특정 메시지로 커스터마이즈할 수 있습니다.

허용되지 않는 쓰기 작업을 수행하려고 하면 오류가 표시됩니다.

유지 관리 모드 배너 및 오류 메시지

Note

관리자 기능#

시스템 관리자는 애플리케이션 설정을 편집할 수 있습니다. 이를 통해 활성화된 후 유지 관리 모드를 비활성화할 수 있습니다.

인증#

모든 사용자가 GitLab 인스턴스에 로그인하고 로그아웃할 수 있지만 새 사용자는 생성할 수 없습니다.

해당 시간에 LDAP 동기화가 예약되어 있는 경우 사용자 생성이 비활성화되어 있으므로 실패합니다. 마찬가지로 SAML 기반 사용자 생성도 실패합니다.

Git 작업#

Geo가 활성화된 경우 기본 및 보조 모두에 대한 Git 푸시가 실패합니다.

병합 요청, 이슈, 에픽#

앞서 언급된 것을 제외한 모든 쓰기 작업이 실패합니다. 예를 들어 사용자는 병합 요청이나 이슈를 업데이트할 수 없습니다.

수신 이메일#

이메일로 새 이슈 답글, 이슈(새 Service Desk 이슈 포함), 병합 요청 생성이 실패합니다.

발신 이메일#

알림 이메일은 계속 도착하지만 비밀번호 재설정과 같이 데이터베이스 쓰기가 필요한 이메일은 도착하지 않습니다.

REST API#

HTTP 요청	허용된 라우트	참고
`POST`	`/admin/application_settings/general`	관리자 UI에서 애플리케이션 설정 업데이트 허용
`PUT`	`/api/v4/application/settings`	API로 애플리케이션 설정 업데이트 허용
`POST`	`/users/sign_in`	사용자 로그인 허용.
`POST`	`/users/sign_out`	사용자 로그아웃 허용.
`POST`	`/oauth/token`	사용자가 처음으로 Geo 보조에 로그인 허용.
`POST`	`/admin/session`, `/admin/session/destroy`	GitLab 관리자를 위한 Admin Mode 허용
`POST`	`/compare`로 끝나는 경로	Git 리비전 라우트.
`POST`	`.git/git-upload-pack`	Git pull/clone 허용.
`POST`	`/api/v4/internal`	내부 API 라우트
`POST`	`/admin/sidekiq`	Admin 영역에서 백그라운드 작업 관리 허용
`POST`	`/admin/geo`	관리자 UI에서 Geo 노드 업데이트 허용
`POST`	`/api/v4/geo_replication`	보조 사이트에서 특정 Geo 특정 관리자 UI 작업 허용

GraphQL API#

히스토리

허용 목록에 GeoRegistriesUpdate 뮤테이션 추가가 GitLab 16.2에서 도입.

POST /api/graphql 요청은 허용되지만 뮤테이션은 오류 메시지 You cannot perform write operations on a read-only instance와 함께 차단됩니다.

허용되는 유일한 뮤테이션은 레지스트리를 재동기화하고 재검증하는 데 사용되는 GeoRegistriesUpdate입니다.

지속적 통합#

새 작업이나 파이프라인이 시작되지 않습니다(예약된 것 포함).
이미 실행 중인 작업은 GitLab Runner에서 실행이 완료된 경우에도 GitLab UI에서 running 상태를 유지합니다.
프로젝트의 시간 제한보다 오래 running 상태인 작업은 타임아웃되지 않습니다.
파이프라인을 시작, 재시도 또는 취소할 수 없습니다. 새 작업도 생성할 수 없습니다.
/admin/runners의 러너 상태가 업데이트되지 않습니다.
gitlab-runner verify는 ERROR: Verifying runner... is removed 오류를 반환합니다.

Note

유지 관리 모드가 꺼진 후 이전에 running이었던 파이프라인을 재시작해야 합니다.

배포#

파이프라인이 완료되지 않으므로 배포가 진행되지 않습니다.

유지 관리 모드 중에는 자동 배포를 비활성화하고 비활성화되면 다시 활성화해야 합니다.

Terraform 통합#

Terraform 통합은 실행 중인 CI 파이프라인에 의존하므로 차단됩니다.

컨테이너 레지스트리#

docker push는 오류 denied: requested access to the resource is denied와 함께 실패하지만 docker pull은 작동합니다.

패키지 레지스트리#

패키지 레지스트리를 사용하면 패키지를 설치할 수 있지만 게시할 수 없습니다.

백그라운드 작업#

계획된 Geo 장애 조치 중 Geo와 관련된 것을 제외한 모든 cron 작업을 비활성화해야 합니다.

큐를 모니터링하고 작업을 비활성화하려면:

오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Monitoring > Background jobs를 선택합니다.
Sidekiq 대시보드에서 Cron을 선택하고 Disable All을 선택하여 작업을 개별적으로 또는 한 번에 모두 비활성화합니다.

인시던트 관리#

기능 플래그#

개발 기능 플래그는 API를 통해 켜거나 끌 수 없지만 Rails 콘솔을 통해 토글할 수 있습니다.
기능 플래그 서비스는 기능 플래그 확인에 응답하지만 기능 플래그는 토글할 수 없습니다.

Geo 보조#

기본이 유지 관리 모드인 경우 보조도 자동으로 유지 관리 모드로 전환됩니다.

유지 관리 모드를 활성화하기 전에 복제를 비활성화하지 않는 것이 중요합니다.

Admin UI를 통한 레지스트리의 복제, 검증 및 수동 재동기화 및 재검증 작업은 계속 작동하지만 기본으로 프록시된 Git 푸시는 작동하지 않습니다.

보안 기능#

이슈 생성이나 병합 요청 생성 또는 승인에 의존하는 기능은 작동하지 않습니다.

취약점 보고서 페이지에서 취약점 목록을 내보내는 것은 작동하지 않습니다.

발견 사항이나 취약점 오브젝트의 상태를 변경하는 것은 UI에 오류가 표시되지 않더라도 작동하지 않습니다.

SAST와 시크릿 감지는 아티팩트를 생성하기 위해 CI/CD 작업 통과에 의존하므로 시작할 수 없습니다.

사용 사례 예시: 계획된 장애 조치#

계획된 장애 조치 사용 사례에서 기본 데이터베이스의 일부 쓰기는 빠르게 복제되고 수가 많지 않으므로 허용됩니다.

같은 이유로 유지 관리 모드가 활성화될 때 백그라운드 작업을 자동으로 차단하지 않습니다.

결과 데이터베이스 쓰기는 허용됩니다. 여기서 트레이드오프는 더 많은 서비스 저하와 복제 완료 사이에 있습니다.