GitLab은 빌드 환경(GitLab Runner가 실행되는 곳)에서 SSH 키를 관리하는 내장 지원이 없습니다.

다음을 원할 때 SSH 키를 사용하세요:

• 내부 서브모듈을 체크아웃합니다.
• 패키지 관리자를 사용하여 개인 패키지를 다운로드합니다. 예를 들어 Bundler.
• 자체 서버 또는 예를 들어 Heroku에 애플리케이션을 배포합니다.
• 빌드 환경에서 원격 서버로 SSH 명령을 실행합니다.
• 빌드 환경에서 원격 서버로 파일을 Rsync합니다.

가장 널리 지원되는 방법은 .gitlab-ci.yml을 확장하여 빌드 환경에 SSH 키를 주입하는 것입니다. 이 접근 방식은 Docker나 shell과 같은 모든 유형의 executor와 함께 작동합니다.

SSH 키 생성 및 사용#

GitLab CI/CD에서 SSH 키를 생성하고 사용하려면:

1. 새 SSH 키 쌍 생성.
2. 개인 키를 SSH_PRIVATE_KEY라는 파일 유형 CI/CD 변수로 추가합니다.
3. 개인 키를 로드하는 ssh-agent를 job에서 실행합니다.
4. 공개 키를 접근하려는 서버에 복사합니다(일반적으로 ~/.ssh/authorized_keys에). 개인 GitLab 리포지터리에 접근하는 경우 공개 키를 배포 키로 추가해야 합니다.

다음 예시에서 ssh-add - 명령은 job 로그에 $SSH_PRIVATE_KEY의 값을 표시하지 않지만, 디버그 로깅을 활성화하면 노출될 수 있습니다. 또한 파이프라인 가시성을 확인하는 것이 좋습니다.

SSH 키를 파일 유형 변수로 추가#

SSH 키를 프로젝트에 추가하려면 키를 파일 유형 CI/CD 변수로 추가합니다:

1. Visibility를 Visible로 설정합니다.

   [!note] SSH 키에는 공백 문자가 포함되어 있으므로 Masked 또는 Masked and hidden 변수에는 공백 문자를 포함할 수 없기 때문에 가시성 설정은 반드시 Visible이어야 합니다. SSH 키가 job 로그에 표시되지 않도록 변수에 cat이나 tee 같은 명령을 실행하지 마세요.

2. Key 텍스트 상자에 변수 이름을 입력합니다. 예를 들어 SSH_PRIVATE_KEY.

3. Value 텍스트 상자에 개인 키 내용을 붙여넣습니다. 값은 개행 문자(LF 문자)로 끝나야 합니다. 개행을 추가하려면 저장 전 마지막 줄 끝에서 Enter 또는 Return을 누르세요.

SSH 키를 일반 변수로 추가#

파일 유형 CI/CD 변수를 사용하지 않으려면 SSH 예시 프로젝트를 참조하세요. 이 방법은 파일 유형 변수 대신 일반 CI/CD 변수를 사용합니다. 일반적으로 파일 유형 변수가 선호됩니다. 멀티라인 형식을 유지하고 형식 관련 오류 위험을 줄이기 때문입니다.

Docker executor를 사용할 때 SSH 키#

CI/CD job이 Docker 컨테이너에서 실행되면 환경이 격리됩니다. 코드를 개인 서버에 배포하기 위해 SSH 키 쌍을 사용할 수 있습니다.

1. 새 SSH 키 쌍 생성. SSH 키에 패스프레이즈를 추가하지 마세요. before_script가 패스프레이즈를 요청할 수 있습니다.

2. 개인 키를 SSH_PRIVATE_KEY라는 파일 유형 CI/CD 변수로 추가합니다.

3. before_script 액션으로 .gitlab-ci.yml을 수정합니다. 다음 예시는 Debian 기반 이미지와 job이 패키지를 설치할 수 있는 권한이 있는 컨테이너에서 실행된다고 가정합니다.

   before_script:
     ##
     ## Install ssh-agent if not already installed, it is required by Docker.
     ## (change apt-get to yum if you use an RPM-based image)
     ##
     - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )'
   
     ##
     ## Run ssh-agent (inside the build environment)
     ##
     - eval $(ssh-agent -s)
   
     ##
     ## Give the right permissions, otherwise ssh-add will refuse to add files
     ## Add the SSH key stored in SSH_PRIVATE_KEY file type CI/CD variable to the agent store
     ##
     - chmod 400 "$SSH_PRIVATE_KEY"
     - ssh-add "$SSH_PRIVATE_KEY"
   
     ##
     ## Create the SSH directory and give it the right permissions
     ##
     - mkdir -p ~/.ssh
     - chmod 700 ~/.ssh
   
     ##
     ## Optionally, if you use Git commands, set the user name and email.
     ##
     # - git config --global user.email "user@example.com"
     # - git config --global user.name "User name"
   

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

4. 개인 서버의 SSH 호스트 키가 확인되었는지 확인합니다.

5. 마지막 단계로 첫 번째 단계에서 생성한 공개 키를 빌드 환경 내에서 접근하려는 서비스에 추가합니다. 개인 GitLab 리포지터리에 접근하는 경우 배포 키로 추가해야 합니다.

이제 빌드 환경에서 개인 서버 또는 리포지터리에 접근할 수 있습니다.

Shell executor를 사용할 때 SSH 키#

Docker가 아닌 Shell executor를 사용하는 경우 SSH 키를 더 쉽게 설정할 수 있습니다.

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

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

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

   sudo su - gitlab-runner
   

3. 새 SSH 키 쌍 생성. SSH 키에 패스프레이즈를 추가하지 마세요. before_script가 패스프레이즈를 요청할 수 있습니다.

4. 마지막 단계로 이전에 생성한 공개 키를 빌드 환경 내에서 접근하려는 서비스에 추가합니다. 개인 GitLab 리포지터리에 접근하는 경우 배포 키로 추가해야 합니다.

키를 생성한 후 핑거프린트를 수락하기 위해 원격 서버에 로그인을 시도합니다:

ssh example.com

GitLab.com의 리포지터리에 접근하려면 git@gitlab.com을 사용합니다.

SSH 호스트 키 확인#

개인 서버의 공개 키를 확인하여 중간자 공격의 대상이 되지 않도록 하는 것이 좋은 관행입니다. 의심스러운 일이 발생하면 job이 실패하기 때문에 알 수 있습니다(공개 키가 일치하지 않으면 SSH 연결이 실패합니다).

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

## Use the domain name
ssh-keyscan example.com

## Or use an IP
ssh-keyscan 10.0.2.2

호스트를 파일 유형 CI/CD 변수로 프로젝트에 추가합니다. 단:

• Key로 SSH_KNOWN_HOSTS를 사용합니다.
• Value로 ssh-keyscan의 출력을 사용합니다.

여러 서버에 연결해야 하는 경우 모든 서버 호스트 키를 변수의 Value에 수집해야 하며 키당 한 줄씩 입력합니다.

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

before_script:
  ##
  ## Assuming you created the SSH_KNOWN_HOSTS file type CI/CD variable:
  ##
  - cp "$SSH_KNOWN_HOSTS" ~/.ssh/known_hosts
  - chmod 644 ~/.ssh/known_hosts

문제 해결#

오류: ... error in libcrypto#

CI/CD job에서 SSH 키를 로드할 때 다음 오류가 발생할 수 있습니다:

Error loading key "/builds/path/SSH_PRIVATE_KEY": error in libcrypto

이 문제는 SSH 키 값이 개행 문자(LF 문자)로 끝나지 않을 때 발생할 수 있습니다.

이 문제를 해결하려면 파일 유형 CI/CD 변수를 편집하고 변수를 저장하기 전에 SSH 키의 -----END OPENSSH PRIVATE KEY----- 줄 끝에서 Enter 또는 Return을 누르세요.

오류: ... value cannot contain...#

CI/CD 변수로 SSH 키를 저장할 때 오류가 발생할 수 있습니다:

Unable to create masked variable because: The value cannot contain the
following characters: whitespace characters.

이 문제는 변수 Visibility가 Masked 또는 Masked and hidden으로 설정된 경우 발생합니다. 마스킹된 변수는 공백이 없는 단일 줄이어야 하지만 SSH 키에는 마스킹과 호환되지 않는 공백 문자가 포함됩니다.

이 문제를 해결하려면 SSH 키를 파일 유형 변수로 추가할 때 Visibility를 Visible로 설정하세요. 파일 유형 변수는 job 로그에 노출되지 않아 키 값에 대한 추가적인 보호 레이어를 제공합니다.