[Git] Spring Tool Suite(STS) 4에서 GitHub 프로젝트 Clone 및 Import하는 완벽 가이드

 

Spring 기반 프로젝트를 진행할 때, 외부 Git 저장소에 있는 코드를 불러와 작업하고 싶을 때가 많습니다. 이번 포스팅에서는 Spring Tool Suite(STS) 4를 이용해 GitHub에 있는 프로젝트를 clone하고, 개발 환경에 import하는 전 과정을 상세히 안내드립니다. Git이나 STS가 처음이신 분들도 그대로 따라 하기만 하면 문제없이 설정할 수 있도록 하나하나 캡처와 함께 설명해 드립니다.

---

🧩 사전 준비 사항

Spring Tool Suite 4에서 Git 프로젝트를 clone하여 import하기 위해서는 다음 준비물이 필요합니다:

1. Spring Tool Suite 4 (STS4) – Eclipse 기반 Spring 전용 IDE
2. Git 설치 – 시스템에 Git이 설치되어 있어야 합니다.
3. GitHub 계정 및 원격 저장소 URL – 공개 또는 개인 저장소 주소
4. GitHub 인증 정보 – HTTPS 또는 SSH 방식 중 선택 가능

---

1. STS에서 Git 프로젝트 Import 시작하기

가장 먼저 STS의 Import 메뉴로 진입합니다.

🔹 1-1. File > Import 메뉴 선택

STS의 상단 메뉴바에서 File > Import... 를 클릭합니다.

• 해당 메뉴는 새로운 프로젝트를 STS로 불러올 때 사용하는 기본 경로입니다.
• 단축키: Alt + F + I를 활용하면 빠르게 접근할 수 있습니다.

---

2. Git 프로젝트 불러오기 위한 옵션 선택

🔹 2-1. Git > Projects from Git 선택

Import 메뉴가 열리면 Git > Projects from Git 옵션을 찾아 선택하고 Next 버튼을 누릅니다.

이 옵션은 외부 Git 저장소에서 프로젝트를 불러올 때 사용하는 표준 절차입니다.

---

3. Clone 방식 선택하기

🔹 3-1. Clone URI 선택

프로젝트를 직접 clone하는 방식으로 진행하기 위해, Clone URI를 선택한 뒤 Next를 클릭합니다.

• 다른 옵션으로는 Existing local repository 등이 있지만, 우리는 원격 저장소에서 처음부터 가져오기 때문에 Clone URI가 맞습니다.

---

4. 원격 저장소 정보 입력

🔹 4-1. GitHub 주소 입력

GitHub에서 복사한 저장소 주소를 입력합니다. 예를 들어:

https://github.com/username/repository-name.git

해당 주소를 입력하면 나머지 정보는 자동으로 채워집니다.

항목 내용

Host	github.com
Repository Path	/username/repository-name.git
Protocol	https 또는 ssh

🔐 개인 저장소의 경우 인증 정보 입력이 필요합니다.
🔁 SSH 인증이 더 안정적이며, 비밀번호 없이 인증 가능한 장점이 있습니다.

---

5. 인증 문제 해결 (HTTPS vs SSH)

🔹 5-1. SSH 방식이 더 안전하고 편리

테스트 중 인증 실패가 반복될 경우, SSH 주소를 사용하는 것이 좋습니다. SSH 방식은 GitHub에서 공개 키 등록만 해두면 별도의 비밀번호 입력 없이 자동 인증이 됩니다.

• SSH 주소 예시:

git@github.com:username/repository-name.git

⚠️ SSH Key는 사전에 GitHub에 등록해 두어야 합니다.
등록 방법은 [GitHub SSH Key 등록 가이드]를 참조하세요.

---

6. 브랜치 선택

🔹 6-1. 원하는 브랜치 선택

다음 단계에서는 Git 저장소의 브랜치 리스트가 나타납니다. 이 중에서 개발에 사용할 브랜치를 체크합니다.

• 기본 브랜치는 main 또는 master입니다.
• 여러 브랜치가 존재할 경우 필요한 기능/버전의 브랜치를 선택하세요.

✅ 브랜치 선택 후에는 Clone 및 Checkout 작업이 자동으로 수행됩니다.

---

7. 프로젝트 저장 위치 및 remote name 설정

🔹 7-1. 기본 경로 및 설정 그대로 사용 가능

• Directory: 프로젝트를 저장할 로컬 경로
• Initial branch: 선택한 브랜치가 자동 지정
• Remote name: 기본은 origin

remote name은 나중에 git push, git pull 등에서 사용되는 원격 저장소 별칭입니다.

---

8. Import 방식 선택

🔹 8-1. Import as general project 선택

프로젝트를 어떤 형식으로 불러올지 선택하는 단계입니다.

✅ Import as general project를 선택하세요.
이 방식은 Java 프로젝트가 아닌 구조에도 유연하게 대응할 수 있습니다.

• 나중에 Configure > Convert to Maven Project 등을 통해 변경 가능

---

9. 프로젝트 이름 및 마무리

🔹 9-1. 폴더명 설정

기본적으로 GitHub 저장소 이름이 자동 지정됩니다. 원한다면 프로젝트 폴더명을 변경할 수 있습니다.

• 예: spring-rest-api-sample → my-spring-api

🔹 9-2. Finish 클릭

모든 설정이 완료되면 Finish 버튼을 클릭합니다.
프로젝트가 자동으로 clone되고 STS 내에 import됩니다.

---

✅ 마무리 및 확인

STS의 Package Explorer에서 clone한 프로젝트가 잘 보이는지 확인합니다. 만약 프로젝트가 closed 상태라면, 마우스 우클릭 → Open Project로 열 수 있습니다.

🔧 필요에 따라 추가 설정

• Maven Project인 경우, pom.xml 우클릭 → Maven > Update Project
• Gradle Project인 경우, build.gradle 우클릭 → Gradle > Refresh Gradle Project

---

🧠 팁: 자주 발생하는 오류와 해결 방법

문제 해결 방법

인증 실패	SSH 방식 사용, GitHub 토큰 재생성
프로젝트 구조 인식 불가	Maven/Gradle import로 전환
프로젝트 import 안됨	STS 재시작, .git 폴더 확인

---

✨ 결론: STS와 Git 연동, 어렵지 않아요!

Spring Tool Suite(STS) 4에서 GitHub 프로젝트를 clone하고 import하는 과정은 처음엔 복잡해 보여도 몇 번만 해보면 금방 익숙해집니다. 특히 팀 프로젝트나 오픈소스 기반 개발을 할 때 Git과의 연동은 필수적인 작업입니다.

이번 포스팅을 통해 Git 연동과 프로젝트 셋업을 한 번에 마스터해보세요!
또한, 다음 글에서는 STS에서 Git 커밋, 푸시(push), 풀(pull)하는 방법도 자세히 다뤄드릴 예정입니다.