배포 키

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

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

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

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

외부 승인(external authorization)이 활성화된 경우 배포 키로 Git 작업을 수행할 수 없습니다.

범위

배포 키가 생성될 때 정의된 범위가 있습니다:

  • 프로젝트 배포 키: 선택한 프로젝트로의 액세스가 제한됨.
  • 공개 배포 키: GitLab 인스턴스 내의 모든 프로젝트로의 액세스가 허용됨. 각 프로젝트에 액세스하려면 적어도 Maintainer 역할을 가진 사용자가 액세스를 부여해야 합니다.

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

권한

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

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

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

GitLab은 배포 키를 생성한 사용자의 권한을 부여하며, Git 명령이 추가적인 프로세스를 트리거하는 경우 예를 들어:

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

보안 영향

배포 키의 의도된 사용 사례는 비인간적 상호작용을 위한 것입니다. 예를 들어, 조직 내 서버에서 실행되는 자동화된 스크립트 등이 해당됩니다.

서비스 계정으로 작동할 수 있도록 전용 계정을 만들고 해당 서비스 계정으로 배포 키를 생성해야 합니다. 배포 키 생성을 위해 다른 사용자 계정을 사용하는 경우 해당 사용자에게 지속적인 권한이 부여됩니다.

또한:

  • 사용자가 그룹 또는 프로젝트에서 제거된 경우에도 배포 키는 여전히 작동합니다.
  • 배포 키 생성자는 그룹 또는 프로젝트에 대한 액세스를 유지하며 사용자의 역할이 변경되거나 삭제된 경우에도 액세스 권한이 유지됩니다.
  • 보호된 브랜치 규칙에 배포 키가 지정된 경우, 배포 키의 생성자는 보호된 브랜치 및 배포 키 자체에 액세스 권한을 얻게 됩니다.

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

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

배포 키 보기

프로젝트에 사용 가능한 배포 키를 확인하려면:

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

사용 가능한 배포 키가 나열됩니다:

  • 활성화된 배포 키: 프로젝트에 액세스 권한을 가진 배포 키들.
  • 개인적으로 액세스 가능한 배포 키: 프로젝트에 액세스 권한이 없는 프로젝트 배포 키들.
  • 공개적으로 액세스 가능한 배포 키: 프로젝트에 액세스 권한이 없는 공개 배포 키들.

프로젝트 배포 키 생성

사전 요구사항:

  • 프로젝트의 최소한 Maintainer 역할이 있어야 합니다.
  • SSH 키 쌍을 생성했어야 합니다. 개인 SSH 키는 저장소에 액세스가 필요한 호스트에 위치시키세요.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
  2. 설정 > 저장소를 선택합니다.
  3. 배포 키를 확장합니다.
  4. 새 키 추가를 선택합니다.
  5. 필드를 작성합니다.
  6. 선택 사항. 읽기 쓰기 권한을 부여하려면 이 키에 쓰기 권한을 부여 확인란을 선택합니다.
  7. 선택 사항. 만료 날짜를 업데이트합니다.

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

공개 배포 키 생성

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

전제 조건:

  • 인스턴스에 관리자 액세스해야 합니다.
  • SSH 키 쌍을 생성해야 합니다.
  • 저장소에 액세스가 필요한 호스트에 개인 SSH 키를 넣어야 합니다.

공개 배포 키를 생성하려면:

  1. 왼쪽 사이드바에서 맨 아래쪽에 있는 관리 영역을 선택합니다.
  2. 배포 키를 선택합니다.
  3. 새로운 배포 키를 선택합니다.
  4. 필드를 작성합니다.
    • 이름에 의미있는 설명을 사용합니다. 예를 들어, 공개 배포 키를 사용하는 외부 호스트나 응용 프로그램의 이름을 포함합니다.

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

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

전제 조건:

  • 프로젝트에 대해 적어도 Maintainer 역할이 있어야 합니다.

프로젝트에 공개 배포 키의 액세스를 부여하려면:

  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: #{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