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

원래 프로젝트에 대한 쓰기 액세스 권한이 있으면 포크가 필요하지 않습니다. 대신 브랜치를 사용하여 작업을 관리합니다. 기여하려는 프로젝트에 쓰기 액세스 권한이 없으면 포크합니다. 포크에서 변경 사항을 만든 다음 머지 리퀘스트를 통해 업스트림 프로젝트에 제출합니다.

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

포크 만들기#

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을 선택합니다. 가시성 수준에 대한 자세한 내용은 프로젝트 및 그룹 가시성을 참조하세요.
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. 포크가 업스트림 프로젝트보다 ahead인 경우 Create merge request를 선택하여 포크의 변경 사항을 업스트림 프로젝트에 추가하는 것을 제안합니다.

6. 포크가 업스트림 프로젝트보다 behind인 경우 Update fork를 선택하여 업스트림 리포지터리에서 변경 사항을 풀합니다.

7. 포크가 업스트림 프로젝트보다 ahead and behind인 경우 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 커뮤니티 포럼: 포크 새로 고침
• 그룹 외부 프로젝트 포크 방지
• 포크와 함께 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) 권한으로 대상 그룹의 구성원이어야 합니다.