Github Actions에서 Gradle 빌드 실패 문제 해결 과정 정리

도입

CICD를 구축하는 과정에서 예상치 못한 문제가 발생했습니다. DockerFile을 정의하고, ECS에 이미지를 푸시하는 과정에서, Gradle에 관련된 빌드 단계가 Github Actions의 Ubuntu 환경에서 정상적으로 실행되지 않았습니다. 처음 겪는 문제였기 때문에 원인을 파악하는 데 시간이 정말 많이 걸렸습니다. 로그를 살펴보면서 Gradle Wrapper(gradlew)가 실행되지 않는 것이 핵심 원인일 가능성이 높다는 결론을 내렸습니다.

 

따라서 이 글에서는 이 문제를 해결하기 위한 과정과 원인 분석을 다루고, 이 문제에 직접적으로 관련 있었던 Gradle Wrapper(gradlew)의 중요성에 대해서도 함께 다루어보고자 합니다.

 

문제 상황

문제상황은 다음과 같았습니다.

• CICD 구축 중 Docker 환경에서 Gradle이 정상적으로 실행되지 않는 문제 발생
• Github Actions의 Ubuntu 환경에서 gradlew 실행이 불가능한 상태

로그를 살펴보면 실행 권한 문제로 보이는 단서가 있지만, 명확한 원인은 불분명했습니다.

 

 

트러블 슈팅

1. Github Actions Workflow 문제일까?

로컬 환경이 아닌, Github Actions 환경에서 Gradle 빌드가 되지 않는 문제였기 때문에 Github Actions의 workflows 파일에서 문제가 있을지도 모르겠다는 생각을했습니다. 따라서 처음에는 .github/workflows/deploy.yml 파일을 수정하며 로그를 찍어보았습니다. 하지만, 빌드 관련된 로그 조차 찍히지 않았습니다.

 

2. Gradle Wrapper(gradlew) 파일 확인

다음으로 Gradle 관련 파일을 직접 확인해보았습니다.

원래는 이래야하는데...

 gradlew 파일을 열어보니 파일이 텅 비어있었습니다. 이 당시 이것이 정확히 무엇을 의미하는지 이해하지 못했습니다. 하지만 본능적으로 무엇가 대단히 잘못된 것 같다는 느낌이 들었습니다.

 

3. Gradlew Wrapper 재생성

이 파일을 새롭게 만들기 위해서 아래 명령어를 통해서 gradlew를 새로 생성해주었습니다.

./gradlew wrapper

그 후, 새롭게 생성된 gradlew 파일을 Git에 커밋하고 다시 푸시한 후, Github Actions를 실행해보았습니다.

 

그리고 빌드가 정상적으로 수행되는 것을 확인할 수 있었습니다.

 

---

Gradle Wrapper란 무엇인가?

 여기서 자연스럽게 궁금증이 생겼습니다.

"도대체 gradlew 파일은 어떤 역할을 하는거지? 왜 이 파일이 손상되면 빌드가 되지 않는 것이지.."

 

Gradle Wrapper의 기능과 역할

 Gradle 공식문서에 따르면, Gradle Wrapper(줄여서 gradlew)는 Gradle 빌드를 실행할 때 사용하는 스크립트로, 특정 버전의 Gradle을 자동으로 다운로드하고 실행할 수 있도록 도와줍니다. 이를 통해서 개발자들은 로컬 환경에 Gradle을 별도로 설치하지 않고도 프로젝트를 쉽게 빌드할 수 있습니다.

 

Gradle Wrapper는 Gradle 빌드를 실행하는 가장 권장되는 방법이고, CI/CD 환경에서 안정적이고 일관된 빌드 환경을 제공하는 핵심 도구였습니다.

 

즉 Github에 저는 해당 파일을 올리지 않아 빌드 환경을 구성할 수 없었습니다. 이때까지 로컬에서 잘 돌아갔던 이유는 저의 로컬 환경에 Gradle이 별도로 설치되어있기 때문이었습니다.

 

주요 기능

Gradle Wrapper를 사용하는 가장 두드러지는 장점들은 아래와 같습니다.

1. 일관된 Gradle 버전을 유지할 수 있습니다.
   • 프로젝트에 특정 버전의 Gradle을 강제할 수 있습니다.
   • gradlew를 사용하면 CICD 서버가 동일한 Gradle 버전을 사용하게 되어 빌드 환경이 일관되게 유지됩니다.
2. Gradle이 설치되지 않은 로컬 환경에서도 빌드 가능합니다.
   • 로컬에 Gradle이 설치되지 않아도, gradlew가 자동으로 Gradle을 다운로드하고 실행합니다. 
   • 개발자나 CI 서버가 별도로 Gradle을 설치할 필요가 없습니다.
3. CI/CD 환경 및 IDE에서 유연한 사용 가능합니다.
   • IDE나 Github Actions 같은 CI/CD 환경에서 별다른 설정 없이 Gradle을 사용할 수 있습니다.
   • 새로운 Gradle 버전이 필요할 때 gradlew의 설정만 변경하면 됩니다.
4. 버전 업그레이드 및 관리가 간편합니다.
   • gradlew를 통해 Gradle 버전을 손쉽게 업그레이드할 수 있습니다.
   • 프로젝트마다 Gradle 버전을 개별적으로 설정할 수 있어, 최신 기능을 점진적으로 도입하는 것이 가능합니다.

 

Gradle Wrapper 파일 구성

 원래 Gradle Wrapper를 생성하면 3가지 파일이 추가가 됩니다.

• 실행 스크립트: gradlew(macOS, Linus), gradlew.bat(Windows)
• Gradle Wrapper JAR파일:gradle/wrapper/gradle-wrapper.jar
• Gradle Wrapper 설정 파일: gradle/wrapper/gradle-wrapper.properties

 실행스크립트는 프로젝트 루트 디렉터리에 존재하고, Gradle 빌드를 실행합니다. CI/CD 환경에서 이 파일을 사용해 Gradle을 실행합니다.  다음으로 Gradle Wrapper JAR파일이 Gradle을 자동으로 다운로드하고 실행하는 역할을 하고, Gradle Wrapper 설정 파일이 Gradle 버전과 다운로드 URL을 저장하고 있습니다. 버전을 변경할 때 해당 파일을 수정하면 됩니다.

 

추가적으로..

특정 Gradle 버전을 사용하고 싶다면?

./gradlew wrapper --gradle-version 8.12.1 --distribution-type all

 

Gradle Wrapper로 빌드하려면?

./gradlew build

 

Gradle Wrapper 업그레이드

./gradlew wrapper --gradle-version latest // 최신 버전
./gradlew wrapper --gradle-version 8.12.1 // 특정 버전

이 외에도 다양한 명령어를 통해서 이 파일들을 관리/실행 할 수 있습니다.

 

결론

Gradle Wrapper파일은 반드시 사용되어야 합니다.

 

 이를 통해서 로컬 환경과 CI/CD 환경 간 빌드 일관성을 보장할 수 있고, 추가적으로 버전 업그레이드나 굳이 로컬에 설치하지 않아도 프로젝트를 실행할 수 있습니다. CI/CD 환경(Github Actions, Jenkins, GitLab CI/CD)등에서 gradlew를 사용하면 별도의 설정 없이 Gradle을 실행할 수 있습니다.

 

만약에 저처럼 Gradle Wrapper를 사용하지 않는다면...

• CI/CD 환경에서 Gradle이 설치되지 않아 빌드가 실패하거나...
• 팀원들마다 다른 Gradle 버전을 사용하여 빌드 문제가 생긴다거나...
• 매번 Gradle을 수동으로 설치해야한다거나...

위와 같은 문제들을 겪을 수 있습니다.

 

이 경험을 통해서 Gradle Wrapper는 사용하는게 좋고, .gitigonre에서 실수로 이를 제외하지 않도록 주의해야겠다 생각했습니다.

 

 

참고 문헌

• https://docs.gradle.org/current/userguide/gradle_wrapper.html