배포 키
배포 키를 사용하여 GitLab에 호스팅된 리포지토리에 액세스하세요. 대부분의 경우 배포 키를 사용하여 외부 호스트, 즉 빌드 서버 또는 CI(Continuous Integration) 서버에서 리포지토리에 액세스합니다.
필요에 따라 리포지토리에 액세스하기 위해 배포 토큰을 사용하고 싶을 수도 있습니다.
| 속성 | 배포 키 | 배포 토큰 |
|---|---|---|
| 공유 | 서로 다른 그룹의 여러 프로젝트 간에 공유 가능. | 프로젝트 또는 그룹에 속함. |
| 소스 | 외부 호스트에서 생성된 공개 SSH 키. | GitLab 인스턴스에서 생성되며, 생성 시에만 사용자에게 제공됨. |
| 접근할 수 있는 리소스 | SSH를 통한 Git 리포지토리 | HTTP를 통한 Git 리포지토리, 패키지 레지스트리 및 컨테이너 레지스트리. |
배포 키는 외부 인증이 활성화된 경우 Git 작업에 사용할 수 없습니다.
범위
배포 키는 생성될 때 정의된 범위를 가집니다:
- 프로젝트 배포 키: 접근이 선택된 프로젝트로 제한됩니다.
- 공개 배포 키: GitLab 인스턴스의 모든 프로젝트에 접근할 수 있습니다. 각 프로젝트에 대한 접근은 최소한 Maintainer 역할을 가진 사용자가 부여해야 합니다.
배포 키를 생성한 후에 그 범위를 변경할 수 없습니다.
권한
배포 키는 생성될 때 권한 수준이 부여됩니다:
- 읽기 전용: 읽기 전용 배포 키는 리포지토리에서 읽기만 할 수 있습니다.
- 읽기-쓰기: 읽기-쓰기 배포 키는 리포지토리에서 읽고 쓸 수 있습니다.
배포 키의 권한 수준은 생성 후에 변경할 수 있습니다. 프로젝트 배포 키의 권한 변경은 현재 프로젝트에만 적용됩니다.
배포 키를 사용하는 푸시가 추가 프로세스를 트리거하는 경우, 키의 생성자는 권한이 부여되어야 합니다. 예:
- 배포 키가 보호된 분기에 커밋을 푸시하는 데 사용되는 경우, 배포 키의 생성자는 그 분기에 접근할 수 있어야 합니다.
- 배포 키가 CI/CD 파이프라인을 트리거하는 커밋을 푸시하는 데 사용되는 경우, 배포 키의 생성자는 보호된 환경 및 비밀 변수 등 CI/CD 리소스에 접근할 수 있어야 합니다.
보안 고려 사항
배포 키는 GitLab과의 비인간 상호작용을 촉진하기 위해 설계되었습니다. 예를 들어, 서버에서 자동으로 실행되는 스크립트에 권한을 부여하기 위해 배포 키를 사용할 수 있습니다.
서비스 계정 역할을 수행할 전용 계정을 생성하고, 서비스 계정으로 배포 키를 생성해야 합니다. 다른 사용자 계정을 사용하여 배포 키를 생성하는 경우, 해당 사용자는 배포 키가 철회될 때까지 지속적으로 권한이 부여됩니다.
또한:
- 배포 키는 이를 생성한 사용자가 그룹 또는 프로젝트에서 제거되더라도 작동합니다.
- 배포 키의 생성자는 사용자가 강등되거나 제거되더라도 그룹 또는 프로젝트에 대한 접근 권한을 유지합니다.
- 보호된 분기 규칙에 배포 키가 지정될 경우, 배포 키의 생성자는:
- 보호된 분기에 대한 접근 및 배포 키 자체에 대한 접근을 가집니다.
- 배포 키에 읽기-쓰기 권한이 있는 경우 보호된 분기에 푸시할 수 있습니다.
이는 모든 사용자의 변경에 대해 보호된 분리 소속일지라도 마찬가지입니다.
모든 민감한 정보와 마찬가지로 비밀 정보를 읽을 수 있는 사람을 최소한으로 제한해야 합니다. 사람 간의 상호작용에는 개인 접근 토큰과 같은 사용자와 연결된 자격 증명을 사용하세요.
잠재적인 비밀 유출을 탐지하는 데 도움을 주기 위해 감사 이벤트 기능을 사용할 수 있습니다.
배포 키 보기
프로젝트에 사용할 수 있는 배포 키를 보려면:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
- 설정 > 저장소를 선택합니다.
- 배포 키를 확장합니다.
사용 가능한 배포 키가 나열됩니다:
- 활성화된 배포 키: 프로젝트에 접근할 수 있는 배포 키입니다.
- 개인적으로 접근할 수 있는 배포 키: 프로젝트에 접근할 수 없는 프로젝트 배포 키입니다.
- 공개적으로 접근할 수 있는 배포 키: 프로젝트에 접근할 수 없는 공개 배포 키입니다.
프로젝트 배포 키 생성
필수 요구 사항:
- 프로젝트에 대해 최소 Maintainer 역할을 가져야 합니다.
- SSH 키 쌍 생성을 수행해야 합니다. 개인 SSH 키를 저장소에 접근해야 하는 호스트에 두십시오.
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
- 설정 > 저장소를 선택합니다.
- 배포 키를 확장합니다.
- 새 키 추가를 선택합니다.
- 필드를 작성합니다.
- 선택 사항.
read-write권한을 부여하려면 이 키에 대한 쓰기 권한 부여 체크박스를 선택합니다. - 선택 사항. 만료 날짜를 업데이트합니다.
프로젝트 배포 키는 생성할 때 활성화됩니다. 프로젝트 배포 키의 이름과 권한만 수정할 수 있습니다. 배포 키가 여러 프로젝트에 활성화된 경우 배포 키 이름을 수정할 수 없습니다.
공개 배포 키 생성
세부정보:
Tier: Free, Premium, Ultimate
Offering: Self-managed, GitLab Dedicated
필수 요구 사항:
- 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.
- SSH 키 쌍을 생성해야 합니다.
- 개인 SSH 키를 저장소에 접근해야 하는 호스트에 두셔야 합니다.
공개 배포 키를 생성하려면:
- 왼쪽 사이드바에서 하단의 관리자를 선택합니다.
- 배포 키를 선택합니다.
- 새 배포 키를 선택합니다.
- 필드를 작성합니다.
- 이름에 대해 의미 있는 설명을 사용하십시오. 예를 들어, 공개 배포 키를 사용하는 외부 호스트 또는 애플리케이션의 이름을 포함합니다.
공개 배포 키의 이름만 수정할 수 있습니다.
공개 배포 키에 프로젝트 접근 권한 부여
필수 요구 사항:
- 프로젝트에 대해 최소 Maintainer 역할을 가져야 합니다.
공개 배포 키에 프로젝트 접근 권한을 부여하려면:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
- 설정 > 저장소를 선택합니다.
- 배포 키를 확장합니다.
- 공개적으로 접근할 수 있는 배포 키를 선택합니다.
- 키의 행에서 활성화를 선택합니다.
- 공개 배포 키에 대한 읽기-쓰기 권한을 부여하려면:
- 키의 행에서 편집({연필})을 선택합니다.
- 이 키에 대한 쓰기 권한 부여 체크박스를 선택합니다.
배포 키의 프로젝트 접근 권한 편집
필수 요구 사항:
- 프로젝트에 대해 최소 Maintainer 역할을 가져야 합니다.
배포 키의 프로젝트 접근 권한을 편집하려면:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
- 설정 > 저장소를 선택합니다.
- 배포 키를 확장합니다.
- 키의 행에서 편집({연필})을 선택합니다.
- 이 키에 대한 쓰기 권한 부여 체크박스를 선택하거나 선택 해제합니다.
배포 키의 프로젝트 액세스 취소
배포 키의 프로젝트에 대한 액세스를 취소하려면 해당 키를 비활성화할 수 있습니다. 키가 비활성화되면 해당 배포 키에 의존하는 모든 서비스가 작동을 중지합니다.
전제 조건:
- 프로젝트에 대해 최소한 Maintainer 역할을 가져야 합니다.
배포 키를 비활성화하려면:
- 왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
- Settings > Repository를 선택합니다.
- Deploy keys를 확장합니다.
- Disable()를 선택합니다.
배포 키가 비활성화될 때의 처리 방식은 다음과 같습니다:
- 키가 공개적으로 접근 가능한 경우, 프로젝트에서 제거되지만 Publicly accessible deploy keys 탭에서는 여전히 사용할 수 있습니다.
- 키가 비공식적으로 접근 가능하고 이 프로젝트에서만 사용되고 있다면 삭제됩니다.
- 키가 비공식적으로 접근 가능하고 다른 프로젝트에서도 사용되고 있다면, 프로젝트에서 제거되지만 여전히 Privately accessible deploy keys 탭에서는 사용할 수 있습니다.
문제 해결
배포 키가 보호된 브랜치에 푸시할 수 없음
배포 키가 보호된 브랜치에 푸시하지 못하는 여러 시나리오가 있습니다.
- 배포 키와 연결된 소유자가 보호된 브랜치의 프로젝트에 대한 멤버십을 가지고 있지 않습니다.
- 배포 키와 연결된 소유자가 View project code에 필요한 것보다 낮은 프로젝트 멤버십 권한을 가지고 있습니다.
- 배포 키가 프로젝트에 대한 읽기-쓰기 권한을 가지고 있지 않습니다.
- 배포 키가 취소되었습니다.
- 보호된 브랜치의 Allowed to push and merge 섹션에서 No one이 선택되어 있습니다.
모든 배포 키는 계정과 연결되어 있습니다. 계정에 대한 권한이 변경될 수 있으므로, 이로 인해 작동하던 배포 키가 갑자기 보호된 브랜치에 푸시할 수 없는 시나리오가 발생할 수 있습니다.
배포 키를 사용하는 프로젝트에는 서비스 계정을 생성하고 배포 키를 서비스 계정에 연결하는 것을 권장합니다.
비회원 및 차단된 사용자와 연결된 배포 키 식별
비회원 또는 차단된 사용자에 속하는 키를 찾아야 하는 경우, Rails 콘솔을 사용하여 다음과 유사한 스크립트를 사용하여 사용할 수 없는 배포 키를 식별할 수 있습니다:
ghost_user_id = Users::Internal.ghost.id
DeployKeysProject.with_write_access.find_each do |deploy_key_mapping|
project = deploy_key_mapping.project
deploy_key = deploy_key_mapping.deploy_key
user = deploy_key.user
access_checker = Gitlab::DeployKeyAccess.new(deploy_key, container: project)
# can_push_for_ref?는 deploy_key가 기본 브랜치에 푸시할 수 있는지 테스트합니다.
# 기본 브랜치는 보호된 브랜치일 가능성이 높습니다.
can_push = access_checker.can_do_action?(:push_code)
can_push_to_default = access_checker.can_push_for_ref?(project.repository.root_ref)
next if access_checker.allowed? && can_push && can_push_to_default
if user.nil? || user.id == ghost_user_id
username = 'none'
state = '-'
else
username = user.username
user_state = user.state
end
puts "배포 키: #{deploy_key.id}, 프로젝트: #{project.full_path}, 푸시 가능?: " + (can_push ? 'YES' : 'NO') +
", 기본 브랜치 #{project.repository.root_ref}에 푸시 가능?: " + (can_push_to_default ? 'YES' : 'NO') +
", 사용자: #{username}, 사용자 상태: #{user_state}"
end
도움말