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

기본 브랜치

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

• 삭제할 수 없습니다.
• 최초로 보호됨으로 강제 푸시에 대해 보호됩니다.
• 병합 요청에서 이슈를 닫기 위해 이슈 닫는 패턴을 사용하면 해당 작업이 이 브랜치로 통합됩니다.

새 프로젝트의 기본 브랜치 이름은 GitLab 관리자가 만든 인스턴스 수준 또는 그룹 수준 구성 변경에 따라 달라집니다. GitLab은 먼저 특정 사용자 정의를 확인한 다음 보다 넓은 수준에서 확인하여 사용자 정의가 없으면 GitLab 기본값을 사용합니다.

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

GitLab UI에서 언제든지 기본값을 변경할 수 있습니다. 또한 GitLab은 리포지토리의 기본 브랜치 이름을 업데이트하는 데 필요한 Git 명령을 제공합니다.

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

필수 조건:

• 프로젝트에 대한 소유자 또는 관리자 역할이 있어야 합니다.

개별 프로젝트의 기본 브랜치를 업데이트하려면 다음 단계를 수행합니다:

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

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

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

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

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

GitLab의 자체 관리 인스턴스 관리자는 해당 인스턴스에 호스팅된 프로젝트의 초기 브랜치를 사용자 정의할 수 있습니다. 개별 그룹 및 서브그룹은 이 인스턴스 전체 설정을 무시할 수 있습니다.

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

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

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

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

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

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

초기 기본 브랜치 보호

• GitLab 16.0에서 최초 푸시 후 완전 보호가 소개됨.

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

• 완전 보호 - 기본값. 개발자는 새 커밋을 푸시할 수 없지만 유지자는 가능합니다. 강제 푸시가 불가능합니다.
• 최초 푸시 후 완전 보호 - 개발자는 저장소에 초기 커밋을 푸시할 수 있지만 그 후에는 더 이상 할 수 없습니다. 유지자는 항상 푸시할 수 있습니다. 강제 푸시가 불가능합니다.
• 푸시에 대한 보호 - 개발자는 새 커밋을 푸시할 수 없지만 해당 브랜치로의 병합 요청을 수락하는 것은 허용됩니다. 유지자는 브랜치로 푸시할 수 있습니다.
• 부분적으로 보호 - 개발자와 유지자 둘 다 새 커밋을 푸시할 수 있지만 강제 푸시는 불가능합니다.
• 보호하지 않음 - 개발자와 유지자 둘 다 새 커밋을 푸시하고 강제 푸시할 수 있습니다.

경고: 완전 보호를 선택하지 않는 경우 악의적인 개발자가 민감한 데이터를 탈취하려는 시도가 있을 수 있습니다. 예를 들어, 보호된 브랜치에 악성 .gitlab-ci.yml 파일을 커밋하고 나중에 해당 브랜치에 대해 파이프라인이 실행되면 그룹 CI/CD 변수의 유출로 이어질 수 있습니다.

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

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

• 저장소의 브랜치 보호 구성.
• 그룹용 브랜치 보호 구성.

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

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

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

기본 브랜치의 인스턴스 수준 보호는 그룹 소유자가 그룹별로 재정의할 수 있습니다. GitLab Premium 또는 Ultimate에서, GitLab 관리자는 그룹 소유자가 이 권한을 해제하도록 설정하여 인스턴스 수준 보호 규칙을 강제할 수 있습니다:

1. 왼쪽 사이드바에서 가장 아래에서 Admin을 선택합니다.
2. Settings > Repository를 선택합니다.
3. 기본 브랜치 섹션을 확장합니다.
4. 그룹별로 기본 브랜치 보호를 관리할 수 있는 권한 부여 확인란을 선택 해제합니다.
5. 변경 사항 저장을 선택합니다.

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

그룹 수준 기본 브랜치 보호

기본 브랜치의 인스턴스 수준 보호는 그룹 소유자가 그룹별로 재정의할 수 있습니다. GitLab Premium 또는 Ultimate에서, GitLab 관리자는 초기 기본 브랜치 보호 강화를 할 수 있습니다. 이렇게 하면 이 설정이 그룹 소유자에 대해 잠겨집니다.

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

리파지토리의 기본 브랜치 이름 업데이트

경고: 기본 브랜치의 이름을 변경하면 테스트, CI/CD 구성, 서비스, 도우미 유틸리티 및 리파지토리가 사용하는 모든 연동이 손상될 수 있습니다. 브랜치 이름을 변경하기 전에 프로젝트 소유자 및 유지 관리자와 협의하세요. 이 변경의 범위에 이전 브랜치 이름에 대한 참조와 스크립트도 포함되어 있는지 확인하세요.

기존 리파지토리의 기본 브랜치 이름을 변경할 때, 새로운 브랜치를 생성하는 것이 아니라 리파지토리의 기본 브랜치 이름을 변경하여 기본 브랜치의 이력을 보존해야 합니다. 다음은 Git 리파지토리(example)의 기본 브랜치 이름을 변경하는 예입니다.

1. 로컬 명령줄에서 example 리파지토리로 이동하고, 기본 브랜치에 있는지 확인합니다:

   cd example
   git checkout master
   

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

   git branch -m master main
   

3. 새로 생성된 main 브랜치를 upstream으로 밀고, 로컬 브랜치를 동일한 이름의 원격 브랜치를 추적하도록 설정합니다:

   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은 이전 기본 브랜치의 이름을 기록합니다. 해당 브랜치가 삭제되면 해당 브랜치의 파일이나 디렉터리를 보는 시도가 “찾을 수 없음” 페이지를 표시하는 대신 현재 기본 브랜치로 리디렉션됩니다.

관련 주제

• 위키의 기본 브랜치 구성
• 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
        }
      }
    }
  }
}

하위 그룹은 상위 그룹의 기본 브랜치 이름을 상속받지 않습니다

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

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