배포 오류 : Asciidoctor 빌드 오류(asGemPath())

서비스 품질을 높이기 위해선 안정적인 테스트와 빌드 과정이 필수적이다. 하지만 자동화된 배포 환경을 구축하다 보면 예기치 못한 오류를 만나기도 한다. 이번에 Gradle과 Spring REST Docs를 활용해 CI/CD를 구성하면서 발생했던 오류와 해결 방법을 기록해본다.

🚩 오류 상황

배포 자동화를 구현하는 과정에서 갑자기 빌드 오류가 발생했다. 에러 메시지를 확인해 보니 다음과 같은 문제가 있었다.

 

검색 결과 Gradle의 버전과 관련된 이슈라는 정보를 찾았고, 버전을 6.5로 낮춰도 여전히 문제가 해결되지 않았다.

 

🛠️ 문제 해결 방법

결국 플러그인과 build.gradle 파일을 수정하여 문제를 해결할 수 있었다.

1️⃣ 플러그인 수정

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.1'
    id 'io.spring.dependency-management' version '1.1.4'
//    id "org.asciidoctor.convert" version "1.5.9.2" // 기존 설정 주석 처리
    id 'org.asciidoctor.jvm.convert' version "3.3.2" // 변경
}

2️⃣ configurations 추가

configurations를 추가하여 새로 적용한 플러그인을 사용하도록 설정했다.

configurations {
    asciidoctorExtensions
}

3️⃣ dependencies 설정 변경

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
//    asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor' // 기존 설정 주석 처리
    asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor' // 변경
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}

4️⃣ asciidoctor task 변경

마지막으로 asciidoctor task에 새로 추가한 configurations를 지정해주었다.

asciidoctor {
    inputs.dir snippetsDir
    dependsOn test
    configurations 'asciidoctorExtensions'
}

단, 위 변경사항으로 인해 HTML의 생성 경로가 /build/docs/html5에서 /build/docs/asciidoc으로 변경될 수 있으니, 정적 파일로 복사하는 경로를 다시 확인해야 한다.

📌 참고자료

• Configuring asciidoctor when using Spring Restdoc
• [SPRING] Asciidoctor 빌드 오류(asGemPath())