[Spring Cloud][업그레이드] Gateway starter가 Boot 4.1에서 verifier를 통과했는데도 CI가 깨질 때 starter override와 BOM drift를 어디부터 다시 보나

IT 리서치 노트

[Spring Cloud][업그레이드] Gateway starter가 Boot 4.1에서 verifier를 통과했는데도 CI가 깨질 때 starter override와 BOM drift를 어디부터 다시 보나

Spring Boot 4.1로 올린 뒤 compatibility verifier는 통과했는데 Gateway starter 관련 CI만 계속 깨지는 경우가 있다. 2026년 8월 3일 기준 Spring 공식 문서를 다시 보면, verifier는 Boot-Cloud 조합의 1차 관문일 뿐이고, Spring Cloud는 release train BOM 사용을 권장하며, managed dependency 수동 override는 호환성 문제를 일으킬 수 있다고 경고한다. 이 글은 Gateway starter가 Boot 4.1에서 verifier를 통과했는데도 CI가 깨질 때 starter override와 BOM drift를 어디부터 다시 보는 편이 덜 꼬이는지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 Gateway starter CI 실패는 verifier 설정을 다시 보는 것보다 BOM drift와 starter 수동 버전 핀을 먼저 확인하는 편이 빠르다. verifier는 release train과 Boot 조합의 1차 가드레일이지만, gateway starter의 실제 classpath는 여전히 BOM import 방식과 수동 override에 영향을 받는다. 그래서 CI가 깨질 때는 compatible-boot-versions를 한 번 더 손대기 전에 dependency tree와 starter 좌표부터 봐야 한다.

즉 이 문제는 'Boot 4.1이 안 된다'가 아니라 'verifier는 통과했지만 starter 조합이 어긋났다'는 신호일 때가 많다. 같은 release train 안에서도 starter별 smoke test를 별개로 남기고 로그 결과를 저장하면 재발을 줄일 수 있다.

2. 어디서 실제로 막히는가

실무에서 가장 자주 꼬이는 지점은 세 가지다. 첫째, verifier를 disable하거나 compatible Boot versions override로 일단 통과시킨 뒤 CI 실패도 같은 설정 문제로 본다. 둘째, gateway starter 한 좌표만 수동 버전 핀으로 올려 놓고 BOM은 예전 release train에 그대로 둔다. 셋째, OpenFeign나 다른 starter는 통과하니 gateway도 같은 방식으로 볼 수 있다고 생각한다.

Spring Cloud verifier 문서는 verifier를 끄거나 compatible Boot versions를 override할 수 있다고 설명한다. 하지만 Spring Boot 4.1 시스템 요구사항 문서는 third-party project가 추가 요구사항을 가질 수 있다고 적고, Spring Cloud 프로젝트 페이지는 release train BOM spring-cloud-dependencies 사용을 권장한다. 또 Spring Boot dependency management 문서는 managed dependency를 수동 override하면 compatibility issue가 날 수 있다고 경고한다. 이 네 문서를 같이 읽으면 verifier 통과 뒤의 CI 실패는 BOM drift나 starter override 문제일 가능성이 높다는 결론이 나온다.

• 증상: verifier는 통과하지만 gateway 관련 integration test만 실패한다.
• 실패: compatible-boot-versions 설정을 계속 바꾸며 시간을 쓴다.
• 막힘: gateway starter 좌표를 수동 핀으로 바꿨는지 dependency tree를 안 본다.
• 누락: starter별 smoke test를 한 묶음으로만 보고 gateway branch를 따로 기록하지 않는다.

질문	먼저 볼 곳	실무 판단
verifier 통과 뒤 왜 깨질까	BOM import와 수동 핀	starter drift를 먼저 의심한다
Gateway만 왜 다를까	gateway property / classpath	starter별 smoke test를 따로 본다
어디서 수동 버전이 섞였나	dependency tree와 gradle/maven pin	수동 override를 먼저 지우고 BOM 정렬을 본다

3. 실무에서 적용하는 순서

점검 순서는 다섯 단계가 가장 빠르다. 먼저 verifier 설정은 그대로 두고 dependency tree를 뽑는다. 다음으로 spring-cloud-dependencies BOM import와 Spring Boot BOM import 위치를 확인한다. 세 번째로 gateway starter와 관련 transitive dependency에 수동 버전 핀이 있는지 찾는다. 네 번째로 gateway property binding과 auto-configuration smoke test를 별도로 돌린다. 마지막으로 OpenFeign 등 다른 starter와 다른 점을 diff로 남기고, 각 단계의 결과 파일과 로그 경로를 저장한다.

1. dependency tree부터 뽑아 starter drift를 본다.
2. Spring Cloud release train BOM import를 확인한다.
3. gateway 관련 수동 버전 핀을 먼저 찾는다.
4. gateway property와 auto-config smoke test를 따로 돌린다.
5. 다른 starter와의 차이를 diff로 남긴다.

실제 CI에서는 dependencyInsight나 mvn dependency:tree 결과, gateway starter 좌표, BOM import 위치, gateway route/property smoke test를 같은 메모 표에 두는 편이 좋다. 이때는 build 파일의 import 블록, starter 버전 필드, CI 로그 링크, 실패한 테스트 이름, 재현 명령어를 같이 적어 두어야 비교가 빨라진다. verifier는 통과했는데 gateway만 깨진다면, 대부분은 release train 전체를 다시 맞추거나 수동 override를 걷어내는 쪽이 compatible-boot-versions를 또 건드리는 것보다 짧다.

ci_note:
boot_version=4.1.0
spring_cloud_bom=2026.x
verifier_override=false
gateway_starter_override=true
dependency_tree_diff_saved=true
gateway_smoke_test_failed=true

이 메모가 있으면 'verifier는 통과한다'는 사실과 'starter 조합이 맞는다'는 사실을 섞지 않고, BOM drift를 훨씬 빨리 자를 수 있다. 특히 dependency tree 파일, Gradle/Maven 설정 위치, smoke test 로그, gateway property 결과를 같은 순서로 확인하면 원인 분리가 쉬워진다.

4. 공식 문서와 예시 화면으로 확인하기

첫 공식 화면은 Spring Cloud compatibility verifier 문서다. 여기서는 verifier를 끄거나 compatible Boot versions를 override할 수 있다고 설명한다.

Spring Cloud는 compatibility verifier를 끄거나 compatible Boot versions를 override할 수 있다고 설명한다.

즉 verifier 통과는 1차 관문일 뿐이다. 이 설정만 맞췄다고 starter 레벨의 transitive dependency가 모두 안전해진다는 뜻은 아니다.

두 번째 자료는 Spring Boot 4.1 시스템 요구사항 문장이다. Spring Boot는 third-party project가 별도 요구사항을 가질 수 있다고 명시한다.

Spring Boot 4.1 문서는 third-party project가 추가 요구사항을 가질 수 있다고 설명한다.

Gateway starter가 verifier를 통과했는데도 CI가 깨질 수 있는 이유가 바로 여기다. Boot 자체는 올라왔어도 Spring Cloud release train이나 starter 쪽 조합이 아직 다를 수 있다.

세 번째 공식 화면은 Spring Cloud 프로젝트 페이지의 BOM 권고 문장이다. Spring Cloud는 release train BOM `spring-cloud-dependencies` 사용을 권장한다.

Spring Cloud는 release train BOM `spring-cloud-dependencies` 사용을 권장한다.

이 권고를 무시하고 일부 starter 버전만 수동 핀으로 고정하면 verifier는 지나도 CI에서 runtime 조합이 어긋날 수 있다. BOM drift를 먼저 의심해야 하는 이유가 여기에 있다.

네 번째 자료는 Spring Boot dependency management 문서다. 수동 버전 override는 호환성 문제를 일으킬 수 있으니 주의하라고 분명히 적고 있다.

Spring Boot는 managed dependency를 수동 override하면 compatibility issue가 날 수 있다고 경고한다.

이미 verifier disable과 override 분기 글이 1차 선택을 다뤘다면, 이번 글은 verifier를 통과한 뒤에도 남는 starter override drift를 좁히는 후속편이다.

다섯 번째 공식 화면은 Spring Cloud Gateway reference appendix다. gateway starter가 실제로 살아 있으면 이 property 집합을 읽는 구간과 관련 auto-configuration이 classpath에 붙는다.

Spring Cloud Gateway reference는 `spring.cloud.gateway.server.webflux.enabled` 등 gateway property 집합을 문서화한다.

그래서 verifier가 통과했는데도 gateway 관련 테스트가 깨질 때는 property 바인딩, starter 조합, classpath drift를 같이 봐야 한다. 단순히 Boot 버전 숫자만 다시 보는 것으로는 부족하다.

마지막 자료는 CI triage 표다. verifier failure와 starter drift는 겉보기엔 비슷해도 먼저 볼 지점이 다르다.

Spring Cloud Gateway starter CI 실패를 verifier, BOM drift, starter override로 나누는 triage 표다.

같은 업그레이드 가지의 최근 글인 OpenFeign starter 후속 글과 같이 보면, 같은 release train에서도 starter별 smoke test 순서를 따로 가져가야 한다는 점이 더 선명해진다.

5. 주의사항과 리스크

첫 번째 리스크는 verifier를 통과시켰으니 runtime starter 조합도 안전하다고 생각하는 것이다. 두 번째는 gateway starter 한 좌표만 급하게 올리고 release train BOM은 그대로 두는 것이다. 세 번째는 managed dependency override 경고를 무시하고 수동 핀을 여러 곳에 남겨 놓는 것이다.

운영 전에 확인할 때는 Boot 버전, Cloud BOM 버전, verifier 설정, starter 수동 핀, gateway smoke test 결과 다섯 칸을 같은 표에 두는 편이 좋다. 그래야 다음 업그레이드에서도 'verifier 문제'와 'starter drift 문제'를 별개로 기록할 수 있다. 실제로는 build.gradle 또는 pom.xml 필드, dependency tree 결과 파일, CI 로그, 테스트 이름, gateway route 설정 값을 같은 순서로 확인해야 누락이 적다.

• verifier 통과와 starter 호환성은 같은 신호가 아니다.
• release train BOM과 starter 수동 핀을 함께 본다.
• gateway branch는 starter별 smoke test로 따로 관리한다.

6. 결론

Gateway starter가 Boot 4.1에서 verifier를 통과했는데도 CI가 깨질 때는 compatible-boot-versions를 또 만지는 것보다 BOM drift와 starter override를 먼저 보는 편이 빠르다. Spring Cloud release train BOM을 기준으로 다시 맞추고, gateway property/classpath smoke test를 분리하면 원인을 훨씬 빨리 자를 수 있다. 실제 작업에서는 dependency tree 파일, build import 위치, starter 버전 필드, CI 로그 결과를 같은 표에 저장해 두는 편이 가장 안전하다.

• dependency tree와 BOM import를 먼저 본다.
• gateway starter 수동 핀을 먼저 의심한다.
• starter별 smoke test를 따로 남긴다.

이번 triage를 실제 CI 대응 순서로 더 좁히려면 새 후속 글인 Gateway starter가 Boot 4.1에서 verifier와 BOM 정렬은 맞는데도 CI가 깨질 때 property smoke test와 classpath diff를 어디부터 분리하나를 이어서 보면 된다. BOM과 starter 핀을 확인한 다음 어떤 property 세트와 classpath diff 표를 먼저 남겨야 하는지까지 한 단계 더 정리해 두었다.

같은 업그레이드 가지의 앞단에는 verifier disable과 compatible Boot versions override 분기 글, OpenFeign starter 후속 글, Spring Cloud release train과 Boot 조합 글이 있다. 그 위에 이번 gateway starter drift triage를 얹으면 verifier 이후 CI 대응 경로가 더 촘촘해진다.

7. 참고 링크

1. https://docs.spring.io/spring-cloud-commons/reference/spring-cloud-commons/common-abstractions.html
2. https://docs.spring.io/spring-boot/system-requirements.html
3. https://spring.io/projects/spring-cloud/
4. https://docs.spring.io/spring-boot/gradle-plugin/managing-dependencies.html
5. https://docs.spring.io/spring-cloud-gateway/reference/appendix.html