Git LFS 문제 해결

Git LFS를 사용할 때 다음과 같은 문제가 발생할 수 있습니다.

  • Git LFS 원본 v1 API는 지원되지 않습니다.
  • Git LFS 요청은 HTTPS 자격 증명을 사용하며, 따라서 Git 자격 증명 저장소를 사용해야 합니다.
  • 그룹 위키는 Git LFS를 지원하지 않습니다.

오류: 저장소 또는 개체를 찾을 수 없음

이러한 오류는 몇 가지 이유로 발생할 수 있습니다.

  • 일부 LFS 개체에 액세스할 권한이 없습니다. 프로젝트에 푸시할 권한이나 프로젝트에서 가져올 수 있는 권한이 있는지 확인하세요.
  • 프로젝트가 LFS 개체에 액세스할 수 없습니다. 푸시하려는 LFS 개체가 더 이상 프로젝트에서 사용할 수 없습니다. 대부분의 경우에는 해당 개체가 서버에서 제거된 경우입니다.
  • 로컬 Git 저장소가 Git LFS API의 폐기된 버전을 사용하고 있습니다. 로컬 Git LFS를 업데이트하고 다시 시도하세요.

무효한 상태 <url> : 501

Git LFS는 실패를 로그 파일에 기록합니다. 이 로그 파일을 보려면:

  1. 터미널 창에서 프로젝트의 디렉토리로 이동합니다.

  2. 최근 로그 파일을 보려면 다음 명령을 실행합니다. 

    git lfs logs last

이러한 문제로 501 오류가 발생할 수 있습니다:

  • Git LFS가 프로젝트 설정에서 활성화되어 있지 않습니다. 프로젝트 설정을 확인하고 Git LFS를 활성화하세요.
  • GitLab 서버에서 Git LFS 지원이 비활성화되어 있습니다. 서버에서 Git LFS가 비활성화된 이유에 대해 GitLab 관리자에게 문의하세요. Git LFS 지원을 사용하도록 설정하는 방법은 LFS 관리 문서를 참조하세요.
  • GitLab 서버에서 지원하지 않는 Git LFS 클라이언트 버전을 사용하고 있습니다. 다음을 확인해야 합니다:
    1. git lfs version으로 Git LFS 버전을 확인합니다.
    2. git lfs -l로 프로젝트의 Git 설정을 확인합니다. 설정이 batch = false로 되어 있다면 해당 줄을 제거하고, Git LFS 클라이언트를 업데이트하세요. GitLab은 1.0.1 버전 이상만 지원합니다.

개체를 푸시할 때 항상 자격 증명이 필요합니다

Git LFS는 모든 개체를 푸시할 때마다 사용자를 HTTP 기본 인증으로 인증하므로 사용자 HTTPS 자격 증명이 필요합니다. 기본적으로 Git은 사용하는 각 저장소에 대해 자격 증명을 기억합니다. 자세한 내용은 공식 Git 문서를 참조하세요.

예를 들어, Git에게 특정 시간 동안 자격 증명을 기억하도록 지시할 수 있습니다. 다음 예시는 1시간(3600초) 동안 자격 증명을 기억하며, 1시간 후에 다시 인증해야 합니다. 

git config --global credential.helper 'cache --timeout=3600'

자격 증명을 저장하고 암호화하는 방법은 다음과 같습니다:

사용자 자격 증명을 저장하는 자세한 내용은 Git 자격 증명 저장소 문서를 참조하세요.

LFS 개체가 푸시될 때 누락됨

GitLab은 LFS 포인터를 감지하기 위해 푸시 시 파일을 확인합니다. LFS 포인터가 감지되면 GitLab은 해당 파일이 LFS에 이미 존재하는지 확인합니다. 별도의 Git LFS 서버를 사용하고 이 문제가 발생하는 경우:

  1. 로컬에 Git LFS가 설치되어 있는지 확인합니다.
  2. git lfs push --all과 같은 수동 푸시를 고려하세요.

Git LFS 파일을 GitLab 외부에 저장하는 경우, 프로젝트에서 Git LFS를 사용 안 함으로 설정할 수 있습니다.

LFS 개체를 외부로 호스팅

사용자 정의 LFS URL을 설정하여 LFS 개체를 외부에 호스팅할 수 있습니다. 

git config -f .lfsconfig lfs.url https://example.com/<project>.git/info/lfs

이렇게 하는 이유는 LFS 데이터를 Nexus Repository 같은 장치에 저장하는 경우입니다. 외부 LFS 저장소를 사용하는 경우, GitLab은 LFS 개체를 확인할 수 없습니다. 따라서 GitLab LFS 지원이 활성화된 경우 푸시가 실패합니다.

푸시 실패를 방지하려면 프로젝트 설정에서 Git LFS 지원을 사용 안 함으로 설정할 수 있습니다. 그러나 이 방법은 GitLab LFS 기능의 일부를 비활성화하기 때문에 원하는 방법이 아닐 수 있습니다. 또한, 다음과 같은 GitLab LFS 기능이 비활성화됩니다:

  • LFS 개체 확인.
  • LFS용 GitLab UI 통합.

LFS 개체를 푸시할 때 I/O 타임아웃

네트워크 상태가 불안정한 경우, Git LFS 클라이언트가 파일을 업로드하려고 할 때 타임아웃될 수 있습니다. 다음과 같은 오류가 발생할 수 있습니다: 

LFS: Put "http://example.com/root/project.git/gitlab-lfs/objects/<OBJECT-ID>/15":
read tcp your-instance-ip:54544->your-instance-ip:443: i/o timeout
error: failed to push some refs to 'ssh://example.com:2222/root/project.git'

이 문제를 해결하려면 클라이언트 활동 타임아웃을 더 높은 값으로 설정하세요. 예를 들어, 타임아웃을 60초로 설정하려면: 

git config lfs.activitytimeout 60

포인터여야 할 파일 n개를 만났지만 그렇지 않았습니다

이 오류는 저장소가 Git LFS로 파일을 추적해야 하지만 그렇지 않은 경우를 나타냅니다. 이슈 326342는 GitLab 16.10에서 해결된 문제 중 하나였습니다.

이 문제를 해결하려면 영향을 받는 파일을 이전하고 저장소로 푸시하세요:

  1. 파일을 LFS로 이전합니다: 

    git lfs migrate import --yes --no-rewrite "<your-file>"

  2. 저장소로 다시 푸시합니다: 

    git push

  3. 선택 사항. .git 폴더를 정리합니다: 

    git reflog expire --expire-unreachable=now --all
git gc --prune=now