• 프로젝트의 기본 브랜치 이름 변경
• 인스턴스 또는 그룹의 기본 브랜치 이름 변경
  • 인스턴스 수준의 사용자 정의 초기 브랜치 이름
  • 그룹 수준의 사용자 정의 초기 브랜치 이름
• 초기 기본 브랜치 보호
  • 인스턴스 수준의 기본 브랜치 보호
    • 기본 브랜치 보호 재정의 방지
  • 그룹 수준의 기본 브랜치 보호
• 리포지터리의 기본 브랜치 이름 변경
• 기본 브랜치 이름 변경 리다이렉트
• 관련 주제
• 문제 해결
  • 기본 브랜치를 변경할 수 없음: 현재 브랜치로 재설정함
  • GraphQL을 사용하여 기본 브랜치 쿼리

기본 브랜치

새 프로젝트를 만들 때 GitLab은 리포지터리에 기본 브랜치를 생성합니다. 기본 브랜치에는 다른 브랜치와 공유되지 않는 특별한 구성 옵션이 있습니다:

• 삭제할 수 없음.
• 초기에는 강제 푸시에 대해 보호됨.
• Merge Request이 이 브랜치에 작업을 Merge할 때 이슈를 닫기 위한 패턴을 사용하면 작업이 이 브랜치로 Merge됩니다.

새 프로젝트의 기본 브랜치의 이름은 GitLab 관리자가 만든 인스턴스 수준 또는 그룹 수준 구성 변경에 따라 다릅니다. GitLab은 먼저 특정한 사용자 정의를 확인한 후, 사용자 정의가 없는 경우 GitLab 기본값을 사용합니다:

1. 프로젝트별 사용자 정의 기본 브랜치 이름.
2. 하위 그룹 수준의 사용자 정의 기본 브랜치 이름.
3. 그룹 수준의 사용자 정의 기본 브랜치 이름.
4. 인스턴스 수준의 사용자 정의 기본 브랜치 이름.
5. 어떠한 수준에서도 사용자 정의 기본 브랜치 이름이 설정되지 않은 경우 GitLab은 main으로 기본값을 설정합니다.

GitLab UI에서 언제든지 기본값을 변경할 수 있습니다. 또한, 복제본의 리포지터리를 업데이트하는 데 필요한 Git 명령을 제공합니다.

프로젝트의 기본 브랜치 이름 변경

전제 조건:

• 프로젝트에서 소유자 또는 유지 관리자 역할을 가지고 있어야 합니다.

개별 프로젝트를 업데이트하려면 다음을 수행합니다:

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 설정 > 리포지터리를 선택합니다.
3. 브랜치 기본값을 확장합니다. 기본 브랜치에서 새로운 기본 브랜치를 선택합니다.
4. 선택적으로 기본 브랜치에서 참조된 이슈를 자동으로 닫음 확인란을 선택하여 Merge Request이 닫는 패턴을 사용할 때 이슈를 닫습니다.
5. 변경사항 저장을 선택합니다.

API 사용자는 프로젝트 API의 default_branch 속성을 사용하여 프로젝트를 만들거나 편집할 수 있습니다.

인스턴스 또는 그룹의 기본 브랜치 이름 변경

GitLab 관리자는 인스턴스 수준 또는 그룹 수준에서 새로운 기본 브랜치 이름을 구성할 수 있습니다.

인스턴스 수준의 사용자 정의 초기 브랜치 이름

GitLab 관리자는 Self-Managed형 인스턴스의 초기 브랜치를 사용자 정의할 수 있습니다. 개별 그룹과 하위 그룹은 이 인스턴스 전역 설정을 그들의 프로젝트에 대해 재정의할 수 있습니다.

1. 왼쪽 사이드바에서 맨 아래에서 관리 영역을 선택합니다.
2. 설정 > 리포지터리를 선택합니다.
3. 기본 브랜치를 확장합니다.
4. 초기 기본 브랜치 이름에서 새로운 기본 브랜치를 선택합니다.
5. 변경사항 저장을 선택합니다.

이 설정을 변경한 후에 만든 프로젝트는 사용자 정의 브랜치 이름을 사용하며, 하위 그룹 수준 구성이 이를 재정의하지 않는 경우에 한합니다.

그룹 수준의 사용자 정의 초기 브랜치 이름

그룹과 하위 그룹의 소유자는 그룹의 기본 브랜치 이름을 구성할 수 있습니다:

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
2. 설정 > 리포지터리를 선택합니다.
3. 기본 브랜치를 확장합니다.
4. 초기 기본 브랜치 이름에서 새로운 기본 브랜치를 선택합니다.
5. 변경사항 저장을 선택합니다.

이 설정을 변경한 후에 생성된 프로젝트는 사용자 정의 브랜치 이름을 사용하며, 하위 그룹 구성이 이를 재정의하지 않는 경우에 한합니다.

초기 기본 브랜치 보호

• 16.0의 전체 보호 이후에 도입되었습니다.

GitLab 관리자 및 그룹 소유자는 다음 옵션 중 하나를 사용하여 모든 리포지터리의 기본 브랜치에 적용할 브랜치 보호를 정의할 수 있습니다:

• 완전 보호 - 기본값. 개발자는 새로운 커밋을 푸시할 수 없지만 유지 관리자는 할 수 있습니다. 강제 푸시를 할 수 없습니다.
• 초기 푸시 후 완전 보호 - 개발자는 리포지터리에 초기 커밋을 푸시할 수 있지만 이후에는 할 수 없습니다. 유지 관리자는 항상 푸시할 수 있습니다. 강제 푸시를 할 수 없습니다.
• 푸시에 대해 보호됨 - 개발자는 새로운 커밋을 푸시할 수 없지만 Merge Request을 허용합니다. 유지 관리자는 브랜치로 푸시할 수 있습니다.
• 부분 보호 - 개발자와 유지 관리자 모두 새로운 커밋을 푸시할 수 있지만 강제 푸시할 수는 없습니다.
• 보호되지 않음 - 개발자와 유지 관리자 모두 새로운 커밋을 푸시하고 강제 푸시할 수 있습니다.

인스턴스 수준의 기본 브랜치 보호

이 설정은 각 리포지터리의 기본 브랜치에만 적용됩니다. 다른 브랜치를 보호하려면 다음 중 하나를 수행해야 합니다:

• 리포지터리에서 브랜치 보호 구성.
• 그룹의 브랜치 보호 구성.

Self-Managed형 인스턴스의 관리자는 Self-Managed형 인스턴스에서 호스팅되는 프로젝트의 초기 기본 브랜치 보호를 사용자 정의할 수 있습니다. 개별 그룹 및 하위 그룹은 이 인스턴스 전역 설정을 그룹의 프로젝트에 대해 재정의할 수 있습니다.

1. 왼쪽 사이드바에서 맨 아래에서 관리 영역을 선택합니다.
2. 설정 > 리포지터리를 선택합니다.
3. 기본 브랜치를 확장합니다.
4. 초기 기본 브랜치 보호를 선택합니다.
5. 그룹 소유자가 인스턴스의 기본 브랜치 보호를 재정의할 수 있도록 허용하려면 그룹의 기본 브랜치 보호 관리 허용를 선택합니다.
6. 변경사항 저장을 선택합니다.

기본 브랜치 보호 재정의 방지

기본 브랜치의 인스턴스 수준 보호는 GitLab Premium 또는 Ultimate에서, GitLab 관리자가 그룹 소유자가 이 권한을 비활성화하여 그룹당으로 기본 브랜치 보호 규칙을 강제할 수 있습니다:

1. 왼쪽 사이드바에서 맨 아래에서 관리 영역을 선택합니다.
2. 설정 > 리포지터리를 선택합니다.
3. 기본 브랜치 섹션을 확장합니다.
4. 그룹 소유자가 기본 브랜치 보호를 그룹당으로 관리할 수 있도록 허용 확인란을 해제합니다.
5. 변경사항 저장을 선택합니다.

그룹 수준의 기본 브랜치 보호

기본 브랜치에 대한 인스턴스 수준 보호 설정은 그룹의 소유자가 재정의할 수 있습니다. GitLab Premium 또는 Ultimate에서, GitLab 관리자가 그룹당으로 이 설정을 잠금으로 설정할 수 있습니다.

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
2. 설정 > 리포지터리를 선택합니다.
3. 기본 브랜치를 확장합니다.
4. 초기 기본 브랜치 보호를 선택합니다.
5. 변경사항 저장을 선택합니다.

리포지터리의 기본 브랜치 이름 변경

기존 리포지터리의 기본 브랜치 이름을 변경할 때는 새로운 브랜치를 만드는 대신 브랜치의 이름을 변경하여 기본 브랜치의 이력을 보존해야 합니다. 다음 예제는 Git 리포지터리의 (example) 기본 브랜치의 이름을 바꾸는 방법을 보여줍니다.

1. 로컬 명령줄에서 example 리포지터리로 이동하고 기본 브랜치에 있는지 확인하세요:

   cd example
   git checkout master
   

2. 기존 기본 브랜치의 이름을 새 이름 (main)으로 변경합니다. -m 인수는 모든 커밋 이력을 새 브랜치로 이전합니다:

   git branch -m master main
   

3. 새로 만든 main 브랜치를 원격으로 푸시하고 로컬 브랜치를 동일한 이름의 원격 브랜치를 추적하도록 설정합니다:

   git push -u origin main
   

4. 이전 기본 브랜치를 제거할 계획이라면 HEAD를 새로운 기본 브랜치인 main을 가리키도록 업데이트합니다:

   git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
   

5. Maintainer 이상의 권한을 가진 계정으로 GitLab에 로그인하고 프로젝트의 기본 브랜치를 변경하는 지침을 따릅니다. main을 새로운 기본 브랜치로 선택합니다.
6. 새로운 main 브랜치를 보호된 브랜치 설명서에 설명된 대로 보호합니다.
7. 선택 사항. 기존 기본 브랜치를 삭제하려는 경우:
   1. 해당 브랜치를 가리키는 것이 없는지 확인합니다.

   2. 원격에서 브랜치를 삭제합니다:

      git push origin --delete master
      

      새로운 기본 브랜치가 제대로 작동하는 것을 확인한 후 나중에 브랜치를 삭제할 수 있습니다.

8. 이 변경 사항을 프로젝트 기여자에게 알립니다. 이들은 몇 가지 단계를 수행해야 합니다:

   • 기여자는 새 기본 브랜치를 자신의 로컬 리포지터리로 가져와야 합니다.
   • 이전 기본 브랜치를 대상으로 하는 열린 Merge Request이 있는 기여자는 해당 Merge Request을 매뉴얼으로 main을 사용하도록 다시 지정해야 합니다.
9. 리포지터리에서 코드에서 이전 브랜치 이름에 대한 참조를 업데이트하세요.
10. 도우미 유틸리티 및 통합과 같이 리포지터리 외부에 있는 관련 코드 및 스크립트에서 이전 브랜치 이름에 대한 참조를 업데이트하세요.

기본 브랜치 이름 변경 리다이렉트

프로젝트의 특정 파일 또는 디렉터리에 대한 URL은 프로젝트의 기본 브랜치 이름을 포함하며, 종종 문서나 브라우저 즐겨찾기에 나타납니다. 리포지터리의 기본 브랜치 이름을 업데이트하면 이러한 URL이 변경되어 업데이트해야 합니다.

이전 기본 브랜치를 삭제한 경우 GitLab은 프로젝트의 기본 브랜치가 변경될 때 기간을 짧게하는 데 도움이 되도록 기존 기본 브랜치의 이름을 기록합니다. 해당 브랜치가 삭제된 경우 “찾을 수 없음” 페이지가 표시되는 대신 파일이나 디렉터리를 보려고 하면 현재 기본 브랜치로 리디렉션됩니다.

관련 주제

• 위키의 기본 브랜치 설정 구성
• Git 메일링 리스트에서의 기본 브랜치 이름 변경에 대한 토론
• 2021년 3월 블로그 글: 새로운 Git 기본 브랜치 이름

문제 해결

기본 브랜치를 변경할 수 없음: 현재 브랜치로 재설정함

이 문제는 이슈 20474에서 추적 중입니다. 이 문제는 리포지터리에 HEAD라는 이름의 브랜치가 있는 경우에 발생하는 경우가 많습니다. 문제를 해결하려면 다음을 수행하세요:

1. 로컬 리포지터리에서 새로운 임시 브랜치를 만들고 푸시합니다:

   git checkout -b tmp_default && git push -u origin tmp_default
   

2. GitLab에서 기본 브랜치를 변경하여 해당 임시 브랜치로 이동합니다.

3. 로컬 리포지터리에서 HEAD 브랜치를 삭제합니다:

   git push -d origin HEAD
   

4. GitLab에서 기본 브랜치를 변경하여 사용할 의도의 브랜치로 변경합니다.

GraphQL을 사용하여 기본 브랜치 쿼리

GraphQL 쿼리를 사용하여 그룹 내 모든 프로젝트의 기본 브랜치를 검색할 수 있습니다.

결과의 첫 페이지를 반환하려면 GROUPNAME을 그룹의 전체 경로로 바꿉니다. GitLab은 결과의 첫 페이지를 반환합니다. hasNextPage가 true인 경우 after: null을 endCursor의 값으로 교체하여 다음 페이지를 요청할 수 있습니다:

{
 group(fullPath: "GROUPNAME") {
   projects(after: null) {
     pageInfo {
       hasNextPage
       endCursor
     }
     nodes {
       name
       repository {
         rootRef
       }
     }
   }
 }
}