브랜치

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

브랜치는 프로젝트의 작업 트리 버전입니다. 새 프로젝트를 만들 때 GitLab는 리포지터리에 대한 기본 브랜치 (삭제할 수 없음)를 생성합니다. 기본 브랜치 설정은 프로젝트, 서브그룹, 그룹 또는 인스턴스 수준에서 구성할 수 있습니다.

프로젝트가 성장함에 따라 팀은 가능한 한 브랜치 네이밍 패턴을 따르는 것이 좋습니다. 각 브랜치는 개발 작업이 병렬로 진행되도록 하여 변경의 모음을 나타냅니다. 하나의 브랜치에서의 개발 작업은 다른 브랜치에 영향을 미치지 않습니다.

브랜치는 프로젝트에서 개발의 기반이 됩니다:

  1. 시작하려면 브랜치를 만들고 커밋을 추가합니다.
  2. 작업이 검토 준비가 되면 Merge Request을 만들어서 브랜치의 변경 사항을 Merge하기를 제안하세요. 이 과정을 간소화하기 위해 브랜치 네이밍 패턴을 따르는 것이 좋습니다.
  3. 리뷰 앱에서 브랜치의 변경 사항을 미리 보세요.
  4. 브랜치의 내용이 Merge된 후에는 Merge된 브랜치를 삭제하세요.

브랜치 생성

전제 조건:

  • 프로젝트에 대해 적어도 개발자 역할을 가지고 있어야 합니다.

GitLab UI에서 새 브랜치를 만들려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. Code > Branches를 선택합니다.
  3. 오른쪽 상단에서 새 브랜치를 선택합니다.
  4. 브랜치 이름을 입력합니다.
  5. Create from에서 브랜치의 기준을 선택합니다: 기존 브랜치, 기존 태그 또는 커밋 SHA.
  6. Create branch를 선택합니다.

빈 프로젝트에서

빈 프로젝트에는 브랜치가 없지만 추가할 수 있습니다.

전제 조건:

  • 프로젝트에 대해 적어도 개발자 역할을 가지고 있어야 합니다.
  • 유지관리자 또는 소유자 역할이 없는 경우, 기본 브랜치 보호 은 기본 브랜치에 커밋을 푸시할 수 있도록 부분적으로 보호 또는 보호하지 않음으로 설정되어 있어야 합니다.

빈 프로젝트에 기본 브랜치를 추가하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 이 프로젝트의 리포지터리는 비어 있음으로 스크롤하고 추가하려는 파일 유형을 선택합니다.
  3. 웹 IDE에서 파일을 원하는 대로 변경한 후 커밋 작성을 선택합니다.
  4. 커밋 메시지를 입력하고 커밋을 선택합니다.

GitLab은 기본 브랜치를 만들고 파일을 추가합니다.

이슈에서

전제 조건:

  • 프로젝트에 대해 적어도 개발자 역할을 가지고 있어야 합니다.

이슈를 보고 있을 때 해당 페이지에서 직접 연결된 브랜치를 만들 수 있습니다. 이 방식으로 만든 브랜치는 변수를 포함한 이슈로부터 브랜치 이름에 대한 기본 패턴을 사용합니다.

전제 조건:

  • 프로젝트에 대해 적어도 개발자 역할을 가지고 있어야 합니다.

이슈에서 브랜치를 만들려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. Plan > Issues을 선택하고 이슈를 찾습니다.
  3. 이슈 설명 아래에서 Merge Request 만들기 드롭다운 디렉터리을 찾아 을 선택하여 드롭다운 디렉터리을 표시합니다.
  4. 브랜치 생성을 선택합니다. 프로젝트의 기본 브랜치를 기준으로, 기본 브랜치 이름이 제공됩니다. 원하는 경우 다른 브랜치 이름을 입력합니다.
  5. 프로젝트의 기본 브랜치를 기준으로 브랜치를 만들기 위해 브랜치 만들기를 선택합니다.

브랜치 관리 및 보호

GitLab은 개별 브랜치를 보호하는 여러 가지 방법을 제공합니다. 이 방법들은 브랜치가 생성될 때부터 삭제될 때까지 감독 및 품질 점검을 받도록 합니다:

  • 프로젝트의 기본 브랜치는 추가적인 보호를 받습니다.
  • 보호된 브랜치를 구성하여 해당 브랜치에 대해 커밋을 푸시하거나 다른 브랜치를 Merge하거나 브랜치 자체를 다른 브랜치에 Merge할 수 있는 사용자를 제한할 수 있습니다.
  • 승인 규칙을 구성하여 브랜치를 Merge하기 전에 보안 관련 승인을 포함한 검토 요구 사항을 설정할 수 있습니다.
  • 상태 확인을 제 3자와 통합해서 브랜치 내용이 사용자의 품질 기준을 충족하는지 확인할 수 있습니다.

브랜치를 관리할 수 있습니다:

모든 브랜치 보기

GitLab 사용자 인터페이스에서 브랜치를 보고 관리하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. Code > Branches를 선택합니다.

이 페이지에서 다음을 할 수 있습니다:

  • 모든 브랜치를 볼 수 있거나 활성 또는 폐기된 브랜치만 볼 수 있습니다.

    커밋이 최근 3개월 내에 이루어진 경우 브랜치는 활성으로 간주됩니다. 그렇지 않으면 폐가된 것으로 간주됩니다.

  • 새 브랜치를 만들 수 있습니다.
  • 브랜치 비교.
  • Merge된 브랜치를 삭제할 수 있습니다.

보호 구성된 브랜치 보기

  • GitLab 15.1에서 branch_rules라는 플래그로 소개됨. 기본적으로 비활성화됨.
  • GitLab 15.10에서 GitLab.com에서 활성화됨.
  • GitLab 15.11에서 Self-managed에서 활성화됨.
Self-managed GitLab의 경우 이 기능은 기본적으로 사용할 수 있습니다. 기능을 숨기려면 관리자가 branch_rules라는 피처 플래그를 비활성화할 수 있습니다. GitLab.com 및 GitLab Dedicated의 경우, 이 기능을 사용할 수 있습니다.

리포지터리의 브랜치는 여러 방법으로 보호할 수 있습니다. 다음을 할 수 있습니다:

  • 누가 브랜치에 푸시할 수 있는지 제한합니다.
  • 누가 브랜치를 Merge할 수 있는지 제한합니다.
  • 모든 변경 사항의 승인을 요구합니다.
  • 외부 테스트가 통과되어야 합니다.

브랜치 규칙 개요 페이지에서 모든 보호된 브랜치와 그 보호 방법을 볼 수 있습니다:

보호된 브랜치 예시

전제 조건:

  • 프로젝트에 대해 적어도 유지관리자 역할을 가지고 있어야 합니다.

브랜치 규칙 개요 디렉터리을 보려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 리포지터리를 선택합니다.
  3. 브랜치 규칙을 확장하여 보호된 브랜치를 모두 볼 수 있습니다.
    • 새 브랜치에 보호를 추가하려면:
      1. 브랜치 규칙 추가를 선택합니다.
      2. 보호된 브랜치 만들기를 선택합니다.
    • 기존 브랜치의 보호 정보를 더 자세히 보려면:
      1. 자세히 알아보려는 브랜치를 식별합니다.
      2. 세부 정보 보기를 선택하여 다음과 관련된 정보를 볼 수 있습니다:

브랜치 이름 지정

Git은 브랜치 이름 규칙을 강제하여 브랜치 이름이 다른 도구와 호환되도록 합니다. GitLab은 브랜치 이름에 추가 요구 사항을 더하고, 잘 구조화된 브랜치 이름에 대한 혜택을 제공합니다.

GitLab은 모든 브랜치에 대해 다음과 같은 추가 규칙을 강제합니다:

  • 브랜치 이름에는 공백이 허용되지 않습니다.
  • 40개의 16진수 문자로 이루어진 브랜치 이름은 Git 커밋 해시와 유사하기 때문에 금지됩니다.
  • 브랜치 이름은 대소문자를 구분합니다.

Docker와 같은 일반 소프트웨어 패키지는 추가적인 브랜치 이름 규정을 강제할 수 있습니다.

다른 소프트웨어 패키지와의 최상의 호환성을 위해 다음만 사용하세요:

  • 숫자
  • 하이픈 (-)
  • 밑줄 (_)
  • ASCII 표준표의 소문자

브랜치 이름에는 슬래시 (/) 및 이모지를 사용할 수 있지만, 다른 소프트웨어 패키지와의 호환성은 보장되지 않을 수 있습니다.

특정 서식의 브랜치 이름은 추가 혜택을 제공합니다:

이슈에서 브랜치 이름의 기본 패턴 구성

기본적으로 GitLab은 이슈에서 브랜치를 생성할 때 패턴 %{id}-%{title}을 사용하지만, 이 패턴을 변경할 수 있습니다.

전제 조건:

  • 프로젝트에 대한 최소한의 Maintainer 역할이 있어야 합니다.

다음을 수행하여 이슈에서 생성된 브랜치의 기본 패턴을 변경합니다:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 리포지터리를 선택합니다.
  3. 브랜치 기본값을 확장합니다.
  4. 브랜치 이름 템플릿으로 스크롤하여 값을 입력합니다. 이 필드는 다음 변수를 지원합니다:
    • %{id}: 이슈의 숫자 ID
    • %{title}: 이슈의 제목을 Git 브랜치 이름에서 허용되는 문자만 사용하도록 수정한 것
  5. 변경 사항 저장을 선택합니다.

이슈 번호로 브랜치 이름에 접두어를 붙이기

Merge Request을 간소화하기 위해 Git 브랜치 이름을 이슈 번호부터 시작하여 하이픈으로 연결합니다. 예를 들어, 이슈 #123에 브랜치를 연결하려면 브랜치 이름을 123-으로 시작합니다.

이슈와 브랜치는 동일한 프로젝트에 있어야 합니다.

GitLab은 이슈 번호를 사용하여 Merge Request으로 데이터를 가져옵니다:

  • 이슈가 Merge Request과 관련되었음을 표시합니다. 이슈와 Merge Request은 서로에 대한 링크를 표시합니다.
  • 브랜치가 이슈와 연결됩니다.
  • 만약 프로젝트가 기본 종료 패턴으로 구성된 경우, Merge Request을 합병하는 것으로 관련된 이슈를 자동으로 닫을 수 있습니다.
  • 이슈 마일스톤 및 레이블이 Merge Request으로 복사됩니다.

브랜치 비교

리포지터리에서 브랜치를 비교하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 코드 > 리비전 비교를 선택합니다.
  3. 원하는 브랜치를 검색할 소스 브랜치를 선택합니다. 정확한 일치는 먼저 표시됩니다. 연산자를 사용하여 검색을 정확히 할 수 있습니다:
    • ^은 브랜치 이름의 시작과 일치합니다: ^feat은 feat/user-authentication과 일치합니다.
    • $은 브랜치 이름의 끝과 일치합니다: widget$은 feat/search-box-widget과 일치합니다.
    • *은 와일드카드를 사용하여 일치합니다: branch*cache*는 fix/branch-search-cache-expiration와 일치합니다.
    • 연산자를 결합할 수 있습니다: ^chore/*migration$은 chore/user-data-migration과 일치합니다.
  4. 대상 리포지터리와 브랜치를 선택합니다. 정확한 일치는 먼저 표시됩니다.
  5. 변경 사항 표시 아래에서 브랜치를 비교할 방법을 선택합니다:
    • 소스에서의 변경 사항만 표시 (기본값)은 최신 공통 커밋부터 소스 브랜치에서 만든 변경 사항을 보여줍니다. 소스 브랜치가 생성된 후 대상 브랜치에 대해 무관한 변경은 포함하지 않습니다. 이 방법은 실제 커밋 대신 Merge 베이스를 사용하므로 체리픽된 커밋에서 변경 사항이 새로운 변경으로 표시됩니다.
    • 대상이 소스가 생성된 이후의 변경 사항 포함은 두 브랜치 간의 모든 차이점을 보여줍니다.
  6. 비교를 선택하여 커밋 디렉터리과 변경된 파일을 표시합니다.
  7. 원하는 경우 소스 및 대상을 반대로 하려면 리비전 바꾸기를 선택합니다 ().

Merge된 브랜치 삭제

다음 기준을 모두 충족하는 경우 Merge된 브랜치를 대량으로 삭제할 수 있습니다:

  • 보호된 브랜치가 아닙니다.
  • 프로젝트의 기본 브랜치에 Merge되었습니다.

전제 조건:

  • 프로젝트에 대한 최소한의 Developer 역할이 있어야 합니다.

다음을 수행합니다:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 코드 > 브랜치를 선택합니다.
  3. 페이지 오른쪽 상단에 있는 더 보기 를 선택합니다.
  4. Merge된 브랜치 삭제를 선택합니다.
  5. 대화상자에서 확인을 위해 단어 delete를 입력한 후 Merge된 브랜치 삭제를 선택합니다.

대상 브랜치용 워크플로 구성

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
  • GitLab 16.4에서 특징으로 도입되었으며, 기본적으로 target_branch_rules_flag이라는 플래그로 활성화되어 있습니다.
  • GitLab 16.7에서 피처 플래그가 제거되었습니다.

일부 프로젝트는 develop 및 qa와 같이 장기 브랜치를 사용하여 개발하는 경우가 있습니다. 이러한 프로젝트에서는 main을 기본 브랜치로 유지할 수 있지만, Merge Request은 develop 또는 qa를 대상으로 할 것으로 예상할 수 있습니다. 대상 브랜치 워크플로는 Merge Request이 프로젝트의 적절한 개발 브랜치를 대상으로하는지 확인하는 데 도움이 됩니다.

Merge Request을 생성할 때 워크플로는 브랜치 이름을 확인합니다. 브랜치 이름이 워크플로와 일치하는 경우 Merge Request은 지정한 브랜치를 대상으로 합니다. 브랜치 이름이 일치하지 않는 경우 Merge Request은 프로젝트의 기본 브랜치를 대상으로 합니다.

규칙은 “첫 일치” 기반으로 처리됩니다. 즉, 두 개의 규칙이 동일한 브랜치 이름과 일치하는 경우 맨 위에 있는 규칙이 적용됩니다.

전제 조건:

  • 최소한의 Maintainer 역할이 있어야 합니다.

대상 브랜치 워크플로를 만들려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > Merge Request를 선택합니다.
  3. Merge Request 브랜치 워크플로로 스크롤합니다.
  4. 브랜치 대상 추가를 선택합니다.
  5. 브랜치 이름 패턴에 브랜치 이름과 일치하는 문자열 또는 와일드카드를 제공합니다.
  6. 대상 브랜치를 선택하여 브랜치 이름 패턴과 일치할 때 사용할 대상 브랜치를 지정합니다.
  7. 저장을 선택합니다.

예시

프로젝트를 다음 대상 브랜치 워크플로를 구성할 수 있습니다.

브랜치 이름 패턴 대상 브랜치
feature/* develop
bug/* develop
release/* main

이러한 대상 브랜치는 다음과 같은 프로젝트의 Merge Request 생성 프로세스를 단순화합니다.

  • main을 애플리케이션의 배포된 상태를 나타내는 데 사용합니다.
  • develop와 같이 현재 릴리스되지 않은 개발 작업을 추적하는 또 다른 장기 러닝 브랜치에 있습니다.

작업흐름이 처음부터 새로운 기능을 main이 아닌 develop에 두는 경우, 이러한 대상 브랜치는 feature/* 또는 bug/*와 일치하는 모든 브랜치가 실수로 main을 대상으로하지 않도록합니다.

main에 릴리즈할 준비가 되면 release/*라는 브랜치를 생성하고 이 브랜치가 main을 대상으로 하도록 합니다.

대상 브랜치 워크플로 삭제

대상 브랜치 워크플로를 제거할 때, 기존의 Merge Request은 변경되지 않습니다.

전제 조건:

  • 적어도 Maintainer 역할을 가지고 있어야 합니다.

수행 방법:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
  2. 설정 > Merge Request을 선택합니다.
  3. 삭제하려는 대상 브랜치를 선택한 뒤 삭제를 선택합니다.

관련 주제

문제 해결

동일한 커밋을 포함하는 여러 브랜치

보다 깊은 기술적 수준에서 Git 브랜치는 별도의 개체가 아닌 커밋 SHA 세트에 부착된 라벨입니다. GitLab은 브랜치가 Merge되었는지 여부를 결정할 때 해당 커밋 SHA의 대상 브랜치의 존재 여부를 확인합니다. 이 동작은 두 Merge Request이 동일한 커밋을 포함할 때 예상치 못한 결과를 초래할 수 있습니다. 예를 들어 브랜치 B와 C가 모두 브랜치 A의 동일한 커밋(3)에서 시작하는 경우:

gitGraph commit id:"a" branch "branch A" commit id:"b" commit id:"c" type: HIGHLIGHT branch "branch B" commit id:"d" checkout "branch A" branch "branch C" commit id:"e" checkout main merge "branch B" id:"브랜치 브랜치B에 커밋 b, c, d를 Merge"

브랜치 B를 Merge하면, 브랜치 A도 Merge된 것처럼 보입니다(특별한 조치 없이) 왜냐하면, 브랜치 A의 모든 커밋이 대상 브랜치 main에 나타나기 때문입니다. 브랜치 C는 Merge되지 않은 상태로 남아 있습니다. 왜냐하면 커밋 5가 브랜치 A 또는 B의 일부가 아니기 때문입니다.

Merge Request A는 여전히 Merge된 상태이며, Merge Request A에 새로운 커밋을 푸시하려고 하더라도 변경 사항이 Merge Request A의 일부가 아니기 때문에 여전히 Merge된 상태로 유지됩니다. Merge Request A에서 변경 사항이 남아 있는 경우 이에 대한 새로운 Merge Request을 엽니다.

오류: 애매모호한 HEAD 브랜치가 존재합니다

Git의 2.16.0보다 이전 버전에서 HEAD라는 이름의 브랜치를 만들 수 있었습니다. 이 HEAD라는 브랜치는 Git이 활성화(체크 아웃)된 브랜치를 설명하는 데 사용하는 내부 참조(또한 HEAD라고 함)와 충돌합니다. 이러한 이름 충돌로 인해 귀하의 리포지터리의 기본 브랜치를 업데이트하는 것을 방해할 수 있습니다. 

오류: 기본 브랜치를 설정할 수 없습니다. 리포지터리에 'HEAD'라는 이름의 브랜치가 있습니까?

이 문제를 해결하려면 다음을 수행합니다:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
  2. 코드 > 브랜치를 선택합니다.
  3. HEAD라는 이름의 브랜치를 검색합니다.
  4. 브랜치에 커밋되지 않은 변경 사항이 없는지 확인합니다.
  5. 브랜치 삭제를 선택한 후 예, 브랜치 삭제를 선택합니다.

Git의 2.16.0 버전 이상에서는 이 이름으로 브랜치를 만드는 것을 방지합니다.

귀하가 작성한 모든 브랜치 찾기

프로젝트에서 귀하가 작성한 모든 브랜치를 찾으려면 Git 리포지터리에서 다음 명령을 실행합니다: 

git for-each-ref --format='%(refname:short) %(authoremail)'  | grep $(git config --get user.email)

프로젝트의 모든 브랜치의 총 수를 얻으려면 작성자별로 정렬하여 Git 리포지터리에서 다음 명령을 실행합니다: 

git for-each-ref --format='%(authoremail)'  | sort | uniq -c | sort -g