GitLab 유지 관리 모드

요약

유지 관리 모드를 사용하면 관리자가 유지 관리 작업을 수행하는 동안 쓰기 operation을 최소로 줄일 수 있습니다. 유지 관리 모드가 활성화되면 새 동작이 들어오지 않고 내부 상태 변경이 최소화되므로 진행 중인 동작이 비교적 빠르게 끝납니다.

유지 관리 모드를 사용하면 관리자가 유지 관리 작업을 수행하는 동안 쓰기 operation을 최소로 줄일 수 있습니다. 주된 목적은 내부 상태를 변경하는 모든 외부 동작을 차단하는 것입니다. 내부 상태에는 PostgreSQL 데이터베이스가 포함되며, 특히 파일, Git 리포지터리, 컨테이너 리포지터리가 해당합니다.

유지 관리 모드가 활성화되면 새 동작이 들어오지 않고 내부 상태 변경이 최소화되므로 진행 중인 동작이 비교적 빠르게 끝납니다. 이 상태에서는 각종 유지 관리 작업이 더 수월합니다. 서비스를 완전히 중지하거나, 그렇지 않은 경우보다 더 짧은 기간만 제한된 상태로 운영할 수 있습니다. 예를 들어 cron job을 중지하고 큐를 비우는 작업이 비교적 빠르게 끝납니다.

유지 관리 모드는 내부 상태를 변경하지 않는 대부분의 외부 동작을 허용합니다. 큰 틀에서 HTTP POST, PUT, PATCH, DELETE 요청이 차단되며, 특수한 경우의 처리 방식은 별도로 정리되어 있습니다.

유지 관리 모드 활성화#

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

Web 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"

유지 관리 모드 비활성화#

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

Web 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 기능 동작#

유지 관리 모드가 활성화되면 페이지 상단에 배너가 표시됩니다. 이 배너는 원하는 메시지로 사용자 정의할 수 있습니다.

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

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

Note

동작에 대한 시각적 피드백이 실제와 다를 수 있습니다. 예를 들어 프로젝트에 별을 지정하면 Star 버튼이 Unstar 동작을 표시하도록 바뀝니다. 그러나 이는 UI만 갱신한 것이며 POST 요청의 상태는 반영하지 않습니다.

관리자 기능#

시스템 관리자는 애플리케이션 설정을 편집할 수 있습니다. 따라서 유지 관리 모드를 활성화한 뒤에도 비활성화할 수 있습니다.

인증#

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

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

Git 동작#

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

Geo가 활성화되어 있으면 기본 사이트와 보조 사이트 모두에 대한 Git 푸시가 실패합니다.

머지 리퀘스트, 이슈, 에픽#

앞서 언급한 동작을 제외한 모든 쓰기 동작이 실패합니다. 예를 들어 사용자는 머지 리퀘스트나 이슈를 업데이트할 수 없습니다.

수신 이메일#

이메일로 새 이슈 답글, 이슈(새 서비스 데스크 이슈 포함), 머지 리퀘스트를 생성하는 작업이 실패합니다.

발신 이메일#

알림 이메일은 계속 전달되지만, 비밀번호 재설정처럼 데이터베이스 쓰기가 필요한 이메일은 전달되지 않습니다.

REST API#

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

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 영역에서 백그라운드 job 관리를 허용
`POST`	`/admin/geo`	관리자 UI에서 Geo 노드 업데이트를 허용
`POST`	`/api/v4/geo_replication`	보조 사이트에서 일부 Geo 전용 관리자 UI 동작을 허용

GraphQL API#

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

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

지속적 통합#

러너가 새 job을 가져올 수 없으므로 새 job이나 파이프라인이 실행되지 않습니다.
UI나 API로 파이프라인을 시작, 재시도, 취소할 수 없습니다. 외부 동작으로도 새 job을 생성할 수 없습니다.
이미 실행 중이던 job은 GitLab Runner에서 실행이 끝나더라도 GitLab UI에서 계속 running 상태로 표시됩니다.
프로젝트의 시간 제한을 초과해 running 상태에 머무는 job도 시간 초과되지 않습니다.
/admin/runners의 러너 상태가 업데이트되지 않습니다.
gitlab-runner verify는 ERROR: Verifying runner... is removed 오류를 반환합니다.

Warning

파이프라인 스케줄러는 Sidekiq cron job이므로 유지 관리 모드에서 자동으로 비활성화되지 않습니다. 유지 관리 중에도 예약된 파이프라인이 내부적으로 생성될 수 있습니다. 유지 관리 모드를 해제하는 즉시 러너가 이 파이프라인을 가져가므로 대기 job이 한꺼번에 몰릴 수 있습니다. 이를 방지하려면 유지 관리 모드를 활성화하기 전에 cron job을 수동으로 비활성화합니다. 자세한 내용은 백그라운드 job을 참고합니다.

유지 관리 모드를 해제하면 새 job을 다시 가져옵니다. 유지 관리 모드를 활성화하기 전에 running 상태였던 job은 실행을 재개하고 로그도 다시 업데이트되기 시작합니다.

Note

유지 관리 모드를 해제한 뒤에는 이전에 running 상태였던 파이프라인을 다시 시작해야 합니다.

배포#

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

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

Terraform 통합#

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

컨테이너 레지스트리#

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

패키지 레지스트리#

패키지 레지스트리에서는 패키지를 설치할 수 있지만 게시할 수는 없습니다.

백그라운드 job#

백그라운드 job(cron job, Sidekiq)은 자동으로 비활성화되지 않으므로 그대로 계속 실행됩니다. 백그라운드 job은 인스턴스의 내부 상태를 바꿀 수 있는 operation을 수행하므로, 유지 관리 모드가 활성화된 동안 일부 또는 전체를 비활성화하는 방안을 고려합니다.

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

큐를 모니터링하고 job을 비활성화하려면 다음 단계를 수행합니다.

오른쪽 위 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Monitoring > Background jobs를 선택합니다.
Sidekiq 대시보드에서 Cron을 선택하고 job을 개별적으로 비활성화하거나 Disable All을 선택해 한 번에 비활성화합니다.

인시던트 관리#

인시던트 관리 기능이 제한됩니다. 경고와 인시던트 생성이 전면 중단됩니다. 따라서 경고와 인시던트에 대한 알림과 호출도 비활성화됩니다.

기능 플래그#

개발용 기능 플래그는 API로 켜거나 끌 수 없지만 Rails 콘솔로는 전환할 수 있습니다.
기능 플래그 서비스는 기능 플래그 확인 요청에 응답하지만 기능 플래그를 전환할 수는 없습니다

Geo 보조 사이트#

기본 사이트가 유지 관리 모드이면 보조 사이트도 자동으로 유지 관리 모드로 전환됩니다.

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

복제, 검증, 그리고 Admin UI로 레지스트리를 재동기화·재검증하는 수동 동작은 계속 동작하지만, 기본 사이트로 프록시되는 Git 푸시는 동작하지 않습니다.

보안 기능#

이슈를 생성하거나 머지 리퀘스트를 생성·승인하는 데 의존하는 기능은 동작하지 않습니다.

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

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

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

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

계획된 장애 조치 사례에서는 기본 데이터베이스에 일부 쓰기가 발생해도 무방합니다. 복제가 빠르게 이루어지고 건수도 많지 않기 때문입니다.

같은 이유로 유지 관리 모드가 활성화되더라도 백그라운드 job을 자동으로 차단하지 않습니다.

그 결과로 발생하는 데이터베이스 쓰기는 허용 가능한 수준입니다. 여기서는 서비스 제한을 더 강화하는 것과 복제를 완료하는 것 사이의 절충이 이루어집니다.

다만 계획된 장애 조치 중에는 Geo와 무관한 cron job을 수동으로 끄도록 안내합니다. 새 데이터베이스 쓰기와 Geo 외 cron job이 없으면 새 백그라운드 job은 아예 생성되지 않거나 극히 적습니다.

GitLab 유지 관리 모드

GitLab v19.5

Tier: Premium, Ultimate
Offering: GitLab Self-Managed

원문 보기

번역일: 2026-09-18

요약

유지 관리 모드 활성화#

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

Web 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"

유지 관리 모드 비활성화#

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

Web 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 기능 동작#

유지 관리 모드가 활성화되면 페이지 상단에 배너가 표시됩니다. 이 배너는 원하는 메시지로 사용자 정의할 수 있습니다.

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

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

Note

관리자 기능#

시스템 관리자는 애플리케이션 설정을 편집할 수 있습니다. 따라서 유지 관리 모드를 활성화한 뒤에도 비활성화할 수 있습니다.

인증#

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

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

Git 동작#

Geo가 활성화되어 있으면 기본 사이트와 보조 사이트 모두에 대한 Git 푸시가 실패합니다.

머지 리퀘스트, 이슈, 에픽#

앞서 언급한 동작을 제외한 모든 쓰기 동작이 실패합니다. 예를 들어 사용자는 머지 리퀘스트나 이슈를 업데이트할 수 없습니다.

수신 이메일#

이메일로 새 이슈 답글, 이슈(새 서비스 데스크 이슈 포함), 머지 리퀘스트를 생성하는 작업이 실패합니다.

발신 이메일#

알림 이메일은 계속 전달되지만, 비밀번호 재설정처럼 데이터베이스 쓰기가 필요한 이메일은 전달되지 않습니다.

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 영역에서 백그라운드 job 관리를 허용
`POST`	`/admin/geo`	관리자 UI에서 Geo 노드 업데이트를 허용
`POST`	`/api/v4/geo_replication`	보조 사이트에서 일부 Geo 전용 관리자 UI 동작을 허용

GraphQL API#

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

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

지속적 통합#

러너가 새 job을 가져올 수 없으므로 새 job이나 파이프라인이 실행되지 않습니다.
UI나 API로 파이프라인을 시작, 재시도, 취소할 수 없습니다. 외부 동작으로도 새 job을 생성할 수 없습니다.
이미 실행 중이던 job은 GitLab Runner에서 실행이 끝나더라도 GitLab UI에서 계속 running 상태로 표시됩니다.
프로젝트의 시간 제한을 초과해 running 상태에 머무는 job도 시간 초과되지 않습니다.
/admin/runners의 러너 상태가 업데이트되지 않습니다.
gitlab-runner verify는 ERROR: Verifying runner... is removed 오류를 반환합니다.

Warning

Note

유지 관리 모드를 해제한 뒤에는 이전에 running 상태였던 파이프라인을 다시 시작해야 합니다.

배포#

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

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

Terraform 통합#

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

컨테이너 레지스트리#

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

패키지 레지스트리#

패키지 레지스트리에서는 패키지를 설치할 수 있지만 게시할 수는 없습니다.

백그라운드 job#

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

큐를 모니터링하고 job을 비활성화하려면 다음 단계를 수행합니다.

오른쪽 위 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Monitoring > Background jobs를 선택합니다.
Sidekiq 대시보드에서 Cron을 선택하고 job을 개별적으로 비활성화하거나 Disable All을 선택해 한 번에 비활성화합니다.

인시던트 관리#

인시던트 관리 기능이 제한됩니다. 경고와 인시던트 생성이 전면 중단됩니다. 따라서 경고와 인시던트에 대한 알림과 호출도 비활성화됩니다.

기능 플래그#

개발용 기능 플래그는 API로 켜거나 끌 수 없지만 Rails 콘솔로는 전환할 수 있습니다.
기능 플래그 서비스는 기능 플래그 확인 요청에 응답하지만 기능 플래그를 전환할 수는 없습니다

Geo 보조 사이트#

기본 사이트가 유지 관리 모드이면 보조 사이트도 자동으로 유지 관리 모드로 전환됩니다.

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

보안 기능#

이슈를 생성하거나 머지 리퀘스트를 생성·승인하는 데 의존하는 기능은 동작하지 않습니다.

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

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

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

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

계획된 장애 조치 사례에서는 기본 데이터베이스에 일부 쓰기가 발생해도 무방합니다. 복제가 빠르게 이루어지고 건수도 많지 않기 때문입니다.

같은 이유로 유지 관리 모드가 활성화되더라도 백그라운드 job을 자동으로 차단하지 않습니다.