배포 키를 사용하면 GitLab에 호스팅된 리포지터리에 접근할 수 있습니다. 대부분의 경우 빌드 서버나 지속적 통합(CI) 서버 같은 외부 호스트에서 리포지터리에 접근할 때 배포 키를 사용합니다.

필요에 따라 리포지터리 접근에 배포 토큰을 대신 사용할 수도 있습니다.

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

범위#

배포 키는 생성 시점에 범위가 정해집니다:

• 프로젝트 배포 키: 선택한 프로젝트로 접근이 제한됩니다.
• 공개 배포 키: GitLab 인스턴스의 모든 프로젝트에 접근 권한을 부여할 수 있습니다. 각 프로젝트에 대한 접근은 최소 Maintainer 권한을 가진 사용자가 부여해야 합니다.

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

권한#

배포 키는 생성 시점에 권한 수준이 부여됩니다:

• 읽기 전용: 읽기 전용 배포 키는 리포지터리에서 읽기만 할 수 있습니다.
• 읽기 및 쓰기: 읽기 및 쓰기 배포 키는 리포지터리에서 읽고 쓸 수 있습니다.

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

배포 키를 사용한 푸시가 추가 프로세스를 트리거하는 경우, 키를 만든 사용자에게 권한이 있어야 합니다. 예를 들면 다음과 같습니다:

• 배포 키로 보호된 브랜치에 커밋을 푸시하는 경우, 배포 키를 만든 사용자에게 해당 브랜치에 대한 접근 권한이 있어야 합니다.
• 배포 키로 CI/CD 파이프라인을 트리거하는 커밋을 푸시하는 경우, 배포 키를 만든 사용자에게 보호된 환경과 시크릿 변수를 포함한 CI/CD 리소스에 대한 접근 권한이 있어야 합니다.

보안 영향#

배포 키는 사람이 아닌 주체와 GitLab 사이의 상호작용을 위한 것입니다. 예를 들어 조직의 서버에서 자동으로 실행되는 스크립트에 권한을 부여할 때 배포 키를 사용할 수 있습니다.

서비스 계정을 사용해 그 서비스 계정으로 배포 키를 만드는 것을 권장합니다. 다른 사용자 계정으로 배포 키를 만들면 해당 사용자에게 배포 키를 취소할 때까지 유지되는 권한이 부여됩니다.

또한 다음 사항에 유의합니다:

• 배포 키 소유자가 차단되면 해당 배포 키는 거부됩니다. 풀과 푸시를 포함한 어떤 리포지터리 작업에도 사용할 수 없습니다.
• 배포 키 소유자가 그룹이나 프로젝트에서 제거되어도 배포 키는 거부되지 않습니다. 해당 배포 키는 취소될 때까지 계속 접근을 허용합니다.
• 보호된 브랜치 규칙에 배포 키가 지정되면, 그 배포 키를 만든 사용자는 다음과 같은 상태가 됩니다:
  • 보호된 브랜치와 배포 키 자체에 접근할 수 있습니다.
  • 배포 키에 읽기 및 쓰기 권한이 있으면 보호된 브랜치에 푸시할 수 있습니다. 이는 모든 사용자의 변경으로부터 브랜치가 보호되어 있어도 마찬가지입니다.

모든 민감 정보와 마찬가지로, 시크릿에 접근해야 하는 대상만 이를 읽을 수 있도록 해야 합니다. 사람이 수행하는 작업에는 개인 액세스 토큰처럼 사용자에 연결된 자격 증명을 사용합니다.

시크릿 유출 가능성을 탐지하려면 감사 이벤트 기능을 사용할 수 있습니다.

배포 키 보기#

프로젝트에서 사용할 수 있는 배포 키를 보려면 다음과 같이 진행합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Deploy keys를 확장합니다.

사용할 수 있는 배포 키가 다음과 같이 표시됩니다:

• Enabled deploy keys: 프로젝트에 접근할 수 있는 배포 키입니다.
• Privately accessible deploy keys: 프로젝트에 접근할 수 없는 프로젝트 배포 키입니다.
• Public accessible deploy keys: 프로젝트에 접근할 수 없는 공개 배포 키입니다.

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

프로젝트 배포 키 만들기#

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.
• SSH 키 쌍을 생성합니다. 리포지터리 접근이 필요한 호스트에 개인 SSH 키를 배치합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Deploy keys를 확장합니다.
4. Add new key를 선택합니다.
5. 필드를 입력합니다.
6. 선택 사항. read-write 권한을 부여하려면 Grant write permissions to this key 체크박스를 선택합니다.
7. 선택 사항. Expiration date를 수정합니다.

프로젝트 배포 키는 생성과 동시에 활성화됩니다. 프로젝트 배포 키는 이름과 권한만 수정할 수 있습니다. 배포 키가 둘 이상의 프로젝트에서 활성화되어 있으면 배포 키 이름은 수정할 수 없습니다.

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

공개 배포 키 만들기#

사전 요구 사항:

• 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.
• SSH 키 쌍을 생성해야 합니다.
• 리포지터리 접근이 필요한 호스트에 개인 SSH 키를 배치해야 합니다.

공개 배포 키를 만들려면 다음과 같이 진행합니다:

1. 오른쪽 위에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Access > Deploy keys를 선택합니다.
3. New deploy key를 선택합니다.
4. 필드를 입력합니다.
   • Name에는 의미가 분명한 설명을 사용합니다. 예를 들어 공개 배포 키를 사용하는 외부 호스트나 애플리케이션의 이름을 포함합니다.

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

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

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

공개 배포 키에 프로젝트 접근 권한을 부여하려면 다음과 같이 진행합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Deploy keys를 확장합니다.
4. Publicly accessible deploy keys를 선택합니다.
5. 해당 키의 행에서 Enable을 선택합니다.
6. 공개 배포 키에 읽기 및 쓰기 권한을 부여하려면 다음과 같이 진행합니다:
   1. 해당 키의 행에서 Edit (✏️)를 선택합니다.
   2. Grant write permissions to this key 체크박스를 선택합니다.

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

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

배포 키의 프로젝트 액세스 권한을 편집하려면 다음과 같이 진행합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Deploy keys를 확장합니다.
4. 해당 키의 행에서 Edit (✏️)를 선택합니다.
5. Grant write permissions to this key 체크박스를 선택하거나 선택 해제합니다.

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

배포 키를 비활성화하면 해당 프로젝트에 대한 접근 권한을 취소할 수 있습니다. 배포 키에 의존하는 서비스는 키가 비활성화되면 동작을 멈춥니다.

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

배포 키를 비활성화하려면 다음과 같이 진행합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Deploy keys를 확장합니다.
4. Disable ([cancel])을 선택합니다.

비활성화된 배포 키가 어떻게 처리되는지는 다음에 따라 달라집니다:

• 공개적으로 접근 가능한 키이면 프로젝트에서는 제거되지만 Publicly accessible deploy keys 탭에는 계속 남아 있습니다.
• 비공개로 접근 가능한 키이면서 이 프로젝트에서만 사용 중이면 삭제됩니다.
• 비공개로 접근 가능한 키이면서 다른 프로젝트에서도 사용 중이면 해당 프로젝트에서만 제거되고 Privately accessible deploy keys 탭에는 계속 남아 있습니다.

관련 주제#

• GitLab CLI 배포 키 명령

문제 해결#

배포 키가 거부됨#

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

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

배포 키가 거부되면 풀과 푸시를 포함한 어떤 리포지터리 작업에도 사용할 수 없습니다.

이 문제를 해결하려면 다음과 같이 진행합니다:

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

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

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

• 배포 키에 연결된 소유자가 보호된 브랜치가 있는 프로젝트의 멤버가 아닙니다.
• 배포 키에 연결된 소유자의 프로젝트 멤버십 권한이 View project code에 필요한 수준보다 낮습니다.
• 배포 키에 프로젝트에 대한 읽기 및 쓰기 권한이 없습니다.
• 배포 키가 취소되었습니다.
• 보호된 브랜치의 Allowed to push and merge 섹션에서 No one 이 선택되어 있습니다.

이 문제는 모든 배포 키가 계정에 연결되어 있기 때문에 발생합니다. 계정의 권한은 바뀔 수 있으므로, 잘 동작하던 배포 키가 갑자기 보호된 브랜치에 푸시하지 못하는 상황이 생길 수 있습니다.

이 문제를 해결하려면 배포 키 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()