• 프로젝트에 대한 기본 브랜치 이름 변경
• 인스턴스 또는 그룹에 대한 기본 브랜치 이름 변경
  • 인스턴스 수준 사용자 정의 초기 브랜치 이름
  • 그룹 수준의 사용자 정의 초기 브랜치 이름
• 초기 기본 브랜치 보호
  • 인스턴스 수준 기본 브랜치 보호
    • 기본 브랜치 보호의 덮어쓰기를 방지
  • 그룹 수준의 기본 브랜치 보호
• 리포지토리에서 기본 브랜치 이름 업데이트
• 기본 브랜치 이름 변경 리디렉션
• 관련 주제
• 문제 해결
  • 기본 브랜치를 변경할 수 없음: 현재 브랜치로 리셋됨
  • 기본 브랜치에 대한 GraphQL 쿼리
  • 새로운 하위 그룹이 상위 하위 그룹에서 기본 브랜치 이름을 상속받지 않음

기본 브랜치

새로운 프로젝트를 생성하면 GitLab은 저장소에 기본 브랜치를 생성합니다. 기본 브랜치는 다른 브랜치와 공유되지 않는 특별한 구성 옵션을 가지고 있습니다:

• 삭제할 수 없습니다.
• 강제로 푸시되는 것을 초기적으로 보호합니다.
• 병합 요청이 이슈 닫기 패턴을 사용하여 이슈를 닫으면, 작업이 이 브랜치에 병합됩니다.

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

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

GitLab UI에서 사용자는 어느 수준에서든 기본값을 변경할 수 있습니다. GitLab은 또한 저장소 복사본을 업데이트하는 데 필요한 Git 명령어를 제공합니다.

프로젝트에 대한 기본 브랜치 이름 변경

사전 요구 사항:

• 해당 프로젝트의 소유자 또는 유지 관리자 역할을 가지고 있습니다.

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

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 설정 > 저장소를 선택합니다.
3. 브랜치 기본값을 확장합니다. 기본 브랜치에서 새 기본 브랜치를 선택합니다.
4. 선택 사항. 기본 브랜치에서 참조된 이슈 자동 닫기 체크박스를 선택하여 병합 요청이 닫기 패턴을 사용할 때 이슈를 닫습니다.
5. 변경 사항 저장을 선택합니다.

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

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

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

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

GitLab 관리자들은 해당 인스턴스에서 호스팅되는 프로젝트의 초기 브랜치를 사용자 정의할 수 있습니다. 개별 그룹과 하위 그룹은 자신의 프로젝트에 대해 이 인스턴스 전체 설정을 재정의할 수 있습니다.

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

설정을 변경한 후 이 인스턴스에서 생성된 프로젝트는 사용자 정의 브랜치 이름을 사용하며, 그룹 수준 또는 하위 그룹 수준의 구성이 이를 재정의하지 않는 한 그대로 적용됩니다.

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

그룹 및 하위 그룹의 소유자 역할을 가진 사용자는 그룹의 기본 브랜치 이름을 구성할 수 있습니다:

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

설정을 변경한 후 이 그룹에서 생성된 프로젝트는 사용자 지정 브랜치 이름을 사용합니다,

하위 그룹 구성이 이를 덮어쓰지 않는 한.

초기 기본 브랜치 보호

Offering: GitLab.com, Self-managed, GitLab Dedicated

• 초기 푸쉬 이후의 전체 보호가 소개됨 GitLab 16.0에서.

GitLab 관리자는 그룹 소유자가 모든 리포지토리의 기본 브랜치에 적용할 브랜치 보호를 정의할 수 있습니다.

인스턴스 수준 및 그룹 수준의 다음 옵션 중 하나로:

• 완전 보호 - 기본값. 개발자는 새 커밋을 푸쉬할 수 없지만, 관리자는 가능합니다. 아무도 강제 푸시할 수 없습니다.
• 초기 푸시 이후 완전 보호 - 개발자는 리포지토리에 초기 커밋을 푸쉬할 수 있지만, 이후에는 불가능합니다. 관리자는 항상 푸시할 수 있습니다. 아무도 강제 푸시할 수 없습니다.
• 푸쉬에 대한 보호 - 개발자는 새 커밋을 푸쉬할 수 없지만, 브랜치에 대한 병합 요청을 수락할 수 있습니다. 관리자는 브랜치에 푸시할 수 있습니다.
• 부분적으로 보호 - 개발자와 관리자가 모두 새 커밋을 푸쉬할 수 있지만, 강제 푸시할 수 없습니다.
• 보호 없음 - 개발자와 관리자가 모두 새 커밋을 푸쉬하고 강제 푸시할 수 있습니다.

경고:

완전 보호가 선택되지 않는 한, 악의적인 개발자가 귀하의 민감한 데이터를 훔치려 할 수 있습니다. 예를 들어, 악의적인 .gitlab-ci.yml 파일이 보호된 브랜치에 커밋될 수 있으며, 나중에 해당 브랜치에서 파이프라인이 실행되면 그룹 CI/CD 변수가 유출될 수 있습니다.

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

Offering: Self-managed, GitLab Dedicated

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

• 리포지토리에서 브랜치 보호 구성.
• 그룹에 대한 브랜치 보호 구성.

자체 관리 인스턴스의 관리자는 해당 인스턴스에서 호스팅된 프로젝트에 대한 초기 기본 브랜치 보호를 사용자 정의할 수 있습니다. 개별 그룹 및 하위 그룹은 프로젝트에 대한 이 인스턴스 전체 설정을 덮어쓸 수 있습니다.

1. 왼쪽 사이드바에서 가장 아래에서 Admin을 선택합니다.
2. Settings > Repository를 선택합니다.
3. Default branch를 확장합니다.
4. Initial default branch protection를 선택합니다.
5. 그룹 소유자가 인스턴스의 기본 브랜치 보호를 덮어쓸 수 있도록 하려면, Allow owners to manage default branch protection per group를 선택합니다.
6. Save changes를 선택합니다.

기본 브랜치 보호의 덮어쓰기를 방지

Offering: Self-managed, GitLab Dedicated

기본 브랜치에 대한 인스턴스 수준 보호는 그룹 소유자가 그룹별로 덮어쓸 수 있습니다. GitLab Premium 또는 Ultimate에서는 GitLab 관리자가 그룹 소유자에 대한 이 권한을 비활성화하여 인스턴스 수준 보호 규칙을 시행할 수 있습니다:

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

참고:

GitLab 관리자는 여전히 그룹의 기본 브랜치 보호를 업데이트할 수 있습니다.

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

인스턴스 수준의 기본 브랜치 보호는 그룹 소유자가 그룹별로 재정의할 수 있습니다.
GitLab Premium 또는 Ultimate에서는 GitLab 관리자가
초기 기본 브랜치 보호를 시행할 수 있으며,
이 설정이 그룹 소유자에게 잠겨 있습니다.

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

리포지토리에서 기본 브랜치 이름 업데이트

경고:
기본 브랜치의 이름을 변경하면 테스트, CI/CD 구성, 서비스, 도우미 유틸리티 및 리포지토리가 사용하는 모든 통합에 잠재적으로 문제가 발생할 수 있습니다. 이 브랜치 이름을 변경하기 전에 프로젝트 소유자 및 유지 관리와 상담하세요.
그들이 이 변경의 범위가 관련된 코드 및 스크립트에서 이전 브랜치 이름에 대한 참조를 포함한다는 것을 이해해야 합니다.

기존 리포지토리에 대해 기본 브랜치 이름을 변경할 때는
새로운 브랜치를 만드는 대신 이름을 바꿔서 기본 브랜치의 기록을 보존해야 합니다.
이 예제는 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. 최소한 유지 관리자인 역할로 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에서 이 문제를 추적하고 있습니다.