새 프로젝트를 생성하면 GitLab 이 리포지터리에 기본 브랜치를 만듭니다. 기본 브랜치에는 다른 브랜치에 없는 특별한 구성 옵션이 적용됩니다.

• 삭제할 수 없습니다.
• 강제 푸시에 대해 초기에 보호되어 있습니다.
• 머지 리퀘스트가 이슈 종료 패턴으로 이슈를 닫을 때, 작업 내용이 이 브랜치에 머지됩니다.

새 프로젝트의 기본 브랜치 이름은 GitLab 관리자가 인스턴스나 그룹에 적용한 구성 변경에 따라 달라집니다. GitLab은 먼저 구체적인 사용자 지정 값을 확인한 다음 더 넓은 범위를 확인하며, 사용자 지정 값이 전혀 없을 때만 GitLab 기본값을 사용합니다.

1. 프로젝트별 사용자 지정 기본 브랜치 이름.
2. 프로젝트가 속한 직계 하위 그룹에 지정된 사용자 지정 그룹 기본 브랜치 이름.
3. 프로젝트가 속한 최상위 그룹에 지정된 사용자 지정 그룹 기본 브랜치 이름.
4. 인스턴스에 설정된 사용자 지정 기본 브랜치 이름.
5. 어느 수준에도 사용자 지정 기본 브랜치 이름이 없으면 GitLab은 main을 사용합니다.

GitLab UI에서는 모든 수준의 기본값을 변경할 수 있습니다. 또한 GitLab은 리포지터리 사본을 갱신하는 데 필요한 Git 명령도 제공합니다.

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

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

개별 프로젝트의 기본 브랜치를 변경하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Branch defaults를 확장합니다. Default branch에서 새 기본 브랜치를 선택합니다.
4. 선택 사항. 머지 리퀘스트가 종료 패턴을 사용할 때 이슈를 닫으려면 Auto-close referenced issues on default branch 체크박스를 선택합니다.
5. Save changes를 선택합니다.

프로젝트 API의 default_branch 속성을 사용할 수도 있습니다. API로 프로젝트를 생성하면서 initialize_with_readme를 true로 설정하면, default_branch 파라미터를 다음 두 가지 형태로 지정할 수 있습니다.

• 브랜치 이름. 예를 들어 main 입니다.
• 정규화된 참조. 예를 들어 refs/heads/main 입니다.

정규화된 참조를 지정하면 API가 refs/heads/ 접두사를 제거합니다.

인스턴스에서 새 프로젝트의 기본 브랜치 이름 변경#

GitLab Self-Managed의 관리자는 해당 인스턴스에 호스팅된 프로젝트의 초기 브랜치를 사용자 지정할 수 있습니다. 개별 그룹과 하위 그룹은 자기 프로젝트에 대해 인스턴스 기본값을 재정의할 수 있습니다.

1. 오른쪽 위에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Default branch를 확장합니다.
4. Initial default branch name에서 새 기본 브랜치를 선택합니다.
5. Save changes를 선택합니다.

설정을 변경한 뒤 이 인스턴스에서 생성되는 프로젝트는 그룹이나 하위 그룹 구성이 재정의하지 않는 한 사용자 지정 브랜치 이름을 사용합니다.

그룹에서 새 프로젝트의 기본 브랜치 이름 변경#

사전 요구 사항:

• 그룹과 하위 그룹에 대한 Owner 권한이 있어야 합니다.

그룹에서 새 프로젝트의 기본 브랜치 이름을 변경하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Default branch를 확장합니다.
4. Initial default branch name에서 새 기본 브랜치를 선택합니다.
5. Save changes를 선택합니다.

설정을 변경한 뒤 이 그룹에서 생성되는 프로젝트는 하위 그룹 구성이 재정의하지 않는 한 사용자 지정 브랜치 이름을 사용합니다.

초기 기본 브랜치 보호#

GitLab 관리자와 그룹 Owner는 인스턴스 전체 또는 개별 그룹의 모든 리포지터리 기본 브랜치에 적용할 브랜치 보호를 다음 옵션 중 하나로 정의할 수 있습니다.

• Fully protected - 기본값입니다. Developer는 새 커밋을 푸시할 수 없지만 Maintainer는 푸시할 수 있습니다. 강제 푸시는 누구도 할 수 없습니다.
• Fully protected after initial push - Developer는 리포지터리에 최초 커밋을 푸시할 수 있지만 이후에는 푸시할 수 없습니다. Maintainer는 언제든 푸시할 수 있습니다. 강제 푸시는 누구도 할 수 없습니다.
• Protected against pushes - Developer는 새 커밋을 푸시할 수 없지만 해당 브랜치로의 머지 리퀘스트를 수락할 수는 있습니다. Maintainer는 브랜치에 푸시할 수 있습니다.
• Partially protected - Developer와 Maintainer 모두 새 커밋을 푸시할 수 있지만 강제 푸시는 할 수 없습니다.
• Not protected - Developer와 Maintainer 모두 새 커밋을 푸시하고 강제 푸시도 할 수 있습니다.

인스턴스의 모든 프로젝트에 대해#

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

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

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

1. 오른쪽 위에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Default branch를 확장합니다.
4. Initial default branch protection을 선택합니다.
5. 그룹 Owner가 인스턴스의 기본 브랜치 보호를 재정의할 수 있도록 하려면 Allow owners to manage default branch protection per group을 선택합니다.
6. Save changes를 선택합니다.

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

그룹 Owner는 인스턴스 전체에 설정된 기본 브랜치 보호를 그룹 단위로 재정의할 수 있습니다. GitLab Premium 또는 Ultimate에서는 GitLab 관리자가 그룹 Owner의 이 권한을 비활성화해 인스턴스에 설정된 보호 규칙을 강제할 수 있습니다.

1. 오른쪽 위에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Default branch 섹션을 확장합니다.
4. Allow owners to manage default branch protection per group 체크박스를 해제합니다.
5. Save changes를 선택합니다.

그룹의 모든 프로젝트에 대해#

그룹 Owner는 인스턴스 전체에 설정된 기본 브랜치 보호를 그룹 단위로 재정의할 수 있습니다. GitLab Premium 또는 Ultimate에서는 GitLab 관리자가 초기 기본 브랜치 보호를 강제할 수 있으며, 이 경우 그룹 Owner에게는 이 설정이 잠깁니다.

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Default branch를 확장합니다.
4. Initial default branch protection을 선택합니다.
5. Save changes를 선택합니다.

리포지터리의 기본 브랜치 이름 업데이트#

기존 리포지터리의 기본 브랜치 이름을 변경할 때는 새 브랜치를 만들지 않습니다. 이름을 변경해 기본 브랜치의 히스토리를 유지합니다. 다음 예시는 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. 프로젝트 기여자도 몇 가지 조치를 해야 하므로 이 변경 사항을 알립니다.

   • 기여자는 새 기본 브랜치를 리포지터리의 로컬 사본으로 가져와야 합니다.
   • 이전 기본 브랜치를 대상으로 하는 머지 리퀘스트가 열려 있는 기여자는 해당 머지 리퀘스트가 main을 사용하도록 직접 다시 지정해야 합니다.

9. 리포지터리에서 코드에 남아 있는 이전 브랜치 이름 참조를 갱신합니다.

10. 헬퍼 유틸리티나 통합 기능처럼 리포지터리 외부에 있는 관련 코드와 스크립트의 이전 브랜치 이름 참조도 갱신합니다.

기본 브랜치 이름 변경 리디렉션#

프로젝트의 특정 파일이나 디렉터리 URL에는 프로젝트의 기본 브랜치 이름이 포함되며, 이런 URL은 문서나 브라우저 북마크에 자주 남습니다. 리포지터리의 기본 브랜치 이름을 업데이트하면 이 URL 이 바뀌므로 함께 갱신해야 합니다.

전환 기간의 부담을 줄이기 위해, 프로젝트의 기본 브랜치가 변경될 때마다 GitLab은 이전 기본 브랜치 이름을 기록합니다. 해당 브랜치가 삭제된 뒤 그 브랜치의 파일이나 디렉터리를 보려고 하면 "not found" 페이지 대신 현재 기본 브랜치로 리디렉션됩니다.

관련 주제#

• 위키의 기본 브랜치 구성
• 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의 null을 endCursor 값으로 바꿔 다음 페이지를 요청할 수 있습니다.

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

새 하위 그룹이 상위 수준 하위 그룹에서 기본 브랜치 이름을 상속하지 않음#

프로젝트를 포함한 다른 하위 그룹이 들어 있는 하위 그룹에 기본 브랜치를 구성하면, 그 기본 브랜치가 상속되지 않습니다.

이 문제는 이슈 327208에서 추적하고 있습니다.