배포 키

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

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

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

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

외부 권한 부여가 활성화된 경우 배포 키로 Git 작업을 수행할 수 없습니다.

범위

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

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

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

권한

배포 키를 생성할 때 권한 수준이 지정됩니다.

  • 읽기 전용: 읽기 전용 배포 키는 리포지터리에서 읽기만 가능합니다.
  • 읽기/쓰기: 읽기/쓰기 배포 키는 리포지터리에서 읽기와 쓰기가 모두 가능합니다.

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

GitLab은 Git 명령을 트리거하는 경우 배포 키의 생성자를 인가합니다. 예를 들어:

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

보안 영향

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

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

더불어:

  • 배포 키는 생성한 사용자가 그룹이나 프로젝트에서 제거되어도 작동합니다.
  • 배포 키의 생성자는 사용자가 강등되거나 제거되어도 그룹이나 프로젝트에 대한 액세스 권한을 유지합니다.
  • 배포 키가 보호된 브랜치 규칙에서 지정된 경우, 해당 배포 키의 생성자는 보호된 브랜치와 배포 키 자체에 대한 액세스 권한을 얻습니다.

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

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

배포 키 보기

프로젝트에 대한 사용 가능한 배포 키를 보려면:

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

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

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

프로젝트 배포 키 생성

사전 요구 사항:

  • 프로젝트에 적어도 Maintainer 역할을 가지고 있어야 합니다.
  • SSH 키 쌍 생성이 필요합니다. 개인 SSH 키는 리포지터리에 액세스해야 하는 호스트에 저장하세요.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 리포지터리를 선택합니다.
  3. 배포 키를 확장합니다.
  4. 새 키 추가를 선택합니다.
  5. 필드를 작성합니다.
  6. 원하는 경우 이 키에 쓰기 권한 부여 확인란을 선택하여 read-write 권한을 부여할 수 있습니다.
  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. 비활성화 ()를 선택합니다.

키가 비활성화되면 다음과 같은 사항이 적용됩니다:

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

Troubleshooting

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

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

모든 배포 키는 계정과 관련되어 있습니다. 계정의 권한이 변경될 수 있기 때문에, 이로 인해 작동하던 배포 키가 갑자기 보호된 브랜치로 푸시할 수 없게 될 수 있습니다.

배포 키를 사용하는 프로젝트에 대해 서비스 계정을 만들고 배포 키를 서비스 계정과 연결하는 것을 권장합니다.

비멤버 및 차단된 사용자와 연결된 배포 키 식별

비멤버 또는 차단된 사용자의 키를 찾아야 하는 경우, 다음과 유사한 스크립트를 사용하여 사용할 수 없는 배포 키를 식별하는 데 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? 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 ? 'YES' : 'NO') +
       ", 기본 브랜치 #{project.repository.root_ref}로 푸시 가능?: " + (can_push_to_default ? 'YES' : 'NO') +
       ", 사용자: #{username}, 사용자 상태: #{user_state}"
end