Jenkins URL cannot start with localhost 오류 해결

🔴 문제 상황

GitLab Branch Source 플러그인을 사용해 멀티브랜치 파이프라인 설정을 저장하는 과정에서
아래 오류 팝업이 발생하며 설정 저장이 실패했다.

A problem occurred while processing the request
Logging ID=xxxx

---

🔍 원인 분석

Docker로 실행 중인 Jenkins 컨테이너 로그를 확인한 결과, 원인은 다음과 같았다.

java.lang.IllegalStateException: Jenkins URL cannot start with http://localhost
URL is: http://localhost:8080/
    at io.jenkins.plugins.gitlabbranchsource.GitLabHookCreator.checkURL(...)

핵심 원인

• Jenkins 시스템 URL이 http://localhost:8080으로 설정
• GitLab Branch Source 플러그인이
  Webhook 자동 등록을 위해 외부에서 접근 가능한 Jenkins URL을 요구
• localhost는 외부(GitLab)에서 접근 불가 → 설정 저장 시 예외 발생

즉, Jenkins URL 미설정(또는 localhost 유지) 이 직접적인 원인이었다.

---

🧠 왜 이런 문제가 발생했는가?

Jenkins의 Jenkins URL 값은 Jenkins가 외부 시스템과 연동할 때 사용하는 기준 URL(Base URL) 로 사용된다.

특히 GitLab Branch Source 플러그인은:

• 멀티브랜치 설정 저장 시
• Jenkins URL을 기준으로 GitLab Webhook URL을 생성
• 이 URL이 localhost이면 의도적으로 예외를 발생시킴

GitLab과 CI/CD 파이프라인을 연동할 때 Jenkins URL은 GitLab Webhook이 호출할 외부 접근 가능한 기준 URL이어야 한다.

Jenkins URL이 localhost로 설정되면 GitLab에서 접근할 수 없으므로, 플러그인은 이를 유효하지 않은 설정으로 판단해 예외를 발생시킨다.

---

✅ 해결 방법

방법 1. Jenkins UI에서 수정 (권장)

1. Manage Jenkins → System
2. Jenkins Location 섹션 이동
3. Jenkins URL을 실제 외부 접속 주소로 변경

예시:

https://jenkins.example.com/

또는

http://<EC2_PUBLIC_IP>:8080/

4. 저장 후 멀티브랜치 설정 다시 저장 → 정상 동작

---

방법 2. UI 접근 불가 시 (Docker 직접 수정)

docker exec -it jenkins sh

cat /var/jenkins_home/jenkins.model.JenkinsLocationConfiguration.xml

sed -i 's#http://localhost:8080/#https://jenkins.example.com/#g' \
/var/jenkins_home/jenkins.model.JenkinsLocationConfiguration.xml

exit
docker restart jenkins

---

📌 정리

• Jenkins URL은 GitLab Branch Source + Webhook 자동 등록 사용 시 필수 설정
• localhost로 두면 설정 저장 단계에서 바로 오류 발생
• 외부 접근 가능한 실제 URL을 반드시 지정해야 함