Housekeeping

요약

GitLab은 Git 저장소에서 하우스키핑 작업을 지원하고 자동화하여 가능한 한 효율적으로 서비스를 제공할 수 있도록 합니다. GitLab이 제어하는 Git 저장소에서 하우스키핑을 수행하기 위해 수동으로 Git 명령을 실행하지 마세요.

GitLab은 Git 저장소에서 하우스키핑 작업을 지원하고 자동화하여 가능한 한 효율적으로 서비스를 제공할 수 있도록 합니다. 하우스키핑 작업에는 다음이 포함됩니다:

Git 객체와 리비전 압축.
도달할 수 없는 객체 제거.
잠금 파일과 같은 오래된 데이터 제거.
성능을 향상시키는 데이터 구조 유지 관리.
포크 간의 객체 중복 제거를 개선하기 위한 객체 풀 업데이트.

Warning

GitLab이 제어하는 Git 저장소에서 하우스키핑을 수행하기 위해 수동으로 Git 명령을 실행하지 마세요. 그렇게 하면 저장소가 손상되고 데이터 손실이 발생할 수 있습니다.

하우스키핑 전략#

Gitaly는 두 가지 방식으로 Git 저장소에서 하우스키핑 작업을 수행할 수 있습니다:

즉각적 하우스키핑은 저장소 상태에 관계없이 특정 하우스키핑 작업을 실행합니다.
휴리스틱 하우스키핑은 저장소 상태에 따라 실행해야 할 하우스키핑 작업을 결정하는 일련의 휴리스틱을 기반으로 하우스키핑 작업을 실행합니다.

즉각적 하우스키핑#

"즉각적" 하우스키핑 전략은 저장소 상태에 관계없이 저장소에서 하우스키핑 작업을 실행합니다. 이것이 수동 트리거 및 푸시 기반 트리거에서 사용하는 기본 전략입니다.

즉각적 하우스키핑 전략은 GitLab 애플리케이션에 의해 제어됩니다. 하우스키핑 작업을 실행시킨 트리거에 따라 GitLab은 Gitaly에 특정 하우스키핑 작업을 수행하도록 요청합니다. Gitaly는 저장소가 최적화된 상태에 있더라도 이러한 작업을 수행합니다. 결과적으로 이 전략은 하우스키핑 작업 수행이 느릴 수 있는 대형 저장소에서 비효율적일 수 있습니다.

휴리스틱 하우스키핑#

히스토리

GitLab 14.9에서 수동 트리거 및 optimized_housekeeping이라는 플래그와 함께 푸시 기반 트리거에 대해 도입되었습니다. 기본적으로 활성화되어 있습니다.
GitLab 14.10에서 GitLab.com에서 활성화되었습니다.
GitLab 15.8에서 일반적으로 사용 가능해졌습니다. 기능 플래그 optimized_housekeeping이 제거되었습니다.

휴리스틱(또는 "기회주의적") 하우스키핑 전략은 저장소 상태를 분석하고 하나 이상의 데이터 구조가 충분히 최적화되지 않은 경우에만 하우스키핑 작업을 실행합니다. 이것이 예약된 하우스키핑에서 사용하는 전략입니다.

휴리스틱 하우스키핑은 실행해야 할 작업을 결정하기 위해 다음 정보를 사용합니다:

느슨하고 오래된 객체의 수.
이미 압축된 객체를 포함하는 팩 파일의 수.
느슨한 참조의 수.
커밋 그래프의 존재 여부.

분석된 데이터 구조를 최적화해야 하는지 여부의 결정은 저장소의 크기에 따라 달라집니다:

모든 객체의 총 크기가 클수록 객체가 더 자주 리팩됩니다.
총 참조 수가 많을수록 참조가 덜 자주 리팩됩니다.

Gitaly는 데이터 구조가 커질수록 최적화에 더 많은 시간이 걸리는 사실을 상쇄하기 위해 이를 수행합니다. 특히 많은 트래픽을 받는 대형 모노레포에서 너무 자주 최적화하는 것을 피하는 것이 중요합니다.

Gitaly에 저장소 최적화를 요청하는 빈도를 변경할 수 있습니다.

오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Repository를 선택합니다.
Repository maintenance를 확장합니다.
Housekeeping 섹션에서 하우스키핑 옵션을 구성합니다.
Save changes를 선택합니다.

Enable automatic repository housekeeping: Gitaly에 저장소 최적화를 정기적으로 실행하도록 요청합니다. 이 설정을 오랫동안 비활성화된 상태로 유지하면 GitLab 서버의 Git 저장소 액세스가 느려지고 저장소가 더 많은 디스크 공간을 사용합니다.
Optimize repository period: Gitaly가 저장소를 최적화하도록 요청받는 Git 푸시 횟수.

하우스키핑 작업 실행#

GitLab이 하우스키핑 작업을 실행하는 방법에는 여러 가지가 있습니다:

프로젝트 관리자가 저장소 하우스키핑 작업을 수동으로 트리거할 수 있습니다.
GitLab은 여러 Git 푸시 후 자동으로 하우스키핑 작업을 예약할 수 있습니다.
GitLab은 구성 가능한 시간 프레임 내에 모든 저장소에 대한 하우스키핑 작업을 실행하는 작업을 예약할 수 있습니다.

수동 트리거#

저장소 관리자는 저장소에서 하우스키핑 작업을 수동으로 트리거할 수 있습니다. 일반적으로 GitLab이 자동으로 하우스키핑 작업을 실행하는 것을 알고 있으므로 이는 필요하지 않습니다. 수동 트리거는 다음 중 하나의 경우에 유용할 수 있습니다:

저장소에 하우스키핑이 필요한 것으로 알려진 경우.
하우스키핑 작업의 자동 푸시 기반 예약이 비활성화된 경우.

하우스키핑 작업을 수동으로 트리거하려면:

상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
Settings > General을 선택합니다.
Advanced를 확장합니다.
Run housekeeping을 선택합니다.

이를 통해 프로젝트 저장소에 대한 비동기 백그라운드 워커가 시작됩니다. 백그라운드 워커는 Gitaly에 여러 최적화를 수행하도록 요청합니다.

하우스키핑은 또한 매 200번 푸시마다 프로젝트에서 참조되지 않은 LFS 파일을 제거하여 프로젝트의 스토리지 공간을 확보합니다.

도달할 수 없는 객체 정리#

도달할 수 없는 객체는 예약된 하우스키핑의 일부로 정리됩니다. 그러나 수동 정리도 트리거할 수 있습니다. 하우스키핑을 트리거하면 도달할 수 없는 객체가 2주의 유예 기간으로 정리됩니다. 도달할 수 없는 객체 정리를 수동으로 트리거하면 유예 기간이 30분으로 줄어듭니다.

Warning

도달할 수 없는 객체 정리는 유출된 비밀과 기타 민감한 정보의 제거를 보장하지 않습니다. 커밋되었지만 푸시되지 않은 비밀을 제거하는 방법에 대한 정보는 커밋에서 비밀 제거 튜토리얼을 참조하세요. 또한 blob을 개별적으로 제거할 수 있습니다. 해당 작업 수행의 가능한 결과에 대한 문서를 참조하세요.

동시 프로세스(예: git push)가 객체를 생성했지만 아직 객체에 대한 참조를 생성하지 않은 경우 객체가 삭제된 후 객체에 대한 참조가 추가되면 저장소가 손상될 수 있습니다. 유예 기간은 이러한 경쟁 조건의 가능성을 줄이기 위해 존재합니다. 예를 들어, 때로는 매우 느린 연결을 통해 많은 대형 객체를 자주 푸시하는 경우 도달할 수 없는 객체 정리에 따른 위험은 기업 내부에서만 접근할 수 있는 성능 좋은 연결을 갖는 환경보다 훨씬 높습니다. 이 옵션을 사용할 때 프로젝트 사용 프로파일을 고려하고 조용한 시간을 선택하세요.

도달할 수 없는 객체의 수동 정리를 트리거하려면:

상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
Settings > General을 선택합니다.
Advanced를 확장합니다.
Run housekeeping을 선택합니다.
작업이 완료될 때까지 30분 기다립니다.
Run housekeeping을 선택한 페이지로 돌아가서 Prune unreachable objects를 선택합니다.

예약된 하우스키핑#

GitLab은 푸시 횟수에 따라 자동으로 하우스키핑 작업을 수행하지만 푸시가 전혀 없는 저장소는 유지 관리하지 않습니다. 결과적으로 휴면 저장소나 읽기 요청만 받는 저장소는 저장소 하우스키핑 전략의 개선 사항을 활용하지 못할 수 있습니다.

관리자는 이 상황을 해결하기 위해 사용자 지정 가능한 간격으로 모든 저장소에서 하우스키핑을 수행하는 백그라운드 작업을 활성화할 수 있습니다. 이 백그라운드 작업은 Gitaly 노드가 호스팅하는 모든 저장소를 무작위 순서로 처리하고 적극적으로 하우스키핑 작업을 수행합니다. Gitaly 노드는 구성된 간격보다 더 오래 걸리면 저장소 처리를 중지합니다.

예약된 하우스키핑 구성#

Git 저장소의 백그라운드 유지 관리는 Gitaly에서 구성됩니다. 기본적으로 Gitaly는 매일 오전 12시에 10분 동안 백그라운드 저장소 유지 관리를 수행합니다.

Gitaly 구성에서 이 기본값을 변경할 수 있습니다.

Gitaly Cluster(Praefect)가 있는 환경의 경우 예약된 하우스키핑이 여러 노드에서 동시에 실행되지 않도록 Gitaly 노드 간에 예약된 하우스키핑 시작 시간을 엇갈리게 설정할 수 있습니다.

예약된 하우스키핑 실행이 지정된 duration에 도달하면 실행 중인 작업이 점진적으로 취소됩니다. 이후 예약된 하우스키핑 실행에서 Gitaly는 처리할 저장소 목록을 무작위로 섞습니다.

다음 스니펫은 default 스토리지에 대해 23:00부터 1시간 동안 일일 백그라운드 저장소 유지 관리를 활성화합니다:

[daily_maintenance]
start_hour = 23
start_minute = 00
duration = 1h
storages = ["default"]

다음 스니펫을 사용하여 백그라운드 저장소 유지 관리를 완전히 비활성화합니다:

[daily_maintenance]
disabled = true

gitaly['configuration'] = {
  daily_maintenance: {
    disabled: false,
    start_hour: 23,
    start_minute: 00,
    duration: '1h',
    storages: ['default'],
  },
}

다음 스니펫을 사용하여 백그라운드 저장소 유지 관리를 완전히 비활성화합니다:

gitaly['configuration'] = {
  daily_maintenance: {
    disabled: true,
  },
}

예약된 하우스키핑이 실행될 때 Gitaly 로그에서 다음 항목을 볼 수 있습니다:

# 예약된 하우스키핑이 시작될 때
{"level":"info","msg":"maintenance: daily scheduled","pid":197260,"scheduled":"2023-09-27T13:10:00+13:00","time":"2023-09-27T00:08:31.624Z"}

# 예약된 하우스키핑이 완료될 때
{"actual_duration":321181874818,"error":null,"level":"info","max_duration":"1h0m0s","msg":"maintenance: daily completed","pid":197260,"time":"2023-09-27T00:15:21.182Z"}

actual_duration(나노초)은 예약된 유지 관리 실행에 걸린 시간을 나타냅니다. 이전 예시에서 예약된 하우스키핑은 5분 조금 넘게 완료되었습니다.

객체 풀 저장소#

객체 풀 저장소는 GitLab이 저장소 포크 간에 객체를 중복 제거하는 데 사용됩니다. 첫 번째 포크를 만들 때:

포크될 저장소의 모든 객체를 포함하는 객체 풀 저장소를 만듭니다.
Git의 alternates 메커니즘을 사용하여 저장소를 이 새 객체 풀에 연결합니다.
저장소를 리팩하여 객체 풀의 객체를 사용하도록 합니다. 따라서 객체의 자체 복사본을 삭제할 수 있습니다.

이 저장소의 모든 포크는 이제 객체 풀에 연결될 수 있으며 따라서 기본 저장소에서 분기된 객체만 유지하면 됩니다.

GitLab은 객체 풀에서 특별한 하우스키핑 작업을 수행해야 합니다:

Gitaly는 연결된 포크에서 사용될 수 있기 때문에 객체 풀에서 도달할 수 없는 객체를 절대 삭제할 수 없습니다.
Gitaly는 같은 이유로 모든 객체를 도달 가능하게 유지해야 합니다. 따라서 객체 풀은 "dangling" 객체에 대한 참조를 유지하여 삭제되지 않도록 합니다.
GitLab은 기본 저장소에 추가된 새 객체를 가져오기 위해 객체 풀을 정기적으로 업데이트해야 합니다. 그렇지 않으면 객체 풀이 객체 중복 제거에 점점 비효율적이 됩니다.

이러한 하우스키핑 작업은 표준 Git 저장소에 대해 실행하는 일반 하우스키핑 작업을 실행하면서 이러한 모든 특별 작업을 처리하는 특수 FetchIntoObjectPool RPC에 의해 수행됩니다.

객체 풀은 기본 구성원이 가비지 컬렉션될 때마다 자동으로 최적화됩니다. 따라서 해당 프로젝트에서 동일한 Git GC 기간을 사용하여 주기를 구성할 수 있습니다.

Rails 콘솔에서 RPC를 수동으로 호출해야 하는 경우 project.pool_repository.object_pool.fetch를 호출할 수 있습니다. 이는 잠재적으로 오래 실행되는 작업이지만 Gitaly는 약 8시간 후에 타임아웃됩니다.

Housekeeping

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

원문 보기

번역일: 2026-05-22

요약

Git 객체와 리비전 압축.
도달할 수 없는 객체 제거.
잠금 파일과 같은 오래된 데이터 제거.
성능을 향상시키는 데이터 구조 유지 관리.
포크 간의 객체 중복 제거를 개선하기 위한 객체 풀 업데이트.

Warning

하우스키핑 전략#

Gitaly는 두 가지 방식으로 Git 저장소에서 하우스키핑 작업을 수행할 수 있습니다:

즉각적 하우스키핑은 저장소 상태에 관계없이 특정 하우스키핑 작업을 실행합니다.
휴리스틱 하우스키핑은 저장소 상태에 따라 실행해야 할 하우스키핑 작업을 결정하는 일련의 휴리스틱을 기반으로 하우스키핑 작업을 실행합니다.

즉각적 하우스키핑#

휴리스틱 하우스키핑#

히스토리

GitLab 14.9에서 수동 트리거 및 optimized_housekeeping이라는 플래그와 함께 푸시 기반 트리거에 대해 도입되었습니다. 기본적으로 활성화되어 있습니다.
GitLab 14.10에서 GitLab.com에서 활성화되었습니다.
GitLab 15.8에서 일반적으로 사용 가능해졌습니다. 기능 플래그 optimized_housekeeping이 제거되었습니다.

휴리스틱 하우스키핑은 실행해야 할 작업을 결정하기 위해 다음 정보를 사용합니다:

느슨하고 오래된 객체의 수.
이미 압축된 객체를 포함하는 팩 파일의 수.
느슨한 참조의 수.
커밋 그래프의 존재 여부.

분석된 데이터 구조를 최적화해야 하는지 여부의 결정은 저장소의 크기에 따라 달라집니다:

모든 객체의 총 크기가 클수록 객체가 더 자주 리팩됩니다.
총 참조 수가 많을수록 참조가 덜 자주 리팩됩니다.

Gitaly에 저장소 최적화를 요청하는 빈도를 변경할 수 있습니다.

오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Repository를 선택합니다.
Repository maintenance를 확장합니다.
Housekeeping 섹션에서 하우스키핑 옵션을 구성합니다.
Save changes를 선택합니다.

Enable automatic repository housekeeping: Gitaly에 저장소 최적화를 정기적으로 실행하도록 요청합니다. 이 설정을 오랫동안 비활성화된 상태로 유지하면 GitLab 서버의 Git 저장소 액세스가 느려지고 저장소가 더 많은 디스크 공간을 사용합니다.
Optimize repository period: Gitaly가 저장소를 최적화하도록 요청받는 Git 푸시 횟수.

하우스키핑 작업 실행#

GitLab이 하우스키핑 작업을 실행하는 방법에는 여러 가지가 있습니다:

프로젝트 관리자가 저장소 하우스키핑 작업을 수동으로 트리거할 수 있습니다.
GitLab은 여러 Git 푸시 후 자동으로 하우스키핑 작업을 예약할 수 있습니다.
GitLab은 구성 가능한 시간 프레임 내에 모든 저장소에 대한 하우스키핑 작업을 실행하는 작업을 예약할 수 있습니다.

수동 트리거#

저장소에 하우스키핑이 필요한 것으로 알려진 경우.
하우스키핑 작업의 자동 푸시 기반 예약이 비활성화된 경우.

하우스키핑 작업을 수동으로 트리거하려면:

상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
Settings > General을 선택합니다.
Advanced를 확장합니다.
Run housekeeping을 선택합니다.

이를 통해 프로젝트 저장소에 대한 비동기 백그라운드 워커가 시작됩니다. 백그라운드 워커는 Gitaly에 여러 최적화를 수행하도록 요청합니다.

하우스키핑은 또한 매 200번 푸시마다 프로젝트에서 참조되지 않은 LFS 파일을 제거하여 프로젝트의 스토리지 공간을 확보합니다.

도달할 수 없는 객체 정리#

Warning

도달할 수 없는 객체의 수동 정리를 트리거하려면:

상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
Settings > General을 선택합니다.
Advanced를 확장합니다.
Run housekeeping을 선택합니다.
작업이 완료될 때까지 30분 기다립니다.
Run housekeeping을 선택한 페이지로 돌아가서 Prune unreachable objects를 선택합니다.

예약된 하우스키핑#

예약된 하우스키핑 구성#

Gitaly 구성에서 이 기본값을 변경할 수 있습니다.

다음 스니펫은 default 스토리지에 대해 23:00부터 1시간 동안 일일 백그라운드 저장소 유지 관리를 활성화합니다:

[daily_maintenance]
start_hour = 23
start_minute = 00
duration = 1h
storages = ["default"]

다음 스니펫을 사용하여 백그라운드 저장소 유지 관리를 완전히 비활성화합니다:

[daily_maintenance]
disabled = true

gitaly['configuration'] = {
  daily_maintenance: {
    disabled: false,
    start_hour: 23,
    start_minute: 00,
    duration: '1h',
    storages: ['default'],
  },
}

다음 스니펫을 사용하여 백그라운드 저장소 유지 관리를 완전히 비활성화합니다:

gitaly['configuration'] = {
  daily_maintenance: {
    disabled: true,
  },
}

예약된 하우스키핑이 실행될 때 Gitaly 로그에서 다음 항목을 볼 수 있습니다:

# 예약된 하우스키핑이 시작될 때
{"level":"info","msg":"maintenance: daily scheduled","pid":197260,"scheduled":"2023-09-27T13:10:00+13:00","time":"2023-09-27T00:08:31.624Z"}

# 예약된 하우스키핑이 완료될 때
{"actual_duration":321181874818,"error":null,"level":"info","max_duration":"1h0m0s","msg":"maintenance: daily completed","pid":197260,"time":"2023-09-27T00:15:21.182Z"}

actual_duration(나노초)은 예약된 유지 관리 실행에 걸린 시간을 나타냅니다. 이전 예시에서 예약된 하우스키핑은 5분 조금 넘게 완료되었습니다.

객체 풀 저장소#

객체 풀 저장소는 GitLab이 저장소 포크 간에 객체를 중복 제거하는 데 사용됩니다. 첫 번째 포크를 만들 때:

포크될 저장소의 모든 객체를 포함하는 객체 풀 저장소를 만듭니다.
Git의 alternates 메커니즘을 사용하여 저장소를 이 새 객체 풀에 연결합니다.
저장소를 리팩하여 객체 풀의 객체를 사용하도록 합니다. 따라서 객체의 자체 복사본을 삭제할 수 있습니다.

이 저장소의 모든 포크는 이제 객체 풀에 연결될 수 있으며 따라서 기본 저장소에서 분기된 객체만 유지하면 됩니다.

GitLab은 객체 풀에서 특별한 하우스키핑 작업을 수행해야 합니다:

Gitaly는 연결된 포크에서 사용될 수 있기 때문에 객체 풀에서 도달할 수 없는 객체를 절대 삭제할 수 없습니다.
Gitaly는 같은 이유로 모든 객체를 도달 가능하게 유지해야 합니다. 따라서 객체 풀은 "dangling" 객체에 대한 참조를 유지하여 삭제되지 않도록 합니다.
GitLab은 기본 저장소에 추가된 새 객체를 가져오기 위해 객체 풀을 정기적으로 업데이트해야 합니다. 그렇지 않으면 객체 풀이 객체 중복 제거에 점점 비효율적이 됩니다.