배포 키를 사용하여 GitLab에서 호스팅되는 저장소에 액세스하세요. 대부분의 경우 배포 키를 사용하여 빌드 서버나 CI(Continuous Integration) 서버와 같은 외부 호스트에서 저장소에 액세스합니다.

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

외부 인증이 활성화된 경우 배포 키를 Git 작업에 사용할 수 없습니다.

범위#

배포 키는 생성 시 정의된 범위를 가집니다:

• 프로젝트 배포 키: 액세스가 선택한 프로젝트로 제한됩니다.
• 공개 배포 키: GitLab 인스턴스의 모든 프로젝트에 액세스 권한을 부여할 수 있습니다. 각 프로젝트에 대한 액세스는 최소 유지 관리자 역할을 가진 사용자가 부여해야 합니다.

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

권한#

배포 키는 생성 시 권한 수준이 주어집니다:

• 읽기 전용: 읽기 전용 배포 키는 저장소에서만 읽을 수 있습니다.
• 읽기-쓰기: 읽기-쓰기 배포 키는 저장소에서 읽고 쓸 수 있습니다.

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

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

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

보안 영향#

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

서비스 계정을 사용하고 서비스 계정으로 배포 키를 만드는 것이 좋습니다. 다른 사용자 계정을 사용하여 배포 키를 만들면 배포 키가 취소될 때까지 해당 사용자에게 권한이 부여됩니다.

또한:

• 배포 키 소유자가 차단된 경우, 배포 키가 거부됩니다. 풀 및 푸시를 포함한 모든 저장소 작업에 사용할 수 없습니다.
• 배포 키 소유자가 그룹 또는 프로젝트에서 제거된 경우에는 배포 키가 거부되지 않습니다. 배포 키는 취소될 때까지 계속 액세스를 제공합니다.
• 배포 키가 보호된 브랜치 규칙에 지정된 경우, 배포 키 생성자는:
  • 보호된 브랜치와 배포 키 자체에 대한 액세스 권한을 얻습니다.
  • 배포 키에 읽기-쓰기 권한이 있으면 보호된 브랜치에 푸시할 수 있습니다. 브랜치가 모든 사용자의 변경으로부터 보호되어 있어도 마찬가지입니다.

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

잠재적인 비밀 유출을 탐지하는 데 도움이 되도록 감사 이벤트 기능을 사용할 수 있습니다.

배포 키 보기#

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

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

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

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

GitLab CLI는 glab deploy-key list 명령을 제공합니다.

프로젝트 배포 키 만들기#

사전 요구 사항:

• 프로젝트에 대한 유지 관리자 또는 소유자 역할이 있어야 합니다.
• SSH 키 쌍을 생성합니다. 비공개 SSH 키를 저장소에 액세스해야 하는 호스트에 배치합니다.

1. 상단 메뉴에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 설정 > 저장소를 선택합니다.
3. 배포 키를 펼칩니다.
4. 새 키 추가를 선택합니다.
5. 필드를 작성합니다.
6. 선택 사항. read-write 권한을 부여하려면 이 키에 쓰기 권한 부여 체크박스를 선택합니다.
7. 선택 사항. 만료 날짜를 업데이트합니다.

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

GitLab CLI는 glab deploy-key add 명령을 제공합니다.

공개 배포 키 만들기#

사전 요구 사항:

• 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.
• SSH 키 쌍을 생성해야 합니다.
• 비공개 SSH 키를 저장소에 액세스해야 하는 호스트에 배치해야 합니다.

공개 배포 키를 만들려면:

1. 오른쪽 상단에서 관리를 선택합니다.
2. 왼쪽 사이드바에서 배포 키를 선택합니다.
3. 새 배포 키를 선택합니다.
4. 필드를 작성합니다.
   • 이름에 의미 있는 설명을 사용합니다. 예를 들어 공개 배포 키를 사용하는 외부 호스트 또는 애플리케이션의 이름을 포함합니다.

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

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

사전 요구 사항:

• 프로젝트에 대한 유지 관리자 또는 소유자 역할이 있어야 합니다.

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

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

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

사전 요구 사항:

• 프로젝트에 대한 유지 관리자 또는 소유자 역할이 있어야 합니다.

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

1. 상단 메뉴에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 설정 > 저장소를 선택합니다.
3. 배포 키를 펼칩니다.
4. 키의 행에서 편집 (✏️)을 선택합니다.
5. 이 키에 쓰기 권한 부여 체크박스를 선택하거나 지웁니다.

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

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

사전 요구 사항:

• 프로젝트에 대한 유지 관리자 또는 소유자 역할이 있어야 합니다.

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

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

배포 키가 비활성화될 때 발생하는 일은 다음에 따라 다릅니다:

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

관련 항목#

• GitLab CLI 배포 키 명령

문제 해결#

배포 키가 거부됨#

다음과 같은 경우 배포 키가 거부됩니다:

• 키 소유자가 차단된 경우.
• 키가 만료된 경우.

배포 키가 거부되면 풀 및 푸시를 포함한 모든 저장소 작업에 사용할 수 없습니다.

이 문제를 해결하려면:

• 키 소유자가 차단된 경우, 사용자를 차단 해제하거나 키 소유자를 변경하여 활성 사용자로 설정합니다.
• 키가 만료된 경우, 새 배포 키를 만듭니다.

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

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

• 배포 키에 연결된 소유자가 보호된 브랜치의 프로젝트에 구성원 자격이 없습니다.
• 배포 키에 연결된 소유자의 프로젝트 구성원 자격 권한이 프로젝트 코드 보기에 필요한 것보다 낮습니다.
• 배포 키에 프로젝트에 대한 읽기-쓰기 권한이 없습니다.
• 배포 키가 취소되었습니다.
• 보호된 브랜치의 푸시 및 머지 허용 섹션에서 없음이 선택되어 있습니다.

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

이 문제를 해결하려면 배포 키 API를 사용하여 자신의 사용자가 아닌 프로젝트 서비스 계정 사용자를 위한 배포 키를 만들 수 있습니다:

1. 서비스 계정 사용자를 만듭니다.

2. 해당 서비스 계정 사용자를 위한 개인 액세스 토큰을 만듭니다. 이 토큰은 최소한 api 범위가 있어야 합니다.

3. 서비스 계정 사용자를 프로젝트에 초대합니다.

4. 배포 키 API를 사용하여 서비스 계정 사용자를 위한 배포 키를 만듭니다:

   curl --request POST --header "PRIVATE-TOKEN: <service_account_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"title": "My deploy key", "key": "ssh-rsa AAAA...", "can_push": "true"}' \
     --url "https://gitlab.example.com/api/v4/projects/5/deploy_keys/"
   

비구성원 및 차단된 사용자와 연결된 배포 키 식별#

비구성원 또는 차단된 사용자에 속하는 키를 찾아야 하는 경우 Rails 콘솔을 사용하여 다음과 유사한 스크립트로 사용할 수 없는 배포 키를 식별할 수 있습니다:

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.ghost?
    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

배포 키 소유자 설정#

배포 키는 특정 사용자에게 속하며 사용자가 차단된 경우 거부됩니다. 소유자가 차단될 때 배포 키가 계속 작동하도록 하려면 소유자를 활성 사용자로 변경합니다.

배포 키의 지문이 있으면 다음 명령으로 배포 키와 연결된 사용자를 변경할 수 있습니다:

k = Key.find_by(fingerprint: '5e:51:92:11:27:90:01:b5:83:c3:87:e3:38:82:47:2e')
k.user_id = User.find_by(username: 'anactiveuser').id
k.save()