🚀 Coolify에서 Gitea Git 저장소에 SSH 키로 안전하게 연결하는 방법

초보자도 따라할 수 있도록, 실전 위주로 정리한 완벽 가이드입니다. Gitea와 Coolify를 사용하여 자동 배포를 구현하고 싶은 분들을 위한 문서입니다.

---

🧩 왜 SSH 키가 필요한가요?

Git 저장소에 안전하게 접근하려면 비밀번호 방식보다 보안성이 높은 SSH 키 방식을 사용하는 것이 일반적입니다. Coolify처럼 자동 배포를 위한 플랫폼은 SSH 키 인증을 기본으로 사용합니다.

---

📦 구성 개요

항목	내용
배포 플랫폼	Coolify (Self-hosted)
Git 저장소	Gitea (Docker 기반, 포트 22222 사용)
인증 방식	SSH Key (Public/Private Key Pair)

---

🛠️ Step 1. Coolify에서 SSH 키 생성하기

Coolify 대시보드 → Security 메뉴에서 Private Key 생성

• Public Key는 자동 생성됨
• Private Key는 Coolify가 내부적으로 저장하고 사용함

👉 이 공개키(ssh-ed25519 ...)를 복사해서 Gitea에 등록해야 합니다.

---

🔑 Step 2. Gitea에 공개키 등록하기

1. Gitea 로그인 (자신의 사용자 계정)
2. 우측 상단 프로필 > Settings
3. 좌측 메뉴에서 SSH / GPG Keys
4. Add Key 클릭
5. Coolify에서 생성한 공개키 전체를 붙여넣기
6. 이름은 coolify-deploy-key 등으로 지정

✅ 공개키 등록이 완료되면 Gitea는 해당 키로 접속하는 사용자를 인식합니다.

---

🌐 Step 3. 포트가 다를 때 SSH 접속하는 법

Gitea를 Docker로 운영 중이라면 아래처럼 포트를 다르게 매핑했을 수 있습니다:

-p 22222:22

이럴 땐 다음처럼 포트 명시해서 SSH 접속:

ssh -i ~/.ssh/coolify_key -p 22222 git@your-gitea-host

메시지 예시:

Hi there! You've successfully authenticated with the key...

→ 이 메시지가 보이면 인증 성공입니다.

---

🧪 Step 4. 직접 SSH 테스트하기

ssh -i ~/.ssh/coolify_key -p 22222 git@your-gitea-host

만약 다음과 같은 메시지가 보이면?

Permission denied (publickey).

👉 이 경우:

• 키 경로를 정확히 지정했는지 확인 (-i 옵션)
• Gitea에 정확히 해당 공개키가 등록되었는지 재확인
• 키 권한 설정 확인: chmod 600 ~/.ssh/coolify_key

---

⚙️ Step 5. Coolify에서 Git Repository 연결하기

Coolify 앱 설정 → Git 탭에서 다음 정보 입력:

• Repository URL:

ssh://git@your-gitea-host:22222/your-user/your-repo.git

• Build Pack: Dockerfile 또는 Static (선택사항)
• Private Key: 앞서 생성한 키 선택

---

📌 마무리 요약

항목	설명
공개키 등록 위치	Gitea 웹 → Settings → SSH Keys
접속 계정	git 사용자 (Gitea는 내부적으로 매핑)
인증 성공 메시지	"You've successfully authenticated..."
Git clone 주소	ssh://git@도메인:포트/사용자/저장소.git

---

🎯 Tip: .ssh/config 설정 예시

Host your-gitea-host
  HostName your-gitea-host
  Port 22222
  User git
  IdentityFile ~/.ssh/coolify_key
  IdentitiesOnly yes

→ 이제는 그냥 다음처럼 간단하게 접속 가능:

ssh your-gitea-host

---

🙌 마치며

Coolify에서 Gitea 저장소에 SSH 키로 접근하는 구조를 이해하면, 자동 배포 시스템을 안정적이고 안전하게 구성할 수 있습니다. 특히 Gitea처럼 개인 서버에서 운영하는 Git 저장소에 연결할 때 이 방식은 필수입니다.

필요하시다면 다음 글에서 "Coolify에서 자동 배포 트리거 + Webhook 설정"도 소개해드릴게요.