Jenkins ssh key 설정 방법(Credentials로 git 연동) 2가지

Jenkins에서 특정 프로젝트의 git 저장소 활용은 빼놓을 수 없습니다. 아무에게나 git 저장소를 개방할 수는 없으며, 허가받은 사용자에게만 인증처리를 해주어야 합니다. 그럼 프로젝트에서 git 연동을 위한 인증 처리 방법으로 Jenkins SSH Key 설정 방법을 살펴보겠습니다.

프로젝트에서 Git 연동(feat. Jenkins SSH Key 설정)

앞서 말씀드렸듯이 Jenkins에서 git repository를 설정하는 경우 Credentials를 통해서 인증처리를 해 줘야 합니다. Jenkins가 해당 리포지터리를 접근하게 되면 Git Server(Github, Gitlab, Bitbucket 등)는 허가받은 사용자인지 확인한 후 접근을 허용합니다. 이를 위해서 여기에서는 Jenkins SSH Key 설정을 통해서 접근할 것입니다.

Jenkins에서 Repository URL을 설정해 주면 아래와 같이 원격 저장소를 읽어올 수 없다고 나옵니다. 인증된 SSH키가 등록되어 있지 않으니 당연한 결과겠죠.

그림 1. Jenkins 프로젝트에서 git 연동하기: 인증처리 아직 안 됨
그림 1. Jenkins 프로젝트에서 git 연동하기: 인증처리 아직 안 됨

Git 연동: 저장소 인증 방법 2가지

Jenkins 프로젝트에서 Git 저장소에 인증하는 것은 두 가지 방법을 사용해서 문제를 해결할 수 있습니다.

Jenkins 사용자의 home 디렉토리 활용

첫번째는 ~/.ssh에 공개키와 개인키를 생성하고, Git 서버에 공개키를 등록해 주는 방법입니다. 이 경우에는 Credentials를 별도로 생성할 필요가 없으며, ~/.ssh 하위에 있는 Jenkins 계정의 ssh 키로 인증하는 방법입니다.

별도의 개인키/공개키 쌍 활용

두번째는 이미 가지고 있는 개인키, 공개키 쌍이 있는 경우이고 jenkins의 개인키와 공개키를 별도의 용도로 사용하고 있고, 키를 함께 사용하기 원하지 않는 경우라면, Credentials에 개인키를 등록해 주고, Git 서버에 공개키를 등록해 주는 방법입니다.

어떤 방법이든 SSH 공개키(public key)와 비밀키(private key) 쌍을 필요로 합니다. 이미 공개키와 개인키 쌍이 준비된 경우에는 아래 과정을 생략합니다.

SSH 공개키와 비밀키 생성하기

Docker에서 Jenkins를 이용하는 경우로 예를 들어 설명하겠습니다. 우선 Docker 컨테이너의 shell로 접근하고, ssh-keygen 명령어를 실행해 줍니다.

docker exec -it jenkins-server /bin/sh
~ $ ssh-keygen
ShellScript

원하는 파일 경로가 있다면 입력해 주시고, 그렇지 않으면 넘어갑니다. 기본적으로 개인키와 공개키는 각각 ~/.ssh/id_rsa와 id_rsa.pub 파일로 생성됩니다. 키 쌍에 비밀번호를 입력해 주면 되며, 그냥 엔터를 치면 비밀번호 없이 만들어집니다. 그러면 핑거프린트를 알려주고, RSA 3072 bit 키를 SHA256을 사용해서 만들었다고 알려줍니다.

그림 2. ssh-keygen 사용하여 공개키/개인키 쌍 생성
그림 2. ssh-keygen 사용하여 공개키/개인키 쌍 생성

위의 경우 jenkins의 홈 디렉토리가 /var/jenkins_home이기 때문에 /var/jenkins_home/.ssh 하위에 개인키 id_rsa와 공개키 id_rsa.pub이 만들어집니다.

ls -la ~/.ssh
ShellScript

ls 명령어로 만들어진 파일을 확인합니다.

그림 3. 만들어진 RSA 개인키/공개키 쌍
그림 3. 만들어진 RSA 개인키/공개키 쌍

방금 생성한 키를 그냥 사용하실 거라면 Credentials에 별도로 등록하지 않고 마지막 단계 Git 저장소를 알려진 호스트로 등록하기로 넘어가시면 됩니다.

Jenkins에 Credentials 등록

Jenkins에 Credentials를 등록할 때에는 SSH 개인키가 필요합니다. 위에서 생성한 파일 중 id_rsa입니다. 홈디렉토리로 이동하고 .ssh로 이동해서 id_rsa의 내용을 열람한 후 복사해 둡니다.

cd ~/.ssh
cat id_rsa
ShellScript

이제 Jenkins에서 Credentials를 등록할 차례입니다. “Jenkins 관리”에서 “Manage Credentials”로 들어갑니다.

그림 4. Manage Credentials 메뉴
그림 4. Manage Credentials 메뉴

이제 Stores scoped to Jenkins에서 Domains의 (global)을 눌러주면 Add credentials가 나옵니다. 눌러줍니다.

그림 5. Jenkins에 Credentials 추가하기
그림 5. Jenkins에 Credentials 추가하기

이제 Credentials를 추가하기 위한 입력 폼이 아래와 같이 뜹니다. 우선 Scope는 SSH Username with private key를 선택합니다. ID는 비워두면 UUID가 생성되고, 원하는 ID를 직접 입력해도 됩니다. Username에 식별하기 위한 이름을 적어줍니다. 그리고 Private Key가 보이죠. Add 버튼을 누르고 위에서 복사한 Private Key의 내용을 붙여넣습니다. passphrase가 있다면 입력해 준 후, Create 버튼을 눌러줍니다.

그림 6. Jenkins SSH Key 설정: 새로운 Credentials 추가하기
그림 6. Jenkins SSH Key 설정: 새로운 Credentials 추가하기

아래와 같이 생성된 Credentials를 확인할 수 있습니다.

그림 7. Global credentials에 추가된 Credentials 확인
그림 7. Global credentials에 추가된 Credentials 확인

Private Key와 Public Key는 쌍이죠? 이제 공개키를 Github, GitLab, BitBucket 등의 리포지터리 서버에 등록해 주셔야 합니다. 서비스 마다 약간의 차이가 있겠지만, 사용자 설정으로 가시면 SSH Key를 등록할 수 있는 곳이 있습니다. 그곳에 여러분이 생성한 공개키를 추가해 주시면 됩니다.

Project에서 Git Repository 설정하기

리포지터리 주소를 입력해 주고, Credentials를 선택해 줍니다. 만약 Git Server에 공개키를 등록하지 않았다면 아래와 같은 화면을 보게 됩니다. Permission denied (publickey) 보이시죠? 그러니 서버에 공개키 꼭 등록해 주셔야 합니다.

그림 8. Git 연동에서 Git 서버에 공개키 등록하지 않은 경우 발생하는 오류
그림 8. Git 연동에서 Git 서버에 공개키 등록하지 않은 경우 발생하는 오류

서버에 공개키가 제대로 등록되었는데도, 아래와 같은 화면을 볼 수도 있습니다. 이게 무슨 일일까요? 아래와 같은 메시지가 나오는 분 계신가요?

그림 9. Jenkins 사용자의 known_hosts에 등록되어있지 않은 경우 발생하는 오류
그림 9. Jenkins 사용자의 known_hosts에 등록되어있지 않은 경우 발생하는 오류

아니, 이게 대체 무슨 일일까요? Credentials도 제대로 추가하고 선택해 주었고, Git 서버에 공개키도 정상적으로 업로드 했는데, 왜 이러는 걸까요. 여기에서 해 줄 일이 하나 더 있습니다.

Git 저장소를 알려진 호스트로 등록하기

위의 오류 메시지 “stderr: No RSA host key is known for bitbucket.org and you have requested strict checking. Host key verification failed. fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.”를 보면 bitbucket.org에 대한 알려진 RSA Host Key가 없다고 합니다. 그리고 접속 권한과 리포지터리의 존재를 분명히 해 주라고 안내해 주고 있습니다. 이 경우에는 위에 있는 command를 shell에서 입력해 줍니다. 그리고 yes를 입력해 줍니다. git@ 뒷부분은 여러분의 git 리포지터리 주소를 적으시면 됩니다. Are you sure you want to continue connecting? 이라는 질문에서 yes를 입력하시면 됩니다.

그림 10. ~/.ssh/known_hosts에 Git 저장소 추가
그림 10. ~/.ssh/known_hosts에 Git 저장소 추가

이제 bitbucket.org는 jenkins가 알고있는 호스트가 되었습니다. ~/.ssh/known_hosts에 해당 내용이 추가됐습니다.

이제 Jenkins 프로젝트 설정에 다시 들어가 보시면 어떤 오류 알림도 없는 것을 확인하실 수 있습니다. 젠킨스 SSH Key 설정을 통한 Git 연동이 성공적으로 끝난 겁니다. 축하드립니다.

Jenkins 프로젝트에서 Git 인증 설정을 처음 해 보시는 분들께 도움이 되길 바랍니다. 궁금한 것이나 오류 발생과 관련해서는 댓글 달아주시면 도와드리겠습니다.

관련 자료

Jenkins git 플러그인 공식 문서를 참고하시면 도움이 됩니다.

같이 읽으면 좋은 글

git 기본 브랜치 master에서 main으로 변경하기

master냐 main이냐 등의 여러 논란 끝에 master를 사용하지 않는 분위기죠.
git init으로 초기화 했을 때 메인 브랜치를 main으로 설정하는 방법 확인해 보겠습니다.

기본 브랜치 설정 확인

우선 git init을 했을 때 별다른 말 없이 빈 Git 리포지터리를 만들었다고 한다면, 이미 메인 브랜치 이름에 대한 설정이 돼 있다는 것을 의미합니다.

만약 git init을 했는데, 아래와 같은 힌트 메시지가 나온다면, 기본 브랜치 값 설정이 안 된 상태라는 의미입니다.

hint: Using 'master' as the name for the initial branch. This default branch name
hint: is subject to change. To configure the initial branch name to use in all
hint: of your new repositories, which will suppress this warning, call:
hint: 
hint: 	git config --global init.defaultBranch <name>
hint: 
hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and
hint: 'development'. The just-created branch can be renamed via this command:
hint: 
hint: 	git branch -m <name>

초기화하는 방법은 2가지가 있습니다.

명령어로 기본 브랜치 변경하기

위에서 힌트를 통해 알려주는 대로 명령어를 한 줄 입력하는 방식입니다.

git config --global init.defaultBranch main

설정파일 편집해서 기본 브랜치 변경하기

~/.gitconfig 파일을 열어서 아래의 내용을 넣어주는 것입니다.

[init]
  defaultBranch = main

현 리포지터리의 기본 브랜치만 변경하기

혹은, 기본설정은 그대로 두고, 현재 생성한 리포지터리의 기본 브랜치 이름만 바꾸고 싶다면 다음과 같이 명령합니다.

git branch -m main