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

• 삭제할 수 없습니다.
• 강제 푸시에 대해 초기에 보호됩니다.
• 머지 리퀘스트가 이슈 자동 종료 패턴을 사용하여 이슈를 종료할 때 작업이 이 브랜치에 병합됩니다.

새 프로젝트의 기본 브랜치 이름은 GitLab 관리자가 인스턴스 또는 그룹에 적용한 구성 변경 사항에 따라 달라집니다. GitLab은 먼저 특정 커스터마이즈를 확인한 다음 더 넓은 수준에서 확인하며, 커스터마이즈가 설정되지 않은 경우에만 GitLab 기본값을 사용합니다:

1. 프로젝트별 커스텀 기본 브랜치 이름.
2. 프로젝트의 직접 하위 그룹에 지정된 커스텀 그룹 기본 브랜치 이름.
3. 프로젝트의 최상위 그룹에 지정된 커스텀 그룹 기본 브랜치 이름.
4. 인스턴스에 설정된 커스텀 기본 브랜치 이름.
5. 어느 수준에서도 커스텀 기본 브랜치 이름이 설정되지 않은 경우 GitLab은 기본적으로 main을 사용합니다.

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

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

사전 요구 사항:

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

개별 프로젝트의 기본 브랜치를 업데이트하려면:

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

projects 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 - 기본값. 개발자는 새 커밋을 푸시할 수 없지만 메인테이너는 가능합니다. 아무도 강제 푸시할 수 없습니다.
• Fully protected after initial push - 개발자는 리포지터리에 초기 커밋을 푸시할 수 있지만 그 이후에는 불가능합니다. 메인테이너는 항상 푸시할 수 있습니다. 아무도 강제 푸시할 수 없습니다.
• Protected against pushes - 개발자는 새 커밋을 푸시할 수 없지만 브랜치에 대한 머지 리퀘스트를 수락할 수 있습니다. 메인테이너는 브랜치에 푸시할 수 있습니다.
• Partially protected - 개발자와 메인테이너 모두 새 커밋을 푸시할 수 있지만 강제 푸시는 불가능합니다.
• Not protected - 개발자와 메인테이너 모두 새 커밋을 푸시하고 강제 푸시할 수 있습니다.

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

이 설정은 각 리포지터리의 기본 브랜치에만 적용됩니다. 다른 브랜치를 보호하려면:

• 리포지터리에서 브랜치 보호를 구성하세요.
• 그룹에 대한 브랜치 보호를 구성하세요.

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이 변경되어 업데이트해야 합니다.

전환 기간을 쉽게 하기 위해 프로젝트의 기본 브랜치가 변경될 때마다 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의 null을 endCursor 값으로 대체하여 다음 페이지를 요청할 수 있습니다:

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

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

다른 하위 그룹을 포함하는 하위 그룹에 기본 브랜치를 구성한 경우 프로젝트가 포함된 하위 그룹에서 기본 브랜치가 상속되지 않습니다.

이 문제는 이슈 327208에서 추적 중입니다.