기본 브랜치

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

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

  • 삭제할 수 없습니다.
  • 처음에는 강제 푸시에 대해 보호됩니다.
  • Merge Request이 이슈를 닫는 패턴을 사용하여 작업을 Merge하면 해당 브랜치에 Merge됩니다.

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

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

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

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

전제 조건:

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

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

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

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

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

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

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

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated
  • GitLab 13.2에서 도입. 기본적으로 global_default_branch_name이라는 플래그로 활성화됨.
  • GitLab 13.12에서 일반적으로 이용 가능함. 피처 플래그 global_default_branch_name이 제거됨.

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

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

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

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

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

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

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

초기 기본 브랜치 보호

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
  • 최초 푸시 이후 완전한 보호 도입. GitLab 16.0에서.

GitLab 관리자 및 그룹 소유자는 브랜치 보호를 정의하여 모든 리포지터리의 기본 브랜치에 적용할 수 있습니다. 이 옵션은 인스턴스 수준 및 그룹 수준에서 다음과 같이 하나를 선택합니다:

  • 완전 보호 - 기본값입니다. 개발자는 새 커밋을 푸시할 수 없지만, 유지자는 할 수 있습니다. 강제 푸시를 할 수 없습니다.
  • 최초 푸시 이후 완전 보호 - 개발자는 리포지터리에 처음 커밋을 푸시할 수 있지만 그 후에는 더 이상 할 수 없습니다. 유지자는 항상 푸시할 수 있습니다. 강제 푸시를 할 수 없습니다.
  • 푸시에 대해 보호됨 - 개발자는 새 커밋을 푸시할 수 없지만 Merge Request을 해당 브랜치에 수락할 수 있습니다. 유지자는 브랜치에 푸시할 수 있습니다.
  • 부분적으로 보호됨 - 개발자와 유지자 모두 새 커밋을 푸시할 수 있지만 강제 푸시할 수 없습니다.
  • 보호되지 않음 - 개발자와 유지자 모두 새 커밋을 푸시할 수 있고 강제 푸시할 수 있습니다.
caution
완전 보호를 선택하지 않으면 악의적인 개발자가 민감한 데이터를 탈취하려고 시도할 수 있습니다. 예를 들어, 악의적인 .gitlab-ci.yml 파일이 보호된 브랜치에 커밋되고 나중에 해당 브랜치에 대한 파이프라인이 실행되면, 그룹 CI/CD 변수의 유출로 이어질 수 있습니다.

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

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

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

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

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

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

Tier: Premium, Ultimate Offering: Self-managed, GitLab Dedicated

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

  1. 왼쪽 사이드바에서 맨 아래에서 관리 영역을 선택합니다.
  2. 설정 > 리포지터리를 선택합니다.
  3. 기본 브랜치 섹션을 확장합니다.
  4. 그룹별 기본 브랜치 보호 관리 허용 확인란을 해제합니다.
  5. 변경 사항 저장을 선택합니다.
note
GitLab 관리자는 여전히 그룹의 기본 브랜치 보호를 업데이트할 수 있습니다.

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

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
  • GitLab 12.9에서 도입되었습니다.
  • GitLab 14.9에서 설정이 이동되고 이름이 변경되었습니다.

기본 브랜치에 대한 인스턴스 수준 보호 규칙은 그룹 소유자가 그룹별로 재정의할 수 있습니다. GitLab Premium 또는 Ultimate에서 GitLab 관리자는 그룹 소유자에 대한 이 설정을 잠금 처리하는 초기 기본 브랜치의 보호 강제 적용을 할 수 있습니다.

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

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

caution
기본 브랜치의 이름을 변경하면 테스트, CI/CD 구성, 서비스, 헬퍼 유틸리티 및 리포지터리에서 사용하는 모든 통합에 영향을 줄 수 있습니다. 이 브랜치 이름을 변경하기 전에 프로젝트 소유자 및 유지 관리자와 상의하십시오. 이 변경 사항이 관련 코드 및 스크립트에서 이전 브랜치 이름에 대한 참조를 포함한다는 범위를 파악하세요.

기존 리포지터리의 기본 브랜치 이름을 변경할 때는 새 브랜치를 생성하는 대신 기본 브랜치의 히스토리를 보존해야 합니다. 다음은 Git 리포지터리의 (example) 기본 브랜치 이름을 main으로 변경하는 예시입니다.

  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이 있는 기여자는 매뉴얼으로 main을 사용하도록 Merge Request을 다시 지정해야 합니다.
  9. 코드에서 이전 브랜치 이름에 대한 참조를 업데이트하세요.
  10. 리포지터리 외부에 있는 관련 코드와 스크립트(헬퍼 유틸리티 및 통합 등)에서 이전 브랜치 이름에 대한 참조를 업데이트하세요.

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

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

전환이 원활하도록 프로젝트의 기본 브랜치가 변경될 때마다 GitLab은 이전 기본 브랜치 이름을 기록합니다. 그 브랜치가 삭제되면 해당하는 파일이나 디렉터리를 보기 위한 시도가 “찾을 수 없음” 페이지 대신에 현재 기본 브랜치로 리디렉션됩니다.

관련 주제

문제 해결

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

이 문제를 이슈 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
       }
     }
   }
 }
}