[Tool/Git] GitHub SSH 인증 발급 및 등록하기 (리파지토리마다 설정하기)

1. 왜 SSH를 사용하나요?

GitHub저장소의 코드를 push/pull 하려면 인증이 필요하다.

예전에는 아이디/비밀번호 방식도 가능했지만, 지금은 보안상 Token 혹은 SSH Key 방식을 사용한다.

이글에서는 추가적으로 각 리파지토리마다 ssh를 발급하는 법을 알아보고 권한을 나누는 방식으로 진행한다.

 

1.1 선행 과제 - ssh 발급 툴

선행적으로 발급을 진행할때 ssh-keygen 같은게 설치되어서 ssh 키를 발급 받을 수 있어야한다.

서버에 키를 둬야 편하니 ssh를 사용할 서버에 사용하는 것이 좋다. 다른거 사용해서 발급해도 되지만 이번에는 ssh-keygen 을 사용한다.

ssh-keygen: command not found

Debian / Ubuntu

apt update
apt install -y openssh-client

Alpine

apk add --no-cache openssh-client

1.2 선행 과제 - git 명령어

ssh 인증 테스트나 Jenkins pipeline에서 github 저장소를 가져오려면 git도 필요하다.

확인 방법은 다음과 같다.

git --version

정상 출력 예시

git version 2.39.2

 

Debian / Ubuntu

apt update
apt install -y git

Alpine

apk add --no-cache git

1.3 SSH 키를 저장할 디렉터리에 쓰기 권한이 있어야 함

SSH 키는 일반적으로 사용자 홈 디렉터리 아래의 .ssh 디렉터리에 저장한다.

현재 사용자 정보를 확인한다.

whoami

SSH 디렉터리를 생성하고 파일을 만들 수 있는지 확인한다.

mkdir -p ~/.ssh
touch ~/.ssh/test

에러가 발생하지 않으면 정상적으로 쓰기 권한이 있는 것이다.

작업 후 테스트 파일은 삭제해도 된다.

rm ~/.ssh/test

1.4 GitHub에 접속 가능한 네트워크 환경이여야 함

SSH 키 생성 자체는 인터넷 연결 없이도 가능하다.

하지만 GitHub에 공개키를 등록한 뒤 SSH 인증 테스트를 하려면 GitHub에 접근할 수 있어야 한다.

예를 들어 아래 명령어로 연결을 확인할 수 있다.

ssh -T git@github.com

또는

curl https://github.com

회사 내부망이나 보안 정책이 적용된 환경에서는 SSH 포트(22번)가 차단되어 있을 수 있다.

이 경우 GitHub SSH 연결이 실패할 수 있으므로 네트워크 정책을 먼저 확인하는 것이 좋다.

1.5 SSH가 유지되는 환경이여야함

이 부분은 운영 환경에서 특히 중요하다.

SSH 키를 생성한 위치가 임시 저장소라면 시스템 재설치, 서버 교체, 컨테이너 재생성 등의 작업 이후 키가 사라질 수 있다.

예를 들어 아래와 같은 파일이 생성된다.

~/.ssh/id_ed25519_decisionlog
~/.ssh/id_ed25519_decisionlog.pub

이 파일들이 삭제되면 GitHub에 등록된 공개키와 연결되는 개인키도 함께 사라지게 된다.

실제 운영 환경에서는 보통 다음과 같은 방법을 사용한다.

1. Jenkins Credentials에 SSH Private Key 등록
2. 영구 저장소(Volume, NAS 등)에 SSH 키 보관
3. 서버 백업 정책에 SSH 키 포함

SSH 키는 GitHub 인증의 핵심 정보이므로 안전하게 보관하고 복구 가능한 구조를 갖추는 것이 중요하다.

---

2. 발급 진행하기

2.1 SSH키 발급

GitHub 접근용 SSH 키를 아래 명령어로 생성한다.

ssh-keygen -t ed25519 -C "example-project-key" -f ~/.ssh/id_ed25519_example

옵션의미

옵션	의미
-t ed25519	ed25519 알고리즘으로 SSH 키 생성
-C "example-project-key"	키를 구분하기 위한 주석
-f ~/.ssh/id_ed25519_example	생성할 키 파일 위치와 이름 지정

기본 파일명인 id_ed25519를 그대로 사용해도 된다.

하지만 프로젝트나 사용 환경별로 SSH 키를 구분하려면 id_ed25519_example처럼 이름을 명확하게 지정하는 것이 좋다.

 

명령어를 실행하면 passphrase를 입력하라는 메시지가 나온다.

Enter passphrase (empty for no passphrase):

자동 배포나 서버 환경에서 사용할 키라면 보통 비워두고 Enter를 입력한다.

다시 한 번 확인 메시지가 나온다.

Enter same passphrase again:

다시 Enter를 입력한다.

정상적으로 생성되면 아래와 비슷한 메시지가 출력된다.

Your identification has been saved in /home/example-user/.ssh/id_ed25519_example
Your public key has been saved in /home/example-user/.ssh/id_ed25519_example.pub

2.2 생성된 키 확인

키가 정상적으로 생성되었는지 확인한다.

ls -al ~/.ssh

아래 두 파일이 생성된다.

id_ed25519_example
id_ed25519_example.pub

각 파일의 역할은 다음과 같다.

파일	역할	설명
id_ed25519_example	개인키	내 환경에만 보관
id_ed25519_example.pub	공개키	GitHub에 등록

중요한 점은 GitHub에 등록하는 파일은 .pub 파일이라는 것이다.

등록 O: id_ed25519_example.pub
등록 X: id_ed25519_example

 

2.2.1 공개키 확인

GitHub에 등록할 공개키 내용을 출력한다.

cat ~/.ssh/id_ed25519_example.pub

출력 결과는 실제 키를 그대로 노출하지 않고 아래처럼 마스킹해서 기록한다.

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIxxxxxxxxxxxxxxxxxxxxxxxxxxxx example-project-key

 

공개키도 공개되면 좋을게 없으니 공개하지 말자

특히 개인키는 절대 노출하면 안 된다.

---

3. GitHub에 등록하기

당신이 배포할 리파지토리의 Settigs로 간다.

목록중 Deploy Keys를 클릭후 Add deploy key를 선택한다.

여기서 이제 아까 나온 공개키를 Key에 넣고 Add Key를 하면 된다.

Allow write access를 선택하면 write 권한도 챙기는데 pull 만한다면 굳이 표시할 필요 없다.

 

여기까지 진행하면 GitHub 저장소에 SSH 공개키 등록이 완료된다.

이제 키를 발급한 환경에서 GitHub 저장소에 접근할 수 있는지 확인하면 된다.

ssh -i ~/.ssh/id_ed25519_example -T git@github.com

정상적으로 인증되면 아래와 비슷한 메시지가 출력된다.

Hi example-user! You've successfully authenticated, but GitHub does not provide shell access.

이제 GitHub 저장소에 SSH 방식으로 접근할 준비가 끝났다.

다음 단계에서는 이 SSH 인증을 Jenkins Pipeline과 연결해서, GitHub 저장소의 코드를 가져오고 Docker 이미지 빌드 및 서버 배포까지 이어지도록 구성할 수 있다.