배포 키

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

GitLab에 호스팅된 저장소에 액세스하려면 배포 키를 사용합니다. 대부분의 경우 배포 키는 빌드 서버 또는 연속 통합(CI) 서버와 같은 외부 호스트에서 저장소에 액세스하는 데 사용합니다.

필요에 따라 배포 토큰을 사용하여 저장소에 액세스할 수도 있습니다.

속성 배포 키 배포 토큰
공유 여러 프로젝트 간에 공유할 수 있음, 심지어 다른 그룹에 속한 프로젝트도 가능함. 프로젝트 또는 그룹에 속함.
출처 외부 호스트에서 생성된 공개 SSH 키. GitLab 인스턴스에서 생성되며, 생성 시에만 사용자에게 제공됨.
액세스 가능한 리소스 SSH를 통해 Git 저장소 HTTP를 통해 Git 저장소, 패키지 레지스트리 및 컨테이너 레지스트리.

외부 인가가 활성화되어 있는 경우 배포 키는 Git 작업에 사용할 수 없습니다.

범위

배포 키는 생성될 때 정의된 범위를 갖습니다:

  • 프로젝트 배포 키: 선택한 프로젝트로의 액세스가 제한됨.
  • 공개 배포 키: GitLab 인스턴스의 어떤 프로젝트에 액세스할 수 있음. 각 프로젝트에 대한 액세스는 적어도 관리자 역할을 하는 사용자가 부여해야 함.

배포 키의 범위는 생성 후에 변경할 수 없습니다.

권한

배포 키는 생성될 때 권한 수준이 부여됩니다:

  • 읽기 전용: 읽기 전용 배포 키는 저장소에서만 읽을 수 있습니다.
  • 읽기/쓰기: 읽기/쓰기 배포 키는 저장소에서 읽기 및 쓰기가 모두 가능합니다.

배포 키의 권한 수준은 생성 후에 변경할 수 있습니다. 프로젝트 배포 키의 권한을 변경하면 현재 프로젝트에만 적용됩니다.

배포 키를 사용하여 푸시하는 경우 추가 프로세스가 트리거되면 키를 생성한 사용자가 인가되어야 합니다. 예를 들어:

  • 배포 키를 사용하여 보호된 브랜치에 커밋을 푸시하는 경우, 배포 키를 생성한 사용자는 해당 브랜치에 액세스해야 합니다.
  • 배포 키를 사용하여 CI/CD 파이프라인을 트리거하는 커밋을 푸시하는 경우, 배포 키를 생성한 사용자는 CI/CD 리소스에 액세스해야 합니다(보호된 환경 및 비밀 변수 포함).

보안 상의 영향

배포 키는 GitLab에서 인간이 아닌 상호 작용을 용이하게 하기 위해 사용됩니다. 예를 들어, 조직의 서버에서 자동으로 실행되는 스크립트에 허용 권한을 부여하기 위해 배포 키를 사용할 수 있습니다.

서비스 계정으로 활용할 전용 계정을 작성하고 해당 서비스 계정으로 배포 키를 생성해야 합니다. 다른 사용자 계정을 사용하여 배포 키를 생성하면, 해당 사용자에게 배포 키가 취소될 때까지 지속되는 권한이 부여됩니다.

또한:

  • 배포 키는 해당 키를 생성한 사용자가 그룹 또는 프로젝트에서 제거되더라도 작동합니다.
  • 배포 키를 생성한 사용자는 해당 사용자가 강등/제거되더라도 그룹 또는 프로젝트에 액세스 권한을 계속 유지합니다.
  • 보호된 브랜치 규칙에서 배포 키가 지정된 경우, 배포 키를 생성한 사용자:
    • 보호된 브랜치 및 해당 배포 키에 액세스할 수 있습니다.
    • 읽기/쓰기 권한을 가진 경우 보호된 브랜치에 푸시할 수 있습니다. 이는 모든 사용자로부터의 변경에 대해 보호된 브랜치인 경우에도 동일합니다.

모든 민감한 정보와 마찬가지로, 비밀을 알아야 하는 사람만이 읽을 수 있도록 해야 합니다. 인간 간 상호 작용을 위해 개인 액세스 토큰과 같은 사용자에게 연결된 자격 증명을 사용하세요.

잠재적인 비밀 유출을 탐지하기 위해 감사 이벤트 기능을 사용할 수 있습니다.

배포 키 보기

프로젝트에 사용 가능한 배포 키를 보려면 다음을 수행하세요:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 저장소를 선택합니다.
  3. 배포 키를 확장합니다.

사용 가능한 배포 키는 다음과 같습니다:

  • 활성화된 배포 키: 프로젝트에 액세스 권한이 있는 배포 키.
  • 비공개 액세스 가능한 배포 키: 프로젝트에 액세스 권한이 없는 프로젝트 배포 키.
  • 공개 액세스 가능한 배포 키: 프로젝트에 액세스 권한이 없는 공개 배포 키.

프로젝트 배포 키 생성

전제 조건:

  • 프로젝트에 적어도 관리자 역할이 있어야 합니다.
  • SSH 키 쌍을 생성하여 개인 SSH 키를 저장소에 놓아야 합니다.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 저장소를 선택합니다.
  3. 배포 키를 확장합니다.
  4. 새 키 추가를 선택합니다.
  5. 필드를 입력합니다.
  6. 선택 사항. 읽기-쓰기 권한을 부여하려면 이 키에 쓰기 권한 부여 확인란을 선택합니다.
  7. 선택 사항. 만료 날짜를 업데이트합니다.

프로젝트 배포 키는 생성될 때 활성화됩니다. 프로젝트 배포 키의 이름과 권한만 수정할 수 있습니다. 배포 키가 여러 프로젝트에서 활성화된 경우 배포 키 이름을 수정할 수 없습니다.

공개 배포 키 생성

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

전제 조건:

  • 인스턴스에 관리자 권한이 있어야 합니다.
  • SSH 키 쌍을 생성해야 합니다.
  • 저장소에 액세스할 호스트에 개인 SSH 키를 놓아야 합니다.

공개 배포 키를 생성하려면 다음을 수행하세요:

  1. 왼쪽 사이드바에서 아래쪽에서 관리자를 선택합니다.
  2. 배포 키를 선택합니다.
  3. 새 배포 키를 선택합니다.
  4. 필드를 입력합니다.
    • 이름에 의미 있는 설명을 사용합니다. 예: 공개 배포 키를 사용하는 외부 호스트나 애플리케이션의 이름을 포함합니다.

공개 배포 키의 이름만 수정할 수 있습니다.

프로젝트에 공개 배포 키 액세스 부여

전제 조건:

  • 프로젝트에 적어도 관리자 역할이 있어야 합니다.

공개 배포 키에 프로젝트 액세스를 부여하려면 다음을 수행하세요:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 저장소를 선택합니다.
  3. 배포 키를 확장합니다.
  4. 공개 액세스 가능한 배포 키를 선택합니다.
  5. 키의 행에서 활성화를 선택합니다.
  6. 공개 배포 키에 읽기-쓰기 권한을 부여하려면:
    1. 키의 행에서 편집 ()을 선택합니다.
    2. 이 키에 쓰기 권한 부여 확인란을 선택합니다.

배포 키의 프로젝트 액세스 권한 편집

전제 조건:

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

배포 키의 프로젝트 액세스 권한을 편집하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 저장소를 선택합니다.
  3. 배포 키를 확장합니다.
  4. 키의 행에서 편집을 선택합니다 ().
  5. 이 키에 쓰기 권한 부여 확인란을 선택하거나 선택 해제합니다.

배포 키의 프로젝트 액세스 취소

프로젝트에 대한 배포 키의 액세스를 취소하려면 해당 키를 비활성화할 수 있습니다. 키가 비활성화되면 해당 키를 사용하는 서비스는 작동을 중지합니다.

전제 조건:

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

배포 키를 비활성화하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 저장소를 선택합니다.
  3. 배포 키를 확장합니다.
  4. 비활성화를 선택합니다 ().

키가 비활성화되면 다음과 같은 조건에 따라 키의 상태가 결정됩니다:

  • 키가 공개적으로 액세스 가능한 경우, 프로젝트에서 제거되지만 공개적으로 액세스 가능한 배포 키 탭에 여전히 이용 가능합니다.
  • 키가 비공개적으로 액세스 가능하고 해당 프로젝트에서만 사용 중인 경우, 키가 삭제됩니다.
  • 키가 비공개적으로 액세스 가능하고 다른 프로젝트에서도 사용 중인 경우, 프로젝트에서 제거되지만 비공개적으로 액세스 가능한 배포 키 탭에 여전히 이용 가능합니다.

문제 해결

배포 키가 보호된 브랜치에 푸시할 수 없음

배포 키가 보호된 브랜치에 푸시하지 못하는 몇 가지 시나리오가 있습니다.

  • 배포 키의 소유자가 보호된 브랜치의 프로젝트에 멤버십이 없습니다.
  • 배포 키의 소유자가 프로젝트 멤버 권한이 프로젝트 코드 보기를 요구하는 것보다 낮습니다.
  • 배포 키가 프로젝트에 대한 읽기-쓰기 권한이 없습니다.
  • 배포 키가 취소되었습니다.
  • 보호된 브랜치의 [푸시 및 머지 권한이 허용된 사람]에서 아무도가 선택되지 않았습니다.

모든 배포 키는 계정과 연결됩니다. 계정의 권한이 변경될 수 있으므로, 한 때 작동했던 배포 키가 보호된 브랜치로의 푸시를 갑자기 할 수 없게 되는 시나리오가 발생할 수 있습니다.

배포 키를 사용하는 프로젝트에는 서비스 계정을 생성하고, 서비스 계정에 배포 키를 연결하는 것을 권장합니다.

비멤버 및 차단된 사용자에 연결된 배포 키 확인

비멤버 또는 차단된 사용자에 연결된 키를 찾아야 하는 경우, 다음과 유사한 스크립트를 사용하여 레일즈 콘솔을 사용하여 사용할 수 없는 배포 키를 식별할 수 있습니다: 

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.id}, 프로젝트: #{project.full_path}, 푸시 가능?: " + (can_push ? '예' : '아니요') +
       ", 기본 브랜치 #{project.repository.root_ref}에 푸시 가능?: " + (can_push_to_default ? '예' : '아니요') +
       ", 사용자: #{username}, 사용자 상태: #{user_state}"
end