배포 키

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과의 비인간 상호작용입니다. 예를 들어, 귀하 조직 내의 서버에서 실행되는 자동화된 스크립트입니다.

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

또한:

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

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

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

배포 키 보기

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

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. Settings > Repository를 선택합니다.
  3. Deploy keys를 확장합니다.

사용 가능한 배포 키는 다음과 같이 나열됩니다:

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

프로젝트 배포 키 생성

전제 조건:

  • 해당 프로젝트에 적어도 Maintainer 역할을 가지고 있어야 합니다.
  • SSH 키 쌍 생성이 되어 있어야 합니다. 개인 SSH 키는 리포지터리에 액세스해야 합니다.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. Settings > Repository를 선택합니다.
  3. Deploy keys를 확장합니다.
  4. 새 키 추가를 선택합니다.
  5. 필드를 작성합니다.
  6. 원하는 경우, 이 키에 쓰기 권한 부여 확인란을 선택하여 읽기/쓰기 권한을 부여합니다.
  7. 원하는 경우, 만료 날짜를 업데이트합니다.

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

공개 배포 키 생성

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

전제 조건:

  • 해당 인스턴스에 관리자 액세스권이 있어야 합니다.
  • SSH 키 쌍을 생성해야 합니다.
  • 개인 SSH 키를 리포지터리에 액세스해야 합니다.

공개 배포 키를 만들려면:

  1. 왼쪽 사이드바에서 아래쪽에 위치한 Admin Area를 선택합니다.
  2. Deploy Keys를 선택합니다.
  3. 새로운 배포 키를 선택합니다.
  4. 필드를 작성합니다.
    • 이름에 의미 있는 설명을 사용합니다. 예를 들어, 공개 배포 키를 사용하는 외부 호스트나 애플리케이션의 이름을 포함합니다.

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

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

전제 조건:

  • 해당 프로젝트에 적어도 Maintainer 역할을 가지고 있어야 합니다.

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

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

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

전제 조건:

  • 프로젝트에 대해 적어도 유지자 역할을 가져야 합니다.

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

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

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

프로젝트로부터 배포 키의 액세스를 취소하려면 해당 키를 비활성화할 수 있습니다. 키가 비활성화되면 키를 사용하는 서비스는 작동을 멈춥니다.

전제 조건:

  • 프로젝트에 대해 적어도 유지자 역할을 가져야 합니다.

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

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

키가 비활성화되면 다음과 같은 상황에 따라 키가 어떻게 처리되는지가 달라집니다:

  • 키가 공개적으로 액세스할 수 있는 경우 프로젝트에서 제거되지만 공개적으로 액세스할 수 있는 배포 키 탭에는 계속해서 표시됩니다.
  • 키가 비공개적으로 액세스할 수 있으며 해당 프로젝트에서만 사용 중인 경우 키가 삭제됩니다.
  • 키가 비공개적으로 액세스할 수 있지만 다른 프로젝트에서도 사용 중인 경우 프로젝트에서 제거되지만 비공개적으로 액세스할 수 있는 배포 키 탭에는 계속해서 표시됩니다.

문제 해결

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

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

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

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

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

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