포크는 원하는 네임스페이스에 만드는 다른 프로젝트의 개인 사본입니다. 포크에는 업스트림 프로젝트 리포지터리의 사본과 일부 프로젝트 설정이 포함되지만, 이슈, 머지 리퀘스트, 위키 페이지 같은 프로젝트 콘텐츠는 포함되지 않습니다. 포크에서 업스트림 프로젝트를 대상으로 하는 머지 리퀘스트를 만들 수 있습니다. 포크의 개별 커밋을 업스트림 프로젝트로 체리픽할 수도 있습니다.

원본 프로젝트에 쓰기 권한이 있으면 포크가 필요하지 않습니다. 대신 브랜치로 작업을 관리합니다. 기여하려는 프로젝트에 쓰기 권한이 없으면 포크합니다. 포크에서 변경한 뒤 머지 리퀘스트로 업스트림 프로젝트에 제출합니다.

비공개 머지 리퀘스트를 만들려면 공개 프로젝트의 개인 포크를 사용합니다.

포크 만들기#

GitLab의 기존 프로젝트를 포크하려면 다음 절차를 따릅니다.

1. 프로젝트 홈페이지의 오른쪽 상단에서 Fork ([fork])를 선택합니다.

2. 선택 사항. Project name을 편집합니다.

3. Project URL에서 포크가 속할 네임스페이스를 선택합니다.

4. Project slug를 추가합니다. 이 값은 포크 URL의 일부가 됩니다. 네임스페이스 안에서 고유해야 합니다.

5. 선택 사항. Project description을 추가합니다.

6. Branches to include 옵션 중 하나를 선택합니다.

   • All branches (기본값).
   • Only the default branch. --single-branch 및 --no-tags Git 옵션을 사용합니다.

7. 포크의 Visibility level을 선택합니다. 포크의 공개 범위는 업스트림 프로젝트와 포크가 속한 네임스페이스의 공개 범위보다 최소한 같거나 더 제한적이어야 합니다. 그 밖의 공개 범위 수준은 선택할 수 없습니다. 공개 범위 수준에 관한 자세한 내용은 프로젝트 및 그룹 공개 범위를 참고합니다.

   [!note] 포크를 만든 뒤 업스트림 프로젝트가 더 제한적으로 바뀌어도 포크의 공개 범위는 자동으로 바뀌지 않습니다. 직접 변경할 수 있지만 같은 규칙이 적용됩니다. 포크는 업스트림 프로젝트보다 최소한 같거나 더 제한적이어야 합니다.

8. Fork project를 선택합니다.

GitLab이 포크를 만들고 새 포크 페이지로 이동하며, 포크 생성 사실을 감사 로그에 기록합니다.

변경 사항을 업스트림에 자주 기여할 예정이라면 포크에 기본 대상을 설정하는 방안을 검토합니다.

포크 업데이트#

포크는 업스트림 프로젝트와 동기화가 어긋나 업데이트가 필요할 수 있습니다.

• 앞선 상태(Ahead): 업스트림 리포지터리에 없는 새 커밋이 포크에 있습니다. 포크를 동기화하려면 머지 리퀘스트를 만들어 변경 사항을 업스트림 리포지터리에 푸시합니다.
• 뒤처진 상태(Behind): 포크에 없는 새 커밋이 업스트림 리포지터리에 있습니다. 포크를 동기화하려면 새 커밋을 포크로 가져옵니다.
• 앞서면서 뒤처진 상태(Ahead and behind): 업스트림 리포지터리와 포크 양쪽에 서로에게 없는 새 커밋이 있습니다. 포크를 완전히 동기화하려면 머지 리퀘스트를 만들어 변경 사항을 푸시하고, 업스트림 리포지터리의 새 변경 사항을 포크로 가져옵니다.

포크를 업스트림 프로젝트와 동기화하려면 GitLab UI나 명령줄에서 업데이트합니다. GitLab Premium 및 Ultimate 티어에서는 포크를 업스트림 프로젝트의 풀 미러로 구성해 업데이트를 자동화할 수도 있습니다.

UI에서#

UI에서 포크를 업데이트하면 포크의 다음 리포지터리 보호 설정이 무시됩니다.

• 포크에 구성된 푸시 규칙.
• 포크의 파일에 적용된 파일 잠금.

이 동작은 업스트림 프로젝트와 포크의 보호 구성이 다를 때 동기화가 실패하지 않도록 합니다. 동기화 과정은 업스트림 리포지터리에서 변경 사항을 가져와 포크에 바로 적용합니다.

사전 요구 사항:

• 업스트림 프로젝트의 보호되지 않은 브랜치에서 포크를 만들어야 합니다.

GitLab UI에서 포크를 업데이트하려면 다음 절차를 따릅니다.

1. 상단 바에서 Search or go to를 선택합니다.

2. View all my projects를 선택합니다.

3. 업데이트할 포크를 선택합니다.

4. 브랜치 이름 드롭다운 목록 아래의 Forked from ([fork]) 정보 상자에서 포크가 앞선 상태인지, 뒤처진 상태인지, 둘 다인지 확인합니다. 이 예시에서 포크는 업스트림 프로젝트보다 뒤처져 있습니다.

   

5. 포크가 업스트림 프로젝트보다 앞선 상태 이면 Create merge request를 선택해 포크의 변경 사항을 업스트림 프로젝트에 추가하도록 제안합니다.

6. 포크가 업스트림 프로젝트보다 뒤처진 상태 이면 Update fork를 선택해 업스트림 리포지터리의 변경 사항을 가져옵니다.

7. 포크가 업스트림 프로젝트보다 앞서면서 뒤처진 상태 이면 GitLab이 머지 충돌을 감지하지 않은 경우에만 UI에서 업데이트할 수 있습니다.

   • 포크에 머지 충돌이 없으면 Create merge request를 선택해 변경 사항을 업스트림 프로젝트에 푸시하도록 제안하거나, Update fork를 선택해 변경 사항을 포크로 가져오거나, 둘 다 수행할 수 있습니다. 포크에 포함된 변경의 성격에 따라 적절한 작업이 달라집니다.
   • 포크에 머지 충돌이 있으면 GitLab이 명령줄에서 포크를 업데이트하는 단계별 안내를 표시합니다.

명령줄에서#

명령줄에서도 포크를 업데이트할 수 있습니다.

사전 요구 사항:

• 로컬 머신에 Git 클라이언트를 내려받아 설치해야 합니다.
• 업데이트할 프로젝트의 포크를 만들어야 합니다.

명령줄에서 포크를 업데이트하려면 Git으로 포크 업데이트의 안내를 따릅니다.

리포지터리 미러링 사용#

다음 조건을 모두 충족하면 포크를 업스트림 프로젝트의 미러로 구성할 수 있습니다.

1. 구독이 GitLab Premium 또는 GitLab Ultimate입니다.
2. 모든 변경을 브랜치(main 아님)에서 수행합니다.
3. main 변경이 필요한 비공개 이슈용 머지 리퀘스트를 사용하지 않습니다.

리포지터리 미러링은 포크를 원본 프로젝트와 동기화된 상태로 유지합니다. 이 방식은 수동 git pull 없이 한 시간에 한 번 포크를 업데이트합니다. 설정 방법은 풀 미러링 구성을 참고합니다.

업스트림으로 변경 사항 머지#

코드를 업스트림 프로젝트로 보낼 준비가 되면 포크에서 작업할 때에 설명된 대로 새 머지 리퀘스트를 만듭니다. 머지가 완료되면 변경 사항이 업스트림 리포지터리에 추가됩니다.

머지 리퀘스트가 업스트림에 머지된 뒤에도 포크의 브랜치는 일괄 삭제 목적에서 자동으로 Merged로 간주되지 않습니다. 포크의 기본 브랜치에 해당 변경 사항이 포함되어야만 머지된 것으로 간주됩니다. 포크에서 이러한 브랜치를 머지됨으로 표시하려면 포크를 업데이트해 업스트림 프로젝트와 동기화합니다.

포크 연결 해제#

포크 관계를 제거하면 포크가 업스트림 프로젝트에서 분리됩니다. 그러면 포크는 독립적인 프로젝트가 됩니다.

사전 요구 사항:

• 포크 연결을 해제하려면 프로젝트 소유자여야 합니다.

포크 관계를 제거하려면 다음 절차를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Advanced를 펼칩니다.
4. Remove fork relationship 섹션에서 Remove fork relationship을 선택합니다.
5. 확인을 위해 프로젝트 경로를 입력하고 Confirm을 선택합니다.

GitLab은 연결 해제 작업을 감사 로그에 기록합니다. 해시 스토리지 풀을 사용해 다른 리포지터리와 객체를 공유하는 포크의 연결을 해제하면 다음과 같이 동작합니다.

• 풀의 모든 객체가 포크로 복사됩니다.
• 복사가 완료된 뒤에는 스토리지 풀의 추가 업데이트가 포크로 전파되지 않습니다.

포크 삭제#

포크를 삭제하면 포크 관계를 포함해 프로젝트와 모든 콘텐츠가 영구적으로 제거됩니다. 이 작업은 다른 프로젝트를 삭제하는 것과 동일합니다.

포크를 삭제하려면 프로젝트 삭제를 참고합니다.

포크의 스토리지 사용량 확인#

포크는 필요한 스토리지 공간을 줄이기 위해 중복 제거 전략을 사용합니다. 포크는 원본 프로젝트에 연결된 객체 풀에 접근할 수 있습니다.

자세한 내용과 스토리지 사용량 확인 방법은 프로젝트 포크 스토리지 사용량 보기를 참고합니다.

관련 주제#

• GitLab 커뮤니티 포럼: Refreshing a fork
• 그룹 외부로의 프로젝트 포크 방지
• Git LFS가 포크에서 동작하는 방식 이해

문제 해결#

오류: An error occurred while forking the project. Please try again#

이 오류는 포크된 프로젝트와 새 네임스페이스 사이에 인스턴스 러너 설정이 일치하지 않을 때 발생할 수 있습니다. 자세한 내용은 포크된 프로젝트에서 인스턴스 러너 사용을 참고합니다.

포크 관계 제거 실패#

UI나 API로 포크를 제거할 수 없으면 Rails 콘솔 세션에서 포크 관계 제거를 시도할 수 있습니다.

p = Project.find_by_full_path('<project_path>')
u = User.find_by_username('<username>')
Projects::UnlinkForkService.new(p, u).execute

오류: User is not allowed to import projects#

서비스 계정으로 프로젝트를 포크할 때 다음과 같은 오류가 발생할 수 있습니다.

{"message":["Namespace is not valid","User is not allowed to import projects"]}

이 문제는 서비스 계정이 봇 사용자여서, 프로젝트 한도를 늘리더라도 개인 네임스페이스로는 프로젝트를 포크할 수 없기 때문에 발생합니다.

서비스 계정으로 프로젝트를 포크할 때는 프로젝트 포크 API에서 namespace_id 또는 namespace_path로 대상 그룹 네임스페이스를 지정하는 방법으로 해결합니다. 서비스 계정은 대상 그룹의 멤버여야 하며 Developer, Maintainer 또는 Owner 권한이 있어야 합니다.