GitLab CI/CD에서 SSH 키 사용하기

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

GitLab은 빌드 환경(GitLab Runner가 실행되는 곳)에서 SSH 키를 관리할 수 있는 기본 지원 기능이 없습니다.

SSH 키를 사용하려면 다음과 같을 때 사용합니다.

  • 내부 서브모듈을 확인하는 경우
  • 패키지 관리자를 통해 비공개 패키지를 다운로드하는 경우. 예를 들어 Bundler를 사용하는 경우
  • 응용 프로그램을 자체 서버에 배포하는 경우 또는 예를 들어 Heroku에 배포하는 경우
  • 빌드 환경에서 원격 서버로 SSH 명령을 실행하는 경우
  • 빌드 환경에서 파일을 원격 서버로 Rsync하는 경우

위의 내용 중 어느 것이라도 해당된다면, 아마도 SSH 키가 필요할 것입니다.

가장 널리 지원되는 방법은 .gitlab-ci.yml을 확장하여 빌드 환경에 SSH 키를 삽입하는 것이며, 이 방법은 executor(예: Docker 또는 shell) 종류에 따라 작동합니다.

SSH 키 생성 및 사용하기

GitLab CI/CD에서 SSH 키를 생성하고 사용하려면 다음을 수행하세요.

  1. ssh-keygen을 사용하여 로컬에서 새 SSH 키 쌍을 생성합니다.
  2. 프로젝트에 파일 유형 CI/CD 변수로 비공개 키를 추가합니다. 변수 값은 새 줄 (LF 문자)로 끝나야 합니다. 줄 바꿈을 추가하려면 SSH 키의 마지막 줄 뒤에 Enter 또는 Return을 누릅니다.
  3. 작업에서 ssh-agent를 실행하여 비공개 키를 로드합니다.
  4. 서버에 공개 키를 복사하여 액세스할 서버에 추가합니다(보통 ~/.ssh/authorized_keys에 추가됨). 개인 GitLab 리포지토리에 액세스하는 경우 공개 키를 배포 키로 추가해야 합니다.

아래 예에서 ssh-add - 명령은 작업 로그에 $SSH_PRIVATE_KEY 값을 표시하지 않지만, 디버그 로그를 활성화하면 노출될 수 있습니다. 또한 파이프라인의 가시성을 확인할 수 있습니다.

Docker executor 사용 시 SSH 키

CI/CD 작업이 Docker 컨테이너 내에서 실행되고(환경이 격리되어 있는 경우) 코드를 비공개 서버에 배포하려는 경우 SSH 키 쌍이 필요합니다.

  1. 먼저 SSH 키 쌍을 생성해야 합니다. 자세한 정보는 SSH 키 생성 지침을 따르세요. SSH 키에 암호를 추가하지 마세요. 그렇지 않으면 before_script에서 암호를 묻게 됩니다.

  2. 새 파일 유형 CI/CD 변수를 생성합니다.
    • 키 필드에 SSH_PRIVATE_KEY를 입력합니다.
    • 값 필드에 이전에 생성한 키페어의 비공개 키 내용을 붙여넣습니다. 파일이 새 줄로 끝나도록 확인합니다. 줄 바꿈을 추가하려면 Enter 또는 Return를 눌러 SSH 키의 마지막 줄 뒤에 추가한 후 변경 사항을 저장합니다.

  3. .gitlab-ci.yml을 수정하여 before_script 작업을 추가합니다. 다음 예제에서는 Debian 기반 이미지를 사용하였습니다. 필요에 따라 편집하세요. 

    before_script:
  ##
  ## ssh-agent가 설치되어있지 않다면 설치합니다. Docker에 필요합니다.
  ## (RPM 기반 이미지의 경우 apt-get 대신 yum을 사용합니다)
  ##
  - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )'

  ##
  ## ssh-agent 실행 (빌드 환경 내)
  ##
  - eval $(ssh-agent -s)

  ##
  ## 올바른 권한 부여, 그렇지 않을 경우 ssh-add가 파일 추가를 거부합니다
  ## SSH_PRIVATE_KEY 파일 유형 CI/CD 변수에 저장된 SSH 키를 에이전트 저장소에 추가합니다.
  ##
  - chmod 400 "$SSH_PRIVATE_KEY"
  - ssh-add "$SSH_PRIVATE_KEY"

  ##
  ## SSH 디렉토리 생성 및 올바른 권한 설정
  ##
  - mkdir -p ~/.ssh
  - chmod 700 ~/.ssh

  ##
  ## 필요한 경우 Git 명령을 사용할 예정이라면 사용자 이름과 이메일을 설정하세요.
  ##
  # - git config --global user.email "user@example.com"
  # - git config --global user.name "User name"

    before_script은 기본값 또는 작업별로 설정할 수 있습니다.

  4. 사설키의 SSH 호스트 키를 확인합니다.

  5. 마지막 단계로, 처음에 생성한 공개 키를 빌드 환경 내에서 액세스하려는 서비스에 추가하세요. 개인 GitLab 리포지토리에 액세스하는 경우 배포 키로 추가해야 합니다.

여기까지입니다! 이제 빌드 환경에서 개인 서버 또는 리포지토리에 액세스할 수 있습니다.

Shell executor 사용 시 SSH 키

Shell executor를 사용하고 Docker가 아닌 경우 SSH 키를 설정하는 것이 더 쉽습니다.

SSH 키를 GitLab Runner가 설치된 서버에서 생성하고, 이 키를 해당 서버에서 실행되는 모든 프로젝트에 사용할 수 있습니다.

  1. 먼저 작업을 실행하는 서버에 로그인합니다.

  2. 그런 다음 터미널에서 gitlab-runner 사용자로 로그인합니다. 

    sudo su - gitlab-runner

  3. SSH 키 생성 지침에 설명된대로 SSH 키 쌍을 생성합니다. SSH 키에 암호를 추가하지 마세요. 그렇지 않으면 before_script에서 암호를 묻게 됩니다.

  4. 마지막 단계로, 처음에 생성한 공개 키를 빌드 환경 내에서 액세스하려는 서비스에 추가하세요. 개인 GitLab 리포지토리에 액세스하는 경우 배포 키로 추가해야 합니다.

키를 생성한 후에 원격 서버에 로그인하여 지문을 수락해보세요. 

ssh example.com

GitLab.com 리포지토리에 액세스하려면 git@gitlab.com을 사용합니다.

SSH 호스트 키 확인하기

사생활을 지키기 위해 개인 서버의 공개 키를 확인하는 것은 좋은 실천 방법입니다. 그렇게 하면 중간자 공격을 받고 있지는 않은지 확인할 수 있습니다. 수상한 일이 일어나면 작업이 실패합니다 (공개 키가 일치하지 않을 때 SSH 연결에 실패합니다).

서버의 호스트 키를 찾으려면 신뢰할 수 있는 네트워크(이상적으로는 개인 서버 자체)에서 ssh-keyscan 명령을 실행하세요: 

## 도메인 이름 사용
ssh-keyscan example.com

## 또는 IP 사용
ssh-keyscan 10.0.2.2

SSH_KNOWN_HOSTS를 “Key”로 하고 ssh-keyscan의 출력을 “Value”로 추가하여 파일 유형 CI/CD 변수를 생성하세요. 파일은 개행으로 끝나야 합니다. 개행을 추가하려면 SSH 키의 마지막 줄 뒤에 Enter 또는 Return을 누르세요.

여러 서버에 연결해야 하는 경우 모든 서버의 호스트 키를 변수의 Value에 모아야 합니다. 각 키를 한 줄에 하나씩 작성하세요.

참고: ssh-keyscan을 .gitlab-ci.yml 안에 직접 사용하는 대신에 파일 유형 CI/CD 변수를 사용하면, 호스트 도메인 이름이 어떤 이유로든 변경되어도 .gitlab-ci.yml을 변경할 필요가 없습니다. 또한, 값은 미리 정의되어 있어서 호스트 키가 갑자기 변경되어도 CI/CD 작업이 실패하지 않아야 합니다. 따라서 서버나 네트워크에 문제가 있는 것입니다.

이제 SSH_KNOWN_HOSTS 변수가 생성되었으므로 .gitlab-ci.yml의 내용에 추가해야 합니다: 

before_script:
  ##
  ## SSH_KNOWN_HOSTS 파일 유형 CI/CD 변수를 만들었다고 가정하고 다음 두 줄을 주석 해제하세요.
  ##
  - cp "$SSH_KNOWN_HOSTS" ~/.ssh/known_hosts
  - chmod 644 ~/.ssh/known_hosts

  ##
  ## 또는 개인 서버의 키를 스캔하기 위해 ssh-keyscan을 사용하세요. example.com을 개인 서버의 도메인 이름으로 대체하세요. 여러 서버에 연결해야 하는 경우 해당 명령을 반복하세요. 키 유형을 지정하는 -t 플래그를 포함하세요.
  ##
  # - ssh-keyscan -t rsa,ed25519 example.com >> ~/.ssh/known_hosts
  # - chmod 644 ~/.ssh/known_hosts

  ##
  ## 호스트 키 확인을 선택적으로 비활성화할 수 있습니다. 이렇게 하면 중간자 공격에 취약해집니다.
  ## 경고: 이것은 Docker 실행자와 함께만 사용하세요. shell과 함께 사용하면 사용자의 SSH 구성을 덮어씁니다.
  ##
  # - '[[ -f /.dockerenv ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" >> ~/.ssh/config'

파일 유형 CI/CD 변수를 사용하지 않는 SSH 키 사용

만약 파일 유형 CI/CD 변수를 사용하고 싶지 않다면, 예시 SSH 프로젝트에서 대체 방법을 볼 수 있습니다. 이 방법은 파일 유형 변수 대신 일반 CI/CD 변수를 사용합니다.

문제 해결

/builds/path/SSH_PRIVATE_KEY 키를 불러오는 중 “error in libcrypto” 메시지

이 메시지는 SSH 키에 형식 오류가 있는 경우 반환될 수 있습니다.

파일 유형 CI/CD 변수로 SSH 키를 저장할 때 값은 개행(LF 문자)으로 끝나야 합니다. 개행을 추가하려면 SSH 키의 -----END OPENSSH PRIVATE KEY----- 라인 뒤에 Enter 또는 Return을 누르세요.