기본 브랜치

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

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

  • 삭제할 수 없습니다.
  • 최초에는 강제 푸시에 대해 보호됩니다.
  • 병합 요청이 이 브랜치에서 작업을 병합하는 등 이슈 종료 패턴을 사용할 때 해당 작업이 병합됩니다.

새 프로젝트의 기본 브랜치 이름은 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. 선택 사항. 기본 브랜치에서 참조된 이슈 자동으로 닫기 확인란을 선택하여 병합 요청에서 종료 패턴을 사용하여 이슈를 닫습니다.
  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 제거됨.

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

  1. 왼쪽 사이드바에서 아래로 스크롤하여 관리 영역을 선택합니다.
  2. 설정 > 저장소를 선택합니다.
  3. 기본 브랜치를 확장합니다.
  4. 최초 기본 브랜치 이름에서 새 기본 브랜치를 선택합니다.
  5. 변경 사항 저장을 선택합니다.

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

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

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

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

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

초기 기본 브랜치 보호

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

GitLab 관리자 및 그룹 소유자는 인스턴스 수준 및 그룹 수준에서 각 저장소의 기본 브랜치에 적용할 브랜치 보호를 정의할 수 있습니다. 다음 옵션 중 하나를 선택할 수 있습니다:

  • 전체 보호 - 기본값입니다. 개발자는 새 커밋을 푸시할 수 없지만 유지자는 할 수 있습니다. 강제 푸시는 누구도 할 수 없습니다.
  • 초기 푸시 후 전체 보호 - 개발자는 저장소에 초기 커밋을 푸시할 수 있지만 그 후로는 누구도 할 수 없습니다. 유지자는 항상 푸시할 수 있습니다. 강제 푸시는 누구도 할 수 없습니다.
  • 푸시에 대한 보호 - 개발자는 새 커밋을 푸시할 수 없지만 브랜치로의 병합 요청을 허용합니다. 유지자는 브랜치로 푸시할 수 있습니다.
  • 부분적 보호 - 개발자와 유지자 모두 새 커밋을 푸시할 수 있지만 강제 푸시는 할 수 없습니다.
  • 보호되지 않음 - 개발자와 유지자 모두 새 커밋을 푸시하고 강제 푸시할 수 있습니다.

경고: 전체 보호를 선택하지 않은 경우 악의적인 개발자가 민감한 데이터를 탈취하려고 시도할 수 있습니다. 예를 들어, 악의적인 .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. 변경 사항 저장을 선택합니다.

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

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

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

기본 브랜치의 인스턴스 수준 보호는 그룹 소유자에 의해 그룹별로 재정의될 수 있습니다. 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 브랜치를 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을 리포지토리의 기본 브랜치 이름을 업데이트할 때 이들 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
       }
     }
   }
 }
}