프로젝트 Repository 설정

Default branch

새 프로젝트를 만들 때 GitLab은 main를 리포지터리의 기본 브랜치로 설정합니다. 프로젝트의 Settings > Repository에서 다른 브랜치를 프로젝트의 디폴트(Default)로 선택할 수 있습니다.

이슈 종료 패턴을 통해 병합 요청에서 직접 이슈를 종료할 때, 대상은 프로젝트의 기본 브랜치입니다.

기본 브랜치는 실수로 삭제되거나 강제 푸시되지 않도록 초기에 보호됩니다.

커스텀 초기 브랜치 이름

기본적으로 GitLab에서 새 프로젝트를 만들 때, 초기 브랜치는 main입니다. 자체 관리 형 인스턴스의 경우 GitLab Admin는 초기 브랜치 이름을 다른 이름으로 커스터마이징 할 수 있습니다. 이렇게 하면, 그때부터 새로 생성된 모든 프로젝트는 master가 아닌 커스텀 브랜치 이름에서 시작하게 됩니다. 그렇게 하려면 :

1. Admin Area > Settings > Repository로 이동하여 Default initial branch name을 확장합니다.
2. Default initial branch name 필드에서 원하는 커스텀 이름으로 변경합니다.
3. Save Changes 버튼을 클릭합니다.

Repository 미러링

리포지터리 미러링을 사용하면 외부 소스와 리포지터리를 미러링할 수 있습니다. 리포지터리 간의 브랜치, 태그 및 커밋을 미러링하는 데 사용할 수 있습니다.

GitLab의 리포지터리 미러(mirror)는 자동으로 업데이트됩니다. 최대 5 분마다 업데이트를 수동으로 트리거할 수도 있습니다. 지연을 잠재적으로 줄이는 방법에 대한 토론을 보려면 이 이슈를 따르십시오.

개요

리포지터리 미러링은 GitLab 외부의 리포지터리를 사용하려는 경우 유용합니다.

GitLab에서 지원하는 두 종류의 리포지터리 미러링이 있습니다.

• Push : GitLab 리포지터리를 다른 위치로 미러링합니다.
• Pull : 다른 위치에서 GitLab으로 리포지터리를 미러링합니다.

미러 리포지터리가 업데이트되면, 모든 새 브랜치, 태그 및 커밋이 프로젝트의 활동 피드(activity feed)에 표시됩니다.

Developer 이상의 프로젝트에 대한 액세스 권한이 있는 사용자는 다음과 같은 경우를 제외하고 즉시 업데이트를 강제할 수도 있습니다.

• 미러가 이미 업데이트 중입니다.
• 마지막 업데이트 이후 5 분이 지나지 않았습니다.

보안상의 이유로, GitLab 12.10 이상에서 원본 리포지터리의 URL은 미러링된 프로젝트에 대한 Maintainer 또는 Owner 권한이 있는 사용자에게만 표시됩니다.

사용 사례

다음은 리포지터리 미러링의 몇 가지 가능한 사용 사례입니다.

• GitLab으로 마이그레이션했지만 여전히 프로젝트를 다른 소스에 유지해야 합니다. 이 경우, GitLab으로 미러링하도록(pull) 설정하기 만하면 커밋, 태그 및 브랜치의 모든 필수 기록을 GitLab 인스턴스에서 사용할 수 있습니다.
• 더 이상 적극적으로 사용하지 않지만 보관 목적으로 제거하고 싶지 않은 다른 소스에 오래된 프로젝트가 있습니다. 이 경우, 활성 GitLab 리포지터리가 변경사항을 이전 위치로 푸시할 수 있도록 푸시 미러(push mirror)를 생성할 수 있습니다.
• 개인 정보 보호를 위해 GitLab 자체 관리형 사용자이며 인스턴스가 공개되지 않지만, 오픈 소스를 원하는 특정 소프트웨어 구성 요소는 여전히 보유하고 있습니다. 이 경우, GitLab을 대중으로부터 폐쇄된 기본(primary) 리포지터리로 사용하고 공개된 GitLab.com 리포지터리에 푸시 미러링을 사용하면, 특정 프로젝트를 오픈하고 오픈 소스 커뮤니티에 다시 기여할 수 있습니다.

원격 리포지터리로 푸시

기존 프로젝트의 경우, 다음과 같이 푸시 미러링을 설정할 수 있습니다.

1. 프로젝트의 Settings > Repository로 이동하고 Mirroring repositories 섹션을 확장합니다.
2. 리포지터리 URL을 입력합니다.
3. Mirror direction 드롭다운에서 Push을 선택합니다.
4. 필요한 경우, Authentication method에서 인증 방법을 선택합니다.
5. 원하는 경우, Keep divergent refs (분기 참조 유지) 체크박스를 체크합니다.
6. 필요한 경우, Only mirror protected branches (보호된 브랜치만 미러) 체크박스를 체크합니다.
7. Mirror repository 버튼을 클릭하여 구성을 저장합니다.

푸시 미러링이 활성화된 경우, 미러링된 리포지터리에만 직접 커밋 푸시하여 미러 분기를 방지합니다. 다음과 같은 경우 모든 변경사항은 미러링된 리포지터리에 저장됩니다.

• 커밋은 GitLab에 푸시됩니다.
• 강제 업데이트가 시작됩니다.

리포지터리의 파일에 푸시된 변경사항은 최소한 다음과 같이 원격 미러에 자동으로 푸시됩니다.

• 접수 후 5 분 이내
• Only mirror protected branches가 활성화된 경우 1분 이내

분기된 브랜치의 경우, Mirroring repositories 섹션에 오류가 표시됩니다.

보호된 브랜치

GitLab의 권한은 기본적으로 리포지터리 및 브랜치에 대한 읽기 또는 쓰기 권한을 갖는 개념을 중심으로 정의됩니다. 특정 브랜치에 추가 제한을 적용하기 위해 보호할 수 있습니다.

개요

기본적으로 보호된 브랜치는 네 가지 간단한 작업을 수행합니다.

• Maintainer 권한이 있는 사용자를 제외한 모든 사용자가 아직 생성하지 않은 경우, 생성을 방지합니다.
• Allowed 권한이 있는 사용자를 제외한 모든 사용자의 푸시를 방지합니다.
• 누군가 브랜치에 강제 푸시하는 것을 방지합니다.
• 누구도 브랜치를 삭제하지 못하도록 합니다.

참고 : GitLab Admin은 보호된 브랜치에 푸시할 수 있습니다.

기본 브랜치 보호 수준은 Admin Area에서 설정됩니다.

보호된 브랜치 구성

브랜치를 보호하려면, 최소한 Maintainer 권한 수준이 있어야 합니다. main 브랜치는 기본적으로 보호됩니다.

1. 프로젝트의 Settings > Repository로 이동합니다.
2. 스크롤하여 Protected branches 섹션을 찾습니다.
3. Branch 드롭다운 메뉴에서, 보호할 브랜치를 선택하고 Allowed to merge, Allowed to push 드롭다운에서 원하는 권한을 선택한 다음, Protect 버튼을 클릭합니다. 아래 스크린샷에서 develop 브랜치를 선택했습니다.

4. 완료되면, 보호된 브랜치가 "보호된 브랜치" 목록에 나타납니다.

Allowed to merge과 Allowed to push 설정 사용

GitLab 8.11 이상에서는 보호된 브랜치를 보다 세밀하게 관리할 수 있는 또 다른 분기 보호 계층을 추가했습니다. "Developers can push" 옵션은 "Allowed to push" 설정으로 대체되었습니다. 이 옵션은 Maintainer와 Developer 모두 또는 둘 중 하나가 보호된 브랜치로 푸시하는 것을 허용하거나 금지하도록 설정할 수 있습니다.

"Allowed to push" 및 "Allowed to merge" 설정을 사용하면, 보호된 브랜치를 사용하여 다른 역할이 수행할 수 있는 작업을 제어할 수 있습니다. 예를 들어, "Allowed to push"을 "No one"로, "Allowed to merge"을 "Developers + Maintainers"로 설정하여, 모든 사람이 보호된 브랜치로 이동하는 변경사항에 대한 병합 요청을 제출하도록 요구할 수 있습니다. 이는 GitLab workflow와 같은 워크플로우와 호환됩니다.

그러나, 이것이 필요하지 않은 워크플로우가 있으며, 강제 푸시 및 브랜치 제거로부터 보호하는 것만이 유용한 경우도 있습니다. 이러한 워크플로우의 경우, "Allowed to push"을 "Developers + Maintainers"로 설정하여 쓰기 액세스 권한이 있는 모든 사용자가 보호된 브랜치로 푸시하도록 허용할 수 있습니다.

보호된 브랜치를 생성하는 동안 또는 나중에 이미 보호된 브랜치 목록의 드롭다운에서 원하는 옵션을 선택하여 "Allowed to push" 및 "Allowed to merge" 옵션을 설정할 수 있습니다.

보호된 태그

보호된 태그를 사용하면 태그 생성 권한이 있는 사용자를 제어할 수 있을 뿐만 아니라 생성된 태그를 실수로 업데이트 또는 삭제하는 것을 방지할 수 있습니다. 각 규칙을 사용하면 개별 태그 이름을 일치시키거나 와일드카드를 사용하여 한 번에 여러 태그를 제어할 수 있습니다.

이 기능은 보호된 브랜치에서 발전했습니다.

개요

보호된 태그는 다른 사용자가 태그를 업데이트하거나 삭제하는 것을 방지하고, 선택한 권한을 기반으로 일치하는 태그를 생성하지 못하게 합니다. 기본적으로 Maintainer 권한이 없는 사용자는 태그를 만들 수 없습니다.

보호된 태그 구성

태그를 보호하려면, 최소한 Maintainer 권한 수준이 있어야 합니다.

1. 프로젝트의 Settings > Repository로 이동합니다.
2. 스크롤하여 Protected Tags 섹션을 찾아 확장합니다.
3. Tag 드롭다운 메뉴에서, 보호할 태그를 선택하거나 태그 와일드카드를 입력하고 Create wildcard를 클릭합니다. 아래 스크린샷에서, v*와 일치하는 모든 태그를 보호하도록 선택했습니다.

4. Allowed to create 드롭다운에서, 일치하는 태그를 만들 수 있는 권한을 가진 사용자를 선택한 다음 Protect 버튼을 클릭합니다.

5. 완료되면 보호된 태그가 Protected tag 목록에 나타납니다.

와일드카드 보호 태그

와일드카드 보호 태그를 지정하면, 와일드카드와 일치하는 모든 태그를 보호할 수 있습니다. 예를 들면 :

와일드카드 보호된 태그	매칭 태그
v*	v1.0.0, version-9.1
*-deploy	march-deploy, 1.0-deploy
*gitlab*	gitlab, gitlab/v1
*	v1.0.1rc2, accidental-tag

두 개의 서로 다른 와일드카드가 잠재적으로 동일한 태그와 일치할 수 있습니다. 예를 들어, *-stable와 production-*는 둘 다 production-stable 태그와 일치합니다. 이 경우, 이러한 보호된 태그 중 하나라도 Allowed to created와 같은 설정이 있으면, production-stable도 이 설정을 상속합니다.

보호된 태그의 이름을 클릭하면, 일치하는 모든 태그 목록이 표시됩니다.

배포 토큰

배포 토큰을 사용하면 사용자와 비밀번호 없이 프로젝트의 패키지와 컨테이너 레지스트리 이미지를 다운로드(git clone)하거나 Push 및 Pull 할 수 있습니다. 배포 토큰은 Maintainer만 관리할 수 ​​있습니다. 키 페어가 있는 경우, 배포 키를 대신 사용할 수 있습니다.

배포 토큰 생성

프로젝트 설정에서 필요한 만큼의 배포 토큰을 생성할 수 있습니다. 또는 그룹 범위 배포 토큰을 만들 수도 있습니다.

1. GitLab 계정에 로그인합니다.
2. 배포 토큰을 생성하려는 프로젝트(또는 그룹)로 이동합니다.
3. Settings > Repository로 이동합니다.
4. Deploy Tokens 섹션에서 "Expand"을 클릭합니다.
5. 토큰의 이름, 만료 날짜(선택 사항) 및 사용자 이름(선택 사항)을 입력하거나 선택합니다.
6. 원하는 범위를 선택합니다.
7. Create deploy token 버튼을 클릭합니다.
8. 배포 토큰을 안전한 곳에 저장합니다. 페이지를 나가거나 새로고침 하면, 다시 액세스 할 수 없습니다.

배포 토큰 만료

배포 토큰은 정의한 날짜의 UTC 자정에 만료됩니다.

배포 토큰 취소

언제든지 'Active deploy tokens' 영역 아래에 있는 각각의 Revoke 버튼을 클릭하여 배포 토큰을 취소할 수 있습니다.

배포 토큰의 범위 제한

지정된 토큰이 수행할 수 있는 다양한 작업을 허용하는 다른 범위로 배포 토큰을 생성할 수 있습니다. 사용 가능한 범위는 도입된 GitLab 버전과 함께 다음 표에 설명되어 있습니다.

범위	설명	도입된 GitLab 버전
read_repository	git clone을 통해 Repository에 대한 읽기 액세스 허용	10.7
read_registry	프로젝트가 비공개이고 승인이 필요한 경우 Container Registry 이미지에 대한 읽기 액세스 허용	10.7
write_registry	Container Registry에 대한 쓰기 액세스 (Push) 허용	12.10
read_package_registry	Package Registry에 대한 읽기 액세스 허용	13.0
write_package_registry	Package Registry에 대한 쓰기 액세스 허용	13.0

배포 토큰 커스텀 사용자 이름

기본 사용자 이름 형식은 gitlab+deploy-token-#{n}입니다. 일부 도구 또는 플랫폼은 이 형식을 지원하지 않을 수 있습니다. 이 경우 배포 토큰을 생성할 때 사용할 커스텀 사용자 이름을 지정할 수 있습니다.

배포 키

배포 키는 SSH 공개 키를 GitLab 인스턴스로 가져와서 하나 이상의 리포지터리에 대한 읽기 전용 또는 읽기-쓰기 (활성화된 경우) 액세스를 허용합니다.

이 기능은 CI(Continuous Integration) 서버에 리포지터리를 복제하는 데 유용합니다. 배포 키를 사용하면 가짜 사용자 계정을 설정할 필요가 없습니다.

두 가지 유형의 배포 키가 있습니다.

• 프로젝트 배포 키
• 공개 배포 키

배포 키에 대한 주요 세부 정보

키 배포를 사용하면 원격 시스템(VM, 실제 등)이 몇 단계만으로 GitLab 리포지터리에 액세스할 수 있습니다. 원격 시스템이 자동화에서 GitLab 리포지터리와 상호 작용하도록 하려면 간단한 솔루션입니다.

단점은 원격 시스템이 해커에 의해 손상될 경우 리포지터리가 취약해질 수 있다는 것입니다. 리포지터리에서 배포 키를 활성화하기 전에 원격 시스템에 대한 액세스를 제한해야 합니다. 따라야 할 좋은 규칙은 신뢰할 수 있는 사용자에게만 액세스하고 허용된 사용자에게 GitLab 프로젝트에서 Maintainer 이상의 권한이 있는지 확인하는 것입니다.

이 보안 영향이 조직의 문제인 경우, Deploy Tokens가 대안으로 작동하지만 더 많은 보안 제어 기능을 가지고 있습니다.

배포 키 권한

프로젝트에서 활성화할 때 배포 키의 액세스 수준을 선택할 수 있습니다.

• read-only : 배포 키는 리포지터리를 읽을 수 있습니다.
• read-write : 배포 키는 리포지터리를 읽고 쓸 수 있습니다.

프로젝트 Maintainer와 Owner는 배포 키를 활성화 및 비활성화할 수 있습니다. 또한 이 프로젝트에 자신의 배포 키를 추가하고 사용할 수 있습니다.

write-access 배포 키를 사용하여 커밋을 Push 하는 경우, GitLab은 배포 키의 **작성자(Creator)**가 리소스에 액세스 할 수 있는 권한을 가지고 있는지 여부를 검사합니다. 예를 들면 다음과 같습니다.

• 배포 키를 사용하여 보호된 브랜치에 커밋을 푸시하는 경우, 배포 키의 작성자는 브랜치에 대한 액세스 권한이 있어야 합니다.
• 배포 키가 CI/CD 파이프라인을 트리거하는 커밋을 푸시하는 데 사용되는 경우, 배포 키의 작성자는 CI/CD 리소스(예 : 보호된 환경, 시크릿 변수 등)에 대한 액세스 권한이 있어야 합니다.
• 배포 키의 작성자가 프로젝트의 리포지터리를 읽을 수 있는 권한이 없는 경우, 처리 과정 중 배포 키에 오류가 발생할 수 있습니다.

배포 키와 배포 토큰의 차이점

배포 키와 배포 토큰 모두 리포지터리에 액세스 하는 데 도움이 될 수 있지만 둘 사이에는 몇 가지 주목할만한 차이점이 있습니다.

• 배포 키는 관련이 없거나 동일한 그룹에 속하지 않는 프로젝트 간에 공유할 수 있습니다. 배포 토큰은 프로젝트 또는 그룹에 속합니다.
• 배포 키는 시스템에서 직접 생성하는 데 필요한 SSH 키입니다. 배포 토큰은 GitLab 인스턴스에서 생성되며, 생성 시 사용자에게 한 번만 제공됩니다.
• 배포 키는 등록 및 활성화된 동안 유효합니다. 배포 토큰은 만료 날짜를 설정하여 유효성을 제어할 수 있으므로 시간에 민감할 수 있습니다.
• 배포 키로 레지스트리에 로그인하거나 읽기/쓰기 작업을 수행할 수 없지만, 배포 토큰을 사용하면 가능합니다.
• 배포 키를 사용하려면 SSH 키 페어(key pair)가 필요하지만, 배포 토큰은 필요하지 않습니다.

키 배포를 활성화하는 방법

프로젝트 Maintainer와 Owner는 프로젝트 리포지터리에 대한 배포 키를 추가하거나 활성화할 수 있습니다.

1. 프로젝트의 Settings > Repository 페이지로 이동합니다.
2. Deploy Keys 섹션을 확장합니다.
3. 새 배포 키의 제목을 지정하고 공개 SSH 키를 붙여 넣습니다.
4. (선택 사항) read-write 액세스를 허용하려면 Write access allowed를 선택합니다. read-only 액세스를 위해 선택하지 않은 상태로 둡니다.

프로젝트 배포 키에는 세 가지가 있습니다.

• 배포 키 활성화
• 비공개로 액세스 가능한 배포 키
• 공개 액세스 가능한 배포 키

키를 추가하면 기본적으로 이 프로젝트에 대해 활성화되며, Enabled deploy keys 탭에 표시됩니다.

Privately accessible deploy keys 탭에서, 다른 프로젝트에서 이미 가져온 개인 키를 활성화할 수 있습니다. 이러한 키에 액세스할 수 있는 경우, 다음 중 하나가 있기 때문입니다.

• 이전에 다른 프로젝트에 키를 직접 업로드한 적이 있음
• 키를 가져온 다른 프로젝트의 Maintainer 또는 Owner

Publicly accessible deploy keys 탭에서, 전체 GitLab 인스턴스에서 사용할 수 있는 키를 활성화할 수 있습니다.

키를 추가한 후, 키를 편집하여 제목을 업데이트하거나 read-only 및 read-write 액세스 간에 전환할 수 있습니다.

참고 : 프로젝트에 대해 비공개 또는 공개적으로 액세스할 수 있는 키를 활성화하거나 배포한 다음, 이 키에 대한 액세스 수준을 read-only에서 read-write로 업데이트하면, 변경사항은 현재 프로젝트에만 적용됩니다.

Repository 정리

참고 : 리포지터리를 안전하게 정리하려면 작업 기간 동안 읽기 전용으로 설정해야 합니다. 이는 자동으로 수행되지만 쓰기가 진행 중인 경우 정리 요청 제출이 실패하므로, 계속하기 전에 미해결 git push 작업을 취소하십시오.

리포지터리 정리를 사용하면 개체의 텍스트 파일을 업로드할 수 있으며 GitLab은 이러한 개체에 대한 내부 Git 참조를 제거합니다. git filter-repo를 사용하여 리포지터리 정리에 사용할 수 있는 개체 목록(commit-map 파일에 있는)을 생성할 수 있습니다.

리포지터리를 정리하려면 :

1. 프로젝트의 Settings > Repository 페이지로 이동합니다.
2. Repository cleanup 섹션을 확장합니다.
3. 개체 목록을 업로드합니다. 예를 들어, filter-repo 디렉토리에 있는 git filter-repo에 의해 생성된 commit-map 파일.
   commit-map 파일이 10MB보다 크면, 파일을 분할하여 조금씩 업로드할 수 있습니다.

split -l 100000 filter-repo/commit-map filter-repo/commit-map-

4. Start cleanup을 클릭합니다.

이렇게 하면:

• 이전 커밋에 대한 내부 Git 참조를 제거합니다.
• 리포지터리에 대해 git gc를 실행하여 참조되지 않은 개체를 제거합니다. 새 팩 파일이 만들어질 때까지 이전 팩 파일이 제거되지 않으므로 리포지터리를 일시적으로 다시 패킹하면 리포지터리 크기가 크게 증가합니다.
• 현재 프로젝트에 연결되어 있는 사용하지 않는 LFS 개체의 연결을 해제하여 저장 공간을 확보합니다.
• 디스크의 리포지터리 크기를 다시 계산합니다.

GitLab은 정리가 완료된 후 다시 계산된 리포지터리 크기와 함께 이메일 알림을 보냅니다.

리포지터리 정리를 사용할 때 다음을 참고하십시오.

• 프로젝트 통계는 캐시 됩니다. 스토리지 사용률 감소를 확인하려면 5-10분 정도 기다려야 할 수 있습니다.
• 하우스키핑은 2주 이상 된 느슨한 개체를 정리합니다. 이는 지난 2 주 동안 추가된 개체가 즉시 제거되지 않음을 의미합니다. Gitaly 서버에 액세스할 수 있는 경우, git gc --prune=now를 실행하여 느슨한 개체를 즉시 정리할 수 있습니다.
• 이 프로세스는 GitLab의 캐시 및 데이터베이스에서 다시 작성된 커밋의 일부 복사본을 제거하지만, 여전히 커버리지에서 많은 차이가 있으며 복사본 중 일부는 무한정 지속될 수 있습니다. 인스턴스 캐시를 지우면 일부를 제거하는 데 도움이 될 수 있지만, 보안 목적으로 의존해서는 안됩니다!

Branches
Repository Mirroring
Protected Branches
Protected Tags
Deploy Tokens
Deploy Keys
Repository Cleanup