배포 키
GitLab에 호스팅된 저장소에 액세스하기 위해 배포 키를 사용합니다. 대부분의 경우 배포 키는 빌드 서버나 지속적 통합(CI) 서버와 같은 외부 호스트에서 저장소에 액세스하는 데 사용됩니다.
필요에 따라 배포 토큰을 대신 사용하여 저장소에 액세스할 수도 있습니다.
속성 | 배포 키 | 배포 토큰 |
---|---|---|
공유 | 여러 프로젝트 간에 공유 가능(서로 다른 그룹에 속한 프로젝트도 포함). | 프로젝트나 그룹에 속함. |
소스 | 외부 호스트에서 생성된 공개 SSH 키. | GitLab 인스턴스에서 생성되며, 생성 시에만 사용자에게 제공됨. |
액세스 가능한 리소스 | SSH를 통한 Git 저장소 | HTTP를 통한 Git 저장소, 패키지 레지스트리, 컨테이너 레지스트리. |
외부 승인(external authorization)이 활성화된 경우 배포 키로 Git 작업을 수행할 수 없습니다.
범위
배포 키가 생성될 때 정의된 범위가 있습니다:
- 프로젝트 배포 키: 선택한 프로젝트로의 액세스가 제한됨.
- 공개 배포 키: GitLab 인스턴스 내의 모든 프로젝트로의 액세스가 허용됨. 각 프로젝트에 액세스하려면 적어도 Maintainer 역할을 가진 사용자가 액세스를 부여해야 합니다.
배포 키의 범위는 생성 후에 변경할 수 없습니다.
권한
배포 키가 생성될 때 권한 수준이 부여됩니다:
- 읽기 전용: 읽기 전용 배포 키는 저장소에서 읽기만 가능합니다.
- 읽기/쓰기: 읽기/쓰기 가능한 배포 키는 저장소에서 읽기 및 쓰기가 모두 가능합니다.
배포 키의 권한 수준은 생성 후에 변경할 수 있습니다. 프로젝트 배포 키의 권한을 변경하더라도 현재 프로젝트에만 적용됩니다.
GitLab은 배포 키를 생성한 사용자의 권한을 부여하며, Git 명령이 추가적인 프로세스를 트리거하는 경우 예를 들어:
- 배포 키가 보호된 브랜치에 커밋을 푸시하는 경우, 배포 키의 _생성자_는 해당 브랜치에 액세스해야 합니다.
- 배포 키가 CI/CD 파이프라인을 트리거하는 커밋을 푸시하는 경우, 배포 키의 _생성자_는 CI/CD 리소스(보호된 환경 및 비밀 변수 포함)에 액세스해야 합니다.
보안 영향
배포 키의 의도된 사용 사례는 비인간적 상호작용을 위한 것입니다. 예를 들어, 조직 내 서버에서 실행되는 자동화된 스크립트 등이 해당됩니다.
서비스 계정으로 작동할 수 있도록 전용 계정을 만들고 해당 서비스 계정으로 배포 키를 생성해야 합니다. 배포 키 생성을 위해 다른 사용자 계정을 사용하는 경우 해당 사용자에게 지속적인 권한이 부여됩니다.
또한:
- 사용자가 그룹 또는 프로젝트에서 제거된 경우에도 배포 키는 여전히 작동합니다.
- 배포 키 생성자는 그룹 또는 프로젝트에 대한 액세스를 유지하며 사용자의 역할이 변경되거나 삭제된 경우에도 액세스 권한이 유지됩니다.
- 보호된 브랜치 규칙에 배포 키가 지정된 경우, 배포 키의 생성자는 보호된 브랜치 및 배포 키 자체에 액세스 권한을 얻게 됩니다.
모든 민감한 정보와 마찬가지로, 비밀을 알아야 하는 사용자만이 해당 정보를 읽을 수 있도록해야 합니다. 인간 상호작용의 경우 개인 접근 토큰과 같은 사용자에게 연결된 자격 증명을 사용하세요.
잠재적인 비밀 유출을 감지하기 위해 감사 이벤트 기능을 사용할 수 있습니다.
배포 키 보기
프로젝트에 사용 가능한 배포 키를 확인하려면:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
- 설정 > 저장소를 선택합니다.
- 배포 키를 확장합니다.
사용 가능한 배포 키가 나열됩니다:
- 활성화된 배포 키: 프로젝트에 액세스 권한을 가진 배포 키들.
- 개인적으로 액세스 가능한 배포 키: 프로젝트에 액세스 권한이 없는 프로젝트 배포 키들.
- 공개적으로 액세스 가능한 배포 키: 프로젝트에 액세스 권한이 없는 공개 배포 키들.
프로젝트 배포 키 생성
사전 요구사항:
- 프로젝트의 최소한 Maintainer 역할이 있어야 합니다.
- SSH 키 쌍을 생성했어야 합니다. 개인 SSH 키는 저장소에 액세스가 필요한 호스트에 위치시키세요.
- 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
- 설정 > 저장소를 선택합니다.
- 배포 키를 확장합니다.
- 새 키 추가를 선택합니다.
- 필드를 작성합니다.
- 선택 사항.
읽기 쓰기
권한을 부여하려면 이 키에 쓰기 권한을 부여 확인란을 선택합니다. - 선택 사항. 만료 날짜를 업데이트합니다.
프로젝트 배포 키는 생성될 때 활성화됩니다. 프로젝트 배포 키의 이름과 권한만 수정할 수 있습니다. 배포 키가 여러 프로젝트에서 활성화된 경우에는 배포 키의 이름을 수정할 수 없습니다.
공개 배포 키 생성
전제 조건:
- 인스턴스에 관리자 액세스해야 합니다.
- SSH 키 쌍을 생성해야 합니다.
- 저장소에 액세스가 필요한 호스트에 개인 SSH 키를 넣어야 합니다.
공개 배포 키를 생성하려면:
- 왼쪽 사이드바에서 맨 아래쪽에 있는 관리 영역을 선택합니다.
- 배포 키를 선택합니다.
- 새로운 배포 키를 선택합니다.
- 필드를 작성합니다.
- 이름에 의미있는 설명을 사용합니다. 예를 들어, 공개 배포 키를 사용하는 외부 호스트나 응용 프로그램의 이름을 포함합니다.
공개 배포 키의 이름만 수정할 수 있습니다.
프로젝트에 공개 배포 키에 대한 액세스 부여
전제 조건:
- 프로젝트에 대해 적어도 Maintainer 역할이 있어야 합니다.
프로젝트에 공개 배포 키의 액세스를 부여하려면:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
- 설정 > 저장소를 선택합니다.
- 배포 키를 확장합니다.
- 공개적으로 접근 가능한 배포 키를 선택합니다.
- 키의 행에서 활성화를 선택합니다.
- 공개 배포 키에 읽기-쓰기 권한을 부여하려면:
- 키의 행에서 편집()을 선택합니다.
- 이 키에 쓰기 권한 부여 확인란을 선택합니다.
배포 키의 프로젝트 액세스 권한 편집
전제 조건:
- 프로젝트에 대해 적어도 Maintainer 역할이 있어야 합니다.
배포 키의 프로젝트 액세스 권한을 편집하려면:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
- 설정 > 저장소를 선택합니다.
- 배포 키를 확장합니다.
- 키의 행에서 편집()을 선택합니다.
- 이 키에 쓰기 권한 부여 확인란을 선택하거나 해제합니다.
프로젝트의 배포 키 액세스 취소
프로젝트의 배포 키 액세스를 취소하려면, 해당 키를 비활성화할 수 있습니다. 키가 비활성화되면 해당 키를 사용하는 서비스는 작동을 중지합니다.
전제 조건:
- 프로젝트에 대해 적어도 Maintainer 역할이 있어야 합니다.
배포 키를 비활성화하려면:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
- 설정 > 저장소를 선택합니다.
- 배포 키를 확장합니다.
- 비활성화를 선택합니다().
키가 비활성화되면 다음과 같은 사항에 따라 키의 상태가 달라집니다:
- 키가 공개적으로 접근 가능하면, 프로젝트에서 제거되지만 공개적으로 접근 가능한 배포 키 탭에 여전히 사용 가능합니다.
- 키가 비공개적으로 접근 가능하고 해당 프로젝트에서만 사용 중이면, 키가 삭제됩니다.
- 키가 비공개적으로 접근 가능하고 다른 프로젝트에서도 사용 중이면, 프로젝트에서 제거되지만 비공개적으로 접근 가능한 배포 키 탭에 여전히 사용 가능합니다.
문제 해결
배포 키가 보호된 브랜치로 푸시할 수 없음
배포 키가 보호된 브랜치로 푸시하는 데 실패하는 몇 가지 시나리오가 있습니다.
- 배포 키와 연관된 소유자가 보호된 브랜치의 프로젝트에 멤버십이 없는 경우.
- 배포 키와 연관된 소유자가 프로젝트 멤버십 권한이 프로젝트 코드 보기에 필요한 권한보다 낮은 경우.
- 배포 키가 프로젝트에 대해 읽기-쓰기 권한을 갖고 있지 않은 경우.
- 배포 키가 취소되었을 경우.
- 보호된 브랜치의 푸시 및 병합 권한 허용 대상에서 아무도가 선택되지 않은 경우.
모든 배포 키는 계정과 관련되어 있습니다. 계정의 권한이 변경될 수 있기 때문에, 한 때 작동하던 배포 키가 갑자기 보호된 브랜치로 푸시할 수 없게 될 수 있습니다.
배포 키를 사용하는 프로젝트에는 서비스 계정을 생성하고 배포 키를 서비스 계정에 연결하는 것을 권장합니다.
비멤버 및 차단된 사용자와 연관된 배포 키 식별
비멤버 또는 차단된 사용자에 속한 키를 식별해야 하는 경우, 다음과 유사한 스크립트를 사용하여 레일즈 콘솔을 사용하여 사용할 수 없는 배포 키를 식별할 수 있습니다:
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? tests if deploy_key can push to default branch, which is likely to be protected
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: #{deploy_key.id}, Project: #{project.full_path}, Can push?: " + (can_push ? 'YES' : 'NO') +
", Can push to default branch #{project.repository.root_ref}?: " + (can_push_to_default ? 'YES' : 'NO') +
", User: #{username}, User state: #{user_state}"
end